stageflow 0.35.0 → 0.36.0

package/dist/channels/service.d.ts

@@ -0,0 +1,54 @@
+import { type ChannelErrorCode } from "./errors.js";
+import { type ChannelHealthOptions } from "./health.js";
+import type { ConnectionHealth, ConnectionSummary, ProviderMeta } from "./types.js";
+export type ChannelListing = {
+    connections: Array<ConnectionSummary & {
+        health?: ConnectionHealth;
+    }>;
+    /** Set when `connections.yaml` could not be loaded. The file's content is never included. */
+    error?: ChannelErrorCode;
+    limits: {
+        channelsPerStage: number;
+    };
+};
+export type ChannelMeta = {
+    providers: Array<ProviderMeta & {
+        id: string;
+    }>;
+    errors: Record<string, {
+        reason: string;
+        hint?: string;
+    }>;
+};
+export type ChannelService = {
+    /** What the console shows about each provider and each error code. Static; needs no secrets. */
+    meta(): ChannelMeta;
+    list(): ChannelListing;
+    /** Runs one live check now. Returns undefined when the connection is unknown or disabled. */
+    checkNow(id: string): Promise<ConnectionHealth | undefined>;
+    /** Checks entered values without saving anything. */
+    test(input: unknown): Promise<ConnectionHealth>;
+    /** Static check of a pinned recipient for a connection. No network, no secret read. */
+    validateTarget(id: string, input: unknown): {
+        ok: true;
+    } | {
+        ok: false;
+        issues: string[];
+    };
+    create(input: unknown): Promise<{
+        id: string;
+        health: ConnectionHealth;
+    }>;
+    update(id: string, input: unknown): Promise<{
+        health?: ConnectionHealth;
+    }>;
+    remove(id: string): Promise<void>;
+    stop(): Promise<void>;
+};
+/**
+ * Host-side read and edit model for the Connections page. A `connections.yaml` that fails to load
+ * does not stop the host: the listing reports the error code and stages that use channels fail on
+ * their own, while every other stage is unaffected. Edits keep secrets out of the YAML: each value
+ * goes to the secret store and the file gets a `store:NAME` reference.
+ */
+export declare function startChannelService(cwd: string, options?: Pick<ChannelHealthOptions, "intervalMs" | "timeoutMs">): ChannelService;

package/dist/channels/service.js

