stageflow 0.35.0 → 0.36.0

package/dist/agent/claudeAdapter.js

@@ -78,6 +78,12 @@ function preflight(input) {
             reason: `stage declares skill "${input.stage.skill}"; the claude agent backend does not support skills yet`,
         };
     }
+    if (input.stage.channels?.length) {
+        return {
+            ok: false,
+            reason: "stage declares channels; the claude agent backend does not provide send_message yet, so the stage would run without it",
+        };
+    }
     return resolveClaudeModel(input.stage.model);
 }
 function resultFromCapture(capture, providerError) {

package/dist/agent/piAdapter.js

@@ -49,6 +49,7 @@ import { remindUntilEmitted } from "./stageTurnDriver.js";
 import { createAskOperatorTool, } from "../tools/askOperator.js";
 import { createWriteStageArtifactTool } from "../tools/writeStageArtifact.js";
 import { createSendEmailTool } from "../tools/sendEmail.js";
+import { createSendMessageTool } from "../tools/sendMessage.js";
 import { createReplyEmailTool } from "../tools/replyEmail.js";
 import { createGetEmailTool, createSearchEmailTool, createDownloadEmailAttachmentTool } from "../tools/readEmail.js";
 import "./cursorProvider.js";
@@ -493,6 +494,9 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
             ].join("\n")
             : `Create factory stage artifacts under ${attemptArtifactsPath} relative to the run folder.`;
     return [
+        ...(input.stage.channels?.length ? [
+            `Stageflow channels: ${JSON.stringify(input.stage.channels.map(channel => ({ channel: channel.alias ?? channel.connection, operations: channel.operations })))}. Use send_message with the channel name. Recipients are fixed by configuration and you cannot change them. Use a stable operationKey for each intended message. Provider acceptance does not prove delivery. Never resend an unknown submission automatically.`,
+        ] : []),
         ...(input.stage.email?.length ? [
             `Stageflow email permissions: ${JSON.stringify(input.stage.email)}. Use only declared accounts and operations. Use a stable operationKey for each intended message. Provider acceptance does not prove delivery. Never resend an unknown submission automatically.`,
         ] : []),
@@ -998,6 +1002,11 @@ async function prepareStageSessionWiring(input, sessionManager, existingAskWaitC
             }
             tools.push(...mcpTools.names);
         }
