stageflow 0.35.0 → 0.39.0

package/dist/operatorAgent/profiles/agentAuthor.js

@@ -0,0 +1,192 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { agentAuthorContextAdapter, emptyAgentAuthorDraft, isAgentAuthorContext, readAgentAuthorDraft, } from "../agentAuthorContext.js";
+import { AGENT_ID_PATTERN, parseAgentDefinition } from "../../config/loadAgent.js";
+import { listProjectMcpCatalog } from "../../config/resolveStageMcpServers.js";
+import { AGENT_AUTHOR_PLAYBOOK } from "./agentAuthorPlaybook.js";
+export const AGENT_AUTHOR_PROFILE_ID = "agent-author";
+const MAX_READ_CHARS = 32_000;
+let proposalSeq = 0;
+function nextProposalId() {
+    proposalSeq += 1;
+    return `agent-author-${proposalSeq}`;
+}
+function projectRootOf(ctx) {
+    const context = ctx.getContext();
+    if (!isAgentAuthorContext(context))
+        return undefined;
+    const root = context.projectRoot?.trim();
+    return root || undefined;
+}
+function rejectEscape(root, rel) {
+    if (!rel || path.isAbsolute(rel) || rel.includes("\0"))
+        return "path must be a relative project path";
+    const parts = rel.split(/[/\\]/);
+    if (parts.some((part) => part === ".." || part === ".git" || part === "node_modules")) {
+        return "path is outside the readable project surface";
+    }
+    const target = path.resolve(root, rel);
+    const base = path.resolve(root);
+    if (target !== base && !target.startsWith(base + path.sep))
+        return "path escapes the project";
+    return null;
+}
+function stringArg(args, key) {
+    const value = args[key];
+    return typeof value === "string" ? value : undefined;
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/** Objects merge key by key; arrays and scalars replace; `null` removes the key. */
+export function mergeDraftPatch(draft, patch) {
+    const next = structuredClone(draft);
+    for (const [key, value] of Object.entries(patch)) {
+        if (value === null)
+            delete next[key];
+        else if (isPlainObject(value) && isPlainObject(next[key])) {
+            next[key] = mergeDraftPatch(next[key], value);
+        }
+        else
+            next[key] = structuredClone(value);
+    }
+    return next;
+}
+function slugId(name) {
+    const slug = name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "")
+        .replace(/^[^a-z]+/, "")
+        .slice(0, 64);
+    return AGENT_ID_PATTERN.test(slug) ? slug : "";
+}
+const readProjectFile = {
+    name: "read_project_file",
+    description: "Read a text file inside the operator project. Relative path only. Refuses .git, node_modules, and paths outside the project. Does not write.",
+    async handler(args, ctx) {
+        const root = projectRootOf(ctx);
+        const rel = stringArg(args, "path")?.trim();
+        if (!root)
+            return { ok: false, content: null, error: "project root is not set" };
+        if (!rel)
+            return { ok: false, content: null, error: "path is required" };
+        const rejected = rejectEscape(root, rel);
+        if (rejected)
+            return { ok: false, content: null, error: rejected };
+        try {
+            const bytes = await readFile(path.resolve(root, rel));
+            if (bytes.includes(0))
+                return { ok: false, content: null, error: "file is not text" };
+            const text = bytes.toString("utf8");
+            return {
+                ok: true,
+                content: {
+                    path: rel,
+                    text: text.length > MAX_READ_CHARS ? `${text.slice(0, MAX_READ_CHARS)}\n…truncated` : text,
+                },
+            };
+        }
+        catch {
+            return { ok: false, content: null, error: "file is not readable" };
+        }
+    },
+};
+const listProjectFiles = {
+    name: "list_project_files",
+    description: "List readable project files: AGENTS.md when present, and YAML files under agents/. Does not write.",
+    async handler(_args, ctx) {
+        const root = projectRootOf(ctx);
+        if (!root)
+            return { ok: false, content: null, error: "project root is not set" };
+        const files = [];
+        try {
+            await readFile(path.join(root, "AGENTS.md"));
+            files.push("AGENTS.md");
+        }
+        catch {
+            /* absent */
+        }
+        try {
+            const entries = await readdir(path.join(root, "agents"), { withFileTypes: true });
+            for (const entry of entries) {
+                if (entry.isFile() && /\.ya?ml$/i.test(entry.name))
+                    files.push(`agents/${entry.name}`);
+            }
+        }
+        catch {
+            /* no agents dir */
+        }
+        return { ok: true, content: { files } };
+    },
+};
+const listMcpServers = {
+    name: "list_mcp_servers",
+    description: "List MCP server names declared in the project's .mcp.json. Use these names under tools.mcp. Does not connect.",
+    async handler(_args, ctx) {
+        const root = projectRootOf(ctx);
+        if (!root)
+            return { ok: false, content: null, error: "project root is not set" };
+        const catalog = await listProjectMcpCatalog(root);
+        return { ok: true, content: { status: catalog.status, servers: catalog.servers.map((server) => server.name) } };
+    },
+};
+const updateAgentDraft = {
+    name: "update_agent_draft",
+    description: [
+        "Change the unsaved agent draft. Arguments: patch (object, required) and summary (one short sentence).",
+        "patch uses the agent YAML schema: objects merge key by key, arrays replace, null removes a key.",
+        "The result lists validation issues; fix them in a follow-up patch. Does not write YAML.",
+    ].join(" "),
+    handler(args, ctx) {
+        const patch = args.patch;
+        if (!isPlainObject(patch))
+            return { ok: false, content: null, error: "patch must be an object" };
+        const currentContext = ctx.getContext();
+        const current = readAgentAuthorDraft(currentContext);
+        const next = mergeDraftPatch(current, patch);
+        if (typeof next.name === "string" && next.name.trim() && !(typeof next.id === "string" && next.id.trim())) {
+            const id = slugId(next.name);
+            if (id)
+                next.id = id;
+        }
+        const parsed = parseAgentDefinition(next);
+        const summary = stringArg(args, "summary")?.trim() || "Updated the agent draft";
+        const proposal = {
+            id: nextProposalId(),
+            summary,
+            baseContext: currentContext,
+            nextContext: {
+                kind: "agent_author",
+                ...(isAgentAuthorContext(currentContext) && currentContext.projectRoot
+                    ? { projectRoot: currentContext.projectRoot }
+                    : {}),
+                draft: next,
+            },
+        };
+        ctx.emitProposal(proposal);
+        return {
+            ok: true,
+            content: { summary, valid: parsed.ok, issues: parsed.ok ? [] : parsed.issues.map((issue) => `${issue.path || "(draft)"}: ${issue.message}`) },
+        };
+    },
+};
+export const AGENT_AUTHOR_TOOL_NAMES = ["read_project_file", "list_project_files", "list_mcp_servers", "update_agent_draft"];
+export function createAgentAuthorProfile() {
+    return {
+        id: AGENT_AUTHOR_PROFILE_ID,
+        title: "Agent author",
+        playbook: AGENT_AUTHOR_PLAYBOOK,
+        greeting: "What should this agent do?",
+        tools: [readProjectFile, listProjectFiles, listMcpServers, updateAgentDraft],
+        contextAdapter: agentAuthorContextAdapter(),
+    };
+}
+export function createAgentAuthorContext(input) {
+    return {
+        kind: "agent_author",
+        projectRoot: input.projectRoot,
+        draft: { ...emptyAgentAuthorDraft(), ...structuredClone(input.draft ?? {}) },
+    };
+}

