stageflow 0.39.0 → 0.40.0

package/dist/runtime/sandboxFiles.d.ts

@@ -0,0 +1,20 @@
+import { type SandboxExecResult } from "./sandboxContainer.js";
+export declare class SandboxPathError extends Error {
+    constructor(message: string);
+}
+export declare function shellQuote(value: string): string;
+/** Resolve a tool path onto the sandbox mount. Host absolutes and `..` escapes are rejected. */
+export declare function confineSandboxPath(inputPath: string): string;
+export type SandboxFileTarget = {
+    containerName: string;
+    dockerBin?: string;
+};
+export declare function readSandboxFile(target: SandboxFileTarget, inputPath: string): Promise<string>;
+export declare function writeSandboxFile(target: SandboxFileTarget, inputPath: string, content: string): Promise<void>;
+export declare function editSandboxFile(target: SandboxFileTarget, inputPath: string, edits: readonly {
+    oldText: string;
+    newText: string;
+}[]): Promise<void>;
+export declare function sliceSandboxLines(text: string, offset?: number, limit?: number): string;
+export declare function formatSandboxBashResult(result: SandboxExecResult): string;
+export declare function runSandboxBash(target: SandboxFileTarget, command: string, timeoutMs?: number): Promise<string>;

package/dist/runtime/sandboxFiles.js

@@ -0,0 +1,150 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { copyToSandboxContainer, execInSandboxContainer, SANDBOX_MOUNT_PATH, } from "./sandboxContainer.js";
+export class SandboxPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SandboxPathError";
+    }
+}
+export function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+/** Resolve a tool path onto the sandbox mount. Host absolutes and `..` escapes are rejected. */
+export function confineSandboxPath(inputPath) {
+    if (typeof inputPath !== "string" || inputPath.trim() === "") {
+        throw new SandboxPathError("path must be a non-empty string");
+    }
+    if (inputPath.includes("\0") || inputPath.startsWith("~")) {
+        throw new SandboxPathError("path escapes the sandbox");
+    }
+    const slashes = inputPath.replaceAll("\\", "/");
+    const joined = slashes.startsWith("/")
+        ? path.posix.normalize(slashes)
+        : path.posix.normalize(path.posix.join(SANDBOX_MOUNT_PATH, slashes));
+    if (joined !== SANDBOX_MOUNT_PATH && !joined.startsWith(`${SANDBOX_MOUNT_PATH}/`)) {
+        throw new SandboxPathError("path escapes the sandbox");
+    }
+    return joined;
+}
+function assertFilePath(containerPath) {
+    if (containerPath === SANDBOX_MOUNT_PATH) {
+        throw new SandboxPathError("path must name a file under /workspace");
+    }
+}
+async function requireExec(result, fallback) {
+    if (result.exitCode === 0)
+        return;
+    const detail = result.stderr.trim() || result.stdout.trim();
+    throw new Error(detail || fallback);
+}
+export async function readSandboxFile(target, inputPath) {
+    const containerPath = confineSandboxPath(inputPath);
+    assertFilePath(containerPath);
+    const quoted = shellQuote(containerPath);
+    const result = await execInSandboxContainer({
+        containerName: target.containerName,
+        dockerBin: target.dockerBin,
+        command: `if [ ! -f ${quoted} ]; then echo "No such file: ${containerPath}" >&2; exit 1; fi; base64 < ${quoted}`,
+    });
+    await requireExec(result, `failed to read ${containerPath}`);
+    return Buffer.from(result.stdout, "base64").toString("utf8");
+}
+export async function writeSandboxFile(target, inputPath, content) {
+    const containerPath = confineSandboxPath(inputPath);
+    assertFilePath(containerPath);
+    const parent = path.posix.dirname(containerPath);
+    const made = await execInSandboxContainer({
+        containerName: target.containerName,
+        dockerBin: target.dockerBin,
+        command: `mkdir -p -- ${shellQuote(parent)}`,
+    });
+    await requireExec(made, `failed to write ${containerPath}`);
+    const scratch = await mkdtemp(path.join(tmpdir(), "sf-sandbox-write-"));
+    const payload = path.join(scratch, "payload");
+    try {
+        await writeFile(payload, content);
+        await copyToSandboxContainer({
+            containerName: target.containerName,
+            dockerBin: target.dockerBin,
+            hostPath: payload,
+            containerPath,
+        });
+    }
+    finally {
+        await rm(scratch, { recursive: true, force: true });
+    }
+}
+export async function editSandboxFile(target, inputPath, edits) {
+    if (edits.length === 0) {
+        throw new Error("edits must contain at least one replacement");
+    }
+    const original = await readSandboxFile(target, inputPath);
+    const ranges = [];
+    for (const edit of edits) {
+        if (edit.oldText.length === 0) {
+            throw new Error("oldText must not be empty");
+        }
+        const count = countOccurrences(original, edit.oldText);
+        if (count !== 1) {
+            throw new Error(`oldText matched ${count} times`);
+        }
+        const start = original.indexOf(edit.oldText);
+        ranges.push({ start, end: start + edit.oldText.length, newText: edit.newText });
+    }
+    ranges.sort((a, b) => b.start - a.start);
+    for (let i = 0; i < ranges.length; i += 1) {
+        const later = ranges[i];
+        for (let j = i + 1; j < ranges.length; j += 1) {
+            const earlier = ranges[j];
+            if (earlier.end > later.start) {
+                throw new Error("edits overlap");
+            }
+        }
+    }
+    let next = original;
+    for (const range of ranges) {
+        next = next.slice(0, range.start) + range.newText + next.slice(range.end);
+    }
+    await writeSandboxFile(target, inputPath, next);
+}
+export function sliceSandboxLines(text, offset, limit) {
+    if (offset === undefined && limit === undefined)
+        return text;
+    const lines = text.split("\n");
+    const start = offset !== undefined ? Math.max(0, Math.floor(offset) - 1) : 0;
+    if (start >= lines.length) {
+        throw new Error(`Offset ${offset} is beyond end of file (${lines.length} lines total)`);
+    }
+    const end = limit !== undefined ? start + Math.max(0, Math.floor(limit)) : lines.length;
+    return lines.slice(start, end).join("\n");
+}
+export function formatSandboxBashResult(result) {
+    const parts = [result.stdout];
+    if (result.stderr.trim().length > 0)
+        parts.push(result.stderr);
+    parts.push(`Exit code: ${result.exitCode}`);
+    return parts.join("\n");
+}
+export async function runSandboxBash(target, command, timeoutMs) {
+    const result = await execInSandboxContainer({
+        containerName: target.containerName,
+        dockerBin: target.dockerBin,
+        command,
+        ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+    });
+    return formatSandboxBashResult(result);
+}
+function countOccurrences(haystack, needle) {
+    let count = 0;
+    let from = 0;
+    while (from <= haystack.length) {
+        const at = haystack.indexOf(needle, from);
+        if (at < 0)
+            return count;
+        count += 1;
+        from = at + needle.length;
+    }
+    return count;
+}

