@foldrun/core 0.4.0 → 0.5.0

package/src/translator.ts

@@ -31,6 +31,7 @@ import crypto from "node:crypto";
 import { PROTECTED_PARAMS } from "./providers.ts";
 import { viaEgress } from "./egress.ts";
 import { trimSlashes } from "./paths.ts";
+import { captureRefusalHeaders, isRefusalStatus, refusalLine } from "./refusal.ts";
 
 // ------------------------------------------------------------------ shapes
 
@@ -60,6 +61,10 @@ export interface TranslatorSpec {
    *  upstream request goes through it, and `upstreamKey` is a placeholder
    *  the proxy fills. */
   egress?: string;
+  /** The step's own zone, from the clock cascade — what a reset time in a
+   *  refusal is told in. UTC when nothing said otherwise. */
+  timezone?: string;
+
 }
 
 export interface RunningTranslator {
@@ -419,16 +424,38 @@ export function toResponses(
 
 // ------------------------------------------------------- response mapping
 
-function stopReason(finish: unknown): string {
-  switch (finish) {
-    case "tool_calls":
-    case "function_call":
-      return "tool_use";
-    case "length":
-      return "max_tokens";
-    default:
-      return "end_turn";
-  }
+type Stop = { reason: string; sequence: string | null };
+
+/**
+ * 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: Json, sawTool: boolean, stops: readonly string[]): Stop {
+  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: unknown, sawTool: boolean, sawRefusal: boolean): string {
+  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: unknown): string[] {
+  return Array.isArray(stops) ? stops.filter((s): s is string => typeof s === "string") : [];
 }
 
 function parseArgs(raw: unknown): unknown {
@@ -441,7 +468,7 @@ function parseArgs(raw: unknown): unknown {
 }
 
 /** A finished Chat Completion as an Anthropic message. Pure. */
-export function fromChatCompletion(res: Json, requestedModel: string): Json {
+export function fromChatCompletion(res: Json, requestedModel: string, stopSequences?: unknown): Json {
   const choice = ((res.choices as Json[] | undefined) ?? [])[0] ?? {};
   const msg = (choice.message as Json | undefined) ?? {};
   const content: Json[] = [];
@@ -457,14 +484,15 @@ export function fromChatCompletion(res: Json, requestedModel: string): Json {
     });
   }
   const usage = (res.usage as Json | undefined) ?? {};
+  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),
@@ -485,12 +513,15 @@ export class StreamTranslator {
   private textIndex: number | null = null;
   /** Chat-Completions tool index → Anthropic block index. */
   private tools = new Map<number, { block: number; argsSeen: boolean }>();
-  private finish: unknown = null;
+  /** The last choice's stop fields: finish_reason and any matched stop. */
+  private finish: Json = {};
   private usage: { input: number; output: number } | null = null;
   private id = `msg_${crypto.randomBytes(8).toString("hex")}`;
   private readonly model: string;
-  constructor(model: string) {
+  private readonly stops: string[];
+  constructor(model: string, stopSequences?: unknown) {
     this.model = model;
+    this.stops = stopList(stopSequences);
   }
 
   private event(name: string, data: Json): string {
@@ -534,7 +565,7 @@ export class StreamTranslator {
     }
     const choice = ((chunk.choices as Json[] | undefined) ?? [])[0];
     if (!choice) return out;
-    if (choice.finish_reason) this.finish = choice.finish_reason;
+    if (choice.finish_reason) this.finish = { finish_reason: choice.finish_reason, stop_reason: choice.stop_reason, matched_stop: choice.matched_stop };
     const delta = (choice.delta as Json | undefined) ?? {};
 
     const text = typeof delta.content === "string" ? delta.content : "";
@@ -614,11 +645,11 @@ 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 },
       }),
     );
@@ -648,7 +679,10 @@ export function fromResponses(res: Json, requestedModel: string): Json {
   }
   const usage = (res.usage as Json | undefined) ?? {};
   const incomplete = (res.incomplete_details as Json | undefined)?.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 as Json[]) : []).some(
+    (item) => item.type === "message" && Array.isArray(item.content) && (item.content as Json[]).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",
@@ -679,6 +713,7 @@ export class ResponsesStreamTranslator {
   private usage: { input: number; output: number } | null = null;
   private incomplete: string | null = null;
   private sawTool = false;
+  private sawRefusal = false;
   private id = `msg_${crypto.randomBytes(8).toString("hex")}`;
   private readonly model: string;
   constructor(model: string) {
@@ -743,6 +778,7 @@ 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 } }));
       }