package/dist/operatorAgent/profiles/agentAuthorPlaybook.d.ts

@@ -0,0 +1 @@
+export declare const AGENT_AUTHOR_PLAYBOOK = "You are the Stageflow Agent author. You draft one sealed project agent with the operator. You are not a task runner, and you do not write files.\n\n## How you talk\n- Short turns, plain words, present tense. One to four sentences.\n- Do not narrate tool names. Say what changed in the config.\n- The config panel shows the draft. The operator can edit it directly; your next patch builds on what they changed.\n\n## Tools\n- read_project_file and list_project_files are read-only. Use them when the operator points at the project, an existing agent file, or AGENTS.md.\n- list_mcp_servers names the servers in .mcp.json. Only grant MCP servers that exist there; if the operator wants one that isn't there, say so.\n- update_agent_draft applies a patch to the draft immediately. Call it as soon as you know enough. Do not wait for Keep. If it reports issues, fix them with another patch.\n- Never use bash, write, or edit. Save is the operator's button, not a tool.\n\n## The draft (agents/<id>.agent.yaml schema)\n- id (snake_case, starts with a letter; derived from name when omitted), name, description, greeting, instructions (required).\n- model: { backend: pi | claude, id?: \"provider/model\", thinking: low | medium | high }. Leave id out to use the project default unless they name one, and say so.\n- tools: { builtin: [read | write | shell] (whole groups), builtin_tools: [read | grep | find | ls | write | edit | bash] (single tools), stageflow: { groups: [...], tools: [...] }, mcp: { <server>: [tool names] or [\"*\"] }, skills: [names], browser: bool }.\n- approvals: { ask_first: [tool ids], approvers: { operators: bool, channel_ids: [] }, timeout_minutes, on_timeout: skip | deny }.\n  Tool ids: builtin names (read, grep, find, ls, write, edit, bash), \"<server>.<tool>\" for MCP, \"agent:<id>\" for sub-agents. ask_first may only name granted tools.\n- sub_agents: [agent ids], observability: { capture: off | metadata | full }, limits: { session_minutes, max_turns, cost_usd | null, long_context: summarize | truncate }, guardrails: { block_patterns: [JavaScript regex] }, schedule: { cron, timezone?, message? }.\n\n## Defaults\n- A new agent saves disabled and starts sealed: read only. Write and shell stay off unless the job needs them.\n- Anything that sends, posts, writes, merges or deletes goes in approvals.ask_first.\n- Capture stays metadata unless they ask for full content.\n\n## After an edit\n- One sentence on what the agent will do now. Mention any assumption or open question. Do not paste YAML unless they ask.\n";