+        if (input.channels && input.stage.channels?.some(channel => channel.operations.includes("send"))) {
+            const definition = createSendMessageTool(input.channels);
+            customTools.push(defineTool(definition));
+            tools.push(definition.name);
+        }
         if (input.email) {
             const permitted = new Set(input.stage.email?.flatMap(permission => permission.operations));
             const definitions = [

package/dist/agent/port.d.ts

@@ -8,6 +8,7 @@ import type { StageActivityEvent } from "./activity.js";
 import type { ResolvedMcpServers } from "../config/resolveStageMcpServers.js";
 import type { StageRoots } from "../runtime/stageRoots.js";
 import type { StageEmail } from "../email/host.js";
+import type { StageChannels } from "../channels/host.js";
 import type { QaExchange } from "../hitl/qaTrail.js";
 import type { StageUsage } from "../types/usage.js";
 /** Opaque to runtime; adapters interpret. */
@@ -65,6 +66,7 @@ export type StageRunInput = {
     onAssistantTextDelta?: (delta: string) => void;
     skillFilePath?: string;
     email?: StageEmail;
+    channels?: StageChannels;
     /** Bundled browser skill; set by the runtime when the stage has `browser`. */
     browserSkillFilePath?: string;
     forkEmitContext?: ForkEmitContext;

package/dist/channels/config.d.ts

@@ -0,0 +1,11 @@
+import type { ConnectionEntry, CredentialEntry } from "./types.js";
+export declare const CONNECTIONS_FILE_LIMIT_BYTES = 262144;
+export declare const MAX_CONNECTIONS = 100;
+export declare const MAX_CREDENTIALS = 20;
+export type ConnectionsFile = {
+    credentials: CredentialEntry[];
+    connections: ConnectionEntry[];
+};
+export declare function parseConnectionsYaml(text: string): ConnectionsFile;
+/** A missing file is an empty configuration. Any other fault stops startup instead of half-applying. */
+export declare function loadConnectionsFile(file: string): ConnectionsFile;

package/dist/channels/config.js

@@ -0,0 +1,95 @@
+import { closeSync, constants, fstatSync, openSync, readSync } from "node:fs";
+import { parseDocument } from "yaml";
+import { z } from "zod";
+import { ChannelError } from "./errors.js";
+import { SECRET_REF_PATTERN } from "./secrets.js";
+export const CONNECTIONS_FILE_LIMIT_BYTES = 262144;
+export const MAX_CONNECTIONS = 100;
+export const MAX_CREDENTIALS = 20;
+const idSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/);
+const providerSchema = z.string().regex(/^[a-z][a-z0-9-]{0,63}$/);
+const secretRefSchema = z.string().regex(SECRET_REF_PATTERN);
+const secretFieldSchema = z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,63}$/);
+const secretsSchema = z.record(secretFieldSchema, secretRefSchema).default({});
+const credentialSchema = z.object({
+    id: idSchema,
+    provider: providerSchema,
+    secrets: secretsSchema,
+}).strict();
+const connectionSchema = z.object({
+    id: idSchema,
+    provider: providerSchema,
+    displayName: z.string().min(1).max(200).optional(),
+    enabled: z.boolean().default(true),
+    credential: idSchema.optional(),
+    config: z.record(z.string(), z.unknown()).default({}),
+    secrets: secretsSchema,
+}).strict();
+const fileSchema = z.object({
+    version: z.literal(1),
+    credentials: z.array(credentialSchema).max(MAX_CREDENTIALS).default([]),
+    connections: z.array(connectionSchema).max(MAX_CONNECTIONS).default([]),
+}).strict();
+export function parseConnectionsYaml(text) {
+    const document = parseDocument(text, { uniqueKeys: true, strict: true });
+    if (document.errors.length || document.warnings.length)
+        throw new ChannelError("CHANNEL_INVALID_INPUT");
+    let raw;
+    try {
+        raw = document.toJS({ maxAliasCount: 0 });
+    }
+    catch {
+        throw new ChannelError("CHANNEL_INVALID_INPUT");
+    }
+    const parsed = fileSchema.safeParse(raw);
+    if (!parsed.success)
+        throw new ChannelError("CHANNEL_INVALID_INPUT");
+    assertUnique(parsed.data.credentials.map(entry => entry.id));
+    assertUnique(parsed.data.connections.map(entry => entry.id));
+    return {
+        credentials: parsed.data.credentials.map(entry => ({ ...entry, secrets: entry.secrets })),
+        connections: parsed.data.connections.map(entry => ({ ...entry, secrets: entry.secrets })),
+    };
+}
+function assertUnique(ids) {
+    if (new Set(ids).size !== ids.length)
+        throw new ChannelError("CHANNEL_INVALID_INPUT");
+}
+/** A missing file is an empty configuration. Any other fault stops startup instead of half-applying. */
+export function loadConnectionsFile(file) {
+    let descriptor;
+    try {
+        descriptor = openSync(file, constants.O_RDONLY | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return { credentials: [], connections: [] };
+        throw new ChannelError("CHANNEL_STORAGE_FAILED");
+    }
+    try {
+        const stat = fstatSync(descriptor);
+        if (!stat.isFile())
+            throw new ChannelError("CHANNEL_INVALID_INPUT");
+        if (stat.size > CONNECTIONS_FILE_LIMIT_BYTES)
+            throw new ChannelError("CHANNEL_RESOURCE_LIMIT");
+        const bytes = Buffer.alloc(CONNECTIONS_FILE_LIMIT_BYTES + 1);
+        let length = 0;
+        while (length < bytes.length) {
+            const count = readSync(descriptor, bytes, length, bytes.length - length, null);
+            if (!count)
+                break;
+            length += count;
+        }
+        if (length > CONNECTIONS_FILE_LIMIT_BYTES)
+            throw new ChannelError("CHANNEL_RESOURCE_LIMIT");
+        return parseConnectionsYaml(bytes.toString("utf8", 0, length));
+    }
+    catch (error) {
+        if (error instanceof ChannelError)
+            throw error;
+        throw new ChannelError("CHANNEL_INVALID_INPUT");
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}

package/dist/channels/configWriter.d.ts

@@ -0,0 +1,40 @@
+import type { ConnectionEntry, CredentialEntry } from "./types.js";
+/** Plain-object form of an entry. Optional fields are omitted when unset. */
+export type ConnectionYamlEntry = {
+    id: string;
+    provider: string;
+    displayName?: string;
+    enabled?: boolean;
+    credential?: string;
+    config?: Record<string, unknown>;
+    secrets?: Record<string, string>;
+};
+export declare function toYamlEntry(entry: Pick<ConnectionEntry, "id" | "provider" | "enabled" | "config" | "secrets"> & {
+    displayName?: string;
+    credential?: string;
+}): ConnectionYamlEntry;
+/** Edits keep comments and key order that the user wrote. */
+export declare function addConnectionYaml(text: string, entry: ConnectionYamlEntry, credential?: {
+    id: string;
+    provider: string;
+    secrets: Record<string, string>;
+}): string;
+export type ConnectionPatch = {
+    displayName?: string | null;
+    enabled?: boolean;
+    config?: Record<string, unknown>;
+    secrets?: Record<string, string>;
+};
+export declare function updateConnectionYaml(text: string, id: string, patch: ConnectionPatch): string;
+/** Removes the entry and any credential that no remaining connection uses. Returns what was dropped. */
+export declare function removeConnectionYaml(text: string, id: string): {
+    text: string;
+    removedCredential?: string;
+};
+export declare function readConnectionsText(file: string): string;
+/**
+ * Replaces the file atomically. A bind-mounted file cannot be renamed over, so that case falls
+ * back to writing in place.
+ */
+export declare function writeConnectionsText(file: string, text: string): void;
+export type { CredentialEntry };

package/dist/channels/configWriter.js

@@ -0,0 +1,148 @@
+import { closeSync, constants, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import path from "node:path";
+import { isSeq, parseDocument } from "yaml";
+import { CONNECTIONS_FILE_LIMIT_BYTES } from "./config.js";
+import { ChannelError } from "./errors.js";
+export function toYamlEntry(entry) {
+    return {
+        id: entry.id,
+        provider: entry.provider,
+        ...(entry.displayName ? { displayName: entry.displayName } : {}),
+        ...(entry.enabled === false ? { enabled: false } : {}),
+        ...(entry.credential ? { credential: entry.credential } : {}),
+        ...(Object.keys(entry.config).length ? { config: entry.config } : {}),
+        ...(Object.keys(entry.secrets).length ? { secrets: entry.secrets } : {}),
+    };
+}
+function open(text) {
+    const source = text.trim().length ? text : "version: 1\n";
+    const document = parseDocument(source, { uniqueKeys: true, strict: true });
+    if (document.errors.length)
+        throw new ChannelError("CHANNEL_INVALID_INPUT");
+    return document;
+}
+function sequence(document, key) {
+    let seq = document.get(key, true);
+    if (!isSeq(seq)) {
+        document.set(key, document.createNode([]));
+        seq = document.get(key, true);
+    }
+    const result = seq;
+    result.flow = false;
+    return result;
+}
+function indexOf(seq, id) {
+    return seq.items.findIndex(item => item?.get?.("id") === id);
+}
+/** Edits keep comments and key order that the user wrote. */
+export function addConnectionYaml(text, entry, credential) {
+    const document = open(text);
+    if (credential) {
+        const credentials = sequence(document, "credentials");
+        if (indexOf(credentials, credential.id) < 0)
+            credentials.add(document.createNode({ id: credential.id, provider: credential.provider, secrets: credential.secrets }));
+    }
+    const connections = sequence(document, "connections");
+    if (indexOf(connections, entry.id) >= 0)
+        throw new ChannelError("CHANNEL_OPERATION_CONFLICT", false, { connectionId: entry.id });
+    connections.add(document.createNode(entry));
+    return document.toString();
+}
+export function updateConnectionYaml(text, id, patch) {
+    const document = open(text);
+    const connections = sequence(document, "connections");
+    const index = indexOf(connections, id);
+    if (index < 0)
+        throw new ChannelError("CHANNEL_NOT_FOUND", false, { connectionId: id });
+    const node = connections.items[index];
+    if (patch.displayName !== undefined) {
+        if (patch.displayName === null || patch.displayName === "")
+            node.delete("displayName");
+        else
+            node.set("displayName", patch.displayName);
+    }
+    if (patch.enabled !== undefined) {
+        if (patch.enabled)
+            node.delete("enabled");
+        else
+            node.set("enabled", false);
+    }
+    if (patch.config !== undefined) {
+        if (Object.keys(patch.config).length)
+            node.set("config", document.createNode(patch.config));
+        else
+            node.delete("config");
+    }
+    for (const [field, ref] of Object.entries(patch.secrets ?? {}))
+        node.setIn(["secrets", field], ref);
+    return document.toString();
+}
+/** Removes the entry and any credential that no remaining connection uses. Returns what was dropped. */
+export function removeConnectionYaml(text, id) {
+    const document = open(text);
+    const connections = sequence(document, "connections");
+    const index = indexOf(connections, id);
+    if (index < 0)
+        throw new ChannelError("CHANNEL_NOT_FOUND", false, { connectionId: id });
+    const credentialId = connections.items[index].get("credential");
+    connections.items.splice(index, 1);
+    let removedCredential;
+    if (typeof credentialId === "string") {
+        const stillUsed = connections.items.some(item => item.get("credential") === credentialId);
+        const credentials = document.get("credentials", true);
+        if (!stillUsed && isSeq(credentials)) {
+            const at = indexOf(credentials, credentialId);
+            if (at >= 0) {
+                credentials.items.splice(at, 1);
+                removedCredential = credentialId;
+            }
+        }
+    }
+    return { text: document.toString(), ...(removedCredential ? { removedCredential } : {}) };
+}
+export function readConnectionsText(file) {
+    if (!existsSync(file))
+        return "";
+    const text = readFileSync(file, "utf8");
+    if (Buffer.byteLength(text) > CONNECTIONS_FILE_LIMIT_BYTES)
+        throw new ChannelError("CHANNEL_RESOURCE_LIMIT");
+    return text;
+}
+/**
+ * Replaces the file atomically. A bind-mounted file cannot be renamed over, so that case falls
+ * back to writing in place.
+ */
+export function writeConnectionsText(file, text) {
+    if (Buffer.byteLength(text) > CONNECTIONS_FILE_LIMIT_BYTES)
+        throw new ChannelError("CHANNEL_RESOURCE_LIMIT");
+    try {
+        mkdirSync(path.dirname(file), { recursive: true });
+        const temporary = `${file}.${process.pid}.tmp`;
+        try {
+            writeFileSync(temporary, text, { mode: 0o644 });
+            renameSync(temporary, file);
+        }
+        catch (error) {
+            const code = error.code;
+            try {
+                unlinkSync(temporary);
+            }
+            catch { /* nothing to clean */ }
+            if (code !== "EBUSY" && code !== "EXDEV" && code !== "EPERM")
+                throw error;
+            const descriptor = openSync(file, constants.O_WRONLY | constants.O_TRUNC);
+            try {
+                writeSync(descriptor, text);
+                fsyncSync(descriptor);
+            }
+            finally {
+                closeSync(descriptor);
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof ChannelError)
+            throw error;
+        throw new ChannelError("CHANNEL_STORAGE_FAILED");
+    }
+}

package/dist/channels/connectionEdits.d.ts

@@ -0,0 +1,34 @@
+/** What the edit module needs from the secret store. `ChannelSecretStore` satisfies it. */
+export interface SecretWriter {
+    get(name: string): string | undefined;
+    set(name: string, value: string): void;
+    delete(name: string): void;
+    deleteWithPrefix(prefix: string): void;
+}
+export type ConnectionEdit = {
+    /** Secret store name to value. Written before the file so a reference never points at nothing. */
+    secrets?: Readonly<Record<string, string>>;
+    /** Pure transform of the file text. May name secret prefixes to drop once the edit has committed. */
+    rewrite(text: string): {
+        text: string;
+        dropSecretPrefixes?: readonly string[];
+    };
+};
+export type ConnectionEditsOptions = {
+    file: () => string;
+    store: SecretWriter;
+    /** Throws if the new text would not load. Runs before anything is written to the file. */
+    validate: (text: string) => void;
+};
+/**
+ * One atomic change to connections: secrets and file together. Either both change or neither
+ * does. A secret that already existed is restored to its previous value, not deleted, and a
+ * failure while writing, validating or saving leaves nothing half-applied. Dropping the secrets
+ * of a removed connection happens only after the file has been saved, and a failure there only
+ * leaves an orphaned secret behind, never a broken connection.
+ */
+export declare class ConnectionEdits {
+    private readonly options;
+    constructor(options: ConnectionEditsOptions);
+    apply(edit: ConnectionEdit): void;
+}

package/dist/channels/connectionEdits.js

@@ -0,0 +1,53 @@
+import { readConnectionsText, writeConnectionsText } from "./configWriter.js";
+/**
+ * One atomic change to connections: secrets and file together. Either both change or neither
+ * does. A secret that already existed is restored to its previous value, not deleted, and a
+ * failure while writing, validating or saving leaves nothing half-applied. Dropping the secrets
+ * of a removed connection happens only after the file has been saved, and a failure there only
+ * leaves an orphaned secret behind, never a broken connection.
+ */
+export class ConnectionEdits {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    apply(edit) {
+        const { store } = this.options;
+        const file = this.options.file();
+        const text = readConnectionsText(file);
+        const previous = new Map();
+        let drop = [];
+        try {
+            for (const [name, value] of Object.entries(edit.secrets ?? {})) {
+                previous.set(name, store.get(name));
+                store.set(name, value);
+            }
+            const next = edit.rewrite(text);
+            this.options.validate(next.text);
+            writeConnectionsText(file, next.text);
+            drop = next.dropSecretPrefixes ?? [];
+        }
+        catch (error) {
+            for (const [name, value] of previous) {
+                try {
+                    if (value === undefined)
+                        store.delete(name);
+                    else
+                        store.set(name, value);
+                }
+                catch {
+                    /* restoring is best effort; the original error is the one to report */
+                }
+            }
+            throw error;
+        }
+        for (const prefix of drop) {
+            try {
+                store.deleteWithPrefix(prefix);
+            }
+            catch {
+                /* an orphaned secret is harmless and is overwritten if the id is reused */
+            }
+        }
+    }
+}

package/dist/channels/errorInfo.d.ts

@@ -0,0 +1,18 @@
+import type { ChannelErrorCode } from "./errors.js";
+export type ChannelErrorInfo = {
+    /** One sentence for logs, preflight output and the status line. */
+    reason: string;
+    /** What to do about it, when there is something to do. */
+    hint?: string;
+    /** HTTP status when the code is returned by the connections API. */
+    status: number;
+};
+/**
+ * The one place a channel error code is explained. A `Record` over the code union makes a code
+ * without an entry a compile error. Whether a failure is retryable is not here: it depends on
+ * the operation (a 5xx is retryable in a check but an unknown outcome in a send), so it stays
+ * where the failure is classified.
+ */
+export declare const CHANNEL_ERROR_INFO: Record<ChannelErrorCode, ChannelErrorInfo>;
+export declare function channelErrorReason(code: string): string;
+export declare function channelErrorStatus(code: string): number;

package/dist/channels/errorInfo.js

@@ -0,0 +1,71 @@
+/**
+ * The one place a channel error code is explained. A `Record` over the code union makes a code
+ * without an entry a compile error. Whether a failure is retryable is not here: it depends on
+ * the operation (a 5xx is retryable in a check but an unknown outcome in a send), so it stays
+ * where the failure is classified.
+ */
+export const CHANNEL_ERROR_INFO = {
+    CHANNEL_INVALID_INPUT: {
+        reason: "The settings are not valid for this provider account",
+        hint: "Check the values (for example an unknown inbox or a different workspace) and try again. If the file is hand-edited, fix the entry and restart.",
+        status: 400,
+    },
+    CHANNEL_NOT_FOUND: { reason: "The connection is not defined", status: 404 },
+    CHANNEL_DISABLED: { reason: "The connection is disabled", hint: "Enable it, or remove it from the stage.", status: 400 },
+    CHANNEL_PROVIDER_UNSUPPORTED: {
+        reason: "This provider is not supported here, or its SDK is not installed",
+        hint: "iMessage and WhatsApp need the Spectrum SDK packages, which are optional dependencies.",
+        status: 400,
+    },
+    CHANNEL_SECRET_UNAVAILABLE: {
+        reason: "A secret for this connection is not set on the host",
+        hint: "Set the environment variable each secret names (or its _FILE form) on the host, or use Replace to store one, then check again.",
+        status: 500,
+    },
+    CHANNEL_RESOURCE_LIMIT: { reason: "The request or connections.yaml is too large", status: 413 },
+    CHANNEL_STORAGE_FAILED: {
+        reason: "Stageflow could not read or write connections.yaml or the secret store on this host",
+        hint: "Check that the data directory is writable.",
+        status: 500,
+    },
+    CHANNEL_UNAUTHORIZED: {
+        reason: "Credentials were rejected or lack a required permission",
+        hint: "The provider refused the credential: it is invalid, or it lacks a permission this provider needs (for AgentMail, reading the inbox and sending). Check the key and its permissions, then try again.",
+        status: 500,
+    },
+    CHANNEL_AUTH_FAILED: {
+        reason: "Credentials were rejected",
+        hint: "Replace the secret with a valid one, then check again.",
+        status: 500,
+    },
+    CHANNEL_CONNECTION_FAILED: {
+        reason: "Could not reach the provider",
+        hint: "This is usually temporary. Check the network and try again.",
+        status: 500,
+    },
+    CHANNEL_TIMEOUT: { reason: "The provider did not answer in time", hint: "Try again.", status: 500 },
+    CHANNEL_RATE_LIMIT: { reason: "The provider is rate limiting this account", hint: "Wait and try again.", status: 500 },
+    CHANNEL_WINDOW_CLOSED: {
+        reason: "WhatsApp's 24-hour reply window is closed",
+        hint: "Pin an approved template on the stage so it can message first.",
+        status: 500,
+    },
+    CHANNEL_TARGET_INVALID: { reason: "The pinned recipient is not valid for this provider", status: 400 },
+    CHANNEL_RECIPIENT_REJECTED: {
+        reason: "The provider will not message this recipient",
+        hint: "For iMessage on a Free or Pro Photon project, add them as a project user and have them text their assigned line (the \"Texts on\" number) once.",
+        status: 500,
+    },
+    CHANNEL_SEND_OUTCOME_UNKNOWN: {
+        reason: "The message may or may not have been sent",
+        hint: "Check the provider before sending again. Stageflow never resends it automatically.",
+        status: 500,
+    },
+    CHANNEL_OPERATION_CONFLICT: { reason: "That already exists, or the key was reused with different content", status: 409 },
+};
+export function channelErrorReason(code) {
+    return CHANNEL_ERROR_INFO[code]?.reason ?? code;
+}
+export function channelErrorStatus(code) {
+    return CHANNEL_ERROR_INFO[code]?.status ?? 500;
+}

package/dist/channels/errors.d.ts

@@ -0,0 +1,12 @@
+export type ChannelErrorCode = "CHANNEL_INVALID_INPUT" | "CHANNEL_NOT_FOUND" | "CHANNEL_DISABLED" | "CHANNEL_PROVIDER_UNSUPPORTED" | "CHANNEL_SECRET_UNAVAILABLE" | "CHANNEL_RESOURCE_LIMIT" | "CHANNEL_STORAGE_FAILED" | "CHANNEL_UNAUTHORIZED" | "CHANNEL_AUTH_FAILED" | "CHANNEL_CONNECTION_FAILED" | "CHANNEL_TIMEOUT" | "CHANNEL_RATE_LIMIT" | "CHANNEL_WINDOW_CLOSED" | "CHANNEL_TARGET_INVALID" | "CHANNEL_RECIPIENT_REJECTED" | "CHANNEL_SEND_OUTCOME_UNKNOWN" | "CHANNEL_OPERATION_CONFLICT";
+export type ChannelErrorDetail = {
+    connectionId?: string;
+    field?: string;
+};
+/** The message is always the code. Detail carries only non-secret identifiers. */
+export declare class ChannelError extends Error {
+    readonly code: ChannelErrorCode;
+    readonly retryable: boolean;
+    readonly detail?: ChannelErrorDetail | undefined;
+    constructor(code: ChannelErrorCode, retryable?: boolean, detail?: ChannelErrorDetail | undefined);
+}

package/dist/channels/errors.js

@@ -0,0 +1,13 @@
+/** The message is always the code. Detail carries only non-secret identifiers. */
+export class ChannelError extends Error {
+    code;
+    retryable;
+    detail;
+    constructor(code, retryable = false, detail) {
+        super(code);
+        this.code = code;
+        this.retryable = retryable;
+        this.detail = detail;
+        this.name = "ChannelError";
+    }
+}

package/dist/channels/health.d.ts

@@ -0,0 +1,41 @@
+import type { ChannelRegistry } from "./registry.js";
+import type { ConnectionHealth } from "./types.js";
+export type ChannelHealthOptions = {
+    registry: ChannelRegistry;
+    intervalMs?: number;
+    jitter?: number;
+    timeoutMs?: number;
+    maxBackoffFactor?: number;
+    random?: () => number;
+    onResult?: (connectionId: string, health: ConnectionHealth) => void;
+};
+export declare const DEFAULT_HEALTH_INTERVAL_MS = 300000;
+/**
+ * Host-only background check. It keeps the last result per connection in memory so the
+ * Connections page can show current status. It never sends a message and keeps no secrets.
+ * Failures back off up to `maxBackoffFactor` times the interval; successes return to it.
+ */
+export declare class ChannelHealthMonitor {
+    private readonly registry;
+    private readonly intervalMs;
+    private readonly jitter;
+    private readonly timeoutMs;
+    private readonly maxBackoffFactor;
+    private readonly random;
+    private readonly onResult?;
+    private readonly results;
+    private readonly failures;
+    private readonly timers;
+    private readonly inflight;
+    private controller;
+    private running;
+    constructor(options: ChannelHealthOptions);
+    snapshot(): Record<string, ConnectionHealth>;
+    start(): void;
+    stop(): Promise<void>;
+    /** Runs one check now, outside the schedule. */
+    checkNow(connectionId: string): Promise<ConnectionHealth>;
+    private schedule;
+    private nextDelay;
+    private runCheck;
+}