@foldrun/core 0.3.0 → 0.5.0

package/dist/src/translator.js

@@ -29,6 +29,8 @@ import http from "node:http";
 import crypto from "node:crypto";
 import { PROTECTED_PARAMS } from "./providers.js";
 import { viaEgress } from "./egress.js";
+import { trimSlashes } from "./paths.js";
+import { captureRefusalHeaders, isRefusalStatus, refusalLine } from "./refusal.js";
 function dropped() {
     const seen = new Set();
     return {
@@ -390,17 +392,42 @@ export function toResponses(req, opts, drop = dropped()) {
     }
     return out;
 }
-// ------------------------------------------------------- response mapping
-function stopReason(finish) {
-    switch (finish) {
-        case "tool_calls":
-        case "function_call":
-            return "tool_use";
-        case "length":
-            return "max_tokens";
-        default:
-            return "end_turn";
-    }
+/**
+ * Why a Chat Completion stopped, in Anthropic's words. `content_filter`
+ * (OpenAI, Azure, Gemini's safety block) is a refusal; Mistral's
+ * `model_length` is the context window filling, not max_tokens. A stop
+ * sequence is named only where the provider says which one matched — vLLM
+ * as `stop_reason`, SGLang as `matched_stop` — and only when it is one the
+ * request asked for; plain OpenAI says `stop` either way, which reads as
+ * end_turn. pause_turn has no counterpart: server-side tools are dropped.
+ */
+function chatStop(choice, sawTool, stops) {
+    const finish = choice.finish_reason;
+    if (finish === "content_filter")
+        return { reason: "refusal", sequence: null };
+    if (finish === "length")
+        return { reason: "max_tokens", sequence: null };
+    if (finish === "model_length")
+        return { reason: "model_context_window_exceeded", sequence: null };
+    if (sawTool || finish === "tool_calls" || finish === "function_call")
+        return { reason: "tool_use", sequence: null };
+    const matched = typeof choice.stop_reason === "string" ? choice.stop_reason : choice.matched_stop;
+    if (typeof matched === "string" && stops.includes(matched))
+        return { reason: "stop_sequence", sequence: matched };
+    return { reason: "end_turn", sequence: null };
+}
+/** Why a Response stopped: a refusal part or a content filter is a refusal. */
+function responsesStop(incomplete, sawTool, sawRefusal) {
+    if (sawRefusal || incomplete === "content_filter")
+        return "refusal";
+    if (incomplete === "max_output_tokens")
+        return "max_tokens";
+    if (sawTool)
+        return "tool_use";
+    return "end_turn";
+}
+function stopList(stops) {
+    return Array.isArray(stops) ? stops.filter((s) => typeof s === "string") : [];
 }
 function parseArgs(raw) {
     if (typeof raw !== "string" || !raw.trim())
@@ -413,7 +440,7 @@ function parseArgs(raw) {
     }
 }
 /** A finished Chat Completion as an Anthropic message. Pure. */
-export function fromChatCompletion(res, requestedModel) {
+export function fromChatCompletion(res, requestedModel, stopSequences) {
     const choice = (res.choices ?? [])[0] ?? {};
     const msg = choice.message ?? {};
     const content = [];
@@ -430,14 +457,15 @@ export function fromChatCompletion(res, requestedModel) {
         });
     }
     const usage = res.usage ?? {};
+    const stop = chatStop(choice, content.some((c) => c.type === "tool_use"), stopList(stopSequences));
     return {
         id: String(res.id ?? `msg_${crypto.randomBytes(8).toString("hex")}`),
         type: "message",
         role: "assistant",
         model: String(res.model ?? requestedModel),
         content,
-        stop_reason: stopReason(choice.finish_reason),
-        stop_sequence: null,
+        stop_reason: stop.reason,
+        stop_sequence: stop.sequence,
         usage: {
             input_tokens: Number(usage.prompt_tokens ?? 0),
             output_tokens: Number(usage.completion_tokens ?? 0),
@@ -457,12 +485,15 @@ export class StreamTranslator {
     textIndex = null;
     /** Chat-Completions tool index → Anthropic block index. */
     tools = new Map();
-    finish = null;
+    /** The last choice's stop fields: finish_reason and any matched stop. */
+    finish = {};
     usage = null;
     id = `msg_${crypto.randomBytes(8).toString("hex")}`;
     model;
-    constructor(model) {
+    stops;
+    constructor(model, stopSequences) {
         this.model = model;
+        this.stops = stopList(stopSequences);
     }
     event(name, data) {
         return `event: ${name}\ndata: ${JSON.stringify(data)}\n\n`;
@@ -507,7 +538,7 @@ export class StreamTranslator {
         if (!choice)
             return out;
         if (choice.finish_reason)
-            this.finish = choice.finish_reason;
+            this.finish = { finish_reason: choice.finish_reason, stop_reason: choice.stop_reason, matched_stop: choice.matched_stop };
         const delta = choice.delta ?? {};
         const text = typeof delta.content === "string" ? delta.content : "";
         if (text) {
@@ -574,10 +605,10 @@ export class StreamTranslator {
             }
             out.push(this.event("content_block_stop", { type: "content_block_stop", index: entry.block }));
         }
-        const reason = this.tools.size && this.finish !== "length" ? "tool_use" : stopReason(this.finish);
+        const stop = chatStop(this.finish, this.tools.size > 0, this.stops);
         out.push(this.event("message_delta", {
             type: "message_delta",
-            delta: { stop_reason: reason, stop_sequence: null },
+            delta: { stop_reason: stop.reason, stop_sequence: stop.sequence },
             usage: { input_tokens: this.usage?.input ?? 0, output_tokens: this.usage?.output ?? 0 },
         }));
         out.push(this.event("message_stop", { type: "message_stop" }));
@@ -607,7 +638,8 @@ export function fromResponses(res, requestedModel) {
     }
     const usage = res.usage ?? {};
     const incomplete = res.incomplete_details?.reason;
-    const stop = content.some((c) => c.type === "tool_use") ? "tool_use" : incomplete === "max_output_tokens" ? "max_tokens" : "end_turn";
+    const refused = (Array.isArray(res.output) ? res.output : []).some((item) => item.type === "message" && Array.isArray(item.content) && item.content.some((c) => c.type === "refusal"));
+    const stop = responsesStop(incomplete, content.some((c) => c.type === "tool_use"), refused);
     return {
         id: String(res.id ?? `msg_${crypto.randomBytes(8).toString("hex")}`),
         type: "message",
@@ -637,6 +669,7 @@ export class ResponsesStreamTranslator {
     usage = null;
     incomplete = null;
     sawTool = false;
+    sawRefusal = false;
     id = `msg_${crypto.randomBytes(8).toString("hex")}`;
     model;
     constructor(model) {
@@ -699,6 +732,8 @@ export class ResponsesStreamTranslator {
         if (type === "response.output_text.delta" || type === "response.refusal.delta") {
             const entry = this.blocks.get(Number(ev.output_index));
             const text = String(ev.delta ?? "");
+            if (type === "response.refusal.delta")
+                this.sawRefusal = true;
             if (entry && entry.kind === "text" && text) {
                 out.push(this.event("content_block_delta", { type: "content_block_delta", index: entry.block, delta: { type: "text_delta", text } }));
             }
@@ -751,7 +786,7 @@ export class ResponsesStreamTranslator {
             }
             out.push(this.event("content_block_stop", { type: "content_block_stop", index: entry.block }));
         }
-        const reason = this.sawTool && this.incomplete !== "max_output_tokens" ? "tool_use" : this.incomplete === "max_output_tokens" ? "max_tokens" : "end_turn";
+        const reason = responsesStop(this.incomplete, this.sawTool, this.sawRefusal);
         out.push(this.event("message_delta", {
             type: "message_delta",
             delta: { stop_reason: reason, stop_sequence: null },
@@ -806,7 +841,7 @@ function upstreamMessage(text, status) {
 export async function startTranslator(spec) {
     const key = `fr-${crypto.randomBytes(16).toString("hex")}`;
     const log = [];
-    const base = spec.upstreamBase.replace(/\/+$/, "");
+    const base = trimSlashes(spec.upstreamBase);
     const label = spec.label ?? base;
     const server = http.createServer(async (req, res) => {
         const started = Date.now();
@@ -872,6 +907,18 @@ export async function startTranslator(spec) {
                 const text = await upstream.text();
                 const message = upstreamMessage(text, upstream.status);
                 log.push(`POST ${label} → ${upstream.status} (${Date.now() - started}ms): ${message.slice(0, 160)}`);
+                // The refusal in words, from the headers the response already
+                // carried. Only on a refusal, and only the allow-listed headers:
+                // a 400 about a malformed body is the work's problem, not the
+                // supply's, and explaining it as one would mislead.
+                if (isRefusalStatus(upstream.status)) {
+                    log.push(refusalLine({
+                        status: upstream.status,
+                        headers: captureRefusalHeaders(upstream.headers),
+                        timezone: spec.timezone,
+                        provider: label,
+                    }));
+                }
                 // The status crosses unchanged, so a 401 or 429 from the provider
                 // reads as one to the SDK — and to the fallback decision upstream.
                 return send(upstream.status, errorBody(upstream.status, message));
@@ -887,10 +934,10 @@ export async function startTranslator(spec) {
                     return send(502, errorBody(502, `translator: ${label} answered with something that is not JSON`));
                 }
                 log.push(`POST ${label} → 200 (${Date.now() - started}ms, ${model})`);
-                return send(200, JSON.stringify(responses ? fromResponses(parsed, model) : fromChatCompletion(parsed, model)));
+                return send(200, JSON.stringify(responses ? fromResponses(parsed, model) : fromChatCompletion(parsed, model, body.stop_sequences)));
             }
             res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" });
-            const machine = responses ? new ResponsesStreamTranslator(model) : new StreamTranslator(model);
+            const machine = responses ? new ResponsesStreamTranslator(model) : new StreamTranslator(model, body.stop_sequences);
             const reader = upstream.body?.getReader();
             if (!reader) {
                 for (const e of machine.finishStream())

package/dist/src/trigger-log.d.ts

@@ -0,0 +1,43 @@
+/** What became of one trigger firing. `started` is here too: without it the
+ *  log answers "why did nothing run" and not "how often does anything",
+ *  and the ratio is the whole point of the page. */
+export type TriggerOutcome = "started" | "duplicate" | "throttled" | "debounced" | "quarantined" | "paused" | "overlap-skipped" | "missed" | "failed";
+export interface TriggerEvent {
+    t: string;
+    flow: string;
+    /** The flow's `trigger:` — schedule, webhook, storage, watch, flow, email. */
+    trigger: string;
+    outcome: TriggerOutcome;
+    /** The sentence a person reads. Always says which key decided, so the fix
+     *  is one search away in their own flow file. */
+    detail?: string;
+    runId?: string;
+}
+/** Never throws. A diagnostic that can break a trigger is worse than no
+ *  diagnostic: the whole point is to be reading it on the bad morning. */
+export declare function recordTriggerEvent(tenant: string, workspace: string, event: TriggerEvent): void;
+export declare function readTriggerEvents(tenant: string, workspace: string, limit?: number): TriggerEvent[];
+export interface FlowTriggerSummary {
+    flow: string;
+    trigger: string;
+    fired: number;
+    started: number;
+    /** Every outcome that was not a start, by reason, biggest first. */
+    dropped: {
+        outcome: TriggerOutcome;
+        count: number;
+        detail: string;
+    }[];
+    lastFiredAt: string | null;
+    lastStartedAt: string | null;
+}
+/**
+ * One row per flow: how often it fired, how often that became a run, and
+ * what happened to the difference.
+ *
+ * The gap between `fired` and `started` is the number someone is looking
+ * for. A flow with forty fires and two runs is either working exactly as
+ * configured or badly misconfigured, and the reasons column is what tells
+ * those apart without opening the flow file.
+ */
+export declare function summariseTriggers(tenant: string, workspace: string, sinceMs?: number | null): FlowTriggerSummary[];

package/dist/src/trigger-log.js

@@ -0,0 +1,122 @@
+// Why nothing happened.
+//
+// A run that exists can be read. A run that does not exist leaves no record
+// anywhere, and "the hook fired but nothing ran" is the hardest question the
+// platform gets asked — because every honest answer to it is a thing that
+// deliberately did NOT happen:
+//
+//   the delivery was a duplicate          idempotency:
+//   the burst is still being waited out   debounce:
+//   it arrived inside the window          throttle:
+//   the flow is switched off              disable_after:
+//   yesterday's run is still going        overlap: skip
+//   the platform was down at 05:00        catchup: none
+//
+// Six different reasons, all of them correct behaviour, none of them visible.
+// Before this they were console lines on a box nobody reads.
+//
+// This is deliberately NOT the hook delivery log next door. That one answers
+// "did the request reach us and was it authentic" — a bad token, a failed
+// signature. This one answers "did an event become a run". A delivery can be
+// perfectly authentic and still not start anything, which is exactly the
+// case that needed writing down.
+//
+// One bounded JSONL per workspace, the same shape and the same compaction as
+// the delivery log: this is diagnostics, not an audit trail, and it must
+// never become a disk-full incident with a delay.
+import fs from "node:fs";
+import path from "node:path";
+import { workspaceDir } from "./store.js";
+function logFile(tenant, workspace) {
+    return path.join(workspaceDir(tenant, workspace), "trigger-log.jsonl");
+}
+const KEEP = 500;
+/** Never throws. A diagnostic that can break a trigger is worse than no
+ *  diagnostic: the whole point is to be reading it on the bad morning. */
+export function recordTriggerEvent(tenant, workspace, event) {
+    try {
+        const file = logFile(tenant, workspace);
+        if (!fs.existsSync(path.dirname(file)))
+            return;
+        fs.appendFileSync(file, JSON.stringify(event) + "\n");
+        const lines = fs.readFileSync(file, "utf8").split("\n").filter(Boolean);
+        if (lines.length > KEEP * 2) {
+            const tmp = `${file}.tmp`;
+            fs.writeFileSync(tmp, lines.slice(-KEEP).join("\n") + "\n");
+            fs.renameSync(tmp, file);
+        }
+    }
+    catch {
+        // best effort, always
+    }
+}
+export function readTriggerEvents(tenant, workspace, limit = 200) {
+    let lines;
+    try {
+        lines = fs.readFileSync(logFile(tenant, workspace), "utf8").split("\n").filter(Boolean);
+    }
+    catch {
+        return [];
+    }
+    // One line at a time: a torn line — an append racing a compaction from
+    // another pod — must lose that line, not the whole log, on exactly the
+    // morning the log exists for.
+    const out = [];
+    for (const line of lines.slice(-limit).reverse()) {
+        try {
+            const e = JSON.parse(line);
+            if (e && typeof e.t === "string")
+                out.push(e);
+        }
+        catch {
+            // skip the torn line
+        }
+    }
+    return out;
+}
+/**
+ * One row per flow: how often it fired, how often that became a run, and
+ * what happened to the difference.
+ *
+ * The gap between `fired` and `started` is the number someone is looking
+ * for. A flow with forty fires and two runs is either working exactly as
+ * configured or badly misconfigured, and the reasons column is what tells
+ * those apart without opening the flow file.
+ */
+export function summariseTriggers(tenant, workspace, sinceMs = null) {
+    const rows = new Map();
+    const reasons = new Map();
+    for (const e of readTriggerEvents(tenant, workspace, 500)) {
+        if (sinceMs !== null && new Date(e.t).getTime() < sinceMs)
+            continue;
+        let row = rows.get(e.flow);
+        if (!row) {
+            row = { flow: e.flow, trigger: e.trigger, fired: 0, started: 0, dropped: [], lastFiredAt: null, lastStartedAt: null };
+            rows.set(e.flow, row);
+            reasons.set(e.flow, new Map());
+        }
+        row.fired++;
+        // Events come back newest first, so the first of each is the latest.
+        row.lastFiredAt ??= e.t;
+        if (e.outcome === "started") {
+            row.started++;
+            row.lastStartedAt ??= e.t;
+        }
+        else {
+            const byReason = reasons.get(e.flow);
+            const seen = byReason.get(e.outcome);
+            // Keep the newest detail: "the last run started 4 minutes ago" is more
+            // use than the same sentence from Tuesday.
+            if (seen)
+                seen.count++;
+            else
+                byReason.set(e.outcome, { count: 1, detail: e.detail ?? "" });
+        }
+    }
+    for (const [flow, byReason] of reasons) {
+        rows.get(flow).dropped = [...byReason.entries()]
+            .map(([outcome, v]) => ({ outcome, ...v }))
+            .sort((a, b) => b.count - a.count);
+    }
+    return [...rows.values()].sort((a, b) => b.fired - a.fired || a.flow.localeCompare(b.flow));
+}

package/dist/src/triggers.d.ts

@@ -1,6 +1,9 @@
 import { type FlowInfo, type FlowStep, type RunRecord } from "./store.ts";
 /** Staple a payload to the first step, the way the run route staples a task. */
 export declare function withTask(steps: FlowStep[], tag: string, body: string): FlowStep[];
+/** Which `on:` a settled run answers to: failed, blocked (completed, but
+ *  its work refused itself), or completed. */
+export declare function endingOf(run: RunRecord): "completed" | "failed" | "blocked";
 /** The flows a finished run should start, by this workspace's own files. */
 export declare function chainedFlows(tenant: string, workspace: string, finished: RunRecord): FlowInfo[];
 /**
@@ -22,6 +25,26 @@ export declare function underPrefix(rel: string, prefix: string | null): boolean
  * a loop — every other writer counts.
  */
 export declare function fireStorageTriggers(tenant: string, workspace: string, paths: string[], by: string): Promise<string[]>;
+/**
+ * The value that identifies this delivery, as the flow's `idempotency:`
+ * names it.
+ *
+ * Two shapes, and only two:
+ *
+ *   idempotency: x-github-delivery   a request header
+ *   idempotency: body:id             a top-level field of a JSON body
+ *
+ * A NAME, never an expression — the grammar has no expressions, and this is
+ * not the place to grow one. Nothing is computed, combined or nested: if the
+ * sender does not put an identifier somewhere a name can reach, the flow
+ * cannot dedupe on it, and saying so is better than inventing a syntax.
+ *
+ * Returns null when the flow asks for no key, or when the delivery does not
+ * carry the one it asked for. A missing key admits the delivery: refusing
+ * one because a sender omitted a header would turn "dedupe when you can"
+ * into an outage.
+ */
+export declare function deliveryKey(idempotency: string | null, header: (name: string) => string | null, body: string): string | null;
 export interface SignatureVerdict {
     ok: boolean;
     reason: string;

package/dist/src/triggers.js

@@ -13,7 +13,7 @@
 // an agent reads it — the same rule as every other handoff in the format.
 import crypto from "node:crypto";
 import { platform } from "./platform.js";
-import { listFlows, readRun } from "./store.js";
+import { listFlows, readRun, runVerdict } from "./store.js";
 import { getSecret } from "./secrets.js";
 /** The last step's result — the same reading runner.ts makes, kept local so
  *  this module never imports the runner (the queue imports both). */
@@ -33,6 +33,13 @@ export function withTask(steps, tag, body) {
     return steps.map((s, i) => (i === 0 ? { ...s, instruction: `${s.instruction}\n\n<${tag}>\n${text}\n</${tag}>` } : s));
 }
 // ------------------------------------------------------------ trigger: flow
+/** Which `on:` a settled run answers to: failed, blocked (completed, but
+ *  its work refused itself), or completed. */
+export function endingOf(run) {
+    if (run.status === "failed")
+        return "failed";
+    return runVerdict(run) === "BLOCKED" ? "blocked" : "completed";
+}
 /** The flows a finished run should start, by this workspace's own files. */
 export function chainedFlows(tenant, workspace, finished) {
     if (finished.status !== "completed" && finished.status !== "failed")
@@ -45,7 +52,7 @@ export function chainedFlows(tenant, workspace, finished) {
         // A flow chained on itself is a loop with no bound — refused here and
         // by foldrun check, never started.
         f.name !== finished.flow &&
-        (f.on === "any" || f.on === finished.status));
+        (f.on === "any" || f.on === endingOf(finished)));
 }
 /**
  * Start every flow chained on a run that just settled. The finished run's
@@ -61,15 +68,29 @@ export async function fireChainedFlows(tenant, workspace, finished) {
     const started = [];
     const result = (runResult(finished) ?? "").slice(0, 20_000);
     const body = `run: ${finished.id}\nflow: ${finished.flow}\nstatus: ${finished.status}\n` +
+        (runVerdict(finished) ? `verdict: ${runVerdict(finished)}\n` : "") +
         (finished.summary ? `summary: ${finished.summary}\n` : "") +
         (result ? `\n${result}` : "");
     for (const flow of flows) {
         try {
-            const run = await platform.enqueueFlowRun(tenant, workspace, withTask(flow.steps, "previous_run", body), flow.name, flow.model, [
-                `after:${finished.flow}`,
-            ]);
-            started.push(run.id);
-            console.log(`[foldrun] trigger: flow — ${tenant}/${workspace}/${flow.name} started after ${finished.flow} ${finished.status}`);
+            const gate = await platform.admitTrigger(tenant, workspace, flow, { body, tag: "previous_run" });
+            if (!gate.admit) {
+                console.log(`[foldrun] trigger: flow — ${tenant}/${workspace}/${flow.name} not started: ${gate.detail}`);
+                continue;
+            }
+            try {
+                // A test run's chain stays a test: the flow after it reads a result
+                // nothing real produced, and must not act on it for real either.
+                const run = await platform.enqueueFlowRun(tenant, workspace, withTask(flow.steps, "previous_run", body), flow.name, flow.model, [
+                    `after:${finished.flow}`,
+                ], null, finished.test ? { test: true } : {});
+                started.push(run.id);
+                console.log(`[foldrun] trigger: flow — ${tenant}/${workspace}/${flow.name} started after ${finished.flow} ${finished.status}`);
+            }
+            catch (err) {
+                await platform.rollbackTrigger(tenant, workspace, flow, { reason: err instanceof Error ? err.message : String(err) });
+                throw err;
+            }
         }
         catch (err) {
             console.error(`[foldrun] trigger: flow — ${tenant}/${workspace}/${flow.name}:`, err instanceof Error ? err.message : err);
@@ -115,10 +136,23 @@ export async function fireStorageTriggers(tenant, workspace, paths, by) {
             continue;
         try {
             const body = `by: ${by}\n${hits.map((h) => `- storage/${h}`).join("\n")}`;
-            const run = await platform.enqueueFlowRun(tenant, workspace, withTask(flow.steps, "storage_event", body), flow.name, flow.model, [
-                "storage",
-            ]);
-            started.push(run.id);
+            // A deploy that writes forty files under one prefix is one event, not
+            // forty runs — which is exactly what `debounce:` is for.
+            const gate = await platform.admitTrigger(tenant, workspace, flow, { body, tag: "storage_event" });
+            if (!gate.admit) {
+                console.log(`[foldrun] trigger: storage — ${tenant}/${workspace}/${flow.name} not started: ${gate.detail}`);
+                continue;
+            }
+            try {
+                const run = await platform.enqueueFlowRun(tenant, workspace, withTask(flow.steps, "storage_event", body), flow.name, flow.model, [
+                    "storage",
+                ]);
+                started.push(run.id);
+            }
+            catch (err) {
+                await platform.rollbackTrigger(tenant, workspace, flow, { reason: err instanceof Error ? err.message : String(err) });
+                throw err;
+            }
         }
         catch (err) {
             console.error(`[foldrun] trigger: storage — ${tenant}/${workspace}/${flow.name}:`, err instanceof Error ? err.message : err);
@@ -126,6 +160,61 @@ export async function fireStorageTriggers(tenant, workspace, paths, by) {
     }
     return started;
 }
+/** HTML to the text a prompt reads. Style and script blocks are removed
+ *  until none remain — one pass leaves `<sty<style>le>` behind, which is
+ *  the shape a sanitiser checker (rightly) flags. Nothing here is rendered
+ *  as HTML afterwards; it becomes a task for an agent. */
+function stripTags(html) {
+    let out = html;
+    for (let prev = ""; prev !== out;) {
+        prev = out;
+        out = out.replace(/<(style|script)\b[^>]*>[\s\S]*?<\/\1\s*>/gi, "");
+    }
+    return out.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+}
+// ------------------------------------------------------- idempotency keys
+/**
+ * The value that identifies this delivery, as the flow's `idempotency:`
+ * names it.
+ *
+ * Two shapes, and only two:
+ *
+ *   idempotency: x-github-delivery   a request header
+ *   idempotency: body:id             a top-level field of a JSON body
+ *
+ * A NAME, never an expression — the grammar has no expressions, and this is
+ * not the place to grow one. Nothing is computed, combined or nested: if the
+ * sender does not put an identifier somewhere a name can reach, the flow
+ * cannot dedupe on it, and saying so is better than inventing a syntax.
+ *
+ * Returns null when the flow asks for no key, or when the delivery does not
+ * carry the one it asked for. A missing key admits the delivery: refusing
+ * one because a sender omitted a header would turn "dedupe when you can"
+ * into an outage.
+ */
+export function deliveryKey(idempotency, header, body) {
+    if (!idempotency)
+        return null;
+    if (idempotency.startsWith("body:")) {
+        const field = idempotency.slice(5).trim();
+        if (!field)
+            return null;
+        try {
+            const parsed = JSON.parse(body);
+            const value = parsed?.[field];
+            // A scalar only. An object stringifies to "[object Object]" for every
+            // delivery, which would make the second one and every one after it a
+            // "duplicate" of the first.
+            if (value === undefined || value === null || typeof value === "object")
+                return null;
+            return String(value).slice(0, 200);
+        }
+        catch {
+            return null; // not JSON, so no field to read
+        }
+    }
+    return header(idempotency)?.slice(0, 200) || null;
+}
 function safeEqual(a, b) {
     const x = Buffer.from(a);
     const y = Buffer.from(b);
@@ -259,7 +348,7 @@ export function normaliseInboundEmail(contentType, raw) {
     const subject = pick("subject", "Subject");
     const html = pick("html", "HtmlBody", "body-html");
     const text = pick("text", "TextBody", "body-plain", "stripped-text", "plain") ||
-        html.replace(/<style[\s\S]*?<\/style>/gi, "").replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+        stripTags(html);
     if (!from && !subject && !text)
         return null;
     return { from, to: pick("to", "To", "recipient", "ToFull"), subject, text };

package/dist/src/untrusted-fetch.d.ts

@@ -0,0 +1,11 @@
+/** How many redirects one request may follow. fetch's own limit is 20;
+ *  nothing a tenant points the platform at needs more than a couple. */
+export declare const MAX_REDIRECTS = 5;
+export declare class RedirectRefused extends Error {
+    constructor(message: string);
+}
+export declare function fetchUntrusted(url: string, init?: RequestInit, opts?: {
+    /** The request carries a credential (in its body or its headers):
+     *  follow a redirect only within the origin it was sent to. */
+    sameOrigin?: boolean;
+}): Promise<Response>;

package/dist/src/untrusted-fetch.js

@@ -0,0 +1,77 @@
+// fetch() for a URL a tenant chose, redirects included.
+//
+// platform.fetchUntrusted is the seam: on a platform it refuses private and
+// cluster addresses (by name, by IP literal, and at connect time through a
+// guarded DNS lookup). But it was handed fetch's default `redirect:
+// "follow"`, and a redirect is followed inside fetch, past the seam: a
+// public host answering `302 Location: http://169.254.169.254/…` sent the
+// platform to the metadata endpoint, because an IP literal never reaches the
+// DNS lookup the connect-time guard lives in. And the OAuth token POSTs
+// carried a client secret to wherever a 307 pointed.
+//
+// So redirects are followed here, one hop at a time, each hop through the
+// seam again — every address a request ends up at is checked the same way
+// the first one was. A hop to another origin keeps only the headers that
+// cannot carry a credential, and a caller whose request IS a credential
+// (a token exchange, a provider key in a header) follows none at all.
+import { platform } from "./platform.js";
+/** How many redirects one request may follow. fetch's own limit is 20;
+ *  nothing a tenant points the platform at needs more than a couple. */
+export const MAX_REDIRECTS = 5;
+const REDIRECT = new Set([301, 302, 303, 307, 308]);
+/** Headers that may cross to another origin: none of them can carry a
+ *  credential. Everything else — Authorization, a cookie, an x-api-key, a
+ *  webhook's signature — stays with the origin it was meant for. */
+const CROSS_ORIGIN_SAFE = new Set(["accept", "accept-language", "content-type", "user-agent"]);
+export class RedirectRefused extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RedirectRefused";
+    }
+}
+export async function fetchUntrusted(url, init = {}, opts = {}) {
+    let current = url;
+    let req = { ...init };
+    for (let hop = 0;; hop++) {
+        const res = await platform.fetchUntrusted(current, { ...req, redirect: "manual" });
+        const location = REDIRECT.has(res.status) ? res.headers.get("location") : null;
+        if (!location)
+            return res;
+        // The body of a redirect is never read; free the socket.
+        await res.body?.cancel().catch(() => { });
+        if (hop >= MAX_REDIRECTS)
+            throw new RedirectRefused(`${url}: more than ${MAX_REDIRECTS} redirects — not followed`);
+        let next;
+        try {
+            next = new URL(location, current);
+        }
+        catch {
+            throw new RedirectRefused(`${current} redirected to "${location}", which is not a URL`);
+        }
+        if (next.protocol !== "https:" && next.protocol !== "http:") {
+            throw new RedirectRefused(`${current} redirected to a ${next.protocol} URL — not followed`);
+        }
+        const from = new URL(current);
+        const crossOrigin = next.origin !== from.origin;
+        if (crossOrigin && opts.sameOrigin) {
+            throw new RedirectRefused(`${from.origin} redirected to ${next.origin} — not followed: this request carries a credential, and it goes only where it was sent`);
+        }
+        // fetch's own rewrite: a 303, and a 301/302 answering a POST, is
+        // followed as a GET with no body; a 307/308 repeats the request as it was.
+        const method = (req.method ?? "GET").toUpperCase();
+        const headers = new Headers(req.headers);
+        if ((res.status === 303 && method !== "GET" && method !== "HEAD") || ((res.status === 301 || res.status === 302) && method === "POST")) {
+            req = { ...req, method: "GET", body: undefined };
+            headers.delete("content-type");
+        }
+        if (crossOrigin) {
+            const names = [];
+            headers.forEach((_, name) => names.push(name));
+            for (const name of names)
+                if (!CROSS_ORIGIN_SAFE.has(name))
+                    headers.delete(name);
+        }
+        req = { ...req, headers };
+        current = next.toString();
+    }
+}