package/dist/runtime/stageEnvironment.js

@@ -26,6 +26,8 @@ export const STAGE_ENV_ALLOWLIST = [
     "no_proxy",
     "STAGEFLOW_HOME",
     "STAGEFLOW_CURSOR_EXTENSION",
+    "STAGEFLOW_STAGE_CONTAINER_IMAGE",
+    "STAGEFLOW_STAGE_CONTAINER_DOCKER_BIN",
 ];
 export const PROVIDER_AND_CLOUD_NAMES = [
     "ANTHROPIC_API_KEY",

package/dist/runtime/stageRoots.d.ts

@@ -11,6 +11,14 @@ export type StageRoots = {
     attempt?: number;
     /** Durable Pi auth.json path for ModelRuntime.create({ authPath }). */
     authPath?: string;
+    /**
+     * Sandbox container `stageWorker.ts` started for this attempt, if any.
+     * When set, read/write/edit/bash run inside that container's /workspace
+     * desk. Undefined leaves those tools on the host.
+     */
+    containerName?: string;
+    /** The docker binary the container above was started with (see STAGEFLOW_STAGE_CONTAINER_DOCKER_BIN). */
+    containerDockerBin?: string;
 };
 export declare const STAGEFLOW_CHECKOUT = "STAGEFLOW_CHECKOUT";
 export declare const STAGEFLOW_RUN_WORKSPACE = "STAGEFLOW_RUN_WORKSPACE";
@@ -51,6 +59,7 @@ export declare function stageBindingEnvFromRun(options: {
 };
 export declare function withResolvedAuthPath(roots: StageRoots, factoryCwd: string): StageRoots;
 export declare function rootsForStageWorker(runWorkspaceDir: string, stageId: string, model: string, checkoutRoot?: string, attemptCtx?: StageAttemptContext): StageRoots;
+export declare function withContainerName(roots: StageRoots, containerName: string | undefined, containerDockerBin?: string): StageRoots;
 export declare function bindPiAgentDirEnv(agentDirPath: string): () => void;
 export declare function resolveCheckoutPath(declared: string, cwd: string): string;
 export declare function resolveAndValidateCheckout(task: TaskFile, override: string | undefined, factoryCwd: string): Promise<string | undefined>;

package/dist/runtime/stageRoots.js

@@ -4,6 +4,7 @@ import { isCursorModelRef } from "../agent/cursorProvider.js";
 import { stageDir } from "../runstore/paths.js";
 import { noAttemptContext } from "./stageAttemptContext.js";
 import { resolveCredentialBinding, STAGEFLOW_AGENT_AUTH_PATH_ENV, currentExplicitAuthPath, } from "./credentialBinding.js";
+import { ensureWorktreeCheckout } from "./gitWorktreeCheckout.js";
 import { SF_STAGE_WORKER } from "./stageWorkerProtocol.js";
 export const STAGEFLOW_CHECKOUT = "STAGEFLOW_CHECKOUT";
 export const STAGEFLOW_RUN_WORKSPACE = "STAGEFLOW_RUN_WORKSPACE";
@@ -151,6 +152,11 @@ export function rootsForStageWorker(runWorkspaceDir, stageId, model, checkoutRoo
         cwd: stageDir(runWorkspaceDir, stageId),
     };
 }
+export function withContainerName(roots, containerName, containerDockerBin) {
+    return containerName === undefined
+        ? roots
+        : { ...roots, containerName, containerDockerBin };
+}
 export function bindPiAgentDirEnv(agentDirPath) {
     const prev = process.env[PI_CODING_AGENT_DIR_ENV];
     process.env[PI_CODING_AGENT_DIR_ENV] = agentDirPath;
@@ -170,6 +176,14 @@ export async function resolveAndValidateCheckout(task, override, factoryCwd) {
     const raw = override ?? task.checkout;
     if (raw === undefined)
         return undefined;
+    if (typeof raw !== "string") {
+        return ensureWorktreeCheckout({
+            projectRoot: factoryCwd,
+            branch: raw.branch,
+            base: raw.base,
+            taskId: task.id,
+        });
+    }
     if (raw.trim() === "") {
         throw new Error("Invalid checkout: path is empty or whitespace-only");
     }

package/dist/runtime/stageRunner.d.ts

@@ -53,6 +53,11 @@ export type RunStageOptions = {
     stageEnv?: Record<string, string>;
     /** Test seam for the Host login check run by a `browser_login` verify item. */
     browser?: Pick<StageBrowserSupport, "runner" | "loginCheck">;
+    /**
+     * Runs after the agent turn and before completion verification records a
+     * verdict. Used to copy a sandbox desk back onto the host tree.
+     */
+    beforeVerify?: () => Promise<void>;
 };
 /**
  * Yield loop: next() until completed; on wait, coordinator enterWait (KTD6).

package/dist/runtime/stageRunner.js

@@ -47,6 +47,17 @@ async function appendLifecycleEventAndPatchExecution(options) {
         // no execution row yet
     }
 }
+async function runBeforeVerify(beforeVerify) {
+    if (beforeVerify === undefined)
+        return undefined;
+    try {
+        await beforeVerify();
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
 async function finalizeStageResult(options) {
     const { store, runId, stageId, result, activityChain, attemptCtx, browser } = options;
     const attemptOpt = attemptCtx?.eventOptions();
@@ -125,7 +136,7 @@ export async function runStageYieldLoop(options) {
     }
 }
 export async function runStage(options) {
-    const { agent, store, runId, stage, task, dag, checkoutRoot, workspaceDir, hitl, skipStarted, existingHandle, workerMode, roots: rootsOverride, attemptCtx, factoryCwd, operatorCatalog, completedEnvelopes, skipGates, sessionMode, feedbackLoopContext, resumeToken, stageEnv, browser: browserSeams, } = options;
+    const { agent, store, runId, stage, task, dag, checkoutRoot, workspaceDir, hitl, skipStarted, existingHandle, workerMode, roots: rootsOverride, attemptCtx, factoryCwd, operatorCatalog, completedEnvelopes, skipGates, sessionMode, feedbackLoopContext, resumeToken, stageEnv, browser: browserSeams, beforeVerify, } = options;
     const stageId = options.stageId ?? stage.id;
     const attemptOpt = attemptCtx?.eventOptions();
     const baseRoots = rootsOverride ??
@@ -242,20 +253,43 @@ export async function runStage(options) {
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
+        const synced = await runBeforeVerify(beforeVerify);
+        const fullReason = synced === undefined ? reason : `${reason}; ${synced}`;
         await activityChain;
         hitl?.clearLiveWait(runId, stageId);
         await appendLifecycleEventAndPatchExecution({
             store,
             runId,
             stageId,
-            event: { event: "failed", reason },
+            event: { event: "failed", reason: fullReason },
             attemptCtx,
         });
-        console.error(`Stage ${stageId} failed: ${reason}`);
+        console.error(`Stage ${stageId} failed: ${fullReason}`);
         await handle
             .close(isStageTimeoutReason(reason) ? { park: true } : undefined)
             .catch(() => undefined);
-        return { ok: false, reason };
+        return { ok: false, reason: fullReason };
+    }
+    const syncError = await runBeforeVerify(beforeVerify);
+    if (syncError !== undefined) {
+        const reason = syncError;
+        if (isRunStageWaiting(outcome)) {
+            await activityChain;
+            hitl?.clearLiveWait(runId, stageId);
+            await appendLifecycleEventAndPatchExecution({
+                store,
+                runId,
+                stageId,
+                event: { event: "failed", reason },
+                attemptCtx,
+            });
+            console.error(`Stage ${stageId} failed: ${reason}`);
+            await handle.close().catch(() => undefined);
+            return { ok: false, reason };
+        }
+        outcome = outcome.ok
+            ? { ok: false, reason }
+            : { ok: false, reason: `${outcome.reason}; ${reason}` };
     }
     if (isRunStageWaiting(outcome)) {
         await activityChain;

package/dist/runtime/stageSandbox.d.ts

@@ -0,0 +1,16 @@
+import { type StageRoots } from "./stageRoots.js";
+export type StageSandbox = {
+    roots: StageRoots;
+    beforeVerify?: () => Promise<void>;
+    close: () => Promise<void>;
+    failure?: string;
+};
+export declare function openStageSandbox(input: {
+    env: NodeJS.ProcessEnv;
+    roots: StageRoots;
+    runId: string;
+    stageId: string;
+    attempt: number;
+    attemptDir: string;
+    checkoutRoot?: string;
+}): Promise<StageSandbox>;

package/dist/runtime/stageSandbox.js

@@ -0,0 +1,54 @@
+import { resolveSandboxContainerOptions, startSandboxContainer, stopSandboxContainer, } from "./sandboxContainer.js";
+import { buildSandboxDesk, populateSandboxDesk, syncSandboxDesk, } from "./sandboxDesk.js";
+import { withContainerName } from "./stageRoots.js";
+export async function openStageSandbox(input) {
+    const options = resolveSandboxContainerOptions(input.env);
+    if (!options) {
+        return { roots: input.roots, close: async () => { } };
+    }
+    const started = await startSandboxContainer({
+        image: options.image,
+        dockerBin: options.dockerBin,
+        runId: input.runId,
+        stageId: input.stageId,
+        attempt: input.attempt,
+    });
+    const roots = withContainerName(input.roots, started.containerName, options.dockerBin);
+    const checkout = input.checkoutRoot?.trim();
+    const desk = buildSandboxDesk({
+        attemptDir: input.attemptDir,
+        ...(checkout ? { checkoutRoot: checkout } : {}),
+    });
+    const session = {
+        roots,
+        close: () => stopSandboxContainer({
+            containerName: started.containerName,
+            dockerBin: options.dockerBin,
+        }).catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[stageWorker] failed to stop sandbox container ${started.containerName}: ${message}\n`);
+        }),
+    };
+    try {
+        await populateSandboxDesk({
+            containerName: started.containerName,
+            dockerBin: options.dockerBin,
+            desk,
+        });
+    }
+    catch (err) {
+        session.failure = err instanceof Error ? err.message : String(err);
+        return session;
+    }
+    session.beforeVerify = syncOnce(started.containerName, options.dockerBin, desk);
+    return session;
+}
+function syncOnce(containerName, dockerBin, desk) {
+    let synced = false;
+    return async () => {
+        if (synced)
+            return;
+        synced = true;
+        await syncSandboxDesk({ containerName, dockerBin, desk });
+    };
+}