@@ -0,0 +1,307 @@
+import { z } from "zod";
+import { parseConnectionsYaml } from "./config.js";
+import { addConnectionYaml, removeConnectionYaml, toYamlEntry, updateConnectionYaml } from "./configWriter.js";
+import { ConnectionEdits } from "./connectionEdits.js";
+import { CHANNEL_ERROR_INFO } from "./errorInfo.js";
+import { ChannelError } from "./errors.js";
+import { channelProviders } from "./providers.js";
+import { ChannelHealthMonitor } from "./health.js";
+import { channelHostFor, releaseChannelHost, reloadChannelHosts } from "./host.js";
+import { ChannelRegistry, connectionsFilePath, defaultSecretStore, sealed } from "./registry.js";
+import { STORE_NAME_PATTERN } from "./secretStore.js";
+import { stageChannelLimit } from "./stageChannels.js";
+const idSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/);
+const fieldSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,63}$/);
+const valueSchema = z.string().min(1).max(8192).regex(/^[^\r\n\0]+$/);
+const secretsInput = z.record(fieldSchema, valueSchema);
+const createSchema = z.object({
+    provider: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/),
+    id: idSchema.optional(),
+    displayName: z.string().min(1).max(200).optional(),
+    config: z.record(z.string(), z.unknown()).default({}),
+    secrets: secretsInput.default({}),
+    credential: z.union([idSchema, z.object({ id: idSchema.optional(), secrets: secretsInput })]).optional(),
+}).strict();
+const targetText = z.union([z.string().min(1).max(500), z.number().int()]);
+const targetSchema = z.object({
+    to: z.union([targetText, z.array(targetText).min(1).max(20)]),
+    cc: z.array(targetText).min(1).max(20).optional(),
+    template: z.record(z.string(), z.unknown()).optional(),
+}).strict().transform(value => ({
+    ...value,
+    to: Array.isArray(value.to) ? value.to.map(String) : String(value.to),
+    ...(value.cc ? { cc: value.cc.map(String) } : {}),
+}));
+const updateSchema = z.object({
+    displayName: z.string().max(200).nullable().optional(),
+    enabled: z.boolean().optional(),
+    config: z.record(z.string(), z.unknown()).optional(),
+    secrets: secretsInput.optional(),
+}).strict();
+const limits = () => ({ channelsPerStage: stageChannelLimit() });
+const invalid = (field) => new ChannelError("CHANNEL_INVALID_INPUT", false, field ? { field } : undefined);
+/**
+ * Host-side read and edit model for the Connections page. A `connections.yaml` that fails to load
+ * does not stop the host: the listing reports the error code and stages that use channels fail on
+ * their own, while every other stage is unaffected. Edits keep secrets out of the YAML: each value
+ * goes to the secret store and the file gets a `store:NAME` reference.
+ */
+export function startChannelService(cwd, options = {}) {
+    const file = () => connectionsFilePath(cwd);
+    const store = defaultSecretStore();
+    let host;
+    let monitor;
+    let error;
+    let chain = Promise.resolve();
+    const serialized = (work) => {
+        const next = chain.then(work, work);
+        chain = next.catch(() => undefined);
+        return next;
+    };
+    const startMonitor = () => {
+        monitor = host ? new ChannelHealthMonitor({ registry: host.registry, intervalMs: options.intervalMs, timeoutMs: options.timeoutMs }) : undefined;
+        monitor?.start();
+    };
+    const load = () => {
+        error = undefined;
+        try {
+            host = channelHostFor(cwd);
+        }
+        catch (caught) {
+            host = undefined;
+            error = caught instanceof ChannelError ? caught.code : "CHANNEL_INVALID_INPUT";
+        }
+        startMonitor();
+    };
+    const reload = async () => {
+        await monitor?.stop();
+        reloadChannelHosts();
+        if (host) {
+            try {
+                host.reload();
+            }
+            catch (caught) {
+                error = caught instanceof ChannelError ? caught.code : "CHANNEL_INVALID_INPUT";
+                monitor = undefined;
+                return;
+            }
+            error = undefined;
+            startMonitor();
+        }
+        else {
+            load();
+        }
+    };
+    load();
+    const requireHost = () => {
+        if (!host)
+            throw new ChannelError(error ?? "CHANNEL_STORAGE_FAILED");
+        return host;
+    };
+    /** Validates the edit against the real provider rules before anything is written. */
+    const validate = (text) => {
+        const parsed = parseConnectionsYaml(text);
+        new ChannelRegistry({ cwd, parsed, secretStore: store, providers: requireHost().registry.providerList() });
+    };
+    const edits = new ConnectionEdits({ file, store, validate });
+    const uniqueId = (base, taken) => {
+        if (!taken(base))
+            return base;
+        for (let n = 2; n < 1000; n++)
+            if (!taken(`${base}-${n}`))
+                return `${base}-${n}`;
+        throw invalid("id");
+    };
+    const secretRefs = (prefix, secrets) => {
+        const refs = {};
+        for (const field of Object.keys(secrets)) {
+            const name = `${prefix}.${field}`;
+            if (!STORE_NAME_PATTERN.test(name))
+                throw invalid(field);
+            refs[field] = `store:${name}`;
+        }
+        return refs;
+    };
+    const draft = (input, id) => {
+        const registry = requireHost().registry;
+        const provider = registry.providerById(input.provider);
+        const config = provider.validateConfig(input.config);
+        if (!config.ok)
+            throw invalid("config");
+        const allowed = new Set([...provider.secrets.required, ...(provider.secrets.optional ?? [])]);
+        for (const field of Object.keys(input.secrets))
+            if (!allowed.has(field))
+                throw invalid(field);
+        for (const field of provider.secrets.required)
+            if (!(field in input.secrets))
+                throw invalid(field);
+        let credential;
+        if (provider.credentialProvider) {
+            if (typeof input.credential === "string")
+                credential = registry.resolveCredential(input.credential);
+            else if (input.credential)
+                credential = { id: input.credential.id ?? "draft", provider: provider.credentialProvider, secrets: input.credential.secrets };
+            else
+                throw invalid("credential");
+        }
+        else if (input.credential) {
+            throw invalid("credential");
+        }
+        return sealed({
+            id, scope: registry.scope, provider: input.provider, displayName: input.displayName ?? id,
+            config: config.value, secrets: input.secrets, ...(credential ? { credential } : {}),
+        });
+    };
+    const parseCreate = (input) => {
+        const parsed = createSchema.safeParse(input);
+        if (!parsed.success)
+            throw invalid();
+        return parsed.data;
+    };
+    return {
+        meta() {
+            const providers = host ? host.registry.providerList() : channelProviders();
+            return {
+                providers: providers.map(provider => ({ id: provider.id, ...provider.meta })),
+                errors: Object.fromEntries(Object.entries(CHANNEL_ERROR_INFO).map(([code, info]) => [code, { reason: info.reason, ...(info.hint ? { hint: info.hint } : {}) }])),
+            };
+        },
+        list() {
+            if (!host)
+                return { connections: [], ...(error ? { error } : {}), limits: limits() };
+            const health = monitor?.snapshot() ?? {};
+            return {
+                connections: host.registry.list().map(summary => ({ ...summary, ...(health[summary.id] ? { health: health[summary.id] } : {}) })),
+                ...(error ? { error } : {}),
+                limits: limits(),
+            };
+        },
+        async checkNow(id) {
+            if (!host || !monitor)
+                return undefined;
+            try {
+                host.registry.get(id);
+            }
+            catch {
+                return undefined;
+            }
+            return monitor.checkNow(id);
+        },
+        validateTarget(id, input) {
+            const parsed = targetSchema.safeParse(input);
+            if (!parsed.success)
+                return { ok: false, issues: ["target"] };
+            const provider = requireHost().registry.providerFor(id);
+            const result = provider.validateTarget(parsed.data);
+            return result.ok ? { ok: true } : { ok: false, issues: result.issues };
+        },
+        async test(input) {
+            const parsed = parseCreate(input);
+            const connection = draft(parsed, parsed.id ?? "draft");
+            const provider = requireHost().registry.providerById(parsed.provider);
+            const checkedAt = new Date().toISOString();
+            try {
+                return await provider.check(connection, AbortSignal.timeout(10000));
+            }
+            catch (caught) {
+                const failure = caught instanceof ChannelError ? caught : new ChannelError("CHANNEL_CONNECTION_FAILED", true);
+                return { state: "failed", checkedAt, error: { code: failure.code, retryable: failure.retryable } };
+            }
+        },
+        create(input) {
+            return serialized(async () => {
+                const parsed = parseCreate(input);
+                const registry = requireHost().registry;
+                const provider = registry.providerById(parsed.provider);
+                const id = parsed.id ?? uniqueId(parsed.provider, candidate => registry.hasConnection(candidate));
+                if (registry.hasConnection(id))
+                    throw new ChannelError("CHANNEL_OPERATION_CONFLICT", false, { connectionId: id });
+                draft(parsed, id);
+                const secrets = {};
+                let credentialYaml;
+                let credentialId;
+                if (provider.credentialProvider) {
+                    if (typeof parsed.credential === "string") {
+                        credentialId = parsed.credential;
+                    }
+                    else if (parsed.credential) {
+                        credentialId = parsed.credential.id ?? uniqueId(`${provider.credentialProvider}-main`, candidate => registry.hasCredential(candidate));
+                        credentialYaml = { id: credentialId, provider: provider.credentialProvider, secrets: secretRefs(`credential.${credentialId}`, parsed.credential.secrets) };
+                        for (const [field, value] of Object.entries(parsed.credential.secrets))
+                            secrets[`credential.${credentialId}.${field}`] = value;
+                    }
+                }
+                const refs = secretRefs(`connection.${id}`, parsed.secrets);
+                for (const [field, value] of Object.entries(parsed.secrets))
+                    secrets[`connection.${id}.${field}`] = value;
+                const entry = toYamlEntry({
+                    id, provider: parsed.provider, enabled: true, config: parsed.config, secrets: refs,
+                    ...(parsed.displayName ? { displayName: parsed.displayName } : {}),
+                    ...(credentialId ? { credential: credentialId } : {}),
+                });
+                edits.apply({ secrets, rewrite: text => ({ text: addConnectionYaml(text, entry, credentialYaml) }) });
+                await reload();
+                const health = (await this.checkNow(id)) ?? { state: "failed", checkedAt: new Date().toISOString(), error: { code: "CHANNEL_CONNECTION_FAILED", retryable: true } };
+                return { id, health };
+            });
+        },
+        update(id, input) {
+            return serialized(async () => {
+                const parsed = updateSchema.safeParse(input);
+                if (!parsed.success)
+                    throw invalid();
+                const registry = requireHost().registry;
+                const current = registry.get(id, false);
+                const provider = registry.providerById(current.provider);
+                const patch = {};
+                if (parsed.data.displayName !== undefined)
+                    patch.displayName = parsed.data.displayName;
+                if (parsed.data.enabled !== undefined)
+                    patch.enabled = parsed.data.enabled;
+                if (parsed.data.config !== undefined) {
+                    const config = provider.validateConfig(parsed.data.config);
+                    if (!config.ok)
+                        throw invalid("config");
+                    patch.config = parsed.data.config;
+                }
+                const allowed = new Set([...provider.secrets.required, ...(provider.secrets.optional ?? [])]);
+                const secrets = parsed.data.secrets ?? {};
+                for (const field of Object.keys(secrets))
+                    if (!allowed.has(field))
+                        throw invalid(field);
+                const refs = secretRefs(`connection.${id}`, secrets);
+                if (Object.keys(refs).length)
+                    patch.secrets = refs;
+                edits.apply({
+                    secrets: Object.fromEntries(Object.entries(secrets).map(([field, value]) => [`connection.${id}.${field}`, value])),
+                    rewrite: text => ({ text: updateConnectionYaml(text, id, patch) }),
+                });
+                await reload();
+                const enabled = parsed.data.enabled ?? current.enabled;
+                return enabled ? { health: await this.checkNow(id) } : {};
+            });
+        },
+        remove(id) {
+            return serialized(async () => {
+                requireHost().registry.get(id, false);
+                edits.apply({
+                    rewrite: text => {
+                        const removed = removeConnectionYaml(text, id);
+                        return {
+                            text: removed.text,
+                            dropSecretPrefixes: [`connection.${id}.`, ...(removed.removedCredential ? [`credential.${removed.removedCredential}.`] : [])],
+                        };
+                    },
+                });
+                await reload();
+            });
+        },
+        stop() {
+            return serialized(async () => {
+                await monitor?.stop();
+                if (host)
+                    await releaseChannelHost(cwd);
+            });
+        },
+    };
+}

