@provos/ironcurtain 0.10.0 → 0.12.0

package/dist/workflow/container-snapshots.d.ts

@@ -0,0 +1,29 @@
+import type { ContainerRuntime } from '../docker/types.js';
+import type { CheckpointStore } from './checkpoint.js';
+import type { ContainerSnapshotRef, WorkflowCheckpoint, WorkflowId } from './types.js';
+import type { ResolvedUserConfig } from '../config/user-config.js';
+export declare const IRONCURTAIN_SNAPSHOT_LABEL_WORKFLOW = "ironcurtain.snapshot.workflow";
+export declare const IRONCURTAIN_SNAPSHOT_LABEL_SCOPE = "ironcurtain.snapshot.scope";
+export declare const IRONCURTAIN_SNAPSHOT_LABEL_STOP = "ironcurtain.snapshot.stop";
+export declare function hasContainerSnapshots(checkpoint: WorkflowCheckpoint | undefined): boolean;
+export declare function getContainerSnapshotImages(checkpoint: WorkflowCheckpoint | undefined): readonly string[];
+export declare function commitContainerSnapshot(input: {
+    readonly docker: ContainerRuntime;
+    readonly workflowId: WorkflowId;
+    readonly scope: string;
+    readonly containerId: string;
+    readonly timeoutMs?: number;
+}): Promise<ContainerSnapshotRef>;
+export declare function removeContainerSnapshotImages(docker: ContainerRuntime, snapshots: Readonly<Record<string, ContainerSnapshotRef>> | undefined): Promise<void>;
+export interface ContainerSnapshotGcResult {
+    readonly removedImages: readonly string[];
+    readonly agedImages: readonly string[];
+    readonly orphanImages: readonly string[];
+}
+export declare function sweepContainerSnapshots(input: {
+    readonly baseDir: string;
+    readonly checkpointStore: CheckpointStore;
+    readonly userConfig: ResolvedUserConfig;
+    readonly docker?: ContainerRuntime;
+    readonly now?: Date;
+}): Promise<ContainerSnapshotGcResult>;

package/dist/workflow/container-snapshots.js

