stageflow 0.19.0 → 0.23.0

package/dist/mcp/catalogTools.js

@@ -1,10 +1,30 @@
+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 { 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 { 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,9 +33,27 @@ 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(),
 })
@@ -26,18 +64,49 @@ 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,21 +131,30 @@ 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);
@@ -94,34 +172,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 +221,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 +261,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 +270,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;

package/dist/mcp/providerTools.js

@@ -0,0 +1,17 @@
+import { z } from "zod";
+import { inspectProviderReadiness, mapProviderAuthError, } from "../agent/providerInspect.js";
+import { textResult } from "./toolResults.js";
+export function registerProviderTools(server, deps) {
+    server.registerTool("list_providers", {
+        description: "List login-capable model providers with auth readiness and a Pi-home detect summary. Read-only; does not log in or return secrets.",
+        inputSchema: z.object({}),
+    }, async () => {
+        try {
+            return textResult(await inspectProviderReadiness(deps.cwd, deps.providerAuthContext));
+        }
+        catch (err) {
+            const mapped = mapProviderAuthError(err);
+            return textResult({ error: mapped.body.error, status: mapped.status }, true);
+        }
+    });
+}

package/dist/mcp/readArtifact.d.ts

@@ -1,4 +1,13 @@
 import type { RunStore } from "../runstore/port.js";
 export declare function artifactMediaType(relativePath: string): string | undefined;
+export type ClassifiedArtifactContent = {
+    kind: "image";
+    mimeType: string;
+} | {
+    kind: "utf8";
+} | {
+    kind: "binary";
+};
+export declare function classifyArtifactContent(relativePath: string, bytes: Buffer): ClassifiedArtifactContent;
 export declare function readRunArtifact(store: RunStore, runId: string, relativePath: string): Promise<string>;
 export declare function readRunArtifactBytes(store: RunStore, runId: string, relativePath: string): Promise<Buffer>;

package/dist/mcp/readArtifact.js

@@ -1,3 +1,4 @@
+import { isUtf8 } from "node:buffer";
 import { readFile, realpath } from "node:fs/promises";
 import path from "node:path";
 import { isInsideDir } from "../runstore/workspaceLayout.js";
@@ -28,6 +29,16 @@ export function artifactMediaType(relativePath) {
             return undefined;
     }
 }
+export function classifyArtifactContent(relativePath, bytes) {
+    const mimeType = artifactMediaType(relativePath);
+    if (mimeType !== undefined) {
+        return { kind: "image", mimeType };
+    }
+    if (isUtf8(bytes)) {
+        return { kind: "utf8" };
+    }
+    return { kind: "binary" };
+}
 async function resolveRunArtifactFile(store, runId, relativePath) {
     assertSafeRunId(runId);
     if (typeof relativePath !== "string" || relativePath.trim().length === 0) {

package/dist/mcp/server.js

@@ -34,7 +34,15 @@ function sessionIdFromRequest(req) {
     return undefined;
 }
 function toolDepsFrom(deps) {
-    return { manager: deps.manager, store: deps.store, cwd: deps.cwd };
+    return {
+        manager: deps.manager,
+        store: deps.store,
+        cwd: deps.cwd,
+        ...(deps.providerAuthContext !== undefined
+            ? { providerAuthContext: deps.providerAuthContext }
+            : {}),
+        ...(deps.projectRoot !== undefined ? { projectRoot: deps.projectRoot } : {}),
+    };
 }
 function attachBusNotifications(server, bus) {
     return bus.on((event) => {

package/dist/mcp/tailStreamLog.d.ts

@@ -0,0 +1,8 @@
+export type StreamLogTail = {
+    text: string;
+    nextOffset: number;
+    truncated?: boolean;
+    earliestOffset?: number;
+};
+/** Read new content from a stage's stream.log since a caller's last cursor. */
+export declare function readStreamLogTail(streamLogPath: string, sinceOffset: number | undefined): Promise<StreamLogTail>;

package/dist/mcp/tailStreamLog.js

@@ -0,0 +1,28 @@
+import { readFile } from "node:fs/promises";
+import { parseStreamLogHeader } from "../runtime/stageStreamLog.js";
+/** Read new content from a stage's stream.log since a caller's last cursor. */
+export async function readStreamLogTail(streamLogPath, sinceOffset) {
+    let raw;
+    try {
+        raw = await readFile(streamLogPath);
+    }
+    catch {
+        return { text: "", nextOffset: 0 };
+    }
+    const { base, headerLength } = parseStreamLogHeader(raw);
+    const contentBytes = raw.subarray(headerLength);
+    const eof = base + contentBytes.length;
+    if (sinceOffset === undefined || sinceOffset < base) {
+        const truncated = sinceOffset !== undefined && sinceOffset < base;
+        return {
+            text: contentBytes.toString("utf8"),
+            nextOffset: eof,
+            ...(truncated ? { truncated: true, earliestOffset: base } : {}),
+        };
+    }
+    if (sinceOffset >= eof) {
+        return { text: "", nextOffset: eof };
+    }
+    const slice = contentBytes.subarray(sinceOffset - base);
+    return { text: slice.toString("utf8"), nextOffset: eof };
+}

package/dist/mcp/toolResults.d.ts

@@ -5,3 +5,20 @@ export declare function textResult(data: unknown, isError?: boolean): {
     }[];
     isError?: boolean | undefined;
 };
+export declare function imageResult(mimeType: string, bytes: Buffer, identity: {
+    runId: string;
+    path: string;
+    mimeType: string;
+}): {
+    content: ({
+        type: "image";
+        mimeType: string;
+        data: string;
+        text?: undefined;
+    } | {
+        mimeType?: undefined;
+        data?: undefined;
+        type: "text";
+        text: string;
+    })[];
+};

package/dist/mcp/toolResults.js

@@ -4,3 +4,18 @@ export function textResult(data, isError = false) {
         ...(isError ? { isError: true } : {}),
     };
 }
+export function imageResult(mimeType, bytes, identity) {
+    return {
+        content: [
+            {
+                type: "image",
+                mimeType,
+                data: bytes.toString("base64"),
+            },
+            {
+                type: "text",
+                text: JSON.stringify(identity, null, 2),
+            },
+        ],
+    };
+}