package/dist/channels/stageChannels.d.ts

@@ -0,0 +1,45 @@
+import type { StageChannel, StageConfig } from "../types/stage.js";
+import { type ChannelErrorCode } from "./errors.js";
+import type { ChannelRegistry } from "./registry.js";
+export declare const MAX_STAGE_CHANNELS = 20;
+/**
+ * Policy, not capability: how many channels one stage may use. Everything below (merge by alias,
+ * picking by name, the per-channel ledger key) still handles several, so raising this one number
+ * is all it takes to enable them. It is enforced where a stage is parsed, merged, validated and
+ * at the moment of sending, so no single entry point can bypass it.
+ */
+export declare const MAX_CHANNELS_PER_STAGE = 1;
+export declare function stageChannelLimit(): number;
+/** Tests that exercise multi-channel behavior raise the policy for their own duration. */
+export declare function setStageChannelLimitForTests(limit: number): () => void;
+export declare function channelLimitMessage(count?: number): string;
+export declare const MAX_CHANNEL_TARGETS = 20;
+export type ParsedChannels = {
+    ok: true;
+    value: StageChannel[];
+} | {
+    ok: false;
+    message: string;
+};
+export declare function channelKey(channel: Pick<StageChannel, "alias" | "connection">): string;
+/** Shape check only. Whether the connection exists is checked against `connections.yaml` later. */
+export declare function parseChannels(raw: unknown): ParsedChannels;
+/**
+ * Pipeline `channels` are defaults. A stage that declares its own list merges by alias (or
+ * connection id when there is no alias) with the stage entry winning. An explicit empty
+ * list clears every inherited entry.
+ */
+export declare function mergeChannelDefaults(defaults: readonly StageChannel[] | undefined, own: readonly StageChannel[] | undefined): StageChannel[] | undefined;
+export type StageChannelIssue = {
+    stageId: string;
+    key: string;
+    code: ChannelErrorCode;
+    message: string;
+};
+export declare function channelTarget(channel: StageChannel): {
+    to: string | string[];
+    cc?: string[];
+    template?: Record<string, unknown>;
+};
+/** Static checks against `connections.yaml`. No network and no secret reads. */
+export declare function validateStageChannels(registry: ChannelRegistry, stage: Pick<StageConfig, "id" | "channels">): StageChannelIssue[];