@@ -0,0 +1,137 @@
+import { randomUUID } from 'node:crypto';
+import { createDockerManager } from '../docker/docker-manager.js';
+import { commandExists } from '../trusted-process/container-command.js';
+import * as logger from '../logger.js';
+import { isCheckpointResumable } from './checkpoint.js';
+export const IRONCURTAIN_SNAPSHOT_LABEL_WORKFLOW = 'ironcurtain.snapshot.workflow';
+export const IRONCURTAIN_SNAPSHOT_LABEL_SCOPE = 'ironcurtain.snapshot.scope';
+export const IRONCURTAIN_SNAPSHOT_LABEL_STOP = 'ironcurtain.snapshot.stop';
+const SNAPSHOT_TAG_REPOSITORY = 'ironcurtain-snapshot';
+const DEFAULT_SNAPSHOT_COMMIT_TIMEOUT_MS = 600_000;
+/**
+ * A snapshot image is committed (and labeled) BEFORE its checkpoint is saved
+ * (see the stop paths in orchestrator.ts). For that brief window the image is
+ * labeled but not yet referenced by any checkpoint. The orphan sweep skips
+ * images younger than this so a concurrent sweep can't delete a snapshot that
+ * another workflow is mid-commit on.
+ */
+const ORPHAN_SWEEP_GRACE_MS = 5 * 60 * 1000;
+function sanitizeTagPart(value) {
+    const sanitized = value.toLowerCase().replace(/[^a-z0-9_.-]/g, '_');
+    return sanitized.length > 0 ? sanitized : 'scope';
+}
+function buildSnapshotTag(workflowId, scope, stopId) {
+    return `${SNAPSHOT_TAG_REPOSITORY}:${workflowId}-${sanitizeTagPart(scope)}-${stopId}`;
+}
+function uniqueSnapshotImages(snapshots) {
+    if (!snapshots)
+        return [];
+    return [...new Set(Object.values(snapshots).map((snapshot) => snapshot.image))];
+}
+export function hasContainerSnapshots(checkpoint) {
+    return uniqueSnapshotImages(checkpoint?.containerSnapshots).length > 0;
+}
+export function getContainerSnapshotImages(checkpoint) {
+    return uniqueSnapshotImages(checkpoint?.containerSnapshots);
+}
+export async function commitContainerSnapshot(input) {
+    const stopId = randomUUID();
+    const tag = buildSnapshotTag(input.workflowId, input.scope, stopId);
+    const image = await input.docker.commit(input.containerId, {
+        tag,
+        pause: false,
+        flatten: true,
+        timeoutMs: input.timeoutMs ?? DEFAULT_SNAPSHOT_COMMIT_TIMEOUT_MS,
+        // No need to clear inherited ironcurtain.bundle/scope labels: the flatten
+        // (export/import) path produces an image with no labels at all, so we only
+        // stamp the dedicated snapshot labels used by GC.
+        changes: [
+            `LABEL ${IRONCURTAIN_SNAPSHOT_LABEL_WORKFLOW}=${input.workflowId}`,
+            `LABEL ${IRONCURTAIN_SNAPSHOT_LABEL_SCOPE}=${input.scope}`,
+            `LABEL ${IRONCURTAIN_SNAPSHOT_LABEL_STOP}=${stopId}`,
+        ],
+    });
+    return { image, tag };
+}
+export async function removeContainerSnapshotImages(docker, snapshots) {
+    await Promise.allSettled(uniqueSnapshotImages(snapshots).map((image) => docker.removeImage(image)));
+}
+export async function sweepContainerSnapshots(input) {
+    if (!input.userConfig.snapshot.enabled) {
+        return { removedImages: [], agedImages: [], orphanImages: [] };
+    }
+    // Container snapshots are a Docker-only feature. On a host without the Docker
+    // CLI (e.g. an Apple `container`-only machine) there are no snapshot images to
+    // collect — skip cleanly rather than spawning a missing `docker` binary and
+    // surfacing a caught ENOENT to every caller on each sweep.
+    let docker = input.docker;
+    if (!docker) {
+        if (!commandExists('docker')) {
+            return { removedImages: [], agedImages: [], orphanImages: [] };
+        }
+        docker = createDockerManager();
+    }
+    const nowMs = (input.now ?? new Date()).getTime();
+    const maxAgeMs = input.userConfig.snapshot.maxAgeDays === null ? null : input.userConfig.snapshot.maxAgeDays * 24 * 60 * 60 * 1000;
+    const referenced = new Map();
+    for (const workflowId of input.checkpointStore.listAll()) {
+        let checkpoint;
+        try {
+            checkpoint = input.checkpointStore.load(workflowId);
+        }
+        catch {
+            continue;
+        }
+        if (!checkpoint || !isCheckpointResumable(checkpoint))
+            continue;
+        for (const image of uniqueSnapshotImages(checkpoint.containerSnapshots)) {
+            referenced.set(image, checkpoint);
+        }
+    }
+    const removedImages = [];
+    const orphanImages = [];
+    const agedImages = [];
+    let labeledImages;
+    try {
+        labeledImages = await docker.listImages({ labelFilter: IRONCURTAIN_SNAPSHOT_LABEL_WORKFLOW });
+    }
+    catch (err) {
+        // Expected when Docker is unavailable (e.g. a builtin, non-Docker workflow
+        // triggered the CLI sweep), so degrade quietly -- debug-only so a persistent
+        // failure is still discoverable without spamming non-Docker users.
+        logger.debug(`snapshot GC: listImages failed, skipping sweep: ${err instanceof Error ? err.message : String(err)}`);
+        return { removedImages, agedImages, orphanImages };
+    }
+    for (const image of labeledImages) {
+        if (referenced.has(image.id))
+            continue;
+        const createdMs = Date.parse(image.created);
+        if (Number.isFinite(createdMs) && nowMs - createdMs < ORPHAN_SWEEP_GRACE_MS)
+            continue;
+        if (await docker.removeImage(image.id)) {
+            removedImages.push(image.id);
+            orphanImages.push(image.id);
+        }
+    }
+    if (maxAgeMs !== null) {
+        for (const [image, checkpoint] of referenced.entries()) {
+            const imageInfo = await docker.inspectImage(image);
+            if (!imageInfo)
+                continue;
+            const imageCreatedMs = Date.parse(imageInfo.created);
+            const checkpointMs = Date.parse(checkpoint.timestamp);
+            const validTimes = [imageCreatedMs, checkpointMs].filter((value) => Number.isFinite(value));
+            if (validTimes.length === 0)
+                continue;
+            const bornAtMs = Math.min(...validTimes);
+            if (nowMs - bornAtMs <= maxAgeMs)
+                continue;
+            if (await docker.removeImage(image)) {
+                removedImages.push(image);
+                agedImages.push(image);
+            }
+        }
+    }
+    return { removedImages, agedImages, orphanImages };
+}
+//# sourceMappingURL=container-snapshots.js.map

package/dist/workflow/container-snapshots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container-snapshots.js","sourceRoot":"","sources":["../../src/workflow/container-snapshots.ts"],"names":[],"mappings":"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"}

package/dist/workflow/daemon-gate-commands.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Non-interactive, machine-readable CLI surface for driving gated workflows on
+ * a running daemon: `run` / `status` / `await` / `gate` / `show`.
+ *
+ * These commands talk to the daemon's existing WebSocket JSON-RPC interface via
+ * the leaf {@link DaemonClient}; they never import the orchestrator/manager
+ * runtime. An autonomous agent uses them as run-to-completion tool calls:
+ *
+ *   run -> await -> (show -> gate -> await)* -> terminal
+ *
+ * Output convention: a single newline-terminated JSON object to **stdout** when
+ * `--json` is set (the agent parses stdout); human-readable text to **stderr**.
+ * Exit codes are derived from the authoritative workflow `phase`, never from a
+ * lifecycle event name (a gate-ABORT fires a `completed` event but reports
+ * `phase:'aborted'`).
+ */
+/**
+ * Routes a daemon-backed gate subcommand. Returns the process exit code; the
+ * caller (`workflow-command.ts`) is responsible for `process.exit`.
+ */
+export declare function runDaemonGateCommand(subcommand: string, args: string[]): Promise<number>;