stageflow 0.36.0 → 0.40.0

package/README.md

@@ -34,8 +34,11 @@ The same pipeline runs three ways without rewriting anything:
 - **Envelope handoffs** — typed stage payloads and artifacts via `write_stage_artifact` / `emit_stage_envelope`
 - **Verified stage execution** — after-phase `verify` checks with durable evidence, plus `on_verify_fail` repair or manual operator recovery ([guide](docs/verified-stage-execution.md))
 - **HITL gates** — operator questions in the console; CI exits `2` when a run is waiting
-- **Operator console** — triage runs, connect providers, answer gates, inspect transcripts at `http://127.0.0.1:3847`
+- **Agents** — project-owned, revisioned agents (`agents/*.agent.yaml`) with granted tools, ask-first approvals, traces, channels, schedules and a public web chat page ([guide](docs/agents.md))
+- **Operator console** — an Inbox for gates and agent approvals, pipeline runs, agents and their sessions, connections, MCP servers and settings at `http://127.0.0.1:3847` ([guide](docs/operator-console.md))
 - **MCP endpoint** — Streamable HTTP at `/mcp` when `sf ui` or `sf mcp` is running
+- **MCP servers for agents and stages** — add servers, secrets and OAuth sign-in from Settings → Project MCP, or in the project `.mcp.json` ([guide](docs/mcp-servers.md))
+- **Connections** — Slack, Telegram, iMessage, WhatsApp and AgentMail channels, and email accounts, managed from one page ([guide](docs/channels.md))
 - **Standalone stage execution** — run a single stage directly with `run_stage` (MCP tool, `sf run-stage` CLI, or the A2A `run_stage` operation), no pipeline file required; chain calls with `envelope_ref` (one or many prior results) instead of a pipeline DAG
 - **CI / headless** — `sf validate --strict --json`, `sf run --json` with exit codes `0` / `1` / `2`
 - **Parallel stages** — pipeline DAG with fan-out, join, and Clone Chains (one Clone Instance per Clone Array element; see [YAML catalog](docs/yaml-catalog.md#clone-chain))
@@ -50,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):**
 
@@ -72,36 +109,27 @@ 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
 ```
 
-**Workshop** (rail → `#/workshop`) 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).
+Then ask the agent to set up Stageflow. Details: [docs/skills-suite.md](docs/skills-suite.md).
 
-Expanded walkthrough: [docs/quickstart.md](docs/quickstart.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).
 
-**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).
+Expanded walkthrough: [docs/quickstart.md](docs/quickstart.md)
 
 ## Connect a model provider
 
@@ -140,11 +168,14 @@ Full reference: [docs/providers.md](docs/providers.md)
 
 Start the console with `sf ui` (default `http://127.0.0.1:3847`).
 
-- **Runs** — active and recent pipeline runs, capacity, and status at a glance
-- **Run detail** — spatial stage map; select a stage for the gated workspace (logs, files, envelopes, HITL). Created runs show **not started** with a **Start run** action until history exists
-- **HITL reply** — answer operator gates (`ask_operator`) without leaving the browser
-- **Pipelines** — browse manifest-declared pipeline definitions
-- **Settings → Providers** — connect model providers (`pi_home` or `sf_owned` credential storage)
+- **Inbox** — pipeline gates and agent approvals that wait on you, then failed and finished runs; Approve or Deny without leaving the page, with optional desktop notifications
+- **Pipeline runs** — active and recent runs, capacity, and status at a glance
+- **Run detail** — Timeline, Graph or List of the stages; select a stage for its transcript, events, envelope and artifacts. Created runs show **not started** with a **Start run** action until history exists
+- **Pipelines, Tasks, Catalog, Triggers** — browse and edit the YAML, start runs; **New pipeline** drafts one in the Workshop
+- **Agents** and **Agent sessions** — a directory with each agent's reach (web chat link, channel, schedule), cost and status; create and edit with version history; sessions, approvals and a run inspector
+- **Connections** — channels, email accounts and tool servers
+- **Settings** — Providers (`pi_home` or `sf_owned` credential storage), Concurrency, MCP server, Project MCP (servers, secrets, sign-in) and Notifications
+- **Command palette** — `⌘K` from any page. Page-by-page guide: [docs/operator-console.md](docs/operator-console.md)
 
 Brand assets live under `docs/img/` (`stageflow-og.svg`, `stageflow-icon.svg`).
 