package/dist/operatorAgent/profiles/agentAuthorPlaybook.js

@@ -0,0 +1,29 @@
+export const AGENT_AUTHOR_PLAYBOOK = `You are the Stageflow Agent author. You draft one sealed project agent with the operator. You are not a task runner, and you do not write files.
+
+## How you talk
+- Short turns, plain words, present tense. One to four sentences.
+- Do not narrate tool names. Say what changed in the config.
+- The config panel shows the draft. The operator can edit it directly; your next patch builds on what they changed.
+
+## Tools
+- read_project_file and list_project_files are read-only. Use them when the operator points at the project, an existing agent file, or AGENTS.md.
+- list_mcp_servers names the servers in .mcp.json. Only grant MCP servers that exist there; if the operator wants one that isn't there, say so.
+- update_agent_draft applies a patch to the draft immediately. Call it as soon as you know enough. Do not wait for Keep. If it reports issues, fix them with another patch.
+- Never use bash, write, or edit. Save is the operator's button, not a tool.
+
+## The draft (agents/<id>.agent.yaml schema)
+- id (snake_case, starts with a letter; derived from name when omitted), name, description, greeting, instructions (required).
+- model: { backend: pi | claude, id?: "provider/model", thinking: low | medium | high }. Leave id out to use the project default unless they name one, and say so.
+- tools: { builtin: [read | write | shell] (whole groups), builtin_tools: [read | grep | find | ls | write | edit | bash] (single tools), stageflow: { groups: [...], tools: [...] }, mcp: { <server>: [tool names] or ["*"] }, skills: [names], browser: bool }.
+- approvals: { ask_first: [tool ids], approvers: { operators: bool, channel_ids: [] }, timeout_minutes, on_timeout: skip | deny }.
+  Tool ids: builtin names (read, grep, find, ls, write, edit, bash), "<server>.<tool>" for MCP, "agent:<id>" for sub-agents. ask_first may only name granted tools.
+- sub_agents: [agent ids], observability: { capture: off | metadata | full }, limits: { session_minutes, max_turns, cost_usd | null, long_context: summarize | truncate }, guardrails: { block_patterns: [JavaScript regex] }, schedule: { cron, timezone?, message? }.
+
+## Defaults
+- A new agent saves disabled and starts sealed: read only. Write and shell stay off unless the job needs them.
+- Anything that sends, posts, writes, merges or deletes goes in approvals.ask_first.
+- Capture stays metadata unless they ask for full content.
+
+## After an edit
+- One sentence on what the agent will do now. Mention any assumption or open question. Do not paste YAML unless they ask.
+`;

