stageflow 0.39.0 → 0.40.0

package/README.md

@@ -53,9 +53,43 @@ The scheduler owns orchestration semantics: DAG readiness, bounded parallelism,
 
 See [Architecture](docs/architecture.md) for component boundaries, execution flow, persistence, recovery behavior, and the tradeoffs behind fresh sessions and explicit handoffs.
 
-## Installation
+## Get started
 
-Requires **Node.js ≥ 20**.
+### Docker (recommended)
+
+Run Stageflow from the published image. It is [`ghcr.io/tejasghutukade/stageflow`](https://github.com/tejasghutukade/stageflow/pkgs/container/stageflow). `0.39` is the current minor tag (`0.39.0` is that exact release).
+
+```bash
+docker run --rm --name stageflow \
+  -e STAGEFLOW_ALLOW_UNAUTHENTICATED_BIND=1 \
+  -p 127.0.0.1:3847:3847 \
+  -v stageflow-data:/data \
+  ghcr.io/tejasghutukade/stageflow:0.39 \
+  sf ui
+```
+
+Open [http://127.0.0.1:3847](http://127.0.0.1:3847). Connect a provider under **Settings → Providers**, then **New pipeline** on the Pipelines page. The `stageflow-data` volume keeps that state across runs.
+
+The process inside the container binds `0.0.0.0`, which is what Docker port publish needs. The `-p` address keeps the port on this machine, and the allow flag lets it start without a bearer. Do not publish the port on `0.0.0.0` with that flag set. `sf ui` is required because the image command is `sf mcp`.
+
+To show the console a project directory:
+
+```bash
+docker run --rm --name stageflow \
+  -e STAGEFLOW_ALLOW_UNAUTHENTICATED_BIND=1 \
+  -e STAGEFLOW_ENSURE_PROJECT_ROOTS=/project \
+  -p 127.0.0.1:3847:3847 \
+  -v stageflow-data:/data \
+  -v "$PWD":/project \
+  ghcr.io/tejasghutukade/stageflow:0.39 \
+  sf ui
+```
+
+Building from this checkout, instead of pulling, is [Docker — Local try](docs/docker.md#local-try-compose).
+
+### Node
+
+Install the `sf` command on the machine when you want it in the shell. Requires **Node.js ≥ 20**.
 
 **Quick install (macOS / Linux):**
 
@@ -75,37 +109,28 @@ npm i -g ./stageflow-*.tgz
 
 `better-sqlite3` ships prebuilds for common platforms. `--ignore-scripts` is fine when a prebuild exists. Benign `node-gyp` warnings during install can be ignored if `require("better-sqlite3")` works.
 
-**Harness skills** (Cursor, Claude Code, Codex, Pi, OpenCode) — from a consumer project:
-
-```bash
-npx skills add tejasghutukade/stageflow
-```
-
-Then ask the agent to set up Stageflow. Details: [docs/skills-suite.md](docs/skills-suite.md).
-
-## Quick start
-
 In a project directory (preferably a git repo):
 
 ```bash
 sf init
+sf ui
+sf run --pipeline pipelines/hello.pipeline.yaml --task tasks/hello.task.yaml
 ```
 
-This scaffolds `stageflow.yaml`, `pipelines/hello.pipeline.yaml` (inline stage), and `tasks/hello.task.yaml`.
+`sf init` scaffolds `stageflow.yaml`, `pipelines/hello.pipeline.yaml`, and `tasks/hello.task.yaml`. Connect a provider before `sf run` — see below. The console is [http://127.0.0.1:3847](http://127.0.0.1:3847).
 
-Run (after connecting a provider — see below):
+**Harness skills** (Cursor, Claude Code, Codex, Pi, OpenCode) — from a consumer project:
 
 ```bash
-sf ui                          # operator console at http://127.0.0.1:3847
-sf run --pipeline pipelines/hello.pipeline.yaml --task tasks/hello.task.yaml
+npx skills add tejasghutukade/stageflow
 ```
 
+Then ask the agent to set up Stageflow. Details: [docs/skills-suite.md](docs/skills-suite.md).
+
 **Workshop** (**New pipeline** on the Pipelines page, or `#/workshop`; it has no rail item) drafts a pipeline in chat and saves it under `workshop/<pipeline-id>/` so it shows up on Run. Guide: [docs/workshop.md](docs/workshop.md).
 
 Expanded walkthrough: [docs/quickstart.md](docs/quickstart.md)
 
-**Docker Compose** (UI + MCP in one Host): copy [`.env.example`](.env.example) → `.env`, then `docker compose up --build -d`. The shipped compose file publishes port 3847 on localhost only and does not require a control token. Checklist: [docs/docker.md](docs/docker.md#local-try-compose).
-
 ## Connect a model provider
 
 Each stage sets a **`model`** id in YAML (e.g. `anthropic/claude-sonnet-4-5`). The matching provider must be authenticated before runs succeed — `sf validate` does not check auth.

package/dist/agent/claudeAdapter.js

@@ -41,7 +41,7 @@
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { isAdvancingEnvelope } from "../envelope/check.js";
 import { assertAnswerMatchesPrompt, parseAskOperatorAnswer, summarizeAnswer, } from "../tools/askOperator.js";
-import { buildStageflowMcpServer, EMIT_STAGE_ENVELOPE_TOOL_NAME, STAGEFLOW_MCP_SERVER_NAME, WRITE_STAGE_ARTIFACT_TOOL_NAME, ASK_OPERATOR_TOOL_NAME, } from "./claudeTools.js";
+import { buildStageflowMcpServer, EMIT_STAGE_ENVELOPE_TOOL_NAME, STAGEFLOW_MCP_SERVER_NAME, WRITE_STAGE_ARTIFACT_TOOL_NAME, ASK_OPERATOR_TOOL_NAME, SANDBOX_BASH_TOOL_NAME, SANDBOX_EDIT_TOOL_NAME, SANDBOX_READ_TOOL_NAME, SANDBOX_WRITE_TOOL_NAME, } from "./claudeTools.js";
 import { createClaudeActivityMapper } from "./claudeActivity.js";
 import { DEFAULT_EMIT_REMINDERS, emitReminderPrompt, formatProviderError } from "./stageTurnDriver.js";
 import { readActivityVerbose } from "./activity.js";
@@ -215,6 +215,7 @@ async function runTurn(input, model, markerPath, promptText, resumeSessionId, us
     input.onActivity?.({ event: "turn_start" });
     let sessionId = resumeSessionId;
     let providerError;
+    const containerName = input.roots.containerName;
     try {
         const mcpServer = buildStageflowMcpServer({
             capture: emitCapture,
@@ -238,6 +239,9 @@ async function runTurn(input, model, markerPath, promptText, resumeSessionId, us
                     },
                 }
                 : {}),
+            ...(containerName !== undefined
+                ? { sandboxBash: { containerName, dockerBin: input.roots.containerDockerBin } }
+                : {}),
         });
         const passedServers = Object.fromEntries(Object.entries(input.resolvedMcpServers ?? {}).map(([name, config]) => [
             name,
@@ -258,6 +262,16 @@ async function runTurn(input, model, markerPath, promptText, resumeSessionId, us
                 persistSession: true,
                 strictMcpConfig: true,
                 ...(resumeSessionId !== undefined ? { resume: resumeSessionId } : {}),
+                ...(containerName !== undefined
+                    ? {
+                        toolAliases: {
+                            Bash: SANDBOX_BASH_TOOL_NAME,
+                            Read: SANDBOX_READ_TOOL_NAME,
+                            Write: SANDBOX_WRITE_TOOL_NAME,
+                            Edit: SANDBOX_EDIT_TOOL_NAME,
+                        },
+                    }
+                    : {}),
             },
         });
         for await (const message of stream) {

package/dist/agent/claudeTools.d.ts

@@ -31,10 +31,15 @@ import { type WriteStageArtifactOptions } from "../tools/writeStageArtifact.js";
 import { type AskOperatorKind, type AskOperatorPrompt } from "../tools/askOperator.js";
 import type { CloneEmitContext, ForkEmitContext } from "../types/forkChoice.js";
 import type { PreEmitCheckOptions } from "../envelope/preEmitChecks.js";
+import { execInSandboxContainer as defaultExecInSandboxContainer } from "../runtime/sandboxContainer.js";
 export declare const STAGEFLOW_MCP_SERVER_NAME = "stageflow";
 export declare const EMIT_STAGE_ENVELOPE_TOOL_NAME = "mcp__stageflow__emit_stage_envelope";
 export declare const WRITE_STAGE_ARTIFACT_TOOL_NAME = "mcp__stageflow__write_stage_artifact";
 export declare const ASK_OPERATOR_TOOL_NAME = "mcp__stageflow__ask_operator";
+export declare const SANDBOX_BASH_TOOL_NAME = "mcp__stageflow__sandbox_bash";
+export declare const SANDBOX_READ_TOOL_NAME = "mcp__stageflow__sandbox_read";
+export declare const SANDBOX_WRITE_TOOL_NAME = "mcp__stageflow__sandbox_write";
+export declare const SANDBOX_EDIT_TOOL_NAME = "mcp__stageflow__sandbox_edit";
 export type AskOperatorCapture = {
     prompt?: AskOperatorPrompt;
 };
@@ -72,6 +77,12 @@ export declare const writeStageArtifactShape: {
     path: z.ZodString;
     content: z.ZodString;
 };
+type SandboxExecFn = typeof defaultExecInSandboxContainer;
+export type SandboxBashOptions = {
+    containerName: string;
+    dockerBin?: string;
+    execute?: SandboxExecFn;
+};
 export declare function buildStageflowMcpServer(options: {
     capture: EmitCapture;
     payloadSchema?: unknown;
@@ -83,4 +94,6 @@ export declare function buildStageflowMcpServer(options: {
         capture: AskOperatorCapture;
         allowedKinds?: readonly AskOperatorKind[];
     };
+    sandboxBash?: SandboxBashOptions;
 }): McpServerConfig;
+export {};

package/dist/agent/claudeTools.js

@@ -29,10 +29,16 @@ import { z } from "zod";
 import { createEmitStageEnvelopeTool, } from "../tools/emitStageEnvelope.js";
 import { createWriteStageArtifactTool, } from "../tools/writeStageArtifact.js";
 import { ASK_OPERATOR_KINDS, AskOperatorError, normalizePromptIds, parseAskOperatorParams, } from "../tools/askOperator.js";
+import { execInSandboxContainer as defaultExecInSandboxContainer } from "../runtime/sandboxContainer.js";
+import { editSandboxFile, formatSandboxBashResult, readSandboxFile, sliceSandboxLines, writeSandboxFile, } from "../runtime/sandboxFiles.js";
 export const STAGEFLOW_MCP_SERVER_NAME = "stageflow";
 export const EMIT_STAGE_ENVELOPE_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__emit_stage_envelope`;
 export const WRITE_STAGE_ARTIFACT_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__write_stage_artifact`;
 export const ASK_OPERATOR_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__ask_operator`;
+export const SANDBOX_BASH_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__sandbox_bash`;
+export const SANDBOX_READ_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__sandbox_read`;
+export const SANDBOX_WRITE_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__sandbox_write`;
+export const SANDBOX_EDIT_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__sandbox_edit`;
 /**
  * Exported so a parity test can assert this stays field-for-field aligned
  * with `tools/emitStageEnvelope.ts`'s typebox schema — the two are hand
@@ -74,6 +80,9 @@ const askOperatorShape = {
     questions: z.array(z.record(z.string(), z.unknown())).optional(),
     artifacts: z.array(z.string()).optional(),
 };
+const sandboxBashShape = {
+    command: z.string().min(1),
+};
 /** Adapts a `{content, details?, isError?, terminate?}` tool result to plain MCP CallToolResult. */
 function toCallToolResult(result) {
     return {
@@ -111,6 +120,92 @@ function buildAskOperatorTool(capture, allowedKinds) {
         };
     });
 }
+/**
+ * When a sandbox container is set, Read/Write/Edit/Bash are aliased onto
+ * these tools. They run against the attempt desk at /workspace. Other stage
+ * tools stay on the host.
+ */
+function buildSandboxBashTool(options) {
+    const execute = options.execute ?? defaultExecInSandboxContainer;
+    return tool("sandbox_bash", "Run a shell command inside this stage attempt's sandbox. The working directory is /workspace. The host filesystem is not mounted.", sandboxBashShape, async (args) => {
+        let result;
+        try {
+            result = await execute({
+                containerName: options.containerName,
+                command: args.command,
+                dockerBin: options.dockerBin,
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `sandbox_bash could not run: ${message}` }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{ type: "text", text: formatSandboxBashResult(result) }],
+        };
+    });
+}
+const sandboxReadShape = {
+    file_path: z.string().min(1),
+    offset: z.number().optional(),
+    limit: z.number().optional(),
+};
+const sandboxWriteShape = {
+    file_path: z.string().min(1),
+    content: z.string(),
+};
+const sandboxEditShape = {
+    file_path: z.string().min(1),
+    old_string: z.string(),
+    new_string: z.string(),
+};
+function sandboxFileError(err, label) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        content: [{ type: "text", text: `${label} could not run: ${message}` }],
+        isError: true,
+    };
+}
+function buildSandboxReadTool(options) {
+    return tool("sandbox_read", "Read a file inside this stage attempt's sandbox. Paths are relative to /workspace or absolute under /workspace. Host paths are rejected.", sandboxReadShape, async (args) => {
+        try {
+            const text = await readSandboxFile(options, args.file_path);
+            return {
+                content: [{ type: "text", text: sliceSandboxLines(text, args.offset, args.limit) }],
+            };
+        }
+        catch (err) {
+            return sandboxFileError(err, "sandbox_read");
+        }
+    });
+}
+function buildSandboxWriteTool(options) {
+    return tool("sandbox_write", "Write a file inside this stage attempt's sandbox. Paths are relative to /workspace or absolute under /workspace. Host paths are rejected.", sandboxWriteShape, async (args) => {
+        try {
+            await writeSandboxFile(options, args.file_path, args.content);
+            return { content: [{ type: "text", text: `Successfully wrote to ${args.file_path}` }] };
+        }
+        catch (err) {
+            return sandboxFileError(err, "sandbox_write");
+        }
+    });
+}
+function buildSandboxEditTool(options) {
+    return tool("sandbox_edit", "Edit a file inside this stage attempt's sandbox. old_string must match exactly once. Paths stay under /workspace.", sandboxEditShape, async (args) => {
+        try {
+            await editSandboxFile(options, args.file_path, [
+                { oldText: args.old_string, newText: args.new_string },
+            ]);
+            return { content: [{ type: "text", text: `Successfully edited ${args.file_path}` }] };
+        }
+        catch (err) {
+            return sandboxFileError(err, "sandbox_edit");
+        }
+    });
+}
 export function buildStageflowMcpServer(options) {
     const emitDef = createEmitStageEnvelopeTool(options.capture, options.payloadSchema, options.forkEmitContext, options.cloneEmitContext, options.preEmitCheckOptions);
     const artifactDef = createWriteStageArtifactTool(options.writeStageArtifact);
@@ -123,6 +218,9 @@ export function buildStageflowMcpServer(options) {
     if (options.askOperator) {
         tools.push(buildAskOperatorTool(options.askOperator.capture, options.askOperator.allowedKinds));
     }
+    if (options.sandboxBash) {
+        tools.push(buildSandboxReadTool(options.sandboxBash), buildSandboxWriteTool(options.sandboxBash), buildSandboxEditTool(options.sandboxBash), buildSandboxBashTool(options.sandboxBash));
+    }
     return createSdkMcpServer({
         name: STAGEFLOW_MCP_SERVER_NAME,
         tools,

package/dist/agent/piAdapter.js

@@ -48,6 +48,7 @@ import { createEmitStageEnvelopeTool, } from "../tools/emitStageEnvelope.js";
 import { remindUntilEmitted } from "./stageTurnDriver.js";
 import { createAskOperatorTool, } from "../tools/askOperator.js";
 import { createWriteStageArtifactTool } from "../tools/writeStageArtifact.js";
+import { createSandboxBashTool, createSandboxEditTool, createSandboxReadTool, createSandboxWriteTool, } from "./sandboxPiTools.js";
 import { createSendEmailTool } from "../tools/sendEmail.js";
 import { createSendMessageTool } from "../tools/sendMessage.js";
 import { createMemoryStoreBashDenyExtension } from "../memory/bashDeny.js";
@@ -462,6 +463,7 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
     }
     const attempt = input.roots.attempt ?? 1;
     const attemptArtifactsPath = `stages/${runtimeStageId(input)}/attempts/${attempt}/artifacts/`;
+    const sandboxed = input.roots.containerName !== undefined;
     const skillBaseDirs = [
         input.stage.skill !== undefined && input.skillFilePath !== undefined
             ? path.dirname(input.skillFilePath)
@@ -476,25 +478,36 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
         (input.stage.email?.length ?? 0) > 0
         ? `Large tool results are saved automatically as stage artifacts under ${attemptArtifactsPath}${TOOL_OUTPUT_ARTIFACT_DIR}/. The tool result names the path. Read or grep that file; do not copy tool output into ${artifactToolName ?? "an artifact"}.`
         : "";
-    const artifactGuidance = input.roots.mode === "bound" && artifactToolName !== undefined
+    const artifactGuidance = sandboxed
         ? [
-            `Project checkout (agent cwd): ${input.roots.checkoutRoot}`,
-            `Factory run workspace: ${input.roots.runWorkspaceDir}`,
-            `Builtin tools (read, bash, write, edit) are for work inside the project checkout.`,
-            skillBaseDir !== undefined
-                ? `Absolute read and bash against ${skillBaseDir} are in bounds for the linked skill.`
-                : undefined,
-            `Create factory stage artifacts only with ${artifactToolName} (path relative to ${attemptArtifactsPath}). Use the returned run-relative path in ${emitToolName}.`,
-            `This is soft guidance: prefer ${artifactToolName} for factory files under the run workspace; do not rely on relative builtin writes for those files.`,
-        ]
-            .filter(Boolean)
-            .join("\n")
-        : artifactToolName !== undefined
+            "Sandbox desk: /workspace. read, bash, write, and edit run only inside that desk.",
+            input.roots.checkoutRoot
+                ? `Checkout: /workspace/checkout. The host checkout path is not mounted.`
+                : "This stage has no checkout. Scratch files go in /workspace/work.",
+            "Attempt artifacts are at /workspace/artifacts. Scratch space is /workspace/work.",
+            artifactToolName !== undefined
+                ? `Create factory stage artifacts only with ${artifactToolName} (path relative to ${attemptArtifactsPath}). Use the returned run-relative path in ${emitToolName}.`
+                : `Create factory stage artifacts under ${attemptArtifactsPath} relative to the run folder.`,
+        ].join("\n")
+        : input.roots.mode === "bound" && artifactToolName !== undefined
             ? [
-                `Create factory stage artifacts with ${artifactToolName} (path relative to ${attemptArtifactsPath}). Use the returned run-relative path in ${emitToolName}.`,
+                `Project checkout (agent cwd): ${input.roots.checkoutRoot}`,
+                `Factory run workspace: ${input.roots.runWorkspaceDir}`,
+                `Builtin tools (read, bash, write, edit) are for work inside the project checkout.`,
+                skillBaseDir !== undefined
+                    ? `Absolute read and bash against ${skillBaseDir} are in bounds for the linked skill.`
+                    : undefined,
+                `Create factory stage artifacts only with ${artifactToolName} (path relative to ${attemptArtifactsPath}). Use the returned run-relative path in ${emitToolName}.`,
                 `This is soft guidance: prefer ${artifactToolName} for factory files under the run workspace; do not rely on relative builtin writes for those files.`,
-            ].join("\n")
-            : `Create factory stage artifacts under ${attemptArtifactsPath} relative to the run folder.`;
+            ]
+                .filter(Boolean)
+                .join("\n")
+            : artifactToolName !== undefined
+                ? [
+                    `Create factory stage artifacts with ${artifactToolName} (path relative to ${attemptArtifactsPath}). Use the returned run-relative path in ${emitToolName}.`,
+                    `This is soft guidance: prefer ${artifactToolName} for factory files under the run workspace; do not rely on relative builtin writes for those files.`,
+                ].join("\n")
+                : `Create factory stage artifacts under ${attemptArtifactsPath} relative to the run folder.`;
     return [
         ...(input.stage.channels?.length ? [
             `Stageflow channels: ${JSON.stringify(input.stage.channels.map(channel => ({ channel: channel.alias ?? channel.connection, operations: channel.operations })))}. Use send_message with the channel name. Recipients are fixed by configuration and you cannot change them. Use a stable operationKey for each intended message. Provider acceptance does not prove delivery. Never resend an unknown submission automatically.`,
@@ -1041,6 +1054,15 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
                     tools.push(definition.name);
                 }
         }
+        if (roots.containerName !== undefined) {
+            const sandboxTools = {
+                containerName: roots.containerName,
+                ...(roots.containerDockerBin !== undefined
+                    ? { dockerBin: roots.containerDockerBin }
+                    : {}),
+            };
+            customTools.push(defineTool(createSandboxReadTool(sandboxTools)), defineTool(createSandboxWriteTool(sandboxTools)), defineTool(createSandboxEditTool(sandboxTools)), defineTool(createSandboxBashTool(sandboxTools)));
+        }
         return {
             sessionManager,
             modelRuntime,

package/dist/agent/sandboxPiTools.d.ts

@@ -0,0 +1,99 @@
+import { Type } from "typebox";
+import { type SandboxFileTarget } from "../runtime/sandboxFiles.js";
+export type SandboxPiToolOptions = SandboxFileTarget;
+export declare function createSandboxReadTool(options: SandboxPiToolOptions): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    promptGuidelines: string[];
+    parameters: Type.TObject<{
+        path: Type.TString;
+        offset: Type.TOptional<Type.TNumber>;
+        limit: Type.TOptional<Type.TNumber>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        path: string;
+        offset?: number;
+        limit?: number;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: undefined;
+        isError?: boolean | undefined;
+    }>;
+};
+export declare function createSandboxWriteTool(options: SandboxPiToolOptions): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    promptGuidelines: string[];
+    parameters: Type.TObject<{
+        path: Type.TString;
+        content: Type.TString;
+    }>;
+    execute: (_toolCallId: string, params: {
+        path: string;
+        content: string;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: undefined;
+        isError?: boolean | undefined;
+    }>;
+};
+export declare function createSandboxEditTool(options: SandboxPiToolOptions): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    promptGuidelines: string[];
+    parameters: Type.TObject<{
+        path: Type.TString;
+        edits: Type.TArray<Type.TObject<{
+            oldText: Type.TString;
+            newText: Type.TString;
+        }>>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        path: string;
+        edits: Array<{
+            oldText: string;
+            newText: string;
+        }>;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: undefined;
+        isError?: boolean | undefined;
+    }>;
+};
+export declare function createSandboxBashTool(options: SandboxPiToolOptions): {
+    name: string;
+    label: string;
+    description: string;
+    promptSnippet: string;
+    promptGuidelines: string[];
+    parameters: Type.TObject<{
+        command: Type.TString;
+        timeout: Type.TOptional<Type.TNumber>;
+    }>;
+    execute: (_toolCallId: string, params: {
+        command: string;
+        timeout?: number;
+    }) => Promise<{
+        content: {
+            type: "text";
+            text: string;
+        }[];
+        details: undefined;
+        isError?: boolean | undefined;
+    }>;
+};

package/dist/agent/sandboxPiTools.js

@@ -0,0 +1,109 @@
+import { Type } from "typebox";
+import { editSandboxFile, readSandboxFile, runSandboxBash, sliceSandboxLines, writeSandboxFile, } from "../runtime/sandboxFiles.js";
+function textResult(text, isError = false) {
+    return {
+        content: [{ type: "text", text }],
+        details: undefined,
+        ...(isError ? { isError: true } : {}),
+    };
+}
+function failure(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return textResult(message, true);
+}
+export function createSandboxReadTool(options) {
+    return {
+        name: "read",
+        label: "read",
+        description: "Read a file inside this stage's sandbox. Paths are relative to /workspace (artifacts/, checkout/, grants/, work/) or absolute under /workspace. Host paths are rejected.",
+        promptSnippet: "Read file contents inside /workspace",
+        promptGuidelines: [
+            "Use read to examine files under /workspace instead of cat or sed.",
+        ],
+        parameters: Type.Object({
+            path: Type.String({ description: "Path to the file to read, relative to /workspace or absolute under /workspace" }),
+            offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
+            limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
+        }),
+        execute: async (_toolCallId, params) => {
+            try {
+                const text = await readSandboxFile(options, params.path);
+                return textResult(sliceSandboxLines(text, params.offset, params.limit));
+            }
+            catch (err) {
+                return failure(err);
+            }
+        },
+    };
+}
+export function createSandboxWriteTool(options) {
+    return {
+        name: "write",
+        label: "write",
+        description: "Write a file inside this stage's sandbox. Paths are relative to /workspace or absolute under /workspace. Parent directories are created. Host paths are rejected.",
+        promptSnippet: "Create or overwrite files inside /workspace",
+        promptGuidelines: ["Use write only for new files or complete rewrites under /workspace."],
+        parameters: Type.Object({
+            path: Type.String({ description: "Path to the file to write, relative to /workspace or absolute under /workspace" }),
+            content: Type.String({ description: "Content to write to the file" }),
+        }),
+        execute: async (_toolCallId, params) => {
+            try {
+                await writeSandboxFile(options, params.path, params.content);
+                return textResult(`Successfully wrote to ${params.path}`);
+            }
+            catch (err) {
+                return failure(err);
+            }
+        },
+    };
+}
+export function createSandboxEditTool(options) {
+    return {
+        name: "edit",
+        label: "edit",
+        description: "Edit a file inside this stage's sandbox with exact text replacement. Paths are relative to /workspace or absolute under /workspace. Each oldText must match exactly once in the original file.",
+        promptSnippet: "Make precise file edits inside /workspace",
+        promptGuidelines: [
+            "Use edit for precise changes under /workspace (edits[].oldText must match exactly once).",
+        ],
+        parameters: Type.Object({
+            path: Type.String({ description: "Path to the file to edit, relative to /workspace or absolute under /workspace" }),
+            edits: Type.Array(Type.Object({
+                oldText: Type.String({ description: "Exact text to replace. It must be unique in the original file." }),
+                newText: Type.String({ description: "Replacement text." }),
+            }), { description: "One or more targeted replacements against the original file." }),
+        }),
+        execute: async (_toolCallId, params) => {
+            try {
+                await editSandboxFile(options, params.path, params.edits);
+                return textResult(`Successfully edited ${params.path}`);
+            }
+            catch (err) {
+                return failure(err);
+            }
+        },
+    };
+}
+export function createSandboxBashTool(options) {
+    return {
+        name: "bash",
+        label: "bash",
+        description: "Execute a bash command in this stage's sandbox. The working directory is /workspace. The host filesystem is not mounted.",
+        promptSnippet: "Execute bash commands in /workspace",
+        promptGuidelines: ["The shell starts in /workspace. Do not use host paths."],
+        parameters: Type.Object({
+            command: Type.String({ description: "Shell command to execute" }),
+            timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional)" })),
+        }),
+        execute: async (_toolCallId, params) => {
+            try {
+                const text = await runSandboxBash(options, params.command, params.timeout !== undefined ? params.timeout * 1000 : undefined);
+                return textResult(text);
+            }
+            catch (err) {
+                return failure(err);
+            }
+        },
+    };
+}

package/dist/config/hostConfig.js

@@ -56,6 +56,8 @@ export const KNOWN_STAGEFLOW_ENV_KEYS = new Set([
     "STAGEFLOW_MAX_ACTIVE_STAGES_PER_RUN",
     "STAGEFLOW_MAX_ACTIVE_STAGE_PROCESSES",
     "STAGEFLOW_STAGE_EXECUTION",
+    "STAGEFLOW_STAGE_CONTAINER_IMAGE",
+    "STAGEFLOW_STAGE_CONTAINER_DOCKER_BIN",
     "STAGEFLOW_STAGE_ENV_ALLOW",
     "STAGEFLOW_STAGE_ENV_PASSTHROUGH",
     "STAGEFLOW_GC_INTERVAL_MS",

package/dist/config/loadTask.js

@@ -6,6 +6,16 @@ import { yamlParsePosition } from "./yamlParsePosition.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function parseCheckout(value) {
+    if (typeof value === "string")
+        return value;
+    if (isPlainObject(value)) {
+        const branch = typeof value.branch === "string" ? value.branch : undefined;
+        const base = typeof value.base === "string" ? value.base : undefined;
+        return { ...(branch !== undefined ? { branch } : {}), ...(base !== undefined ? { base } : {}) };
+    }
+    return undefined;
+}
 function parseGitIdentity(raw) {
     if (!isPlainObject(raw))
         return undefined;
@@ -30,7 +40,7 @@ export function coerceTaskFile(raw) {
         goal: record.goal,
         context: typeof record.context === "string" ? record.context : undefined,
         constraints: typeof record.constraints === "string" ? record.constraints : undefined,
-        checkout: typeof record.checkout === "string" ? record.checkout : undefined,
+        checkout: parseCheckout(record.checkout),
         ...(typeof record.repository === "string" ? { repository: record.repository } : {}),
         ...(typeof record.ref === "string" ? { ref: record.ref } : {}),
         ...(typeof record.run_branch_template === "string"
@@ -73,6 +83,29 @@ export function parseTaskFile(raw, source = "task") {
             return { ...issue, taskId: task.id };
         }));
     }
+    if (isPlainObject(record?.checkout)) {
+        const { branch, base } = record.checkout;
+        if (branch !== undefined && typeof branch !== "string") {
+            return loadFailure([
+                {
+                    code: "task.invalid_shape",
+                    message: `Invalid ${source}: checkout.branch must be a string`,
+                    category: "task",
+                    taskId: task.id,
+                },
+            ]);
+        }
+        if (base !== undefined && typeof base !== "string") {
+            return loadFailure([
+                {
+                    code: "task.invalid_shape",
+                    message: `Invalid ${source}: checkout.base must be a string`,
+                    category: "task",
+                    taskId: task.id,
+                },
+            ]);
+        }
+    }
     return loadSuccess(task);
 }
 export function loadTaskFromYamlOutcome(yamlText, source = "task yaml") {