@@ -266,7 +297,11 @@ Full docs: **[tejasghutukade.github.io/stageflow](https://tejasghutukade.github.
 | [docs/a2a.md](docs/a2a.md) | Publish pipelines for other agents to call over JSON-RPC (A2A), plus the wildcard-access `run_stage` operation |
 | [docs/providers.md](docs/providers.md) | Pi providers, `sf providers` |
 | [docs/docker.md](docs/docker.md) | Docker Compose local try, image pull/run, backup, self-hosting |
-| [docs/operator-console.md](docs/operator-console.md) | Console IA and settings |
+| [docs/operator-console.md](docs/operator-console.md) | Console navigation, command palette, shortcuts and routes; one page per area ([Inbox](docs/console-inbox.md), [Runs](docs/console-runs.md), [Agents](docs/console-agents.md), [Connections](docs/console-connections.md), [Settings](docs/console-settings.md)) |
+| [docs/agents.md](docs/agents.md) | Agents: definition, runtime, approvals, channels, schedules, web chat |
+| [docs/mcp-servers.md](docs/mcp-servers.md) | Add MCP servers, secrets and OAuth; use them from agents and stages |
+| [docs/channels.md](docs/channels.md) | Connections and communication channels |
+| [docs/environment-variables.md](docs/environment-variables.md) | Every `STAGEFLOW_*` environment variable |
 | [docs/workshop.md](docs/workshop.md) | Workshop Author — chat-draft a pipeline, save it, and run it |
 | [docs/skills-suite.md](docs/skills-suite.md) | Harness skills — router + jobs for Cursor, Claude Code, Codex, Pi, OpenCode |
 

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";
@@ -84,6 +84,12 @@ function preflight(input) {
             reason: "stage declares channels; the claude agent backend does not provide send_message yet, so the stage would run without it",
         };
     }
