stageflow 0.33.0 → 0.36.0

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;
+}

package/dist/channels/health.js

@@ -0,0 +1,99 @@
+import { ChannelError } from "./errors.js";
+export const DEFAULT_HEALTH_INTERVAL_MS = 300000;
+function failed(code, retryable) {
+    return { state: "failed", checkedAt: new Date().toISOString(), error: { code, retryable } };
+}
+/**
+ * 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 class ChannelHealthMonitor {
+    registry;
+    intervalMs;
+    jitter;
+    timeoutMs;
+    maxBackoffFactor;
+    random;
+    onResult;
+    results = new Map();
+    failures = new Map();
+    timers = new Map();
+    inflight = new Set();
+    controller = new AbortController();
+    running = false;
+    constructor(options) {
+        this.registry = options.registry;
+        this.intervalMs = options.intervalMs ?? DEFAULT_HEALTH_INTERVAL_MS;
+        this.jitter = options.jitter ?? 0.2;
+        this.timeoutMs = options.timeoutMs ?? 8000;
+        this.maxBackoffFactor = options.maxBackoffFactor ?? 8;
+        this.random = options.random ?? Math.random;
+        this.onResult = options.onResult;
+    }
+    snapshot() {
+        return Object.fromEntries([...this.results].map(([id, health]) => [id, structuredClone(health)]));
+    }
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.controller = new AbortController();
+        for (const connection of this.registry.list()) {
+            if (connection.enabled)
+                this.schedule(connection.id, Math.floor(this.random() * 2000));
+        }
+    }
+    async stop() {
+        this.running = false;
+        this.controller.abort();
+        for (const timer of this.timers.values())
+            clearTimeout(timer);
+        this.timers.clear();
+        await Promise.allSettled([...this.inflight]);
+    }
+    /** Runs one check now, outside the schedule. */
+    async checkNow(connectionId) {
+        const health = await this.runCheck(connectionId);
+        this.results.set(connectionId, health);
+        this.onResult?.(connectionId, structuredClone(health));
+        return structuredClone(health);
+    }
+    schedule(id, delay) {
+        if (!this.running)
+            return;
+        const timer = setTimeout(() => {
+            this.timers.delete(id);
+            const work = this.checkNow(id).then(health => {
+                const count = health.state === "ok" ? 0 : (this.failures.get(id) ?? 0) + 1;
+                this.failures.set(id, count);
+                this.schedule(id, this.nextDelay(count));
+            }).finally(() => { this.inflight.delete(work); });
+            this.inflight.add(work);
+        }, delay);
+        timer.unref?.();
+        this.timers.set(id, timer);
+    }
+    nextDelay(failureCount) {
+        const factor = Math.min(2 ** failureCount, this.maxBackoffFactor);
+        const base = this.intervalMs * (failureCount === 0 ? 1 : factor);
+        return Math.round(base * (1 + (this.random() * 2 - 1) * this.jitter));
+    }
+    async runCheck(id) {
+        let timer;
+        try {
+            const provider = this.registry.providerFor(id);
+            const connection = this.registry.resolve(id);
+            const timeout = new Promise(resolve => {
+                timer = setTimeout(() => resolve(failed("CHANNEL_TIMEOUT", true)), this.timeoutMs);
+            });
+            return await Promise.race([provider.check(connection, this.controller.signal), timeout]);
+        }
+        catch (error) {
+            return error instanceof ChannelError ? failed(error.code, error.retryable) : failed("CHANNEL_CONNECTION_FAILED", false);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/channels/host.d.ts

@@ -0,0 +1,55 @@
+import type { StageConfig } from "../types/stage.js";
+import { ChannelRegistry, type ChannelRegistryOptions } from "./registry.js";
+import { type ChannelErrorCode } from "./errors.js";
+import { ChannelSends } from "./ledger.js";
+export type ChannelSendInput = {
+    channel?: string;
+    text: string;
+    subject?: string;
+    operationKey: string;
+};
+export type ChannelSendResult = {
+    channel: string;
+    connection: string;
+    providerMessageId?: string;
+    submittedAt: string;
+    warnings?: string[];
+};
+export type StageChannels = {
+    send(input: ChannelSendInput): Promise<ChannelSendResult>;
+};
+export declare const MAX_MESSAGE_TEXT = 65536;
+export declare class ChannelHost {
+    private readonly cwd;
+    private readonly options;
+    registry: ChannelRegistry;
+    readonly sends: ChannelSends;
+    constructor(cwd: string, options?: Omit<ChannelRegistryOptions, "cwd">);
+    /** Re-reads connections.yaml after an edit. A file that no longer loads keeps the old registry. */
+    reload(): void;
+}
+export declare function channelHostFor(cwd: string): ChannelHost;
+/** Re-reads connections.yaml in every cached host, so an edit made once reaches every project. */
+export declare function reloadChannelHosts(): void;
+export declare function releaseChannelHost(cwd: string): Promise<void>;
+/** Fails with the first problem found. Static only: no network, no secret reads. */
+export declare function validateStageChannelConnections(host: ChannelHost, stage: Pick<StageConfig, "id" | "channels">): void;
+/**
+ * Removes every variable the loaded connections point at, and its `_FILE` form, from a worker
+ * environment. It reads the names from the same registry the host sends with, so the variables
+ * stripped always belong to the file the host actually loaded. A file that cannot be loaded
+ * leaves the environment unchanged.
+ */
+export declare function channelsWorkerEnvironment(env: NodeJS.ProcessEnv, cwd: string): NodeJS.ProcessEnv;
+/**
+ * Host-side authorization and delivery for one stage. The target comes from the stage's
+ * frozen `channels`, never from the caller. The caller's operation key is bound to the run,
+ * stage and channel before it reaches the ledger.
+ */
+export declare function stageChannels(host: ChannelHost, stage: StageConfig, runId: string): StageChannels;
+export declare function channelFault(error: unknown): {
+    code: ChannelErrorCode;
+    retryable: boolean;
+};
+/** The inherited IPC channel identifies the child; no caller-provided run or stage identity is accepted. */
+export declare function workerStageChannels(): StageChannels;

package/dist/channels/host.js

@@ -0,0 +1,185 @@
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
+import { z } from "zod";
+import { ChannelRegistry } from "./registry.js";
+import { ChannelError } from "./errors.js";
+import { ChannelSends } from "./ledger.js";
+import { channelKey, channelTarget, stageChannelLimit, validateStageChannels } from "./stageChannels.js";
+export const MAX_MESSAGE_TEXT = 65536;
+const WORKER_TIMEOUT_MS = 65000;
+const sendSchema = z.object({
+    channel: z.string().min(1).max(200).optional(),
+    text: z.string().min(1).max(MAX_MESSAGE_TEXT),
+    subject: z.string().min(1).max(998).regex(/^[^\r\n]*$/).optional(),
+    operationKey: z.string().min(1).max(120),
+}).strict();
+export class ChannelHost {
+    cwd;
+    options;
+    registry;
+    sends;
+    constructor(cwd, options = {}) {
+        this.cwd = cwd;
+        this.options = options;
+        this.registry = new ChannelRegistry({ cwd, ...options });
+        this.sends = new ChannelSends(this.registry.scope);
+    }
+    /** Re-reads connections.yaml after an edit. A file that no longer loads keeps the old registry. */
+    reload() {
+        this.registry = new ChannelRegistry({ cwd: this.cwd, ...this.options });
+    }
+}
+const hosts = new Map();
+export function channelHostFor(cwd) {
+    const key = path.resolve(cwd);
+    let entry = hosts.get(key);
+    if (entry?.releasing)
+        throw new ChannelError("CHANNEL_CONNECTION_FAILED", true);
+    if (!entry) {
+        entry = { host: new ChannelHost(key) };
+        hosts.set(key, entry);
+    }
+    return entry.host;
+}
+/** Re-reads connections.yaml in every cached host, so an edit made once reaches every project. */
+export function reloadChannelHosts() {
+    for (const entry of hosts.values()) {
+        try {
+            entry.host.reload();
+        }
+        catch {
+            /* a host whose file no longer loads keeps its previous registry until the file is fixed */
+        }
+    }
+}
+export async function releaseChannelHost(cwd) {
+    const key = path.resolve(cwd);
+    const entry = hosts.get(key);
+    if (!entry)
+        return;
+    entry.releasing ??= (async () => {
+        entry.host.sends.setAccepting(false);
+        await entry.host.sends.drain();
+    })();
+    await entry.releasing;
+    if (hosts.get(key) === entry)
+        hosts.delete(key);
+}
+/** Fails with the first problem found. Static only: no network, no secret reads. */
+export function validateStageChannelConnections(host, stage) {
+    const [first] = validateStageChannels(host.registry, stage);
+    if (first)
+        throw new ChannelError(first.code, false, { connectionId: stage.channels?.find(channel => channelKey(channel) === first.key)?.connection });
+}
+/**
+ * Removes every variable the loaded connections point at, and its `_FILE` form, from a worker
+ * environment. It reads the names from the same registry the host sends with, so the variables
+ * stripped always belong to the file the host actually loaded. A file that cannot be loaded
+ * leaves the environment unchanged.
+ */
+export function channelsWorkerEnvironment(env, cwd) {
+    const result = { ...env };
+    let names;
+    try {
+        names = channelHostFor(cwd).registry.envSecretNames();
+    }
+    catch {
+        return result;
+    }
+    for (const name of names) {
+        delete result[name];
+        delete result[`${name}_FILE`];
+    }
+    return result;
+}
+function pick(channels, requested) {
+    if (requested !== undefined) {
+        const found = channels.find(channel => channelKey(channel) === requested);
+        if (!found)
+            throw new ChannelError("CHANNEL_UNAUTHORIZED");
+        return found;
+    }
+    if (channels.length === 1)
+        return channels[0];
+    throw new ChannelError("CHANNEL_INVALID_INPUT", false, { field: "channel" });
+}
+function hashOf(parts) {
+    return createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+}
+/**
+ * Host-side authorization and delivery for one stage. The target comes from the stage's
+ * frozen `channels`, never from the caller. The caller's operation key is bound to the run,
+ * stage and channel before it reaches the ledger.
+ */
+export function stageChannels(host, stage, runId) {
+    const declared = structuredClone(stage.channels ?? []);
+    const stageId = stage.id;
+    const tooMany = declared.length > stageChannelLimit();
+    return {
+        async send(raw) {
+            if (tooMany)
+                throw new ChannelError("CHANNEL_INVALID_INPUT");
+            const parsed = sendSchema.safeParse(raw);
+            if (!parsed.success)
+                throw new ChannelError("CHANNEL_INVALID_INPUT");
+            const input = parsed.data;
+            const channel = pick(declared, input.channel);
+            if (!channel.operations.includes("send"))
+                throw new ChannelError("CHANNEL_UNAUTHORIZED", false, { connectionId: channel.connection });
+            const key = channelKey(channel);
+            const target = host.registry.validateTarget(channel.connection, channelTarget(channel));
+            const provider = host.registry.providerFor(channel.connection);
+            const connection = host.registry.resolve(channel.connection);
+            const message = { text: input.text, ...(input.subject !== undefined ? { subject: input.subject } : {}) };
+            const operationKey = hashOf([runId, stageId, key, input.operationKey]);
+            const receipt = await host.sends.send({ connectionId: channel.connection, operationKey, hash: hashOf([key, channel.connection, channelTarget(channel), message]) }, () => provider.send(connection, target, message, { operationKey, runId, stageId }));
+            return {
+                channel: key,
+                connection: channel.connection,
+                ...(receipt.providerMessageId !== undefined ? { providerMessageId: receipt.providerMessageId } : {}),
+                submittedAt: receipt.submittedAt,
+                ...(receipt.warnings?.length ? { warnings: receipt.warnings } : {}),
+            };
+        },
+    };
+}
+export function channelFault(error) {
+    return error instanceof ChannelError
+        ? { code: error.code, retryable: error.retryable }
+        : { code: "CHANNEL_CONNECTION_FAILED", retryable: false };
+}
+/** The inherited IPC channel identifies the child; no caller-provided run or stage identity is accepted. */
+export function workerStageChannels() {
+    return {
+        send(input) {
+            return new Promise((resolve, reject) => {
+                if (!process.connected || !process.send) {
+                    reject(new ChannelError("CHANNEL_UNAUTHORIZED"));
+                    return;
+                }
+                const requestId = randomUUID();
+                const finish = (error, result) => {
+                    clearTimeout(timer);
+                    process.off("message", receive);
+                    process.off("disconnect", disconnected);
+                    if (error)
+                        reject(error);
+                    else
+                        resolve(result);
+                };
+                const disconnected = () => finish(new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN"));
+                const receive = (message) => {
+                    const response = message;
+                    if (response?.type !== "channel.response" || response.requestId !== requestId)
+                        return;
+                    finish(response.error ? new ChannelError(response.error.code, response.error.retryable) : undefined, response.receipt);
+                };
+                const timer = setTimeout(disconnected, WORKER_TIMEOUT_MS);
+                process.on("message", receive);
+                process.once("disconnect", disconnected);
+                process.send({ type: "channel.send", requestId, input }, error => { if (error)
+                    disconnected(); });
+            });
+        },
+    };
+}

package/dist/channels/http.d.ts

@@ -0,0 +1,31 @@
+import { ChannelError } from "./errors.js";
+export type HttpMode = "check" | "send";
+export type HttpCall = {
+    fetch: typeof fetch;
+    url: string;
+    method: "GET" | "POST";
+    headers: Record<string, string>;
+    body?: unknown;
+    timeoutMs: number;
+    signal?: AbortSignal;
+    mode: HttpMode;
+    connectionId?: string;
+};
+export type HttpResult = {
+    status: number;
+    text: string;
+};
+/**
+ * Maps a transport failure. For a send, only failures that happen before the request leaves
+ * the machine are definite; everything else may have reached the provider, so it is unknown.
+ */
+export declare function networkFailure(error: unknown, mode: HttpMode, timedOut: boolean, connectionId?: string): ChannelError;
+/** Maps an HTTP status to a channel error. `retryable` is true only for transient conditions. */
+export declare function statusFailure(status: number, mode: HttpMode, connectionId?: string): ChannelError;
+/**
+ * One bounded HTTP call. Redirects are refused so a credential header never follows a
+ * redirect to another host. Response bodies are returned to the provider but never put in
+ * an error, so provider messages cannot carry a secret into a log or a tool result.
+ */
+export declare function httpCall(call: HttpCall): Promise<HttpResult>;
+export declare function parseJson(text: string): unknown;

package/dist/channels/http.js

@@ -0,0 +1,79 @@
+import { ChannelError } from "./errors.js";
+const NOT_SENT_CODES = new Set(["ENOTFOUND", "ECONNREFUSED", "EAI_AGAIN", "UND_ERR_CONNECT_TIMEOUT", "ERR_TLS_CERT_ALTNAME_INVALID", "CERT_HAS_EXPIRED", "DEPTH_ZERO_SELF_SIGNED_CERT", "UNABLE_TO_VERIFY_LEAF_SIGNATURE"]);
+function causeCode(error) {
+    const cause = error?.cause;
+    return typeof cause?.code === "string" ? cause.code : undefined;
+}
+/**
+ * Maps a transport failure. For a send, only failures that happen before the request leaves
+ * the machine are definite; everything else may have reached the provider, so it is unknown.
+ */
+export function networkFailure(error, mode, timedOut, connectionId) {
+    const detail = connectionId ? { connectionId } : undefined;
+    if (timedOut)
+        return new ChannelError(mode === "send" ? "CHANNEL_SEND_OUTCOME_UNKNOWN" : "CHANNEL_TIMEOUT", mode !== "send", detail);
+    if (mode === "check")
+        return new ChannelError("CHANNEL_CONNECTION_FAILED", true, detail);
+    const code = causeCode(error);
+    if (code !== undefined && NOT_SENT_CODES.has(code))
+        return new ChannelError("CHANNEL_CONNECTION_FAILED", true, detail);
+    return new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN", false, detail);
+}
+/** Maps an HTTP status to a channel error. `retryable` is true only for transient conditions. */
+export function statusFailure(status, mode, connectionId) {
+    const detail = connectionId ? { connectionId } : undefined;
+    if (status === 401)
+        return new ChannelError("CHANNEL_AUTH_FAILED", false, detail);
+    if (status === 403)
+        return new ChannelError("CHANNEL_UNAUTHORIZED", false, detail);
+    if (status === 429)
+        return new ChannelError("CHANNEL_RATE_LIMIT", true, detail);
+    if (status >= 500) {
+        return mode === "send"
+            ? new ChannelError("CHANNEL_SEND_OUTCOME_UNKNOWN", false, detail)
+            : new ChannelError("CHANNEL_CONNECTION_FAILED", true, detail);
+    }
+    if (status === 408)
+        return new ChannelError(mode === "send" ? "CHANNEL_SEND_OUTCOME_UNKNOWN" : "CHANNEL_TIMEOUT", mode !== "send", detail);
+    return new ChannelError("CHANNEL_INVALID_INPUT", false, detail);
+}
+/**
+ * One bounded HTTP call. Redirects are refused so a credential header never follows a
+ * redirect to another host. Response bodies are returned to the provider but never put in
+ * an error, so provider messages cannot carry a secret into a log or a tool result.
+ */
+export async function httpCall(call) {
+    const timeout = AbortSignal.timeout(call.timeoutMs);
+    const signal = call.signal ? AbortSignal.any([call.signal, timeout]) : timeout;
+    let response;
+    try {
+        response = await call.fetch(call.url, {
+            method: call.method,
+            headers: { ...call.headers, ...(call.body !== undefined ? { "content-type": "application/json" } : {}) },
+            ...(call.body !== undefined ? { body: JSON.stringify(call.body) } : {}),
+            redirect: "error",
+            signal,
+        });
+    }
+    catch (error) {
+        throw networkFailure(error, call.mode, timeout.aborted, call.connectionId);
+    }
+    let text;
+    try {
+        text = await response.text();
+    }
+    catch (error) {
+        if (response.ok && call.mode === "send")
+            return { status: response.status, text: "" };
+        throw networkFailure(error, call.mode, timeout.aborted, call.connectionId);
+    }
+    return { status: response.status, text };
+}
+export function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}