stageflow 0.35.0 → 0.36.0

package/dist/config/draftPackage.js

@@ -77,6 +77,8 @@ function pipelineDocument(pipeline) {
         doc.schemas = pipeline.schemas;
     if (pipeline.requires !== undefined)
         doc.requires = pipeline.requires;
+    if (pipeline.channels !== undefined)
+        doc.channels = pipeline.channels;
     return doc;
 }
 function resolveDirectory(projectRoot, directory) {
@@ -164,6 +166,7 @@ export async function validateDraftPackage(draft, options = {}) {
             ...(draft.pipeline.requires !== undefined
                 ? { requires: draft.pipeline.requires }
                 : {}),
+            ...(draft.pipeline.channels !== undefined ? { channels: draft.pipeline.channels } : {}),
         };
         const result = await loadPipelineValidated(inline, {
             cwd,
@@ -716,6 +719,7 @@ export async function loadDraftPackage(projectRoot, pipelineRelPath, options = {
             ...(raw.model !== undefined ? { model: raw.model } : {}),
             ...(raw.schemas !== undefined ? { schemas: raw.schemas } : {}),
             ...(raw.requires !== undefined ? { requires: raw.requires } : {}),
+            ...(raw.channels !== undefined ? { channels: raw.channels } : {}),
         },
         ...(stageArtifacts.length > 0 ? { stages: stageArtifacts } : {}),
     };

package/dist/config/hostConfig.js

@@ -18,6 +18,7 @@ export class HostConfigError extends Error {
 export const KNOWN_STAGEFLOW_ENV_KEYS = new Set([
     "STAGEFLOW_HOME",
     "STAGEFLOW_CREDENTIAL_HOME",
+    "STAGEFLOW_CONNECTIONS_FILE",
     "STAGEFLOW_BIND",
     "STAGEFLOW_ALLOW_UNAUTHENTICATED_BIND",
     "STAGEFLOW_ALLOWED_HOSTS",

package/dist/config/loadPipeline.js

@@ -1,3 +1,4 @@
+import { MAX_STAGE_CHANNELS, channelLimitMessage, mergeChannelDefaults, stageChannelLimit } from "../channels/stageChannels.js";
 import { access } from "node:fs/promises";
 import path from "node:path";
 import { compilePayloadSchema, expandPayloadSchemaRefs, isPayloadSchemaSubset, UnresolvedSchemaRefError, } from "../envelope/payloadSchema.js";
@@ -128,9 +129,25 @@ export async function loadPipelineFromObject(raw, options = {}) {
     }
     return outcome.value;
 }
+function applyPipelineChannels(stage, defaults, pipelineId) {
+    const channels = mergeChannelDefaults(defaults, stage.channels);
+    if (channels === undefined)
+        return loadSuccess(stage);
+    if (channels.length > Math.min(MAX_STAGE_CHANNELS, stageChannelLimit())) {
+        return loadFailure([
+            {
+                code: "stage.invalid_channels",
+                message: `Pipeline ${pipelineId}: stage "${stage.id}" ends up with ${channels.length} channels after merging pipeline defaults, but ${channelLimitMessage()}. Use \`channels: []\` on the stage to drop the pipeline default.`,
+                category: "stage",
+                stageId: stage.id,
+            },
+        ]);
+    }
+    return loadSuccess({ ...stage, channels });
+}
 async function buildLoadedPipelineFromMerge(merge, options) {
     const { projectRoot, requireIo, pipelinePath } = options;
-    const { entries: rawEntries, pipelineId, agent: pipelineAgent, model: pipelineModel, schemas: pipelineSchemas, requires: pipelineRequires, warnings: mergeWarnings, } = merge;
+    const { entries: rawEntries, pipelineId, agent: pipelineAgent, model: pipelineModel, schemas: pipelineSchemas, requires: pipelineRequires, channels: pipelineChannels, warnings: mergeWarnings, } = merge;
     const ctx = { pipelineId, path: pipelinePath };
     const warnings = [...mergeWarnings];
     const normalizeOutcome = normalizePipelineStageEntries(rawEntries, ctx);
@@ -199,7 +216,10 @@ async function buildLoadedPipelineFromMerge(merge, options) {
             if (inlineRequires.value !== undefined) {
                 stage = { ...stage, requires: inlineRequires.value };
             }
-            stages.push(stage);
+            const inlineChannels = applyPipelineChannels(stage, pipelineChannels, pipelineId);
+            if (!inlineChannels.ok)
+                return loadFailure(inlineChannels.issues);
+            stages.push(inlineChannels.value);
             stageSources[stageId] = { kind: "inline" };
             continue;
         }
@@ -259,8 +279,11 @@ async function buildLoadedPipelineFromMerge(merge, options) {
         if (!fileRequires.ok)
             return loadFailure(fileRequires.issues);
         stageRequires = fileRequires.value;
+        const withChannels = applyPipelineChannels(stageOutcome.value, pipelineChannels, pipelineId);
+        if (!withChannels.ok)
+            return loadFailure(withChannels.issues);
         const stage = {
-            ...stageOutcome.value,
+            ...withChannels.value,
             ...(browser !== undefined ? { browser } : {}),
             ...(entry.mcp !== undefined ? { mcp: entry.mcp } : {}),
             ...(entry.secrets !== undefined ? { secrets: entry.secrets } : {}),
@@ -315,6 +338,7 @@ async function buildLoadedPipelineFromMerge(merge, options) {
         ...(pipelineModel !== undefined ? { model: pipelineModel } : {}),
         ...(pipelineSchemas !== undefined ? { schemas: pipelineSchemas } : {}),
         ...(pipelineRequires !== undefined ? { requires: pipelineRequires } : {}),
+        ...(pipelineChannels !== undefined ? { channels: pipelineChannels } : {}),
     };
     const effectiveRequires = mergeToolRequires([pipelineRequires, ...loadedStages.map((s) => s.requires)], { pipelineId });
     if (!effectiveRequires.ok)

package/dist/config/loadStage.js

@@ -1,3 +1,4 @@
+import { parseChannels } from "../channels/stageChannels.js";
 import { parseAgentField } from "../agent/agentBackend.js";
 import { STAGEFLOW_MCP_SERVER_NAME } from "../agent/claudeTools.js";
 import { STAGE_GATE_KINDS, } from "../types/stage.js";
@@ -362,6 +363,20 @@ function parseStageFields(raw, label, entryId, deferSchemaRefs, requireIo, compi
     if (mcpOutcome.value !== undefined) {
         stage.mcp = mcpOutcome.value;
     }
+    if (raw.channels !== undefined) {
+        const channels = parseChannels(raw.channels);
+        if (!channels.ok) {
+            return loadFailure([
+                {
+                    code: "stage.invalid_channels",
+                    message: `Invalid stage ${label}: ${channels.message}`,
+                    category: "stage",
+                    stageId: entryId,
+                },
+            ]);
+        }
+        stage.channels = channels.value;
+    }
     const secretsOutcome = parseStageSecrets(raw.secrets, label, entryId);
     if (!secretsOutcome.ok)
         return secretsOutcome;

package/dist/config/mergePipelineIncludes.d.ts

@@ -2,6 +2,7 @@ import type { PayloadSchemaMap } from "../envelope/payloadSchema.js";
 import type { InlinePipelineDefinition } from "../types/pipeline.js";
 import { type LoadIssue, type LoadOutcome } from "./loadOutcome.js";
 import { type ToolRequirement } from "./toolRequires.js";
+import type { StageChannel } from "../types/stage.js";
 export type RawMergedEntry = {
     raw: unknown;
     declaringPath: string;
@@ -13,6 +14,7 @@ export declare function mergePipelineStages(rootPath: string): Promise<LoadOutco
     model?: string;
     schemas?: PayloadSchemaMap;
     requires?: ToolRequirement[];
+    channels?: StageChannel[];
     warnings: LoadIssue[];
 }>>;
 /** Synthetic `declaringPath` for stage entries with no backing file. */
@@ -24,5 +26,6 @@ export declare function mergeInlinePipelineStages(raw: InlinePipelineDefinition)
     model?: string;
     schemas?: PayloadSchemaMap;
     requires?: ToolRequirement[];
+    channels?: StageChannel[];
     warnings: LoadIssue[];
 }>>;

package/dist/config/mergePipelineIncludes.js

@@ -6,6 +6,7 @@ import { parseModelField } from "./modelField.js";
 import { readYamlObject } from "./readYamlObject.js";
 import { yamlParsePosition } from "./yamlParsePosition.js";
 import { parseToolRequires } from "./toolRequires.js";
+import { parseChannels } from "../channels/stageChannels.js";
 import { classifyYamlDocument, collectDocumentKeys, mixedDialectIssue, } from "./yamlDialect.js";
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -189,6 +190,10 @@ export async function mergePipelineStages(rootPath) {
     if (!requiresOutcome.ok)
         return requiresOutcome;
     const requires = requiresOutcome.value;
+    const channelsOutcome = parsePipelineChannels(raw.channels, `pipeline ${absRoot}`, pipelineId);
+    if (!channelsOutcome.ok)
+        return channelsOutcome;
+    const channels = channelsOutcome.value;
     const idLocations = new Map();
     const entries = [];
     const warnings = [];
@@ -211,6 +216,7 @@ export async function mergePipelineStages(rootPath) {
         ...(model !== undefined ? { model } : {}),
         ...(schemas !== undefined ? { schemas } : {}),
         ...(requires !== undefined ? { requires } : {}),
+        ...(channels !== undefined ? { channels } : {}),
         warnings,
     });
 }
@@ -273,6 +279,10 @@ export async function mergeInlinePipelineStages(raw) {
     if (!requiresOutcome.ok)
         return requiresOutcome;
     const requires = requiresOutcome.value;
+    const channelsOutcome = parsePipelineChannels(raw.channels, `inline pipeline ${pipelineId}`, pipelineId);
+    if (!channelsOutcome.ok)
+        return channelsOutcome;
+    const channels = channelsOutcome.value;
     const entries = [];
     for (let index = 0; index < raw.stages.length; index++) {
         const entry = raw.stages[index];
@@ -295,9 +305,26 @@ export async function mergeInlinePipelineStages(raw) {
         ...(model !== undefined ? { model } : {}),
         ...(schemas !== undefined ? { schemas } : {}),
         ...(requires !== undefined ? { requires } : {}),
+        ...(channels !== undefined ? { channels } : {}),
         warnings: [],
     });
 }
+function parsePipelineChannels(raw, label, pipelineId) {
+    if (raw === undefined)
+        return loadSuccess(undefined);
+    const parsed = parseChannels(raw);
+    if (!parsed.ok) {
+        return loadFailure([
+            {
+                code: "pipeline.invalid_channels",
+                message: `Invalid ${label}: ${parsed.message}`,
+                category: "pipeline",
+                pipelineId,
+            },
+        ]);
+    }
+    return loadSuccess(parsed.value);
+}
 function parsePipelineSchemas(raw, absPath, pipelineId) {
     if (raw === undefined)
         return loadSuccess(undefined);

package/dist/config/pipelineStageKeys.js

@@ -29,6 +29,7 @@ export const WIRING_KEYS = new Set([
 /** Stage body keys. Target: `io` / `verify`. IR/legacy: `payload_schema`, `pre_emit_checks`, `clone_input_schema`. */
 export const BODY_KEYS = new Set([
     "email",
+    "channels",
     "system_prompt",
     "model",
     "payload_schema",

package/dist/config/validateCatalog.d.ts

@@ -1,9 +1,10 @@
 import type { InlinePipelineDefinition, LoadedPipeline } from "../types/pipeline.js";
 import type { TriggerFile } from "../types/trigger.js";
 import type { LoadIssue } from "./loadOutcome.js";
+import type { AnyChannelProvider } from "../channels/types.js";
 export type ValidationSeverity = "error" | "warning";
 export type ValidationCategory = "pipeline" | "stage" | "catalog" | "task" | "trigger";
-export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.stage_wrapper_skill_rejected" | "pipeline.invalid_completion" | "catalog.path_case_mismatch" | "pipeline.invalid_recovery" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "pipeline.invalid_agent" | "pipeline.invalid_model" | "pipeline.invalid_verify" | "pipeline.io_incompatible" | "pipeline.model_applies" | "pipeline.route_if_invalid" | "pipeline.route_all_gated" | "pipeline.invalid_requires" | "pipeline.requires_conflict" | "stage.invalid_shape" | "stage.invalid_model" | "stage.missing_model" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.unresolved_schema_ref" | "stage.invalid_clone_actions" | "stage.invalid_gate_kinds" | "stage.invalid_pre_emit_checks" | "stage.invalid_timeout_ms" | "stage.invalid_skill" | "stage.invalid_mcp" | "stage.invalid_browser" | "stage.invalid_secrets" | "stage.unknown_secret" | "stage.denied_secret" | "stage.invalid_requires" | "stage.invalid_agent" | "stage.invalid_io" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "task.entry_input_unmet" | "task.binding_conflict" | "task.repository_ref_required" | "task.ref_without_repository" | "task.repository_invalid" | "trigger.invalid_shape" | "trigger.load_error" | "trigger.unknown_pipeline" | "trigger.unknown_task" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error" | "catalog.invalid_mcp" | "catalog.mcp_command_missing" | "catalog.mixed_yaml_dialect" | "catalog.legacy_yaml" | "catalog.stageflow_home_absolute_path";
+export type ValidationFindingCode = "pipeline.invalid_shape" | "pipeline.dag_error" | "pipeline.missing_stage" | "pipeline.load_error" | "pipeline.string_stage_ref" | "pipeline.stage_uses_inline_conflict" | "pipeline.stage_missing_body" | "pipeline.stage_id_mismatch" | "pipeline.stage_wrapper_skill_rejected" | "pipeline.invalid_completion" | "catalog.path_case_mismatch" | "pipeline.invalid_recovery" | "pipeline.include_cycle" | "pipeline.include_invalid" | "pipeline.include_duplicate_stage" | "pipeline.invalid_agent" | "pipeline.invalid_model" | "pipeline.invalid_verify" | "pipeline.io_incompatible" | "pipeline.model_applies" | "pipeline.route_if_invalid" | "pipeline.route_all_gated" | "pipeline.invalid_requires" | "pipeline.requires_conflict" | "pipeline.invalid_channels" | "stage.invalid_shape" | "stage.invalid_model" | "stage.missing_model" | "stage.invalid_payload_schema" | "stage.invalid_clone_input_schema" | "stage.unresolved_schema_ref" | "stage.invalid_clone_actions" | "stage.invalid_gate_kinds" | "stage.invalid_pre_emit_checks" | "stage.invalid_timeout_ms" | "stage.invalid_skill" | "stage.invalid_mcp" | "stage.invalid_channels" | "stage.channel_unavailable" | "stage.invalid_browser" | "stage.invalid_secrets" | "stage.unknown_secret" | "stage.denied_secret" | "stage.invalid_requires" | "stage.invalid_agent" | "stage.invalid_io" | "stage.load_error" | "stage.id_filename_mismatch" | "task.invalid_shape" | "task.load_error" | "task.entry_input_unmet" | "task.binding_conflict" | "task.repository_ref_required" | "task.ref_without_repository" | "task.repository_invalid" | "trigger.invalid_shape" | "trigger.load_error" | "trigger.unknown_pipeline" | "trigger.unknown_task" | "catalog.duplicate_pipeline_id" | "catalog.manifest_missing" | "catalog.manifest_invalid" | "catalog.empty_catalog" | "catalog.manifest_load_error" | "catalog.invalid_mcp" | "catalog.mcp_command_missing" | "catalog.mixed_yaml_dialect" | "catalog.legacy_yaml" | "catalog.stageflow_home_absolute_path";
 export type ValidationFinding = {
     severity: ValidationSeverity;
     code: ValidationFindingCode | string;
@@ -50,6 +51,7 @@ export type ValidatePipelineOptions = {
     projectRoot?: string;
     validateStages?: boolean;
     strict?: boolean;
+    channelProviders?: readonly AnyChannelProvider[];
 };
 export declare function validatePipeline(nameOrPath: string, options?: ValidatePipelineOptions): Promise<ValidationResult>;
 export type LoadPipelineValidatedResult = {
@@ -64,6 +66,7 @@ export declare function loadPipelineValidated(nameOrPath: string | InlinePipelin
     cwd?: string;
     projectRoot?: string;
     validateStages?: boolean;
+    channelProviders?: readonly AnyChannelProvider[];
 }): Promise<LoadPipelineValidatedResult>;
 export declare function collectPipelineIdsFromPaths(pipelinePaths: string[]): Promise<Map<string, string[]>>;
 export declare function collectTaskIdsFromPaths(taskPaths: string[]): Promise<Set<string>>;

package/dist/config/validateCatalog.js

@@ -14,6 +14,9 @@ import { MCP_CATALOG_FILENAME, StageMcpError, assertMcpAllowlistKnown, loadMcpCa
 import { loadSecretRegistry } from "../runtime/stageSecrets.js";
 import { isForeverDeniedSecret } from "../runtime/stageEnvironment.js";
 import { findMissingMcpCommands } from "../preflight/mcpCommands.js";
+import { ChannelError } from "../channels/errors.js";
+import { ChannelRegistry } from "../channels/registry.js";
+import { validateStageChannels } from "../channels/stageChannels.js";
 export function relPath(cwd, absPath) {
     return path.relative(cwd, absPath).replace(/\\/g, "/");
 }
@@ -256,6 +259,23 @@ function collectMcpAllowlistNames(loaded) {
     }
     return [...names];
 }
+function findingsForStageChannels(cwd, pipelinePath, loaded, projectRoot, providers) {
+    const users = loaded.stages.filter((stage) => (stage.channels?.length ?? 0) > 0);
+    if (users.length === 0)
+        return [];
+    let registry;
+    try {
+        registry = new ChannelRegistry({ cwd: projectRoot, providers });
+    }
+    catch (error) {
+        const code = error instanceof ChannelError ? error.code : "CHANNEL_INVALID_INPUT";
+        const field = error instanceof ChannelError && error.detail?.connectionId
+            ? ` (connection "${error.detail.connectionId}"${error.detail.field ? `, field "${error.detail.field}"` : ""})`
+            : "";
+        return users.map((stage) => findingStageError(cwd, pipelinePath, `connections.yaml could not be loaded: ${code}${field}`, "stage.channel_unavailable", stage.id));
+    }
+    return users.flatMap((stage) => validateStageChannels(registry, stage).map((issue) => findingStageError(cwd, pipelinePath, issue.message, "stage.channel_unavailable", issue.stageId)));
+}
 function findingsForStageSecrets(cwd, pipelinePath, loaded) {
     const registry = loadSecretRegistry(process.env);
     const findings = [];
@@ -438,6 +458,7 @@ async function runPipelineValidation(nameOrPath, options) {
     }
     findings.push(...(await findingsForStageMcpCatalog(cwd, outcome.value)));
     findings.push(...findingsForStageSecrets(cwd, pipelinePath, outcome.value));
+    findings.push(...findingsForStageChannels(cwd, pipelinePath, outcome.value, projectRoot, options.channelProviders));
     findings.push(...findingsForStageflowHomeAbsolutePaths(cwd, outcome.value));
     if (validateStages && outcome.value.stageSources) {
         for (const source of Object.values(outcome.value.stageSources)) {
@@ -461,6 +482,7 @@ export async function validatePipeline(nameOrPath, options = {}) {
         cwd,
         projectRoot,
         validateStages,
+        channelProviders: options.channelProviders,
     });
     return buildValidationResult("pipeline", core.findings, strict);
 }
@@ -472,6 +494,7 @@ export async function loadPipelineValidated(nameOrPath, options = {}) {
         cwd,
         projectRoot,
         validateStages,
+        channelProviders: options.channelProviders,
     });
     if (core.ok) {
         return { ok: true, loaded: core.loaded, findings: core.findings };

package/dist/errors/codes.d.ts

@@ -4,7 +4,7 @@ export declare const BUSY_CHECKOUT: "busy_checkout";
 /** Per-caller concurrency quota: queued when under global capacity; reject when queue full. */
 export declare const BUSY_CALLER_QUOTA: "busy_caller_quota";
 export declare const ABORTED: "aborted";
-export declare const NETWORK_ERROR_CODES: readonly ["busy_capacity", "busy_checkout", "busy_caller_quota", "aborted", "unknown_project_root", "absolute_path_not_allowed", "path_outside_project_root", "catalog_root_unreadable", "ensure_project_not_allowed", "config_invalid", "config_unknown_key", "provider_not_configured", "a2a_configuration_error", "untrusted_config_origin", "command_not_on_path", "missing_tool", "tool_version_mismatch", "unknown_version", "secret_unavailable", "not_ready", "internal_error", "retry_in_progress", "hitl_not_retriable", "run_not_retryable", "stage_not_failed", "manual_recovery_required", "run_not_found", "stage_not_found", "artifact_not_found", "artifact_path_denied", "envelope_not_found", "insufficient_disk", "disk_check_failed", "shutting_down", "start.token_rejected", "inline_pipeline_too_large", "skills_invalid_name", "skills_invalid_path", "skills_missing_skill_md", "skills_payload_too_large", "pinned_sha_unavailable", "store_integrity_failed", "store_unsupported_filesystem", "tmpdir_unusable", "backup_insufficient_disk"];
+export declare const NETWORK_ERROR_CODES: readonly ["busy_capacity", "busy_checkout", "busy_caller_quota", "aborted", "unknown_project_root", "absolute_path_not_allowed", "path_outside_project_root", "catalog_root_unreadable", "ensure_project_not_allowed", "config_invalid", "config_unknown_key", "provider_not_configured", "a2a_configuration_error", "untrusted_config_origin", "command_not_on_path", "missing_tool", "tool_version_mismatch", "unknown_version", "secret_unavailable", "channel_check_failed", "not_ready", "internal_error", "retry_in_progress", "hitl_not_retriable", "run_not_retryable", "stage_not_failed", "manual_recovery_required", "run_not_found", "stage_not_found", "artifact_not_found", "artifact_path_denied", "envelope_not_found", "insufficient_disk", "disk_check_failed", "shutting_down", "start.token_rejected", "inline_pipeline_too_large", "skills_invalid_name", "skills_invalid_path", "skills_missing_skill_md", "skills_payload_too_large", "pinned_sha_unavailable", "store_integrity_failed", "store_unsupported_filesystem", "tmpdir_unusable", "backup_insufficient_disk"];
 export type NetworkErrorCode = (typeof NETWORK_ERROR_CODES)[number] | string;
 export type NetworkErrorBody = {
     code: NetworkErrorCode;

package/dist/errors/codes.js

@@ -24,6 +24,7 @@ export const NETWORK_ERROR_CODES = [
     "tool_version_mismatch",
     "unknown_version",
     "secret_unavailable",
+    "channel_check_failed",
     "not_ready",
     "internal_error",
     "retry_in_progress",

package/dist/mcp/catalogTools.js

@@ -63,6 +63,7 @@ const inlinePipelineSchema = z
     model: z.unknown().optional(),
     schemas: z.unknown().optional(),
     requires: z.unknown().optional(),
+    channels: z.unknown().optional(),
 })
     .strict();
 const startRunSchema = z

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.36.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.36.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) => ({
@@ -165,14 +166,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/runtime/pipelineRunner.js

@@ -13,6 +13,7 @@ import { checkTaskEntryInput } from "./taskInput.js";
 import { pipelinePersistenceForStart } from "./startPayload.js";
 import { materializeRunSkills, } from "./runSkills.js";
 import { preflightFailureCode, runPipelinePreflight, } from "../preflight/pipelinePreflight.js";
+import { channelFailureSummary } from "../preflight/channelChecks.js";
 import { networkError } from "../errors/codes.js";
 import { newRunId } from "../runstore/paths.js";
 import { bindingFromFields, buildInitialRunManifest, collectDeclaredSecretValues, finaliseStoredRunManifest, } from "../runstore/runManifest.js";
@@ -24,7 +25,8 @@ export class PipelinePreflightError extends Error {
     code;
     preflight;
     constructor(code, preflight) {
-        super(`Pipeline preflight failed: ${code}`);
+        const detail = code === "channel_check_failed" ? channelFailureSummary(preflight.checks) : undefined;
+        super(`Pipeline preflight failed: ${code}${detail ? `: ${detail}` : ""}`);
         this.name = "PipelinePreflightError";
         this.code = code;
         this.preflight = preflight;

package/dist/runtime/repositoryMaterialize.d.ts

@@ -1,7 +1,7 @@
 import type { RunMeta, RunStore } from "../runstore/port.js";
 import type { TaskFile } from "../types/task.js";
 import type { WorkspaceBinding } from "./workspaceBinding.js";
-export type StartFailureCode = "busy_capacity" | "busy_checkout" | "busy_caller_quota" | "repository_auth_failed" | "repository_not_found" | "ref_not_found" | "repository_fetch_failed" | "worktree_create_failed" | "git_missing" | "insufficient_disk" | "disk_check_failed" | "pinned_sha_unavailable" | "invalid_run_branch" | "task.binding_conflict" | "task.repository_ref_required" | "task.ref_without_repository" | "task.repository_invalid" | "task.invalid_shape" | "task.load_error" | "trigger.task_override_not_allowed" | "trigger.task_required" | "start.token_rejected" | "inline_pipeline_too_large" | "skills_invalid_name" | "skills_invalid_path" | "skills_missing_skill_md" | "skills_payload_too_large" | "missing_tool" | "tool_version_mismatch" | "unknown_version" | "secret_unavailable" | "unresolved_var" | "shutting_down" | "autostart_disabled" | "ensure_project_not_allowed" | "claude_as_root";
+export type StartFailureCode = "busy_capacity" | "busy_checkout" | "busy_caller_quota" | "repository_auth_failed" | "repository_not_found" | "ref_not_found" | "repository_fetch_failed" | "worktree_create_failed" | "git_missing" | "insufficient_disk" | "disk_check_failed" | "pinned_sha_unavailable" | "invalid_run_branch" | "task.binding_conflict" | "task.repository_ref_required" | "task.ref_without_repository" | "task.repository_invalid" | "task.invalid_shape" | "task.load_error" | "trigger.task_override_not_allowed" | "trigger.task_required" | "start.token_rejected" | "inline_pipeline_too_large" | "skills_invalid_name" | "skills_invalid_path" | "skills_missing_skill_md" | "skills_payload_too_large" | "missing_tool" | "tool_version_mismatch" | "unknown_version" | "secret_unavailable" | "channel_check_failed" | "unresolved_var" | "shutting_down" | "autostart_disabled" | "ensure_project_not_allowed" | "claude_as_root";
 export type MaterializedBinding = {
     runId: string;
     checkoutRoot?: string;

package/dist/runtime/runManager.js

@@ -41,6 +41,7 @@ import { getContainerLimits } from "./containerLimits.js";
 import { stageflowCacheRoot } from "./stageCacheEnv.js";
 import { assertClaudeNotRoot, ClaudeRootError } from "../preflight/claudeRoot.js";
 import { preflightFailureCode, runPipelinePreflight, } from "../preflight/pipelinePreflight.js";
+import { channelFailureSummary } from "../preflight/channelChecks.js";
 import { asAgentBackendId } from "../agent/agentBackend.js";
 import { INVALID_SLOT_COUNT_MESSAGE, parseSlotCount, readMaxConcurrentFromGlobal, writeMaxConcurrentToGlobal, } from "./settingsFile.js";
 import { StageHitlController, waitKey, } from "./stageHitl.js";
@@ -2331,7 +2332,9 @@ export class RunManager {
                     "missing_tool";
                 return {
                     ok: false,
-                    reason: `Pipeline preflight failed: ${code}`,
+                    reason: `Pipeline preflight failed: ${code}${code === "channel_check_failed" && channelFailureSummary(preflight.checks)
+                        ? `: ${channelFailureSummary(preflight.checks)}`
+                        : ""}`,
                     status: 400,
                     code,
                 };

package/dist/runtime/stageAttemptBootstrap.js

@@ -1,4 +1,6 @@
 import { emailHostFor, stageEmail, workerStageEmail, validateStageEmailAccounts } from "../email/host.js";
+import { ChannelError } from "../channels/errors.js";
+import { channelHostFor, stageChannels, validateStageChannelConnections, workerStageChannels } from "../channels/host.js";
 import { EmailError } from "../email/port.js";
 import { bindingKindForOrigin, catalogOrSeededOrigin, decideWorkspaceConfigTrust, } from "../config/configOrigin.js";
 import { loginCheckPromptBlock, readStageLoginCheck, } from "../browser/loginCheck.js";
@@ -450,6 +452,16 @@ export async function openStageAttempt(input) {
             throw error;
         }
     }
+    if (process.env.SF_STAGE_WORKER !== "1" && input.stage.channels?.length) {
+        try {
+            validateStageChannelConnections(channelHostFor(input.factoryCwd ?? process.cwd()), input.stage);
+        }
+        catch (error) {
+            if (error instanceof ChannelError)
+                return { ok: false, reason: error.code };
+            throw error;
+        }
+    }
     const opened = await openStageWithOperatorCatalog(input.agent, {
         roots,
         stage: input.stage,
@@ -465,6 +477,10 @@ export async function openStageAttempt(input) {
         resumeToken,
         email: input.stage.email?.length ? (process.env.SF_STAGE_WORKER === "1" ? workerStageEmail()
             : stageEmail(emailHostFor(input.factoryCwd ?? process.cwd()).mailbox, input.stage, input.runId, { workspaceDir: input.workspaceDir, attempt })) : undefined,
+        ...(input.stage.channels?.length ? {
+            channels: process.env.SF_STAGE_WORKER === "1" ? workerStageChannels()
+                : stageChannels(channelHostFor(input.factoryCwd ?? process.cwd()), input.stage, input.runId),
+        } : {}),
         ...(input.sessionMode !== undefined ? { sessionMode: input.sessionMode } : {}),
         onActivity: (event) => {
             input.onActivity?.(input.stage.browser !== undefined