+    if (input.stage.memories?.length) {
+        return {
+            ok: false,
+            reason: "stage pipeline declares memories; the claude agent backend does not provide read_memory, replace_memory, add_memory_card, update_memory_card, read_memory_card, and search_memory_cards yet, so the stage would run without them",
+        };
+    }
     return resolveClaudeModel(input.stage.model);
 }
 function resultFromCapture(capture, providerError) {
@@ -209,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,
@@ -232,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,
@@ -252,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.d.ts

@@ -1,4 +1,4 @@
-import { type AgentSession, type ExtensionFactory, SessionManager } from "@earendil-works/pi-coding-agent";
+import { type AgentSession, type ExtensionFactory, DefaultResourceLoader, SessionManager } from "@earendil-works/pi-coding-agent";
 import type { StageRoots } from "../runtime/stageRoots.js";
 import { type AskOperatorPrompt, type AskOperatorWaitBridge } from "../tools/askOperator.js";
 import "./cursorProvider.js";
@@ -76,6 +76,14 @@ export type RouteSessionEventToProgressOptions = {
 export declare function routeSessionEventToProgress(event: Record<string, unknown>, options: RouteSessionEventToProgressOptions): void;
 export declare function composeStageUserPrompt(input: StageRunInput, emitToolName: string, emitHintOverride?: string, artifactToolName?: string): string;
 export declare function composeFeedbackResumePrompt(input: StageRunInput): string;
+export declare function mcpToolMetadataMissing(loader: DefaultResourceLoader): boolean;
+export declare function collectMcpExtensionToolNames(loader: DefaultResourceLoader): {
+    ok: true;
+    names: string[];
+} | {
+    ok: false;
+    unrequested: string[];
+};
 /** Stable Pi session JSONL path under the run workspace stage dir. */
 export declare function stageSessionFilePath(roots: Pick<StageRoots, "runWorkspaceDir" | "attempt">, stageId: string): string;
 export declare function resolveStageSessionFile(input: StageRunInput): string;

package/dist/agent/piAdapter.js

@@ -48,8 +48,11 @@ 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";
+import { memorySession } from "../tools/memoryTools.js";
 import { createReplyEmailTool } from "../tools/replyEmail.js";
 import { createGetEmailTool, createSearchEmailTool, createDownloadEmailAttachmentTool } from "../tools/readEmail.js";
 import "./cursorProvider.js";
@@ -460,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)
@@ -474,29 +478,45 @@ 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.`,
         ] : []),
+        ...(input.memoryPrompt !== undefined
+            ? [input.memoryPrompt]
+            : input.memory
+                ? [memorySession(input.memory).prompt]
+                : []),
         ...(input.stage.email?.length ? [
             `Stageflow email permissions: ${JSON.stringify(input.stage.email)}. Use only declared accounts and operations. Use a stable operationKey for each intended message. Provider acceptance does not prove delivery. Never resend an unknown submission automatically.`,
         ] : []),
@@ -566,10 +586,10 @@ function mcpExtensionTools(loader) {
         .extensions.filter((ext) => ext.path === inlinePath)
         .flatMap((ext) => [...ext.tools.keys()]);
 }
-function mcpToolMetadataMissing(loader) {
+export function mcpToolMetadataMissing(loader) {
     return mcpExtensionTools(loader).includes("mcp");
 }
-function collectMcpExtensionToolNames(loader) {
+export function collectMcpExtensionToolNames(loader) {
     const names = [];
     const unrequested = [];
     for (const name of mcpExtensionTools(loader)) {
@@ -928,6 +948,12 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
                         : {}),
                 }),
             },
+            ...(input.stage.memories?.length
+                ? [{
+                        name: "stageflow-memory-bash-deny",
+                        factory: createMemoryStoreBashDenyExtension({ home: globalStageflowHome() }),
+                    }]
+                : []),
             {
                 name: STAGEFLOW_TOOL_OUTPUT_EXTENSION_NAME,
                 factory: createToolOutputBudgetExtension({
@@ -1007,6 +1033,12 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             customTools.push(defineTool(definition));
             tools.push(definition.name);
         }
+        if (input.memory) {
+            for (const definition of memorySession(input.memory).tools) {
+                customTools.push(defineTool(definition));
+                tools.push(definition.name);
+            }
+        }
         if (input.email) {
             const permitted = new Set(input.stage.email?.flatMap(permission => permission.operations));
             const definitions = [
@@ -1022,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/piIsolatedMcp.js

@@ -1,5 +1,6 @@
 import path from "node:path";
 import { createEventBus, } from "@earendil-works/pi-coding-agent";
+import { prepareMcpOAuth } from "../config/mcpOAuth.js";
 import { StageMcpError, } from "../config/resolveStageMcpServers.js";
 import { globalStageflowHome } from "../project/globalHome.js";
 import { TOOL_OUTPUT_HARD_CEILING_BYTES } from "./toolOutputBudget.js";
@@ -48,7 +49,7 @@ const EMPTY_ATTACH = {
     connecting: undefined,
 };
 let cachedCreateMcpAdapter;
-function toIsolatedMcpConfig(snapshot, lifecycle = "lazy") {
+function toIsolatedMcpConfig(snapshot, lifecycle = "lazy", oauth = false) {
     const mcpServers = {};
     for (const [name, entry] of Object.entries(snapshot)) {
         const isolated = {
@@ -65,6 +66,7 @@ function toIsolatedMcpConfig(snapshot, lifecycle = "lazy") {
         mcpServers,
         settings: {
             ...ISOLATED_MCP_SETTINGS,
+            ...(oauth ? { oauthCredentialStore: "encrypted-file" } : {}),
             outputGuard: { ...ISOLATED_MCP_SETTINGS.outputGuard },
         },
     };
@@ -235,11 +237,21 @@ export async function attachIsolatedMcp(snapshot, options) {
         return EMPTY_ATTACH;
     }
     const createMcpAdapter = await loadCreateMcpAdapter();
+    let oauth = false;
+    if (Object.values(snapshot).some((entry) => typeof entry.url === "string")) {
+        try {
+            prepareMcpOAuth();
+            oauth = true;
+        }
+        catch {
+            // Sign-in is optional; a store that cannot be prepared must not stop servers that need none.
+        }
+    }
     const extensionFactories = [
         {
             name: STAGEFLOW_PI_MCP_EXTENSION_NAME,
             factory: createMcpAdapter({
-                config: toIsolatedMcpConfig(snapshot, options?.lifecycle ?? "lazy"),
+                config: toIsolatedMcpConfig(snapshot, options?.lifecycle ?? "lazy", oauth),
             }),
         },
     ];

package/dist/agent/piIsolatedMcpProbe.d.ts

@@ -1,15 +1,19 @@
 import { type ResolvedMcpServers } from "../config/resolveStageMcpServers.js";
+import { type McpToolInfo } from "../config/mcpToolCache.js";
 export declare const PROJECT_MCP_PROBE_TIMEOUT_MS = 30000;
 export type ProjectMcpProbeStatus = "connected" | "needs_auth" | "connect_failed" | "unresolved_var" | "invalid_config" | "missing_catalog" | "cancelled";
 export type ProjectMcpProbeResult = {
     name: string;
     status: ProjectMcpProbeStatus;
     error?: string;
+    /** Tools the server lists, set when the probe connected. */
+    tools?: McpToolInfo[];
 };
 export type ProbeProjectMcpServerOptions = {
     projectRoot: string;
     name: string;
-    env?: NodeJS.ProcessEnv;
+    /** Host env that STAGEFLOW_MCP_ENV_ALLOW may draw from. Defaults to process.env; nothing else is read. */
+    hostEnv?: NodeJS.ProcessEnv;
     signal?: AbortSignal;
     timeoutMs?: number;
 };