package/dist/channels/stageChannels.js

@@ -0,0 +1,110 @@
+import { z } from "zod";
+import { ChannelError } from "./errors.js";
+export const MAX_STAGE_CHANNELS = 20;
+/**
+ * Policy, not capability: how many channels one stage may use. Everything below (merge by alias,
+ * picking by name, the per-channel ledger key) still handles several, so raising this one number
+ * is all it takes to enable them. It is enforced where a stage is parsed, merged, validated and
+ * at the moment of sending, so no single entry point can bypass it.
+ */
+export const MAX_CHANNELS_PER_STAGE = 1;
+let channelLimit = MAX_CHANNELS_PER_STAGE;
+export function stageChannelLimit() {
+    return channelLimit;
+}
+/** Tests that exercise multi-channel behavior raise the policy for their own duration. */
+export function setStageChannelLimitForTests(limit) {
+    const previous = channelLimit;
+    channelLimit = limit;
+    return () => { channelLimit = previous; };
+}
+export function channelLimitMessage(count) {
+    const limit = channelLimit;
+    return `a stage can use ${limit === 1 ? "one channel" : `at most ${limit} channels`} for now${count === undefined ? "" : ` (this one has ${count})`}; split the work into separate stages`;
+}
+export const MAX_CHANNEL_TARGETS = 20;
+const targetSchema = z.union([z.string().min(1).max(500), z.number().int().refine(Number.isSafeInteger).transform(String)]);
+const channelSchema = z.object({
+    alias: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/).optional(),
+    connection: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/),
+    operations: z.array(z.enum(["send"])).min(1).max(1),
+    to: z.union([targetSchema, z.array(targetSchema).min(1).max(MAX_CHANNEL_TARGETS)]),
+    cc: z.array(targetSchema).min(1).max(MAX_CHANNEL_TARGETS).optional(),
+    template: z.record(z.string(), z.unknown()).optional(),
+}).strict();
+export function channelKey(channel) {
+    return channel.alias ?? channel.connection;
+}
+/** Shape check only. Whether the connection exists is checked against `connections.yaml` later. */
+export function parseChannels(raw) {
+    if (Array.isArray(raw) && raw.length > channelLimit)
+        return { ok: false, message: `channels: ${channelLimitMessage(raw.length)}` };
+    const parsed = z.array(channelSchema).max(MAX_STAGE_CHANNELS).safeParse(raw);
+    if (!parsed.success)
+        return { ok: false, message: "channels must be a list of { connection, to, operations: [send] } entries (optional alias, cc, template)" };
+    const keys = parsed.data.map(channelKey);
+    if (new Set(keys).size !== keys.length) {
+        return { ok: false, message: "channels entries must have unique aliases; give each entry for the same connection its own alias" };
+    }
+    return { ok: true, value: parsed.data };
+}
+/**
+ * Pipeline `channels` are defaults. A stage that declares its own list merges by alias (or
+ * connection id when there is no alias) with the stage entry winning. An explicit empty
+ * list clears every inherited entry.
+ */
+export function mergeChannelDefaults(defaults, own) {
+    if (own === undefined)
+        return defaults === undefined ? undefined : structuredClone([...defaults]);
+    if (own.length === 0)
+        return [];
+    const merged = new Map();
+    for (const channel of defaults ?? [])
+        merged.set(channelKey(channel), channel);
+    for (const channel of own)
+        merged.set(channelKey(channel), channel);
+    return structuredClone([...merged.values()]);
+}
+export function channelTarget(channel) {
+    return {
+        to: channel.to,
+        ...(channel.cc !== undefined ? { cc: channel.cc } : {}),
+        ...(channel.template !== undefined ? { template: channel.template } : {}),
+    };
+}
+/** Static checks against `connections.yaml`. No network and no secret reads. */
+export function validateStageChannels(registry, stage) {
+    const issues = [];
+    const count = stage.channels?.length ?? 0;
+    if (count > channelLimit) {
+        issues.push({ stageId: stage.id, key: stage.channels[0] ? channelKey(stage.channels[0]) : "", code: "CHANNEL_INVALID_INPUT", message: `stage "${stage.id}": ${channelLimitMessage(count)}` });
+    }
+    for (const channel of stage.channels ?? []) {
+        const key = channelKey(channel);
+        const fail = (code, message) => {
+            issues.push({ stageId: stage.id, key, code, message });
+        };
+        try {
+            registry.get(channel.connection);
+        }
+        catch (error) {
+            if (!(error instanceof ChannelError))
+                throw error;
+            fail(error.code, error.code === "CHANNEL_DISABLED"
+                ? `channel "${key}": connection "${channel.connection}" is disabled`
+                : `channel "${key}": connection "${channel.connection}" is not defined in connections.yaml`);
+            continue;
+        }
+        const provider = registry.providerFor(channel.connection);
+        const unsupported = channel.operations.find(operation => !provider.operations.includes(operation));
+        if (unsupported) {
+            fail("CHANNEL_INVALID_INPUT", `channel "${key}": provider "${provider.id}" does not support "${unsupported}"`);
+            continue;
+        }
+        const target = provider.validateTarget(channelTarget(channel));
+        if (!target.ok) {
+            fail("CHANNEL_TARGET_INVALID", `channel "${key}": invalid target for ${provider.id} (${target.issues.join(", ")})`);
+        }
+    }
+    return issues;
+}