@@ -793,7 +829,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",
@@ -913,6 +949,20 @@ export async function startTranslator(spec: TranslatorSpec): Promise<RunningTran
         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));
@@ -928,11 +978,11 @@ export async function startTranslator(spec: TranslatorSpec): Promise<RunningTran
           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()) res.write(e);

package/src/trigger-log.ts

@@ -38,6 +38,7 @@ export type TriggerOutcome =
   | "throttled"
   | "debounced"
   | "quarantined"
+  | "paused"
   | "overlap-skipped"
   | "missed"
   | "failed";

package/src/triggers.ts

@@ -14,7 +14,7 @@
 
 import crypto from "node:crypto";
 import { platform } from "./platform.ts";
-import { listFlows, readRun, type FlowInfo, type FlowStep, type RunRecord } from "./store.ts";
+import { listFlows, readRun, runVerdict, type FlowInfo, type FlowStep, type RunRecord } from "./store.ts";
 import { getSecret } from "./secrets.ts";
 
 /** The last step's result — the same reading runner.ts makes, kept local so
@@ -36,6 +36,13 @@ export function withTask(steps: FlowStep[], tag: string, body: string): FlowStep
 
 // ------------------------------------------------------------ trigger: flow
 
+/** Which `on:` a settled run answers to: failed, blocked (completed, but
+ *  its work refused itself), or completed. */
+export function endingOf(run: RunRecord): "completed" | "failed" | "blocked" {
+  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: string, workspace: string, finished: RunRecord): FlowInfo[] {
   if (finished.status !== "completed" && finished.status !== "failed") return [];
@@ -48,7 +55,7 @@ export function chainedFlows(tenant: string, workspace: string, finished: RunRec
       // 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)),
   );
 }
 
