stageflow 0.19.0 → 0.25.0

package/dist/mcp/catalogTools.js

@@ -1,10 +1,33 @@
+import path from "node:path";
 import { z } from "zod";
-import { browseCatalog } from "../config/browseCatalog.js";
+import { browseCatalog, } from "../config/browseCatalog.js";
+import { describePipeline } from "../config/describePipeline.js";
 import { loadPipeline } from "../config/loadPipeline.js";
+import { readYamlObject } from "../config/readYamlObject.js";
 import { validateCatalog } from "../config/validateCatalog.js";
+import { PACKAGE_VERSION } from "../package-meta.js";
+import { findProjectRoot } from "../project/findProjectRoot.js";
+import { PipelineValidationError } from "../runtime/pipelineValidationError.js";
+import { EnvelopeRefError, resolveEnvelopeRefsToTask, } from "../runtime/resolveEnvelopeRef.js";
+import { isTerminalProjection, isWaitingProjection, waitRun } from "./waitRun.js";
+import { mapStoreLookupError } from "../server/operatorResults.js";
 import { projectRunForMcp } from "./projectRun.js";
-import { readRunArtifact } from "./readArtifact.js";
-import { textResult } from "./toolResults.js";
+import { classifyArtifactContent, readRunArtifactBytes } from "./readArtifact.js";
+import { imageResult, textResult } from "./toolResults.js";
+/**
+ * Every project a host serving a global store has ever recorded a run for,
+ * plus this host's own launch directory (always included so a project with
+ * zero runs yet still sees its own catalog).
+ */
+async function catalogRootsFor(deps) {
+    const known = await deps.store.listProjectRoots();
+    return [...new Set([...known, deps.cwd])];
+}
+/** Resolve which project a given catalog path (pipeline/task) belongs to. */
+function projectRootForPath(deps, catalogPath) {
+    const absDir = path.dirname(path.resolve(deps.cwd, catalogPath));
+    return findProjectRoot(absDir) ?? deps.cwd;
+}
 const taskFileSchema = z.object({
     id: z.string(),
     goal: z.string(),
@@ -13,31 +36,119 @@ const taskFileSchema = z.object({
     checkout: z.string().optional(),
     input: z.record(z.string(), z.unknown()).optional(),
 });
+/**
+ * Deliberately thin: only enough shape to route to the inline-pipeline
+ * loader. Real structural validation (required io schemas, DAG shape, stage
+ * id uniqueness) happens downstream through the same validator a file-based
+ * pipeline goes through, so a caller gets the same ValidationFinding-shaped
+ * error either way instead of a raw schema-validation error.
+ */
+const inlinePipelineSchema = z
+    .object({
+    id: z.string().min(1),
+    stages: z.array(z.record(z.string(), z.unknown())).min(1),
+    agent: z.unknown().optional(),
+    model: z.unknown().optional(),
+    schemas: z.unknown().optional(),
+})
+    .strict();
 const startRunSchema = z
     .object({
-    pipeline: z.string().describe("Filesystem path to a pipeline YAML file"),
+    pipeline: z
+        .union([z.string(), inlinePipelineSchema])
+        .describe("Filesystem path to a pipeline YAML file, or an inline pipeline definition object ({ id, stages: [...] }) authored directly in this call"),
     task_path: z.string().optional(),
     task: taskFileSchema.optional(),
 })
     .refine((data) => Boolean(data.task_path) !== Boolean(data.task), {
     message: "Exactly one of task_path or task is required",
 });
+/**
+ * Deliberately thin, same reasoning as inlinePipelineSchema above: real
+ * structural validation of the stage body happens downstream through the
+ * same stage loader a pipeline's inline stage goes through.
+ */
+const envelopeRefSchema = z.object({
+    runId: z.string(),
+    stageId: z.string(),
+    attempt: z.number().int().positive().optional(),
+});
+const runStageSchema = z
+    .object({
+    stage: z
+        .union([z.string(), z.record(z.string(), z.unknown())])
+        .describe("Filesystem path to a stage YAML file, or a bare inline stage body object ({ id, system_prompt, io, model?, gate_kinds?, mcp?, verify?, timeout_ms? } — no uses:/route/pipeline wrapper) authored directly in this call"),
+    task_path: z.string().optional(),
+    task: taskFileSchema.optional(),
+    envelope_ref: z
+        .union([envelopeRefSchema, z.array(envelopeRefSchema).min(1)])
+        .optional()
+        .describe("Resolve one or more previously stored StageEnvelopes (from another run_stage call or from any stage inside a full pipeline run) and use them as this stage's input, instead of an inline task/task_path. A single ref: its payload becomes input, its summary becomes goal. Multiple refs (an array): each resolved payload is namespaced under its stageId in input (disambiguated by runId on a stageId collision), and summaries are combined into goal."),
+    checkout: z
+        .string()
+        .optional()
+        .describe("Optional checkout to use with envelope_ref (ignored with task/task_path, which carry their own checkout). Resolving envelope_ref never implies a checkout on its own."),
+    model: z
+        .string()
+        .optional()
+        .describe("Override the model/backend for this call only, taking precedence over the stage's own declared model and the global default. Omit to use the stage's own model (or the global default)."),
+    blocking: z
+        .boolean()
+        .optional()
+        .describe("When true, wait for the run to reach a terminal or waiting state and return the result in this same call, instead of returning immediately with just { runId }"),
+    timeout_ms: z
+        .number()
+        .optional()
+        .describe("Wait budget in ms when blocking is true (same bounds as wait_run)"),
+})
+    .refine((data) => [data.task_path, data.task, data.envelope_ref].filter(Boolean).length === 1, { message: "Exactly one of task_path, task, or envelope_ref is required" });
 const runStatusSchema = z.enum(["created", "running", "succeeded", "failed"]);
 export function registerCatalogTools(server, deps) {
     const { manager, store, cwd } = deps;
     server.registerTool("list_pipelines", {
-        description: "List manifest-declared pipeline paths from the project catalog",
+        description: "List manifest-declared pipeline paths across every project this host knows about (this host's own project plus any project a run has ever been recorded for). Each entry is tagged with project_root. A project with no runs yet won't appear until its first run exists.",
         inputSchema: z.object({}),
     }, async () => {
-        const catalog = await browseCatalog(cwd);
-        return textResult({ pipelines: catalog.pipelines });
+        const roots = await catalogRootsFor(deps);
+        const pipelines = [];
+        for (const root of roots) {
+            try {
+                const catalog = await browseCatalog(root);
+                for (const p of catalog.pipelines) {
+                    pipelines.push({ ...p, project_root: root });
+                }
+            }
+            catch {
+                // stale/unreadable project root recorded on an old run; skip it
+            }
+        }
+        return textResult({ pipelines });
     });
     server.registerTool("list_tasks", {
-        description: "List manifest-declared task paths from the project catalog",
+        description: "List manifest-declared task paths across every project this host knows about (this host's own project plus any project a run has ever been recorded for). Each entry is tagged with project_root. A project with no runs yet won't appear until its first run exists.",
+        inputSchema: z.object({}),
+    }, async () => {
+        const roots = await catalogRootsFor(deps);
+        const tasks = [];
+        for (const root of roots) {
+            try {
+                const catalog = await browseCatalog(root);
+                for (const t of catalog.tasks) {
+                    tasks.push({ ...t, project_root: root });
+                }
+            }
+            catch {
+                // stale/unreadable project root recorded on an old run; skip it
+            }
+        }
+        return textResult({ tasks });
+    });
+    server.registerTool("list_models", {
+        description: "List catalog model ids from the project catalog (same source as GET /api/models)",
         inputSchema: z.object({}),
     }, async () => {
         const catalog = await browseCatalog(cwd);
-        return textResult({ tasks: catalog.tasks });
+        return textResult({ models: catalog.models });
     });
     server.registerTool("list_runs", {
         description: "List known pipeline runs. Optional filters: status, since (ISO created_at lower bound), pipeline (id or path).",
@@ -62,27 +173,133 @@ export function registerCatalogTools(server, deps) {
         return textResult({ runs });
     });
     server.registerTool("get_health", {
-        description: "Server health and soft-max run capacity: activeRunIds, activeCount, maxConcurrent, slotsAvailable. Start until slotsAvailable is 0; then wait for a run to finish or raise STAGEFLOW_MAX_CONCURRENT_RUNS.",
+        description: "Server health and soft-max run capacity: activeRunIds, activeCount, maxConcurrent, slotsAvailable, version. Start until slotsAvailable is 0; then wait for a run to finish or raise STAGEFLOW_MAX_CONCURRENT_RUNS.",
         inputSchema: z.object({}),
-    }, async () => textResult(manager.getHealth()));
+    }, async () => textResult({ ...manager.getHealth(), version: PACKAGE_VERSION }));
     server.registerTool("start_run", {
-        description: "Start a pipeline run using a filesystem pipeline path and either task_path (catalog task file) or an inline task object. Returns { runId }. On conflict returns isError with code busy_capacity (soft max full) or busy_checkout (same checkout leased), plus activeCount/maxConcurrent/activeRunIds and optional conflictingRunId/conflictingCheckout.",
+        description: "Start a pipeline run using a filesystem pipeline path or an inline pipeline definition ({ id, stages: [...] }, each stage the same shape as a YAML stage body — no uses: refs), and either task_path (catalog task file) or an inline task object. Returns { runId }. On conflict returns isError with code busy_capacity (soft max full) or busy_checkout (same checkout leased), plus activeCount/maxConcurrent/activeRunIds and optional conflictingRunId/conflictingCheckout.",
         inputSchema: startRunSchema,
     }, async ({ pipeline, task_path, task }) => {
-        if (!pipeline.trim()) {
+        if (typeof pipeline === "string" && !pipeline.trim()) {
             return textResult({ error: "pipeline is required" }, true);
         }
         const taskInput = task_path ?? task;
         if (taskInput === undefined) {
             return textResult({ error: "Exactly one of task_path or task is required" }, true);
         }
-        const result = await manager.startRun({ pipeline, task: taskInput });
+        let result;
+        try {
+            result = await manager.startRun({ pipeline, task: taskInput });
+        }
+        catch (err) {
+            if (err instanceof PipelineValidationError) {
+                return textResult({ error: "Pipeline validation failed", validation: err.result }, true);
+            }
+            throw err;
+        }
         if (!result.ok) {
             const { ok: _ok, reason, ...rest } = result;
             return textResult({ error: reason, ...rest }, true);
         }
         return textResult({ runId: result.runId });
     });
+    server.registerTool("run_stage", {
+        description: "Run a single stage directly, without authoring a pipeline. `stage` is a filesystem path to a stage YAML file, or a bare inline stage body ({ id, system_prompt, io, model?, gate_kinds?, mcp?, verify?, timeout_ms? } — no uses:/route/pipeline wrapper), and exactly one of task_path, an inline task, or envelope_ref ({ runId, stageId, attempt? }) to resolve a previously stored envelope — from another run_stage call or any stage in a full pipeline run — as this stage's input. Internally this synthesizes a one-stage pipeline and executes it through the normal run path, so it shows up in list_runs/get_run and is polled with wait_run / get_envelope exactly like any other run. By default returns { runId, stageId } immediately (async); pass blocking:true to wait in this same call and get back { runId, stageId, status: \"completed\"|\"needs_input\"|\"timeout\", envelope? , pending_prompt? }.",
+        inputSchema: runStageSchema,
+    }, async ({ stage, task_path, task, envelope_ref, checkout, model, blocking, timeout_ms }) => {
+        let taskInput = task_path ?? task;
+        if (envelope_ref) {
+            try {
+                taskInput = await resolveEnvelopeRefsToTask(store, envelope_ref, checkout);
+            }
+            catch (err) {
+                if (err instanceof EnvelopeRefError) {
+                    return textResult({ error: err.message, status: err.status }, true);
+                }
+                throw err;
+            }
+        }
+        if (taskInput === undefined) {
+            return textResult({ error: "Exactly one of task_path, task, or envelope_ref is required" }, true);
+        }
+        let stageBody;
+        if (typeof stage === "string") {
+            if (!stage.trim()) {
+                return textResult({ error: "stage is required" }, true);
+            }
+            const absPath = path.resolve(cwd, stage);
+            try {
+                stageBody = await readYamlObject(absPath);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return textResult({ error: `Failed to read stage file: ${message}` }, true);
+            }
+        }
+        else {
+            stageBody = stage;
+        }
+        if (typeof stageBody.id !== "string" || !stageBody.id.trim()) {
+            return textResult({ error: "stage.id is required" }, true);
+        }
+        const stageId = stageBody.id;
+        // A call-level model override wins over both the stage's own declared
+        // model and the global default: it replaces the field the stage body
+        // itself would otherwise resolve through, rather than adding a new
+        // tier to resolveModel's stage > pipeline > global chain.
+        const effectiveStageBody = model !== undefined ? { ...stageBody, model } : stageBody;
+        const pipeline = {
+            id: `standalone-${stageId}`,
+            stages: [effectiveStageBody],
+        };
+        let result;
+        try {
+            result = await manager.startRun({ pipeline, task: taskInput });
+        }
+        catch (err) {
+            if (err instanceof PipelineValidationError) {
+                return textResult({ error: "Stage validation failed", validation: err.result }, true);
+            }
+            throw err;
+        }
+        if (!result.ok) {
+            const { ok: _ok, reason, ...rest } = result;
+            return textResult({ error: reason, ...rest }, true);
+        }
+        const runId = result.runId;
+        if (!blocking) {
+            return textResult({ runId, stageId });
+        }
+        const waited = await waitRun({ store, runId, timeoutMs: timeout_ms, until: "any" });
+        if (!waited.ok) {
+            return textResult({
+                error: waited.error,
+                ...(waited.status !== undefined ? { status: waited.status } : {}),
+                ...(waited.code !== undefined ? { code: waited.code } : {}),
+            }, true);
+        }
+        const stageProjection = waited.run.stages.find((s) => s.stage_id === stageId);
+        if (isTerminalProjection(waited.run)) {
+            return textResult({
+                runId,
+                stageId,
+                status: "completed",
+                envelope: stageProjection?.envelope ?? null,
+            });
+        }
+        if (isWaitingProjection(waited.run)) {
+            return textResult({
+                runId,
+                stageId,
+                status: "needs_input",
+                pending_prompt: stageProjection?.pending_prompt,
+                waiting_kind: waited.run.waiting_kind,
+                waiting_prompt_id: waited.run.waiting_prompt_id,
+                waiting_summary: waited.run.waiting_summary,
+            });
+        }
+        return textResult({ runId, stageId, status: "timeout" });
+    });
     server.registerTool("get_run", {
         description: "Poll a run: status, stage statuses, waiting_* / pending_prompt HITL fields, and envelope summary/payload/artifact paths (no events). Use list_stage_events, get_envelope, or get_stage_verification for stage detail.",
         inputSchema: z.object({
@@ -94,34 +311,39 @@ export function registerCatalogTools(server, deps) {
             return textResult(projectRunForMcp(detail));
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            const notFound = /not found|no such|unknown run/i.test(message);
-            return textResult({
-                error: message,
-                status: notFound ? 404 : 500,
-            }, true);
+            const mapped = mapStoreLookupError(err, { policy: "run" });
+            return textResult({ error: mapped.error, status: mapped.status }, true);
         }
     });
     server.registerTool("read_artifact", {
-        description: "Read a text artifact from a run workspace by relative path (contained under the run workspace).",
+        description: "Read a run-workspace artifact by relative path (contained under the run workspace). Known image extensions (png, jpeg, gif, webp) return an MCP image content block. UTF-8 text returns JSON { runId, path, content }. Non-UTF-8 non-image files return isError 400.",
         inputSchema: z.object({
             runId: z.string(),
             path: z.string(),
         }),
     }, async ({ runId, path: artifactPath }) => {
         try {
-            const content = await readRunArtifact(store, runId, artifactPath);
-            return textResult({ runId, path: artifactPath, content });
+            const bytes = await readRunArtifactBytes(store, runId, artifactPath);
+            const classified = classifyArtifactContent(artifactPath, bytes);
+            if (classified.kind === "image") {
+                return imageResult(classified.mimeType, bytes, {
+                    runId,
+                    path: artifactPath,
+                    mimeType: classified.mimeType,
+                });
+            }
+            if (classified.kind === "utf8") {
+                return textResult({
+                    runId,
+                    path: artifactPath,
+                    content: bytes.toString("utf8"),
+                });
+            }
+            return textResult({ error: "Artifact is not valid UTF-8 text", status: 400 }, true);
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            const notFound = message.startsWith("Run not found") ||
-                message.startsWith("Artifact not found") ||
-                /no such|not found/i.test(message);
-            return textResult({
-                error: message,
-                status: notFound ? 404 : 400,
-            }, true);
+            const mapped = mapStoreLookupError(err, { policy: "artifact" });
+            return textResult({ error: mapped.error, status: mapped.status }, true);
         }
     });
     server.registerTool("validate", {
@@ -138,11 +360,36 @@ export function registerCatalogTools(server, deps) {
                 scope = "pipeline";
             else if (task !== undefined && task.trim())
                 scope = "task";
+            if (scope === "full") {
+                const roots = await catalogRootsFor(deps);
+                const results = [];
+                for (const root of roots) {
+                    try {
+                        results.push(await validateCatalog({ cwd: root, scope: "full", strict: strict ?? false }));
+                    }
+                    catch {
+                        // stale/unreadable project root recorded on an old run; skip it
+                    }
+                }
+                const merged = {
+                    scope: "full",
+                    ok: results.every((r) => r.ok),
+                    summary: {
+                        errors: results.reduce((n, r) => n + r.summary.errors, 0),
+                        warnings: results.reduce((n, r) => n + r.summary.warnings, 0),
+                    },
+                    findings: results.flatMap((r) => r.findings),
+                };
+                return textResult(merged);
+            }
+            const target = scope === "pipeline" ? pipeline.trim() : task.trim();
+            const projectRoot = projectRootForPath(deps, target);
             const result = await validateCatalog({
-                cwd,
+                cwd: projectRoot,
                 scope,
-                ...(scope === "pipeline" ? { pipeline: pipeline.trim() } : {}),
-                ...(scope === "task" ? { task: task.trim() } : {}),
+                projectRoot,
+                ...(scope === "pipeline" ? { pipeline: target } : {}),
+                ...(scope === "task" ? { task: target } : {}),
                 strict: strict ?? false,
             });
             return textResult(result);
@@ -153,7 +400,7 @@ export function registerCatalogTools(server, deps) {
         }
     });
     server.registerTool("describe_pipeline", {
-        description: "Describe a pipeline DAG: stages with needs, fork, and gate_kinds. Input is a filesystem pipeline path (same as start_run).",
+        description: "Describe a pipeline DAG from a filesystem path (same as start_run): stages with inbound needs (id, on, optional if), fork, gate_kinds, Clone Chain clone_cap and clone_mode, and feedback_loop, entry, and replay_safe when set.",
         inputSchema: z.object({
             pipeline: z.string(),
         }),
@@ -162,24 +409,10 @@ export function registerCatalogTools(server, deps) {
             return textResult({ error: "pipeline is required", status: 400 }, true);
         }
         try {
-            const loaded = await loadPipeline(pipeline.trim(), { cwd });
-            const gateById = new Map(loaded.stages.map((s) => [s.id, s.gate_kinds]));
-            const stages = loaded.dag.nodes.map((node) => ({
-                id: node.id,
-                needs: node.needsEdges.length > 1
-                    ? node.needsEdges.map((edge) => ({ id: edge.id, on: [...edge.on] }))
-                    : node.needs,
-                ...(node.fork !== undefined ? { fork: node.fork } : {}),
-                ...(node.clone_cap !== undefined ? { clone_cap: node.clone_cap } : {}),
-                ...(gateById.get(node.id) !== undefined
-                    ? { gate_kinds: gateById.get(node.id) }
-                    : {}),
-            }));
-            return textResult({
-                id: loaded.pipeline.id,
-                path: loaded.pipelinePath,
-                stages,
+            const loaded = await loadPipeline(pipeline.trim(), {
+                cwd: projectRootForPath(deps, pipeline.trim()),
             });
+            return textResult(describePipeline(loaded));
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);

package/dist/mcp/controlTools.js

@@ -1,11 +1,15 @@
+import path from "node:path";
 import { z } from "zod";
-import { mapRetryStageFailure, mapStartFailure, } from "../server/operatorResults.js";
+import { findProjectRoot } from "../project/findProjectRoot.js";
+import { mapRetryStageFailure, mapStartFailure, mapStoreLookupError, } from "../server/operatorResults.js";
+import { attemptStreamLogPath } from "../runstore/workspaceLayout.js";
 import { parseAskOperatorAnswer } from "../tools/askOperator.js";
+import { readStreamLogTail } from "./tailStreamLog.js";
 import { textResult } from "./toolResults.js";
 import { projectWaitingGates } from "./waitingGates.js";
 import { readStageVerificationHistory } from "../runstore/verificationHistory.js";
 export function registerControlTools(server, deps) {
-    const { manager, store } = deps;
+    const { manager, store, cwd } = deps;
     server.registerTool("list_waiting", {
         description: "List stages waiting for operator input across runs (optional runId filter). Includes pending_prompt and waiting_* fields per gate.",
         inputSchema: z.object({
@@ -15,6 +19,24 @@ export function registerControlTools(server, deps) {
         const waiting = await projectWaitingGates(store, { runId });
         return textResult({ waiting });
     });
+    server.registerTool("get_waiting_summary", {
+        description: "Lightweight count and identity of stages waiting for operator input — no pending_prompt, waiting_artifacts, or waiting_questions (use list_waiting for full detail). Optional runId scopes to one run; optional path scopes to one project (derived via findProjectRoot, same rule as elsewhere); omitting both spans every project the store knows about.",
+        inputSchema: z.object({
+            runId: z.string().optional(),
+            path: z.string().optional(),
+        }),
+    }, async ({ runId, path: scopePath }) => {
+        const projectRoot = runId === undefined && scopePath !== undefined
+            ? (findProjectRoot(path.resolve(cwd, scopePath)) ?? path.resolve(cwd, scopePath))
+            : undefined;
+        const waiting = await projectWaitingGates(store, { runId, projectRoot });
+        const runs = waiting.map((item) => ({
+            runId: item.runId,
+            stageId: item.stageId,
+            ...(item.waiting_kind !== undefined ? { kind: item.waiting_kind } : {}),
+        }));
+        return textResult({ count: runs.length, runs });
+    });
     server.registerTool("answer_gate", {
         description: "Deliver an AskOperatorAnswer for a stage in waiting_for_input (same semantics as POST /api/runs/:id/stages/:stageId/answer). Pass answer as { promptId, kind, ... } matching the pending prompt.",
         inputSchema: z.object({
@@ -73,8 +95,8 @@ export function registerControlTools(server, deps) {
             await store.readRunMeta(runId);
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return textResult({ error: message, status: 404 }, true);
+            const mapped = mapStoreLookupError(err, { policy: "run" });
+            return textResult({ error: mapped.error, status: 404 }, true);
         }
         try {
             const detail = await store.readRun(runId);
@@ -86,9 +108,46 @@ export function registerControlTools(server, deps) {
             return textResult({ runId, stageId, attempt, events });
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            const notFound = /not found|no such/i.test(message);
-            return textResult({ error: message, status: notFound ? 404 : 500 }, true);
+            const mapped = mapStoreLookupError(err, { policy: "run" });
+            return textResult({ error: mapped.error, status: mapped.status }, true);
+        }
+    });
+    server.registerTool("tail_stage_log", {
+        description: "Poll for new live assistant text a running (or recently finished) stage attempt has produced, since a byte-offset cursor. Separate from list_stage_events — no prompt/artifact/question detail, just the raw redacted text as it streamed. Omit since_offset to catch up on everything currently retained.",
+        inputSchema: z.object({
+            runId: z.string(),
+            stageId: z.string(),
+            attempt: z.number().int().positive().optional(),
+            since_offset: z.number().int().nonnegative().optional(),
+        }),
+    }, async ({ runId, stageId, attempt, since_offset }) => {
+        try {
+            await store.readRunMeta(runId);
+        }
+        catch (err) {
+            const mapped = mapStoreLookupError(err, { policy: "run" });
+            return textResult({ error: mapped.error, status: 404 }, true);
+        }
+        try {
+            const detail = await store.readRun(runId);
+            const stage = detail.stages.find((s) => s.stage_id === stageId);
+            if (!stage) {
+                return textResult({ error: `Stage not found: ${stageId}`, status: 404 }, true);
+            }
+            const effectiveAttempt = attempt ?? stage.attempt_count;
+            const attemptComplete = effectiveAttempt < stage.attempt_count || stage.status !== "running";
+            const streamLogPath = attemptStreamLogPath(store.getWorkspaceDir(runId), stageId, effectiveAttempt);
+            const tail = await readStreamLogTail(streamLogPath, since_offset);
+            return textResult({
+                text: tail.text,
+                next_offset: tail.nextOffset,
+                attempt_complete: attemptComplete,
+                ...(tail.truncated ? { truncated: true, earliest_offset: tail.earliestOffset } : {}),
+            });
+        }
+        catch (err) {
+            const mapped = mapStoreLookupError(err, { policy: "run" });
+            return textResult({ error: mapped.error, status: mapped.status }, true);
         }
     });
     server.registerTool("get_stage_verification", {
@@ -102,9 +161,8 @@ export function registerControlTools(server, deps) {
             return textResult(await readStageVerificationHistory(store, runId, stageId));
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            const notFound = /not found|no such/i.test(message);
-            return textResult({ error: message, status: notFound ? 404 : 500 }, true);
+            const mapped = mapStoreLookupError(err, { policy: "run" });
+            return textResult({ error: mapped.error, status: mapped.status }, true);
         }
     });
     server.registerTool("recover_manual_stage", {
@@ -139,31 +197,31 @@ export function registerControlTools(server, deps) {
         return textResult(result);
     });
     server.registerTool("get_envelope", {
-        description: "Read the full StageEnvelope for a run stage (latest attempt). Returns 404 when absent.",
+        description: "Read the full StageEnvelope for a run stage. Optional attempt (omit = latest). Returns 404 when absent.",
         inputSchema: z.object({
             runId: z.string(),
             stageId: z.string(),
+            attempt: z.number().int().positive().optional(),
         }),
-    }, async ({ runId, stageId }) => {
+    }, async ({ runId, stageId, attempt }) => {
         try {
             await store.readRunMeta(runId);
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            return textResult({ error: message, status: 404 }, true);
+            const mapped = mapStoreLookupError(err, { policy: "run" });
+            return textResult({ error: mapped.error, status: 404 }, true);
         }
         try {
             const detail = await store.readRun(runId);
             if (!detail.stages.some((s) => s.stage_id === stageId)) {
                 return textResult({ error: `Stage not found: ${stageId}`, status: 404 }, true);
             }
-            const envelope = await store.readEnvelope(runId, stageId);
-            return textResult({ runId, stageId, envelope });
+            const envelope = await store.readEnvelope(runId, stageId, attempt);
+            return textResult({ runId, stageId, attempt, envelope });
         }
         catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            const notFound = /not found|no such|envelope/i.test(message);
-            return textResult({ error: message, status: notFound ? 404 : 500 }, true);
+            const mapped = mapStoreLookupError(err, { policy: "envelope" });
+            return textResult({ error: mapped.error, status: mapped.status }, true);
         }
     });
     server.registerTool("retry_stage", {

package/dist/mcp/deps.d.ts

@@ -1,3 +1,4 @@
+import type { ProviderAuthContext } from "../agent/providerAuth.js";
 import type { RunStore } from "../runstore/port.js";
 import type { RunChangeBus } from "../runtime/runChangeBus.js";
 import type { RunManager } from "../runtime/runManager.js";
@@ -5,6 +6,8 @@ export type McpToolDeps = {
     manager: RunManager;
     store: RunStore;
     cwd: string;
+    providerAuthContext?: ProviderAuthContext;
+    projectRoot?: string;
 };
 export type McpHttpDeps = McpToolDeps & {
     runChangeBus: RunChangeBus;

package/dist/mcp/projectMcpTools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { McpToolDeps } from "./deps.js";
+export declare function registerProjectMcpTools(server: McpServer, deps: McpToolDeps): void;

package/dist/mcp/projectMcpTools.js

@@ -0,0 +1,25 @@
+import { z } from "zod";
+import { probeProjectMcpServer } from "../agent/piIsolatedMcpProbe.js";
+import { listProjectMcpCatalog } from "../config/resolveStageMcpServers.js";
+import { textResult } from "./toolResults.js";
+export function registerProjectMcpTools(server, deps) {
+    const { cwd, projectRoot } = deps;
+    const root = projectRoot ?? cwd;
+    server.registerTool("list_project_mcp", {
+        description: "List git-root .mcp.json servers as names and transport only (same as GET /api/project-mcp). Inspect is not attach; it does not interpolate, spawn, or change stage MCP.",
+        inputSchema: z.object({}),
+    }, async () => textResult(await listProjectMcpCatalog(root)));
+    server.registerTool("probe_project_mcp", {
+        description: "Probe one named git-root .mcp.json server with connect-and-exit (same as POST /api/project-mcp/:name/probe). Inspect is not attach; YAML mcp: still allowlists what a stage receives.",
+        inputSchema: z.object({
+            name: z.string(),
+        }),
+    }, async ({ name }, ctx) => {
+        const result = await probeProjectMcpServer({
+            projectRoot: root,
+            name,
+            signal: ctx.mcpReq.signal,
+        });
+        return textResult(result);
+    });
+}

package/dist/mcp/providerTools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+import type { McpToolDeps } from "./deps.js";
+export declare function registerProviderTools(server: McpServer, deps: McpToolDeps): void;