package/dist/channels/types.d.ts

@@ -0,0 +1,142 @@
+import type { ChannelErrorCode } from "./errors.js";
+export type ChannelOperation = "send";
+export type SecretRef = `env:${string}` | `store:${string}`;
+export type ConnectionEntry = {
+    id: string;
+    provider: string;
+    displayName?: string;
+    enabled: boolean;
+    credential?: string;
+    config: Record<string, unknown>;
+    secrets: Record<string, SecretRef>;
+};
+export type CredentialEntry = {
+    id: string;
+    provider: string;
+    secrets: Record<string, SecretRef>;
+};
+export type ConnectionHealth = {
+    state: "ok" | "failed";
+    checkedAt: string;
+    error?: {
+        code: ChannelErrorCode;
+        retryable: boolean;
+    };
+};
+export type ValidationResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    issues: string[];
+};
+export type ResolvedCredential = {
+    id: string;
+    provider: string;
+    secrets: Record<string, string>;
+};
+/**
+ * Secret values are readable by providers but not enumerable, so JSON, logging and
+ * `util.inspect` of a resolved connection never include them.
+ */
+export type ResolvedConnection<C = unknown> = {
+    readonly id: string;
+    readonly scope: string;
+    readonly provider: string;
+    readonly displayName: string;
+    readonly config: C;
+    readonly secrets: Readonly<Record<string, string>>;
+    readonly credential?: ResolvedCredential;
+};
+export type OutboundMessage = {
+    text: string;
+    subject?: string;
+};
+export type SendContext = {
+    operationKey: string;
+    runId?: string;
+    stageId?: string;
+};
+export type SendReceipt = {
+    providerMessageId?: string;
+    submittedAt: string;
+    warnings?: string[];
+};
+export type ProviderSecretSpec = {
+    required: readonly string[];
+    optional?: readonly string[];
+};
+/** One input in the connect form. The provider says what it needs; the console renders it. */
+export type ProviderField = {
+    key: string;
+    label: string;
+    hint?: string;
+    placeholder?: string;
+    /** config goes to connections.yaml, secret to the secret store, credential to the shared credential. */
+    target: "config" | "secret" | "credential";
+    input: "text" | "password" | "select";
+    required: boolean;
+    options?: Array<{
+        value: string;
+        label: string;
+    }>;
+    defaultValue?: string;
+};
+/** Everything the console shows about a provider, so the console holds no provider tables of its own. */
+export type ProviderMeta = {
+    label: string;
+    /** Shown on the "not connected" tile. */
+    blurb: string;
+    /** Presentation key for an icon. The console maps it. */
+    icon: string;
+    /** Set when the provider works through another service, such as "Photon". */
+    via?: string;
+    note?: string;
+    fields: ProviderField[];
+    recipient: {
+        label: string;
+        placeholder: string;
+        multiple: boolean;
+        cc: boolean;
+        template: boolean;
+    };
+    /** Environment variable names for the `env:` form, in the order the YAML example uses them. */
+    envNames: string[];
+    /** A connections.yaml snippet that connects this provider. */
+    yamlExample: string;
+    /** The `to:` lines (and template, if any) of a stage `channels:` entry for this provider. */
+    stageExample: string;
+};
+export interface ChannelProvider<C = unknown, T = unknown> {
+    readonly id: string;
+    readonly meta: ProviderMeta;
+    readonly operations: readonly ChannelOperation[];
+    readonly secrets: ProviderSecretSpec;
+    /** When set, a connection must reference a credential of this provider kind. */
+    readonly credentialProvider?: string;
+    validateConfig(config: unknown): ValidationResult<C>;
+    validateTarget(target: unknown): ValidationResult<T>;
+    /** Masked, non-secret identity for listings, such as an address or workspace. */
+    describe?(config: C): {
+        identity?: string;
+    };
+    check(connection: ResolvedConnection<C>, signal?: AbortSignal): Promise<ConnectionHealth>;
+    /**
+     * Optional live check of the targets stages pin on this connection, such as whether a
+     * recipient is registered. Runs only after `check` succeeds. Targets are already validated.
+     */
+    checkTargets?(connection: ResolvedConnection<C>, targets: T[], signal?: AbortSignal): Promise<ConnectionHealth>;
+    send(connection: ResolvedConnection<C>, target: T, message: OutboundMessage, context: SendContext): Promise<SendReceipt>;
+}
+export type AnyChannelProvider = ChannelProvider<any, any>;
+export type ConnectionSummary = {
+    id: string;
+    scope: string;
+    provider: string;
+    displayName: string;
+    enabled: boolean;
+    identity?: string;
+    credential?: string;
+    /** Where each secret field is read from: the host environment or the console secret store. */
+    secrets: Record<string, "env" | "store">;
+};

package/dist/channels/types.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/doctorCommand.js

@@ -293,7 +293,9 @@ function preflightToDoctorChecks(preflight, strict) {
             ? `toolchain:${c.tool ?? i}`
             : c.kind === "secret"
                 ? `secret:${c.secret ?? i}`
-                : `mcp:${c.server ?? c.stageId ?? i}`;
+                : c.kind === "channel"
+                    ? `channel:${c.connection ?? i}`
+                    : `mcp:${c.server ?? c.stageId ?? i}`;
         let status = "pass";
         if (c.status === "ok") {
             status = "pass";

package/dist/config/draftPackage.d.ts

@@ -12,6 +12,7 @@ export type DraftPackage = {
         model?: unknown;
         schemas?: unknown;
         requires?: unknown;
+        channels?: unknown;
     };
     stages?: DraftStageArtifact[];
     task?: {