@foldrun/core 2.10.1 → 2.11.0

package/dist/src/store.d.ts

@@ -567,6 +567,13 @@ export interface FlowInfo {
     /** `trigger: storage` — a path prefix under storage/; a file landing
      *  there starts the flow with the path as its task. */
     path: string | null;
+    /** `filter:` — the fields a delivery must have before it becomes a run
+     *  (trigger-filter.ts): matched against a webhook's JSON body, an email,
+     *  a chained run or a storage event. Null: no `filter:` line, every
+     *  delivery. Kept exactly as written — a list, `false`, a word — so one
+     *  that cannot be read matches nothing (fails closed) rather than reading
+     *  as no filter at all. Test it with `!= null`, never for truthiness. */
+    filter: unknown;
     /** `idempotency:` — the name of the field that identifies a delivery, so
      *  the same one twice starts one run. A header on the request
      *  ("x-github-delivery"), or "body:<key>" for a top-level field of a JSON
@@ -820,6 +827,7 @@ export declare function listWorkspaces(tenant: string): WorkspaceSummary[];
  * listing asks the writer, so a path that can be saved is a path that shows.
  */
 export declare function isEditablePath(rel: string): boolean;
+export declare function assertEditablePath(rel: string): string;
 export declare function accountFileSealed(rel: string): string | null;
 /**
  * The account directory as it actually is on disk.

package/dist/src/store.js

@@ -43,6 +43,7 @@ export function readFrontmatter(file) {
 }
 import { ownToolNames, legacyUseNames, retiredToolNames } from "./tool-names.js";
 import { refNames } from "./refs.js";
+import { checkFilter } from "./trigger-filter.js";
 import { parseBudget, budgetProblem } from "./budget.js";
 import { timezoneProblem } from "./clock.js";
 import { parseStepLimits, readLimits } from "./limits.js";
@@ -1617,6 +1618,8 @@ export function parseFlow(file, raw) {
     badEnum("catchup", data.catchup, ["none", "last"]);
     badEnum("on", data.on, ["completed", "failed", "blocked", "any"]);
     badEnum("signature", data.signature, ["github", "stripe", "slack", "hmac"]);
+    for (const p of checkFilter(data.filter))
+        frontProblems.push(p);
     steps.sort((a, b) => a.group - b.group);
     return {
         name: data.name ?? file.replace(/\.md$/, ""),
@@ -1646,6 +1649,7 @@ export function parseFlow(file, raw) {
             ? data.signing_secret.trim().replace(/^\$\{|\}$/g, "")
             : null,
         path: typeof data.path === "string" ? data.path.trim().replace(/^\/+/, "") : null,
+        filter: data.filter === undefined || data.filter === null ? null : data.filter,
         // A header name is case-insensitive on the wire; a JSON field is not.
         // `body:eventId` lower-cased to `body:eventid` matched nothing, and a
         // dedupe that matches nothing admits everything.
@@ -2125,7 +2129,7 @@ export function isEditablePath(rel) {
         return false;
     }
 }
-function assertEditablePath(rel) {
+export function assertEditablePath(rel) {
     const norm = path.normalize(rel);
     if (norm.startsWith("..") || path.isAbsolute(norm))
         throw new Error(`illegal path: ${rel}`);

package/dist/src/tar.d.ts

@@ -0,0 +1,30 @@
+export interface TarEntry {
+    path: string;
+    content: Buffer;
+}
+/**
+ * Every regular file in a gzipped tarball.
+ *
+ * Directories, symlinks, and pax/global headers are skipped: a workspace is
+ * files, and following a link out of the archive is exactly the thing a deploy
+ * from an untrusted repository must not do.
+ */
+export declare function readTarGz(gz: Buffer): TarEntry[];
+/**
+ * Drop the single wrapper directory an archive is rooted at.
+ *
+ * GitHub tarballs are rooted at `owner-repo-<sha>/`, which is not part of
+ * anyone's workspace. Stripped only when *every* entry shares one first
+ * segment, so an archive that is already flat is left alone.
+ */
+export declare function stripRoot(entries: TarEntry[]): TarEntry[];
+/**
+ * Read a tarball as the file list a deploy ships.
+ *
+ * `subdir` picks a workspace living inside a larger repository — the common
+ * case, since a repo usually holds more than one thing.
+ */
+export declare function filesFromTarball(gz: Buffer, subdir?: string): {
+    path: string;
+    content: string;
+}[];

package/dist/src/tar.js

@@ -0,0 +1,112 @@
+// Reading a .tar.gz, so a deploy can come from a GitHub tarball.
+//
+// `GET /repos/{owner}/{repo}/tarball/{sha}` is one HTTP call and needs no git
+// binary, no clone, and no working copy on the server — which is the whole
+// reason a markdown workspace can deploy from a webhook in a few hundred
+// milliseconds. What it returns is a tar.gz, and Node has gzip but not tar.
+//
+// Deliberately dependency-free, for the same reason the cron parser is: tar is
+// 512-byte blocks with an octal size field, and a reader is shorter than the
+// argument about which library to add.
+import zlib from "node:zlib";
+import { trimSlashes } from "./paths.js";
+const BLOCK = 512;
+const str = (b, off, len) => {
+    const raw = b.subarray(off, off + len);
+    const end = raw.indexOf(0);
+    return raw.subarray(0, end === -1 ? raw.length : end).toString("utf8");
+};
+// Sizes are octal, space- or NUL-padded. GNU also writes base-256 for large
+// files, flagged by the high bit — irrelevant for markdown, but a silent
+// misparse would be worse than a clear refusal.
+function size(b, off) {
+    if (b[off] & 0x80)
+        throw new Error("tar: base-256 size field is not supported");
+    const raw = str(b, off, 12).trim();
+    return raw ? parseInt(raw, 8) : 0;
+}
+/**
+ * Every regular file in a gzipped tarball.
+ *
+ * Directories, symlinks, and pax/global headers are skipped: a workspace is
+ * files, and following a link out of the archive is exactly the thing a deploy
+ * from an untrusted repository must not do.
+ */
+export function readTarGz(gz) {
+    const buf = zlib.gunzipSync(gz);
+    const out = [];
+    let longName = null;
+    for (let off = 0; off + BLOCK <= buf.length;) {
+        const header = buf.subarray(off, off + BLOCK);
+        // Two consecutive zero blocks end the archive; one is enough to stop.
+        if (header.every((b) => b === 0))
+            break;
+        const name = str(header, 0, 100);
+        const bytes = size(header, 124);
+        const type = String.fromCharCode(header[156]) || "0";
+        const prefix = str(header, 345, 155);
+        off += BLOCK;
+        const body = buf.subarray(off, off + bytes);
+        off += Math.ceil(bytes / BLOCK) * BLOCK;
+        // GNU long name: the next header's name lives in this entry's body.
+        if (type === "L") {
+            longName = body.toString("utf8").replace(/\0+$/, "");
+            continue;
+        }
+        if (type !== "0" && type !== "\0") {
+            longName = null;
+            continue;
+        }
+        const full = longName ?? (prefix ? `${prefix}/${name}` : name);
+        longName = null;
+        if (full)
+            out.push({ path: full, content: Buffer.from(body) });
+    }
+    return out;
+}
+/**
+ * Drop the single wrapper directory an archive is rooted at.
+ *
+ * GitHub tarballs are rooted at `owner-repo-<sha>/`, which is not part of
+ * anyone's workspace. Stripped only when *every* entry shares one first
+ * segment, so an archive that is already flat is left alone.
+ */
+export function stripRoot(entries) {
+    if (entries.length === 0)
+        return entries;
+    const first = entries[0].path.split("/")[0];
+    if (!entries.every((e) => e.path.split("/")[0] === first && e.path.includes("/"))) {
+        return entries;
+    }
+    return entries.map((e) => ({ ...e, path: e.path.slice(first.length + 1) }));
+}
+/**
+ * Read a tarball as the file list a deploy ships.
+ *
+ * `subdir` picks a workspace living inside a larger repository — the common
+ * case, since a repo usually holds more than one thing.
+ */
+export function filesFromTarball(gz, subdir = "") {
+    const prefix = trimSlashes(subdir, "both");
+    const out = [];
+    for (const entry of stripRoot(readTarGz(gz))) {
+        let rel = entry.path;
+        if (prefix) {
+            if (!rel.startsWith(`${prefix}/`))
+                continue;
+            rel = rel.slice(prefix.length + 1);
+        }
+        // A tarball is untrusted input: an entry can name anything at all, and
+        // `../` in an archive is the oldest way to write outside the destination.
+        if (rel.split("/").includes("..") || rel.startsWith("/"))
+            continue;
+        // AppleDouble sidecars. macOS `tar` writes a `._name` beside every file to
+        // carry metadata no other system wants; they are not part of anyone's
+        // workspace, and letting one through means a deploy rejected for shipping
+        // a file the author never wrote.
+        if ((rel.split("/").pop() ?? "").startsWith("._"))
+            continue;
+        out.push({ path: rel, content: entry.content.toString("utf8") });
+    }
+    return out;
+}

package/dist/src/tool-test.js

@@ -26,6 +26,7 @@ import { commandFor, resolveRunPath } from "./script-tools.js";
 import { parseRuntime, prepareRuntime } from "./runtime.js";
 import { hostSafeEnv } from "./host-env.js";
 import { linkWorkspace, workspaceLinkEnv } from "./confine.js";
+import { fetchUntrusted, ResponseTooLarge, MAX_BYTES } from "./untrusted-fetch.js";
 const MAX_DETAIL = 4000;
 const TIMEOUT_MS = 15_000;
 // A tool test runs tenant-authored code directly on the host — real runs are
@@ -132,12 +133,21 @@ export async function testTool(tenant, workspace, def, input = {}) {
             const headers = {};
             for (const [k, v] of Object.entries(api.headers))
                 headers[k] = substitute(v, env);
-            const res = await fetch(url, {
-                method,
-                headers,
-                signal: AbortSignal.timeout(TIMEOUT_MS),
-            });
-            const body = await res.text();
+            // A URL the tenant chose, fetched from the web tier: through the
+            // platform's guard (no private or cluster address, each redirect hop
+            // checked), and the secrets in the headers go only to the origin
+            // they were written for.
+            const res = await fetchUntrusted(url.href, { method, headers, signal: AbortSignal.timeout(TIMEOUT_MS) }, { sameOrigin: true });
+            // The status is the test; a body past the limit is said, not shown.
+            let body;
+            try {
+                body = await res.text();
+            }
+            catch (err) {
+                if (!(err instanceof ResponseTooLarge))
+                    throw err;
+                body = `(the answer was larger than ${MAX_BYTES / (1024 * 1024)} MiB — not shown)`;
+            }
             // An unset secret means the tool cannot authenticate, so it is not
             // working — whatever a permissive endpoint chose to return. Reporting
             // ok on a request that went out with no credentials is how you ship a
@@ -308,7 +318,9 @@ export async function testTool(tenant, workspace, def, input = {}) {
         // A remote server: the honest check we can make without a full client is
         // that the endpoint answers.
         try {
-            const res = await fetch(spec.url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+            // Through the platform's guard, as the http probe is; only the status is read.
+            const res = await fetchUntrusted(spec.url, { signal: AbortSignal.timeout(TIMEOUT_MS) }, { sameOrigin: true });
+            await res.body?.cancel().catch(() => { });
             return done({
                 ok: res.ok,
                 transport: "mcp",

package/dist/src/translator.d.ts

@@ -160,6 +160,10 @@ export declare class ResponsesStreamTranslator {
     /** The stream ended: close what is still open, say why, and stop. */
     finishStream(): string[];
 }
+/** The most one upstream answer may be, read, on the host: a long streamed
+ *  reply is many small events, well past fetchUntrusted's 1 MiB default,
+ *  and still far under this. */
+export declare const UPSTREAM_MAX_BYTES: number;
 /**
  * Start the translator for one step. Binds an ephemeral port on loopback,
  * mints the key the SDK will present, and returns the env that points the

package/dist/src/translator.js

@@ -31,6 +31,7 @@ import http from "node:http";
 import crypto from "node:crypto";
 import { PROTECTED_PARAMS } from "./providers.js";
 import { viaEgress } from "./egress.js";
+import { fetchUntrusted } from "./untrusted-fetch.js";
 import { trimSlashes } from "./paths.js";
 import { captureRefusalHeaders, isRefusalStatus, refusalLine } from "./refusal.js";
 /**
@@ -860,6 +861,10 @@ function upstreamMessage(text, status) {
     return text.slice(0, 500) || `upstream returned HTTP ${status}`;
 }
 // ---------------------------------------------------------------- server
+/** The most one upstream answer may be, read, on the host: a long streamed
+ *  reply is many small events, well past fetchUntrusted's 1 MiB default,
+ *  and still far under this. */
+export const UPSTREAM_MAX_BYTES = 64 * 1024 * 1024;
 /**
  * Start the translator for one step. Binds an ephemeral port on loopback,
  * mints the key the SDK will present, and returns the env that points the
@@ -915,7 +920,8 @@ export async function startTranslator(spec) {
                     log.push(line);
             let upstream;
             try {
-                upstream = await fetch(viaEgress(spec.egress, `${base}${responses ? "/responses" : "/chat/completions"}`), {
+                const target = `${base}${responses ? "/responses" : "/chat/completions"}`;
+                const request = {
                     method: "POST",
                     headers: {
                         "content-type": "application/json",
@@ -923,7 +929,16 @@ export async function startTranslator(spec) {
                         ...(spec.headers ?? {}),
                     },
                     body: JSON.stringify(outbound),
-                });
+                };
+                // In a step the lease's proxy is the way out: it guards the address
+                // and fills the key itself. Without one this runs on the host — an
+                // eval's judge, a dashboard draft — at a base URL the tenant wrote,
+                // so through the platform's guard: no private or cluster address,
+                // the key never follows a redirect off the provider's origin, and
+                // the answer read to UPSTREAM_MAX_BYTES.
+                upstream = spec.egress
+                    ? await fetch(viaEgress(spec.egress, target), request)
+                    : await fetchUntrusted(target, request, { sameOrigin: true, maxBytes: UPSTREAM_MAX_BYTES });
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);
@@ -1008,8 +1023,12 @@ export async function startTranslator(spec) {
             log.push(`translator error: ${message}`);
             if (!res.headersSent)
                 send(500, errorBody(500, `translator: ${message}`));
-            else
+            else {
+                // Mid-stream: say so as an Anthropic error event, so the SDK reads a
+                // failed reply, not a short one that merely stopped.
+                res.write(`event: error\ndata: ${errorBody(500, `translator: ${message}`)}\n\n`);
                 res.end();
+            }
         }
     });
     await new Promise((resolve, reject) => {

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

@@ -0,0 +1,28 @@
+export declare const FILTER_LIMITS: {
+    readonly depth: 10;
+    readonly leaves: 64;
+    readonly values: 32;
+    readonly textChars: 500;
+};
+/**
+ * What is wrong with a `filter:` as written, one sentence each — empty when
+ * it can be read. `foldrun check`, the deploy and the editor report these as
+ * `config/invalid-value`.
+ */
+export declare function checkFilter(filter: unknown): string[];
+export interface FilterVerdict {
+    match: boolean;
+    /** Why, in one sentence: the first condition that failed, or "matched". */
+    reason: string;
+}
+/**
+ * Does this payload pass this filter? No filter passes everything. A filter
+ * the check would refuse never matches — it fails closed, so a typo holds
+ * deliveries back instead of letting all of them through.
+ */
+export declare function matchFilter(filter: unknown, payload: unknown): FilterVerdict;
+/** A webhook body as the filter reads it: its JSON, or null when it is not
+ *  JSON (which no filter matches). */
+export declare function webhookFilterPayload(raw: string): unknown;
+/** The triggers a filter means something for. */
+export declare const FILTERABLE_TRIGGERS: readonly ["webhook", "email", "flow", "storage"];

package/dist/src/trigger-filter.js

@@ -0,0 +1,272 @@
+// `filter:` — which deliveries of an event trigger become runs.
+//
+// A webhook flow used to start for every POST that carried the right token:
+// a GitHub hook for "pull requests" started a run for drafts, bot pushes and
+// label changes alike, and the first step's only job was to say "not this
+// one" — a sandbox, a model call and a run on the record, per non-event.
+// A filter says it in the flow's own file, and nothing starts:
+//
+//   filter:
+//     action: [opened, reopened]          # any of these values
+//     pull_request:
+//       draft: false                      # exactly this value
+//       base:
+//         ref: { starts_with: release/ }  # text, never a regular expression
+//     sender:
+//       type: { not_in: [Bot] }           # none of these
+//
+// What the pattern is matched against depends on the trigger: a webhook's
+// JSON body; an email's { from, to, subject, text }; a chained flow's
+// { run, flow, status, verdict, summary }; a storage event's { by, paths }.
+//
+// The rules, all of them:
+//
+//   · every key must match (AND); a nested object matches the nested field;
+//   · a list is the values allowed (any of them); a scalar is the one value;
+//   · an operator object — only the keys in, not_in, exists, starts_with,
+//     ends_with, contains — says it explicitly; the last three compare text
+//     (case-sensitive) and never run a regular expression, so a body a
+//     sender crafts cannot make one backtrack for minutes;
+//   · strings compare exactly and case-sensitively, numbers numerically
+//     (1 equals 1.0), booleans and null as themselves;
+//   · a field that is missing fails `in`, a value and the text operators, and passes
+//     `not_in`; `exists: false` passes only when it is missing;
+//   · a list in the payload: a nested pattern matches when any element
+//     does; `in` matches when any element is allowed, `not_in` when none is;
+//   · it fails closed — a body that is not JSON, or a pattern that cannot be
+//     evaluated, never matches.
+//
+// Pure and browser-safe: the gate, the check, the editor and the dashboard's
+// Test box all call these two functions.
+export const FILTER_LIMITS = { depth: 10, leaves: 64, values: 32, textChars: 500 };
+const TEXT_OPERATORS = ["starts_with", "ends_with", "contains"];
+const TEXT_VERB = { starts_with: "start with", ends_with: "end with", contains: "contain" };
+const OPERATORS = new Set(["in", "not_in", "exists", ...TEXT_OPERATORS]);
+const isScalar = (v) => v === null || typeof v === "string" || typeof v === "number" || typeof v === "boolean";
+const isPlainObject = (v) => !!v && typeof v === "object" && !Array.isArray(v) && !(v instanceof Date);
+/** An object whose every key is an operator — `{ not_in: [Bot] }`. A pattern
+ *  object mixing operators with field names is refused by the check, since
+ *  it cannot be read one way. */
+function isOperatorObject(v) {
+    if (!isPlainObject(v))
+        return false;
+    const keys = Object.keys(v);
+    return keys.length > 0 && keys.every((k) => OPERATORS.has(k));
+}
+/** YAML reads `2026-10-01` as a Date; a filter means the text. */
+const asScalar = (v) => v instanceof Date ? v.toISOString().slice(0, 10) : isScalar(v) ? v : undefined;
+/** Strings exactly, numbers numerically, the rest by identity. */
+function sameValue(a, b) {
+    if (typeof a === "number" && typeof b === "number")
+        return a === b;
+    return a === b;
+}
+const show = (v) => (typeof v === "string" ? JSON.stringify(v) : JSON.stringify(v ?? null));
+/**
+ * What is wrong with a `filter:` as written, one sentence each — empty when
+ * it can be read. `foldrun check`, the deploy and the editor report these as
+ * `config/invalid-value`.
+ */
+export function checkFilter(filter) {
+    const problems = [];
+    if (filter === undefined || filter === null)
+        return problems;
+    if (!isPlainObject(filter) || Object.keys(filter).length === 0) {
+        return ["filter: is a map of field names to the values they must have — e.g. `action: [opened]`"];
+    }
+    let leaves = 0;
+    const walk = (node, where, depth) => {
+        if (depth > FILTER_LIMITS.depth) {
+            problems.push(`filter: nests deeper than ${FILTER_LIMITS.depth} levels at ${where}`);
+            return;
+        }
+        for (const [key, value] of Object.entries(node)) {
+            const at = where ? `${where}.${key}` : key;
+            if (OPERATORS.has(key)) {
+                problems.push(`filter: ${at} — ${key} is an operator; write it under a field name, e.g. \`sender: { ${key}: … }\``);
+                continue;
+            }
+            if (isPlainObject(value) && Object.keys(value).some((k) => OPERATORS.has(k))) {
+                if (!isOperatorObject(value)) {
+                    problems.push(`filter: ${at} mixes operators (${[...OPERATORS].join(", ")}) with field names — split them`);
+                    continue;
+                }
+                leaves++;
+                problems.push(...checkOperators(value, at));
+                continue;
+            }
+            if (isPlainObject(value)) {
+                if (Object.keys(value).length === 0)
+                    problems.push(`filter: ${at} is an empty map, which says nothing`);
+                else
+                    walk(value, at, depth + 1);
+                continue;
+            }
+            leaves++;
+            if (Array.isArray(value))
+                problems.push(...checkValues(value, at, "the list"));
+            else if (asScalar(value) === undefined)
+                problems.push(`filter: ${at} — a value, a list of values, a map, or { in, not_in, exists, starts_with, ends_with, contains }`);
+        }
+    };
+    walk(filter, "", 1);
+    if (leaves > FILTER_LIMITS.leaves)
+        problems.push(`filter: has ${leaves} conditions — at most ${FILTER_LIMITS.leaves}`);
+    return problems;
+}
+function checkValues(list, at, what) {
+    const out = [];
+    if (list.length === 0)
+        out.push(`filter: ${at} — ${what} is empty, so nothing could ever match`);
+    if (list.length > FILTER_LIMITS.values)
+        out.push(`filter: ${at} — ${what} has ${list.length} values, at most ${FILTER_LIMITS.values}`);
+    if (list.some((v) => asScalar(v) === undefined))
+        out.push(`filter: ${at} — ${what} holds only plain values (text, numbers, true/false, null)`);
+    return out;
+}
+function checkOperators(op, at) {
+    const out = [];
+    const list = (k) => {
+        const v = op[k];
+        if (v === undefined)
+            return null;
+        const arr = Array.isArray(v) ? v : [v];
+        out.push(...checkValues(arr, at, k));
+        return arr.map(asScalar).filter((x) => x !== undefined);
+    };
+    const inList = list("in");
+    const notIn = list("not_in");
+    if (inList && notIn) {
+        const both = inList.filter((v) => notIn.some((w) => sameValue(v, w)));
+        if (both.length)
+            out.push(`filter: ${at} lists ${both.map(show).join(", ")} in both in and not_in`);
+    }
+    if (op.exists !== undefined && typeof op.exists !== "boolean")
+        out.push(`filter: ${at} — exists: is true or false`);
+    const texts = TEXT_OPERATORS.filter((k) => op[k] !== undefined);
+    if (op.exists === false && (inList?.length || texts.length)) {
+        out.push(`filter: ${at} — exists: false cannot also require a value`);
+    }
+    for (const k of texts) {
+        const v = op[k];
+        if (typeof v !== "string" || !v)
+            out.push(`filter: ${at} — ${k}: is text, e.g. \`${k}: "refs/heads/"\``);
+        else if (v.length > FILTER_LIMITS.textChars)
+            out.push(`filter: ${at} — ${k}: is longer than ${FILTER_LIMITS.textChars} characters`);
+    }
+    return out;
+}
+const MISSING = Symbol("missing");
+/** One field's value against one leaf of the pattern. */
+function leafMatches(value, cond, at) {
+    // An operator object.
+    if (isOperatorObject(cond)) {
+        if (cond.exists !== undefined) {
+            const present = value !== MISSING;
+            if (cond.exists === true && !present)
+                return { match: false, reason: `${at} is missing (exists: true)` };
+            if (cond.exists === false && present)
+                return { match: false, reason: `${at} is present (exists: false)` };
+        }
+        const values = Array.isArray(value) ? value : value === MISSING ? [] : [value];
+        if (cond.in !== undefined) {
+            const allowed = (Array.isArray(cond.in) ? cond.in : [cond.in]).map(asScalar).filter((x) => x !== undefined);
+            if (value === MISSING)
+                return { match: false, reason: `${at} is missing` };
+            if (!values.some((v) => allowed.some((a) => sameValue(a, v))))
+                return { match: false, reason: `${at} is ${show(value)}, not one of ${allowed.map(show).join(", ")}` };
+        }
+        if (cond.not_in !== undefined) {
+            const refused = (Array.isArray(cond.not_in) ? cond.not_in : [cond.not_in]).map(asScalar).filter((x) => x !== undefined);
+            const hit = values.find((v) => refused.some((a) => sameValue(a, v)));
+            if (hit !== undefined)
+                return { match: false, reason: `${at} is ${show(hit)}, which not_in refuses` };
+        }
+        for (const k of TEXT_OPERATORS) {
+            const want = cond[k];
+            if (want === undefined)
+                continue;
+            if (value === MISSING)
+                return { match: false, reason: `${at} is missing` };
+            const w = String(want);
+            const texts = values.filter((v) => typeof v === "string" || typeof v === "number").map(String);
+            const hit = texts.some((t) => (k === "starts_with" ? t.startsWith(w) : k === "ends_with" ? t.endsWith(w) : t.includes(w)));
+            if (!hit)
+                return { match: false, reason: `${at} is ${show(value)}, which does not ${TEXT_VERB[k]} ${show(w)}` };
+        }
+        return { match: true, reason: "matched" };
+    }
+    // A list of allowed values, or one value.
+    const allowed = (Array.isArray(cond) ? cond : [cond]).map(asScalar);
+    if (allowed.some((a) => a === undefined))
+        return { match: false, reason: `${at}: the filter's value cannot be compared` };
+    if (value === MISSING)
+        return { match: false, reason: `${at} is missing` };
+    const values = Array.isArray(value) ? value : [value];
+    if (values.some((v) => allowed.some((a) => sameValue(a, v))))
+        return { match: true, reason: "matched" };
+    return {
+        match: false,
+        reason: allowed.length === 1 ? `${at} is ${show(value)}, not ${show(allowed[0])}` : `${at} is ${show(value)}, not one of ${allowed.map(show).join(", ")}`,
+    };
+}
+function nodeMatches(payload, pattern, where, depth) {
+    if (depth > FILTER_LIMITS.depth)
+        return { match: false, reason: `the filter nests deeper than ${FILTER_LIMITS.depth} levels` };
+    for (const [key, cond] of Object.entries(pattern)) {
+        const at = where ? `${where}.${key}` : key;
+        const value = isPlainObject(payload) && Object.prototype.hasOwnProperty.call(payload, key) ? payload[key] : MISSING;
+        if (isPlainObject(cond) && !isOperatorObject(cond)) {
+            // A nested pattern: the field must be an object that matches it, or a
+            // list holding one that does.
+            if (value === MISSING)
+                return { match: false, reason: `${at} is missing` };
+            // A nested pattern needs an object (or a list of them) to look inside:
+            // a scalar or null there is not "every field missing", which would let
+            // not_in and exists: false pass on a malformed delivery.
+            if (!Array.isArray(value) && !isPlainObject(value))
+                return { match: false, reason: `${at} is ${show(value)}, not an object` };
+            if (Array.isArray(value)) {
+                const objects = value.filter(isPlainObject);
+                if (objects.some((o) => nodeMatches(o, cond, at, depth + 1).match))
+                    continue;
+                return { match: false, reason: `no item of ${at} matches` };
+            }
+            const inner = nodeMatches(value, cond, at, depth + 1);
+            if (!inner.match)
+                return inner;
+            continue;
+        }
+        const leaf = leafMatches(value, cond, at);
+        if (!leaf.match)
+            return leaf;
+    }
+    return { match: true, reason: "matched" };
+}
+/**
+ * Does this payload pass this filter? No filter passes everything. A filter
+ * the check would refuse never matches — it fails closed, so a typo holds
+ * deliveries back instead of letting all of them through.
+ */
+export function matchFilter(filter, payload) {
+    if (filter === undefined || filter === null)
+        return { match: true, reason: "no filter" };
+    const problems = checkFilter(filter);
+    if (problems.length)
+        return { match: false, reason: `the filter cannot be read: ${problems[0].replace(/^filter: /, "")}` };
+    if (!isPlainObject(payload))
+        return { match: false, reason: "the delivery is not a JSON object, so no field can match" };
+    return nodeMatches(payload, filter, "", 1);
+}
+/** A webhook body as the filter reads it: its JSON, or null when it is not
+ *  JSON (which no filter matches). */
+export function webhookFilterPayload(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+/** The triggers a filter means something for. */
+export const FILTERABLE_TRIGGERS = ["webhook", "email", "flow", "storage"];

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

@@ -1,7 +1,7 @@
 /** 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" | "halted" | "overlap-skipped" | "missed" | "failed";
+export type TriggerOutcome = "started" | "duplicate" | "throttled" | "debounced" | "quarantined" | "paused" | "halted" | "overlap-skipped" | "missed" | "filtered" | "failed";
 export interface TriggerEvent {
     t: string;
     flow: string;

package/dist/src/triggers.d.ts

@@ -6,6 +6,8 @@ export declare function withTask(steps: FlowStep[], tag: string, body: string):
 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[];
+/** What a chained flow's `filter:` reads: the run that just settled. */
+export declare function chainFields(finished: RunRecord): Record<string, unknown>;
 /**
  * Start every flow chained on a run that just settled. The finished run's
  * one-line summary and its final result are the task; the run id rides