@@ -66,6 +73,7 @@ export async function fireChainedFlows(tenant: string, workspace: string, finish
   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) {

package/src/untrusted-fetch.ts

@@ -0,0 +1,88 @@
+// 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.ts";
+
+/** 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: string) {
+    super(message);
+    this.name = "RedirectRefused";
+  }
+}
+
+export async 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> {
+  let current = url;
+  let req: RequestInit = { ...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: URL;
+    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: string[] = [];
+      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();
+  }
+}

package/src/web-actions.ts

@@ -0,0 +1,237 @@
+// The web, as actions. One question answered in one place: which provider
+// can do which action, and what does foldrun do when none is named?
+//
+// An action is a call with a fixed input and a fixed output — search takes a
+// query and returns URLs, fetch takes a URL and returns the page — whoever
+// answers it. A provider is the list of actions it has an adapter for. foldrun
+// is a provider like any other, and the one used when `web: {<action>: …}` is
+// unset. A provider named for an action it cannot do is an error in `check`,
+// never a quiet fall back to ours: a fallback would bill and behave
+// differently from what the file says.
+//
+// Browse has a second level: inside a page, the steps and modes of
+// the browse action. A browser reached over CDP is driven by our own code, so it
+// takes every step and mode unless it is listed as lacking one; a vendor
+// that runs the steps itself would list the few it has.
+//
+// The vendor facts (endpoint, key, docs page, the date the adapter was last
+// matched to those docs) stay on SEARCH_APIS, FETCH_APIS and BROWSER_APIS in
+// providers.ts; this file reads them rather than restating them.
+
+import { SEARCH_APIS, FETCH_APIS, BROWSER_APIS, ACTION_APIS, WEB_ACTIONS, webConfig, type WebAction } from "./providers.ts";
+
+export { WEB_ACTIONS, type WebAction };
+
+/** What the browse action can return — its `mode`. Kept equal to the tool's own
+ *  MODES by the platform's gallery test. */
+export const BROWSE_MODES = [
+  "text", "markdown", "html", "links", "meta", "table", "network", "screenshot", "pdf", "capture",
+  "aria", "map", "crawl", "console", "vitals", "a11y", "diff", "feed", "webmcp", "react",
+] as const;
+
+/** What the browse action can do in a page — its `actions` steps. Kept equal to
+ *  the tool's own ACTIONS by the platform's gallery test. */
+export const BROWSE_STEPS = [
+  "click", "dblclick", "rightclick", "hover", "check", "uncheck", "drag", "fill", "type", "press", "select",
+  "wait", "goto", "screenshot", "pdf", "scroll", "paste", "upload", "download", "extract", "frame", "tab",
+  "back", "forward", "reload", "focus", "clear", "highlight", "keyboard", "keydown", "keyup", "mouse", "wheel",
+  "tap", "swipe", "clipboard", "eval", "get", "expect", "if", "mock", "unmock", "offline", "cookie",
+  "localstorage", "sessionstorage", "viewport", "dialog", "solve", "pushstate", "insert", "webmcp", "login",
+] as const;
+
+export interface ActionSupport {
+  /** live: callable today. planned: agreed and not built — naming it is an
+   *  error that says so, rather than a tool that does nothing. */
+  status: "live" | "planned";
+  /** How: which tool serves it, and for foldrun's own, with what. */
+  how: string;
+  /** Browse only. cdp: our code drives the browser, so every step and mode
+   *  works unless listed in `lacks`. api: the vendor runs the steps, and
+   *  `steps`/`modes` list what it has. */
+  via?: "cdp" | "api";
+  steps?: readonly string[];
+  modes?: readonly string[];
+  lacks?: readonly string[];
+  /** The vendor page the adapter was built from, and the day it was last
+   *  matched to it (YYYY-MM-DD). Absent on foldrun's own. */
+  docs?: string;
+  checked?: string;
+}
+
+export interface WebProvider {
+  name: string;
+  title: string;
+  actions: Partial<Record<WebAction, ActionSupport>>;
+}
+
+/** Ours: every action, and none of them with a second model in it. */
+export const FOLDRUN: WebProvider = {
+  name: "foldrun",
+  title: "foldrun",
+  actions: {
+    search: { status: "live", how: "the account's own SearXNG" },
+    fetch: { status: "live", how: "one plain HTTP request in the sandbox" },
+    browse: { status: "live", how: "the account's browser pod", via: "cdp" },
+    crawl: { status: "live", how: "plain HTTP, same site, robots.txt honoured" },
+    map: { status: "live", how: "the site's sitemaps, else its links" },
+    extract: { status: "live", how: "selectors, or the page's own JSON-LD and OpenGraph — no model" },
+    answer: { status: "live", how: "search, read the top pages, rank the passages that answer — no model" },
+    monitor: { status: "live", how: "a page's lines or a query's results, against the last call, in state/" },
+  },
+};
+
+type Facts = { name: string; title: string; aliases?: string[]; docs?: string; checked?: string; lacks?: readonly string[] };
+
+/** Every provider and what it can do, foldrun first. Built from the vendor
+ *  lists so a vendor added there is here without a second edit. */
+export function webProviders(): WebProvider[] {
+  const byName = new Map<string, WebProvider>();
+  const add = (f: Facts, action: WebAction, support: ActionSupport) => {
+    const p = byName.get(f.name) ?? { name: f.name, title: f.title, actions: {} };
+    p.actions[action] = { ...support, ...(f.docs ? { docs: f.docs } : {}), ...(f.checked ? { checked: f.checked } : {}) };
+    byName.set(f.name, p);
+  };
+  for (const a of SEARCH_APIS as readonly Facts[]) add(a, "search", { status: "live", how: a.title });
+  for (const a of FETCH_APIS as readonly Facts[]) add(a, "fetch", { status: "live", how: a.title });
+  for (const a of BROWSER_APIS as readonly Facts[]) {
+    add(a, "browse", { status: "live", how: a.title, via: "cdp", ...(a.lacks?.length ? { lacks: a.lacks } : {}) });
+  }
+  for (const [action, apis] of Object.entries(ACTION_APIS) as [WebAction, readonly Facts[]][]) {
+    for (const a of apis) add(a, action, { status: "live", how: a.title });
+  }
+  return [FOLDRUN, ...byName.values()];
+}
+
+/** The names a provider answers to, for lookups. */
+function aliasesOf(name: string): string[] {
+  const all = [...SEARCH_APIS, ...FETCH_APIS, ...BROWSER_APIS, ...Object.values(ACTION_APIS).flat()] as readonly Facts[];
+  return all.filter((a) => a.name === name).flatMap((a) => a.aliases ?? []);
+}
+
+export function findWebProvider(name: string): WebProvider | undefined {
+  const key = name.trim().toLowerCase();
+  if (key === "" || key === "ours") return FOLDRUN;
+  return webProviders().find((p) => p.name === key || aliasesOf(p.name).includes(key));
+}
+
+/** The live providers for an action, foldrun first — for "these do" lines. */
+export function providersFor(action: WebAction): string[] {
+  return webProviders().filter((p) => p.actions[action]?.status === "live").map((p) => p.name);
+}
+
+export type ActionChoice =
+  | { provider: WebProvider; support: ActionSupport; error?: undefined }
+  | { provider?: undefined; support?: undefined; error: string };
+
+/**
+ * Who does `action`. Unset is foldrun. A named provider must have the action
+ * live; anything else is an error naming the providers that do — the rule is
+ * "fix the file", never "we used ours instead".
+ */
+export function resolveWebAction(action: WebAction, name?: string | null): ActionChoice {
+  const field = `web.${action}`;
+  const p = name == null ? FOLDRUN : findWebProvider(name);
+  if (!p) {
+    return { error: `${field}: ${name} — no provider by that name. These ${action}: ${providersFor(action).join(", ")}.` };
+  }
+  const s = p.actions[action];
+  if (!s) {
+    const live = providersFor(action);
+    return {
+      error: `${field}: ${p.name} does not ${action} here.` +
+        (live.length ? ` These do: ${live.join(", ")}.` : " No provider has it wired yet.") +
+        (FOLDRUN.actions[action]?.status === "live" ? " Unset uses foldrun." : ""),
+    };
+  }
+  if (s.status === "planned") {
+    const others = providersFor(action).filter((n) => n !== p.name);
+    return {
+      error: `${field}: ${p.title}'s own ${action} is not built yet` +
+        (others.length ? ` — name a provider that has it: ${others.join(", ")}.` : " and no provider has it wired either."),
+    };
+  }
+  return { provider: p, support: s };
+}
+
+/** Can this browser run this step, or return this mode? */
+export function browseSupports(support: ActionSupport, stepOrMode: string): boolean {
+  if (support.via === "cdp") return !(support.lacks ?? []).includes(stepOrMode);
+  return (support.steps ?? []).includes(stepOrMode) || (support.modes ?? []).includes(stepOrMode);
+}
+
+/** The browsers that can run a step or mode — for the error when one cannot. */
+export function browsersFor(stepOrMode: string): string[] {
+  return webProviders()
+    .filter((p) => p.actions.browse?.status === "live" && browseSupports(p.actions.browse, stepOrMode))
+    .map((p) => p.name);
+}
+
+/** Vendor actions whose adapter has not been matched to the vendor's docs
+ *  within `days` — each as "provider action (checked …)". Empty is healthy.
+ *  The test that calls this is the rule "integrations follow the latest
+ *  docs" in a form CI can fail on. */
+export function staleIntegrations(today: string, days = 90): string[] {
+  const out: string[] = [];
+  const limit = Date.parse(today) - days * 86_400_000;
+  for (const p of webProviders()) {
+    if (p === FOLDRUN) continue;
+    for (const [action, s] of Object.entries(p.actions)) {
+      if (!s || s.status !== "live") continue;
+      if (!s.docs || !s.checked) out.push(`${p.name} ${action} (no docs page or check date recorded)`);
+      else if (Date.parse(s.checked) < limit) out.push(`${p.name} ${action} (checked ${s.checked})`);
+    }
+  }
+  return out;
+}
+
+/** The actions after search, fetch and browse. Those three are resolved by
+ *  providers.ts, which also knows the model providers that search. */
+export const NEWER_ACTIONS = ["crawl", "map", "extract", "answer", "monitor"] as const;
+type NewerAction = (typeof NEWER_ACTIONS)[number];
+
+export type ActionApiChoice =
+  | { provider: null; error?: undefined }
+  | { provider: string; secret: string; host: string; error?: undefined }
+  | { provider: null; error: string };
+
+/**
+ * Who does one of the newer actions, and with which key: unset (or
+ * "foldrun") is ours and needs none; a name, or `{name, key: ${VAULT_NAME}}`
+ * for a key stored under another name, is that provider — if it has the
+ * action. The runner turns a provider into FOLDRUN_WEB_<ACTION>_VIA, the
+ * secret the step holds, and the one host that secret may reach.
+ */
+export function resolveActionApi(action: NewerAction, raw: unknown): ActionApiChoice {
+  const field = `web.${action}`;
+  if (raw === undefined || raw === null || raw === "") return { provider: null };
+  let name: string;
+  let secret: string | undefined;
+  if (typeof raw === "string") name = raw;
+  else if (typeof raw === "object" && !Array.isArray(raw) && typeof (raw as { name?: unknown }).name === "string") {
+    name = (raw as { name: string }).name;
+    const key = (raw as { key?: unknown }).key;
+    if (key !== undefined) {
+      const m = typeof key === "string" ? /^\$\{([A-Z][A-Z0-9_]*)\}$/.exec(key.trim()) : null;
+      if (!m) return { provider: null, error: `${field}.key must be a \${NAME} reference to a secret in the vault, not the key itself.` };
+      secret = m[1];
+    }
+  } else {
+    return { provider: null, error: `${field}: takes a provider name, or a block with name: (and key: for your own vault name).` };
+  }
+  const choice = resolveWebAction(action, name);
+  if (choice.error !== undefined) return { provider: null, error: choice.error };
+  if (choice.provider.name === "foldrun") return { provider: null };
+  const api = ACTION_APIS[action].find((a) => a.name === choice.provider.name)!;
+  return { provider: api.name, secret: secret ?? api.secret, host: api.host };
+}
+
+/** Every newer action in the agent's web: block that names a provider unable
+ *  to do it — the sentences resolveActionApi gives. Empty when all are unset
+ *  or answerable. */
+export function actionProblems(front: Record<string, unknown>): string[] {
+  const { raw } = webConfig(front);
+  return NEWER_ACTIONS.flatMap((a) => {
+    const e = resolveActionApi(a, raw[a]).error;
+    return e ? [e] : [];
+  });
+}

package/src/webhook.ts

@@ -143,8 +143,17 @@ export interface HookDelivery {
   runId?: string;
   bytes?: number;
   detail?: string;
+  /** A run of refusals, collapsed: how many, and when the first came.
+   *  `t` is the latest. Absent means one. */
+  count?: number;
+  first?: string;
 }
 
+/** What anyone can produce without the token or the signing secret. A run
+ *  of these collapses into one line, so a stranger's flood costs the log a
+ *  single entry and can never push an owner's real deliveries out of it. */
+const UNAUTHENTICATED: HookDelivery["outcome"][] = ["invalid-token", "invalid-signature"];
+
 function deliveriesFile(tenant: string, workspace: string) {
   return path.join(workspaceDir(tenant, workspace), "hook-deliveries.jsonl");
 }
@@ -154,6 +163,7 @@ const KEEP_DELIVERIES = 500;
 export function recordDelivery(tenant: string, workspace: string, delivery: HookDelivery) {
   const file = deliveriesFile(tenant, workspace);
   if (!fs.existsSync(path.dirname(file))) return; // no workspace, nothing to log against
+  if (UNAUTHENTICATED.includes(delivery.outcome) && collapseInto(file, delivery)) return;
   fs.appendFileSync(file, JSON.stringify(delivery) + "\n");
   // Bounded: compact to the newest KEEP when it doubles. Amortised cheap,
   // and a log that grows forever is a disk-full incident with a delay.
@@ -169,6 +179,37 @@ export function recordDelivery(tenant: string, workspace: string, delivery: Hook
   }
 }
 
+/** Fold a refusal into the log's last line when that line is a refusal
+ *  too. The flow name is not part of the match: it comes from the URL, so
+ *  a flood that varies it would otherwise never collapse. True when folded. */
+function collapseInto(file: string, delivery: HookDelivery): boolean {
+  let text: string;
+  try {
+    text = fs.readFileSync(file, "utf8");
+  } catch {
+    return false;
+  }
+  const end = text.trimEnd();
+  const cut = end.lastIndexOf("\n") + 1;
+  let last: HookDelivery;
+  try {
+    last = JSON.parse(end.slice(cut)) as HookDelivery;
+  } catch {
+    return false;
+  }
+  if (!UNAUTHENTICATED.includes(last.outcome)) return false;
+  const merged: HookDelivery = {
+    ...delivery,
+    count: (last.count ?? 1) + 1,
+    first: last.first ?? last.t,
+    ...(last.detail === "more than one flow name" || last.flow !== delivery.flow ? { detail: "more than one flow name" } : {}),
+  };
+  const tmp = `${file}.tmp`;
+  fs.writeFileSync(tmp, end.slice(0, cut) + JSON.stringify(merged) + "\n");
+  fs.renameSync(tmp, file);
+  return true;
+}
+
 export function readDeliveries(tenant: string, workspace: string, limit = 20): HookDelivery[] {
   const file = deliveriesFile(tenant, workspace);
   if (!fs.existsSync(file)) return [];

package/templates/hello/agents/curator/agent.md

@@ -24,7 +24,7 @@ Do exactly this:
    - A fact a later run or a knowledge file contradicts: correct it, and say
      in the file what changed and which run showed it.
    - A note that was only ever true for one day (a count, a cursor, "today"):
-     move it to `../../state/` if it is still useful, else delete it.
+     move it to `workspace/state/` if it is still useful, else delete it.
    - Anything you are not sure about: leave it, and list it in your report.
 3. Never write a fact you did not find in a file or a run. Never touch
    `knowledge/` — that is what people gave the agents, and it is theirs.

package/templates/hello/agents/notetaker/agent.md

@@ -18,7 +18,7 @@ Do exactly this, in order:
    again. Save the final text to `outputs/note.md`.
 3. Write one thing you learned to `../../memory/` as a new file — one fact,
    plain markdown, a sentence or two. The platform records who wrote it.
-4. Update `../../state/publishing.md`: increase the note count by one and set
+4. Update `workspace/state/publishing.md`: increase the note count by one and set
    the last topic to what you wrote about. Keep it as markdown.
 
 Then stop. Do not create anything else.