package/dist/operatorAgent/profiles/workshopAuthor.js

@@ -1,4 +1,5 @@
 import { parse as parseYaml } from "yaml";
+import { peekDefaultModel } from "../../models/catalog.js";
 import { validateDraftPackage, } from "../../config/draftPackage.js";
 import { createFilesystemDocsRetriever, } from "../docsRetrieval.js";
 import { readDraftFromContext, workshopDraftContextAdapter, WORKSHOP_AUTHOR_GREETING, } from "../draftContext.js";
@@ -8,7 +9,6 @@ import { buildCreateStageDraft, buildCreateTaskDraft, createSaveTool, createWork
 export const WORKSHOP_AUTHOR_PROFILE_ID = "workshop-author";
 export { WORKSHOP_AUTHOR_PLAYBOOK };
 export { WORKSHOP_AUTHOR_TOOL_NAMES, WORKSHOP_FORBIDDEN_AGENT_TOOLS, buildCreateStageDraft, buildCreateTaskDraft, buildEditStageDraft, buildEditTaskDraft, buildCreatePipelineDraft, buildEditPipelineDraft, createSaveTool, createWorkshopAuthorMutatingTools, } from "./workshopAuthorTools.js";
-const DEFAULT_MODEL = "anthropic/claude-sonnet-4-5";
 const REQUIRED_IO = {
     io: {
         input: { schema: { type: "object" } },
@@ -56,7 +56,7 @@ export function buildStageAddProposal(draft, userText) {
                     body: {
                         id: stageId,
                         system_prompt: `Stage for: ${userText.trim() || "workshop draft"}`,
-                        model: DEFAULT_MODEL,
+                        model: peekDefaultModel(),
                         ...REQUIRED_IO,
                     },
                 },

package/dist/operatorAgent/profiles/workshopAuthorTools.js

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { peekDefaultModel } from "../../models/catalog.js";
 import { parse as parseYaml } from "yaml";
 import { CatalogPathError, resolveDefaultWriteRoot, } from "../../config/catalogRelativePath.js";
 import { defaultWorkshopPackageDirectory } from "../../config/ensureCatalogScanRoot.js";
@@ -33,7 +34,6 @@ export const WORKSHOP_AUTHOR_TOOL_NAMES = [
     "retrieve_docs",
 ];
 export const WORKSHOP_FORBIDDEN_AGENT_TOOLS = ["bash", "write", "edit"];
-const DEFAULT_MODEL = "anthropic/claude-sonnet-4-5";
 const REQUIRED_IO = {
     io: {
         input: { schema: { type: "object" } },
@@ -193,7 +193,7 @@ export function buildCreateStageDraft(draft, args) {
         system_prompt: stringArg(args, "system_prompt") ??
             stringArg(args, "systemPrompt") ??
             `Stage for: ${stringArg(args, "summary") ?? stageId}`,
-        model: stringArg(args, "model") ?? DEFAULT_MODEL,
+        model: stringArg(args, "model") ?? peekDefaultModel(),
         ...REQUIRED_IO,
         ...(bodyFromArgs ?? {}),
     };
@@ -265,7 +265,7 @@ export function buildEditStageDraft(draft, args) {
         ...(existingArt?.body ?? {
             id: stageId,
             system_prompt: `Stage ${stageId}`,
-            model: DEFAULT_MODEL,
+            model: peekDefaultModel(),
             ...REQUIRED_IO,
         }),
         ...patch,

package/dist/operatorAgent/proposals.d.ts

@@ -21,6 +21,7 @@ export type UndoMutationResult = {
     notice?: string;
 };
 export declare function draftFingerprint(draft: DraftPackage): string;
+export declare function operatorContextFingerprint(context: unknown): string;
 export declare function formatArtifact(value: unknown): string;
 export declare function diffDraftPackages(before: DraftPackage, after: DraftPackage): ProposalArtifactDiff[];
 export declare function affectedStageIds(before: DraftPackage, after: DraftPackage): string[];

package/dist/operatorAgent/proposals.js

@@ -1,8 +1,14 @@
+import { isAgentAuthorContext } from "./agentAuthorContext.js";
 import { readDraftFromContext } from "./draftContext.js";
 const UNDO_CONFLICT_NOTICE = "Undo blocked: the draft changed after this mutation. Ask the agent to reverse the change instead of rejecting.";
 export function draftFingerprint(draft) {
     return JSON.stringify(draft);
 }
+export function operatorContextFingerprint(context) {
+    if (isAgentAuthorContext(context))
+        return JSON.stringify(context.draft);
+    return draftFingerprint(readDraftFromContext(context));
+}
 export function formatArtifact(value) {
     return JSON.stringify(value, null, 2);
 }
@@ -117,6 +123,21 @@ export function affectedStageIds(before, after) {
     return [...ids];
 }
 export function enrichProposal(proposal, currentContext) {
+    if (isAgentAuthorContext(proposal.nextContext) ||
+        isAgentAuthorContext(currentContext) ||
+        isAgentAuthorContext(proposal.baseContext)) {
+        const base = isAgentAuthorContext(proposal.baseContext)
+            ? proposal.baseContext
+            : currentContext;
+        return {
+            ...proposal,
+            baseContext: base,
+            baseFingerprint: proposal.baseFingerprint ?? operatorContextFingerprint(base),
+            appliedFingerprint: proposal.appliedFingerprint ?? operatorContextFingerprint(proposal.nextContext),
+            artifacts: proposal.artifacts ?? [],
+            affectedStageIds: proposal.affectedStageIds ?? [],
+        };
+    }
     const baseDraft = readDraftFromContext(proposal.baseContext ?? currentContext);
     const nextDraft = readDraftFromContext(proposal.nextContext);
     const baseContext = proposal.baseContext ??
@@ -132,11 +153,11 @@ export function enrichProposal(proposal, currentContext) {
 }
 /** True when the live draft no longer matches the post-apply fingerprint. */
 export function isMutationConflict(mutation, currentContext) {
-    const current = draftFingerprint(readDraftFromContext(currentContext));
+    const current = operatorContextFingerprint(currentContext);
     if (mutation.appliedFingerprint) {
         return mutation.appliedFingerprint !== current;
     }
-    const next = draftFingerprint(readDraftFromContext(mutation.nextContext));
+    const next = operatorContextFingerprint(mutation.nextContext);
     return next !== current;
 }
 export const UNDO_MUTATION_CONFLICT_NOTICE = UNDO_CONFLICT_NOTICE;

package/dist/package-meta.d.ts

@@ -1,3 +1,3 @@
 export declare const PACKAGE_NAME = "stageflow";
-export declare const PACKAGE_VERSION = "0.35.0";
+export declare const PACKAGE_VERSION = "0.39.0";
 export declare const BUILD_SHA: string;

package/dist/package-meta.js

@@ -1,3 +1,3 @@
 export const PACKAGE_NAME = "stageflow";
-export const PACKAGE_VERSION = "0.35.0";
+export const PACKAGE_VERSION = "0.39.0";
 export const BUILD_SHA = process.env.STAGEFLOW_BUILD_SHA ?? "unknown";

package/dist/preflight/channelChecks.d.ts

@@ -0,0 +1,17 @@
+import type { AnyChannelProvider } from "../channels/types.js";
+import type { LoadedPipeline } from "../types/pipeline.js";
+import type { PreflightItem } from "./pipelinePreflight.js";
+export type ChannelCheckOptions = {
+    projectRoot: string;
+    hostEnv?: NodeJS.ProcessEnv;
+    providers?: readonly AnyChannelProvider[];
+    /** Waits between attempts. Each entry allows one more retry. */
+    retryDelaysMs?: readonly number[];
+    attemptTimeoutMs?: number;
+};
+export declare const DEFAULT_CHANNEL_RETRY_DELAYS_MS: readonly [500, 1500];
+export declare const DEFAULT_CHANNEL_ATTEMPT_TIMEOUT_MS = 8000;
+/** Live check of every connection a pipeline's stages declare. Never sends a message. */
+export declare function checkStageChannels(loaded: LoadedPipeline, options: ChannelCheckOptions): Promise<PreflightItem[]>;
+/** One line naming each failed connection and why. Codes and plain reasons only, never a secret. */
+export declare function channelFailureSummary(checks: readonly PreflightItem[]): string | undefined;

package/dist/preflight/channelChecks.js

@@ -0,0 +1,106 @@
+import { ChannelError } from "../channels/errors.js";
+import { ChannelRegistry } from "../channels/registry.js";
+import { channelErrorReason } from "../channels/errorInfo.js";
+import { channelTarget } from "../channels/stageChannels.js";
+export const DEFAULT_CHANNEL_RETRY_DELAYS_MS = [500, 1500];
+export const DEFAULT_CHANNEL_ATTEMPT_TIMEOUT_MS = 8000;
+function failed(code, retryable) {
+    return { state: "failed", checkedAt: new Date().toISOString(), error: { code, retryable } };
+}
+async function attempt(run, timeoutMs) {
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise(resolve => {
+        timer = setTimeout(() => { controller.abort(); resolve(failed("CHANNEL_TIMEOUT", true)); }, timeoutMs);
+    });
+    try {
+        return await Promise.race([run(controller.signal), timeout]);
+    }
+    catch (error) {
+        return error instanceof ChannelError
+            ? failed(error.code, error.retryable)
+            : failed("CHANNEL_CONNECTION_FAILED", false);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Retries only failures the provider marked transient. Authentication, configuration,
+ * permission and target problems return at once so a bad setup is never slowed or hidden.
+ */
+async function withRetry(run, options) {
+    let result = await attempt(run, options.timeoutMs);
+    for (const delay of options.delays) {
+        if (result.state === "ok" || result.error?.retryable !== true)
+            break;
+        await new Promise(resolve => setTimeout(resolve, delay));
+        result = await attempt(run, options.timeoutMs);
+    }
+    return result;
+}
+function item(connection, health) {
+    if (health.state === "ok")
+        return { kind: "channel", status: "ok", connection };
+    const code = health.error?.code ?? "CHANNEL_CONNECTION_FAILED";
+    return {
+        kind: "channel", status: "channel_check_failed", connection, channelCode: code,
+        retryable: health.error?.retryable ?? false, message: `connection "${connection}": ${code}`,
+    };
+}
+/** Live check of every connection a pipeline's stages declare. Never sends a message. */
+export async function checkStageChannels(loaded, options) {
+    const targetsByConnection = new Map();
+    for (const stage of loaded.stages) {
+        for (const channel of stage.channels ?? []) {
+            const targets = targetsByConnection.get(channel.connection) ?? new Map();
+            targets.set(JSON.stringify(channelTarget(channel)), channelTarget(channel));
+            targetsByConnection.set(channel.connection, targets);
+        }
+    }
+    if (targetsByConnection.size === 0)
+        return [];
+    let registry;
+    try {
+        registry = new ChannelRegistry({ cwd: options.projectRoot, env: options.hostEnv, providers: options.providers });
+    }
+    catch (error) {
+        const code = error instanceof ChannelError ? error.code : "CHANNEL_INVALID_INPUT";
+        return [...targetsByConnection.keys()].map(connection => item(connection, failed(code, false)));
+    }
+    const retry = {
+        delays: options.retryDelaysMs ?? DEFAULT_CHANNEL_RETRY_DELAYS_MS,
+        timeoutMs: options.attemptTimeoutMs ?? DEFAULT_CHANNEL_ATTEMPT_TIMEOUT_MS,
+    };
+    return Promise.all([...targetsByConnection].map(async ([id, targets]) => {
+        let resolved;
+        let provider;
+        try {
+            provider = registry.providerFor(id);
+            resolved = registry.resolve(id);
+        }
+        catch (error) {
+            return item(id, error instanceof ChannelError ? failed(error.code, false) : failed("CHANNEL_CONNECTION_FAILED", false));
+        }
+        const health = await withRetry(signal => provider.check(resolved, signal), retry);
+        if (health.state !== "ok" || !provider.checkTargets)
+            return item(id, health);
+        const validated = [...targets.values()].map(target => provider.validateTarget(target));
+        if (validated.some(result => !result.ok))
+            return item(id, failed("CHANNEL_TARGET_INVALID", false));
+        const values = validated.flatMap(result => (result.ok ? [result.value] : []));
+        return item(id, await withRetry(signal => provider.checkTargets(resolved, values, signal), retry));
+    }));
+}
+/** One line naming each failed connection and why. Codes and plain reasons only, never a secret. */
+export function channelFailureSummary(checks) {
+    const failed = checks.filter(check => check.kind === "channel" && check.status === "channel_check_failed");
+    if (failed.length === 0)
+        return undefined;
+    return failed
+        .map(check => {
+        const code = check.channelCode ?? "CHANNEL_CONNECTION_FAILED";
+        return `${check.connection}: ${channelErrorReason(code)} (${code})`;
+    })
+        .join("; ");
+}

package/dist/preflight/pipelinePreflight.d.ts

@@ -1,10 +1,11 @@
 import type { LoadedPipeline } from "../types/pipeline.js";
 import { type ToolRequirement } from "../config/toolRequires.js";
+import { type ChannelCheckOptions } from "./channelChecks.js";
 import { type CheckToolchainOptions, type ToolchainCheckResult } from "./toolchain.js";
-export type PreflightCheckKind = "toolchain" | "secret" | "mcp";
+export type PreflightCheckKind = "toolchain" | "secret" | "mcp" | "channel";
 export type PreflightItem = {
     kind: PreflightCheckKind;
-    status: "ok" | "missing_tool" | "tool_version_mismatch" | "unknown_version" | "secret_unavailable" | "stage.unknown_secret" | "stage.denied_secret" | "unresolved_var" | "missing_catalog" | "unknown_server" | "invalid_config" | "untrusted_config_origin";
+    status: "ok" | "missing_tool" | "tool_version_mismatch" | "unknown_version" | "secret_unavailable" | "stage.unknown_secret" | "stage.denied_secret" | "unresolved_var" | "missing_catalog" | "unknown_server" | "invalid_config" | "untrusted_config_origin" | "channel_check_failed";
     tool?: string;
     required?: string;
     found?: string;
@@ -12,6 +13,11 @@ export type PreflightItem = {
     secret?: string;
     stageId?: string;
     server?: string;
+    /** Connection id for `kind: "channel"`. */
+    connection?: string;
+    /** Provider-neutral channel error code, such as CHANNEL_AUTH_FAILED. */
+    channelCode?: string;
+    retryable?: boolean;
     message?: string;
 };
 export type PipelinePreflightResult = {
@@ -33,6 +39,7 @@ export declare function runPipelinePreflight(loaded: LoadedPipeline, options: {
     strict?: boolean;
     /** start_run: unknown_version passes; missing/mismatch fail. */
     forStart?: boolean;
+    channels?: Pick<ChannelCheckOptions, "providers" | "retryDelaysMs" | "attemptTimeoutMs">;
 }): Promise<PipelinePreflightResult>;
 export declare function preflightFailureCode(result: PipelinePreflightResult, options?: {
     strict?: boolean;

package/dist/preflight/pipelinePreflight.js

@@ -2,6 +2,7 @@ import { collectEffectiveRequires, } from "../config/toolRequires.js";
 import { resolveStageMcpServers, StageMcpError, } from "../config/resolveStageMcpServers.js";
 import { assertSecretPresent, loadSecretRegistry, SecretUnavailableError, } from "../runtime/stageSecrets.js";
 import { isForeverDeniedSecret } from "../runtime/stageEnvironment.js";
+import { checkStageChannels } from "./channelChecks.js";
 import { checkToolchainRequirements, curatedStageEnv, } from "./toolchain.js";
 function toolchainItems(checks) {
     return checks.map((c) => ({
@@ -114,6 +115,7 @@ export async function checkStageMcpResolution(loaded, options) {
                 allowlist,
                 env: stageEnv,
                 stageId: stage.id,
+                scope: { kind: "stage", secrets: (stage.secrets ?? []).map((d) => d.name) },
             });
             for (const server of allowlist) {
                 items.push({
@@ -165,14 +167,21 @@ export async function runPipelinePreflight(loaded, options) {
         projectRoot: options.projectRoot,
         hostEnv,
     });
+    const channelChecks = await checkStageChannels(loaded, {
+        projectRoot: options.projectRoot,
+        hostEnv,
+        ...options.channels,
+    });
     const checks = [
         ...toolchainItems(toolchain.checks),
         ...secretChecks,
         ...mcpChecks,
+        ...channelChecks,
     ];
     const ok = toolchain.ok &&
         !secretChecks.some((c) => c.status !== "ok") &&
-        !mcpChecks.some((c) => c.status !== "ok");
+        !mcpChecks.some((c) => c.status !== "ok") &&
+        !channelChecks.some((c) => c.status !== "ok");
     return { ok, checks, requirements, toolchain };
 }
 export function preflightFailureCode(result, options = {}) {

package/dist/runstore/createStore.d.ts

@@ -40,3 +40,5 @@ export declare function createRunStoreWithConnection(config: RunStoreConfig): {
  */
 export declare function createRunStore(config: RunStoreConfig): RunStore;
 export type { RunStore };
+/** The SQLite connection behind a RunStore, when it has one (tests may inject a fake store). */
+export declare function sqliteConnectionFromStore(store: RunStore): Database.Database | undefined;

package/dist/runstore/createStore.js

@@ -89,3 +89,11 @@ export function createRunStoreWithConnection(config) {
 export function createRunStore(config) {
     return createRunStoreWithConnection(config).store;
 }
+/** The SQLite connection behind a RunStore, when it has one (tests may inject a fake store). */
+export function sqliteConnectionFromStore(store) {
+    const connection = store.connection;
+    if (connection !== null && typeof connection?.prepare === "function") {
+        return connection;
+    }
+    return undefined;
+}

package/dist/runstore/overviewSummary.d.ts

@@ -0,0 +1,56 @@
+import type { RunStatus } from "./port.js";
+export declare const OVERVIEW_RANGES: readonly ["24h", "7d", "30d"];
+export type OverviewRange = (typeof OVERVIEW_RANGES)[number];
+export declare function isOverviewRange(value: string): value is OverviewRange;
+export declare function overviewWindowMs(range: OverviewRange): number;
+/** One run, as much as the overview needs; no stages. */
+export type OverviewRunRow = {
+    run_id: string;
+    pipeline_id: string;
+    status: RunStatus;
+    created_at: string;
+    finished_at?: string;
+    cost_usd?: number;
+};
+export type OverviewTotals = {
+    runs: number;
+    succeeded: number;
+    failed: number;
+    cancelled: number;
+    in_flight: number;
+    /** succeeded + failed. Cancelled runs are neither a success nor a failure. */
+    finished: number;
+    success_rate: number | null;
+    cost_usd: number;
+};
+export type OverviewBucket = {
+    start: string;
+    succeeded: number;
+    failed: number;
+    cancelled: number;
+};
+export type OverviewPipeline = {
+    pipeline_id: string;
+    runs: number;
+    succeeded: number;
+    failed: number;
+    cancelled: number;
+    success_rate: number | null;
+    median_duration_ms: number | null;
+    cost_usd: number;
+    last_run_at: string;
+};
+export type OverviewSummary = {
+    range: OverviewRange;
+    generated_at: string;
+    since: string;
+    totals: OverviewTotals;
+    previous: OverviewTotals;
+    buckets: OverviewBucket[];
+    pipelines: OverviewPipeline[];
+};
+/**
+ * Rows must cover `[now - 2 * window, now]` by `created_at`; the older half feeds `previous`.
+ * Buckets are rolling segments ending at `now`, so they need no time zone.
+ */
+export declare function buildOverview(rows: readonly OverviewRunRow[], range: OverviewRange, now?: Date): OverviewSummary;