@foldrun/core 0.4.0 → 0.5.0

package/src/locale.ts

@@ -0,0 +1,217 @@
+// Everything a country changes that a language does not — derived, not
+// declared. `region:` is the one key; from language + region the runtime
+// works out the currency, the units, the calendar (and today's date in it),
+// which days are the weekend, the text direction, and how dates and hours
+// read. Overrides exist only where derivation can be wrong for a business:
+// `currency:`, `calendar:`, `units:`. Nothing else is a key, so there is no
+// eighth setting to forget.
+//
+// Intl does the deriving. Every accessor here has a fallback to the older
+// property form (Node 20) and to "unknown", because a runtime that cannot
+// say the weekend must not say Saturday.
+
+import { normalizeLanguage } from "./language.ts";
+
+export interface RegionChoice {
+  /** ISO 3166-1 alpha-2, upper-case: AU, IR, DE. Null when nobody said and
+   *  the language tag carries none. */
+  region: string | null;
+  from: "agent" | "flow" | "workspace" | "account" | "env" | "language" | "none";
+  lines: string[];
+}
+
+export function normalizeRegion(raw: unknown): string | null {
+  if (typeof raw !== "string") return null;
+  const m = /^[a-z]{2}$/i.exec(raw.trim());
+  return m ? raw.trim().toUpperCase() : null;
+}
+
+export function regionProblem(raw: unknown): string | null {
+  if (raw === undefined || raw === null || raw === "") return null;
+  if (normalizeRegion(raw)) return null;
+  return `region: ${JSON.stringify(raw)} is not a country code — write the two letters, like \`au\`, \`ir\` or \`de\`.`;
+}
+
+export function resolveRegion(
+  levels: { level: RegionChoice["from"]; value: unknown }[],
+  languageTag: string,
+  env: Record<string, string | undefined> = process.env,
+): RegionChoice {
+  const lines: string[] = [];
+  for (const { level, value } of levels) {
+    if (value === undefined || value === null || value === "") continue;
+    const r = normalizeRegion(value);
+    if (r) return { region: r, from: level, lines };
+    lines.push(`region: ${level} says ${JSON.stringify(value)}, which is not a country code — using the next level`);
+  }
+  const fromEnv = normalizeRegion(env.FOLDRUN_REGION);
+  if (fromEnv) return { region: fromEnv, from: "env", lines };
+  const tag = normalizeLanguage(languageTag);
+  const fromTag = tag && tag.includes("-") ? tag.split("-")[1] : null;
+  if (fromTag) return { region: fromTag, from: "language", lines };
+  return { region: null, from: "none", lines };
+}
+
+// ISO 4217 by region, for the regions a business here is likely to name.
+// Intl has no region→currency table; this is the smallest one that is not
+// wrong. Absent means "no currency assumed", which is better than a guess.
+const CURRENCY: Record<string, string> = {
+  AU: "AUD", NZ: "NZD", US: "USD", CA: "CAD", GB: "GBP", IE: "EUR", DE: "EUR", FR: "EUR", IT: "EUR", ES: "EUR",
+  NL: "EUR", BE: "EUR", AT: "EUR", PT: "EUR", FI: "EUR", GR: "EUR", CH: "CHF", SE: "SEK", NO: "NOK", DK: "DKK",
+  PL: "PLN", CZ: "CZK", TR: "TRY", RU: "RUB", UA: "UAH", IR: "IRR", IQ: "IQD", AF: "AFN", PK: "PKR", IN: "INR",
+  BD: "BDT", LK: "LKR", NP: "NPR", AE: "AED", SA: "SAR", QA: "QAR", KW: "KWD", BH: "BHD", OM: "OMR", JO: "JOD",
+  IL: "ILS", EG: "EGP", MA: "MAD", ZA: "ZAR", NG: "NGN", KE: "KES", CN: "CNY", HK: "HKD", TW: "TWD", JP: "JPY",
+  KR: "KRW", SG: "SGD", MY: "MYR", ID: "IDR", TH: "THB", VN: "VND", PH: "PHP", BR: "BRL", MX: "MXN", AR: "ARS",
+  CL: "CLP", CO: "COP",
+};
+const IMPERIAL = new Set(["US", "LR", "MM"]);
+
+export type Units = "metric" | "imperial";
+
+export interface LocaleFacts {
+  /** The BCP-47 tag Intl was asked with, e.g. fa-IR. */
+  tag: string;
+  language: string;
+  region: string | null;
+  currency: string | null;
+  units: Units;
+  /** The calendar in use — Intl's first for the locale, or the override. */
+  calendar: string;
+  /** Other calendars the locale commonly uses, e.g. gregory beside persian. */
+  calendars: string[];
+  /** Today in that calendar, formatted for the locale. Null when it is
+   *  gregory and would only repeat FOLDRUN_DATE. */
+  dateLocal: string | null;
+  /** 1 = Monday … 7 = Sunday, ISO. */
+  weekStart: number | null;
+  weekend: number[];
+  direction: "ltr" | "rtl";
+  hourCycle: "h12" | "h23" | null;
+  /** A sample date, so the model sees the order without being told. */
+  dateSample: string;
+}
+
+const DAY = ["", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"];
+export const dayName = (n: number) => DAY[n] ?? String(n);
+
+export function localeProblems(front: Record<string, unknown>): string[] {
+  const out: string[] = [];
+  const r = regionProblem(front.region);
+  if (r) out.push(r);
+  if (front.currency !== undefined && front.currency !== null && front.currency !== "") {
+    if (!/^[A-Za-z]{3}$/.test(String(front.currency))) out.push(`currency: ${JSON.stringify(front.currency)} is not a currency code — three letters, like \`AUD\`, \`IRR\` or \`EUR\`.`);
+  }
+  if (front.units !== undefined && front.units !== null && front.units !== "") {
+    if (!["metric", "imperial"].includes(String(front.units).toLowerCase())) out.push(`units: ${JSON.stringify(front.units)} — write \`metric\` or \`imperial\`.`);
+  }
+  if (front.calendar !== undefined && front.calendar !== null && front.calendar !== "") {
+    const known = supportedCalendars();
+    if (known.length && !known.includes(String(front.calendar).toLowerCase())) {
+      out.push(`calendar: ${JSON.stringify(front.calendar)} is not a calendar this runtime knows — one of ${known.join(", ")}.`);
+    }
+  }
+  return out;
+}
+
+function supportedCalendars(): string[] {
+  try {
+    const f = (Intl as unknown as { supportedValuesOf?: (k: string) => string[] }).supportedValuesOf;
+    return f ? f("calendar") : [];
+  } catch {
+    return [];
+  }
+}
+
+function localeInfo(tag: string): { weekStart: number | null; weekend: number[]; direction: "ltr" | "rtl"; calendars: string[]; hourCycle: "h12" | "h23" | null } {
+  try {
+    const L = new Intl.Locale(tag) as unknown as Record<string, unknown>;
+    const call = <T,>(m: string, p: string): T | undefined => {
+      const fn = L[m];
+      if (typeof fn === "function") return (fn as () => T).call(L);
+      return L[p] as T | undefined;
+    };
+    const wk = call<{ firstDay?: number; weekend?: number[] }>("getWeekInfo", "weekInfo");
+    const ti = call<{ direction?: string }>("getTextInfo", "textInfo");
+    const cals = call<string[]>("getCalendars", "calendars") ?? [];
+    const hc = call<string[]>("getHourCycles", "hourCycles")?.[0];
+    return {
+      weekStart: wk?.firstDay ?? null,
+      weekend: wk?.weekend ?? [],
+      direction: ti?.direction === "rtl" ? "rtl" : "ltr",
+      calendars: cals,
+      hourCycle: hc === "h12" || hc === "h23" ? hc : null,
+    };
+  } catch {
+    return { weekStart: null, weekend: [], direction: "ltr", calendars: [], hourCycle: null };
+  }
+}
+
+export function deriveLocale(
+  language: string,
+  region: string | null,
+  overrides: { currency?: unknown; calendar?: unknown; units?: unknown } = {},
+  timeZone = "UTC",
+  now: Date = new Date(),
+): LocaleFacts {
+  const lang = normalizeLanguage(language) ?? "en";
+  const base = lang.split("-")[0];
+  const tag = region ? `${base}-${region}` : lang;
+  const info = localeInfo(tag);
+  const calendar =
+    typeof overrides.calendar === "string" && overrides.calendar ? overrides.calendar.toLowerCase() : info.calendars[0] ?? "gregory";
+  const currency =
+    typeof overrides.currency === "string" && overrides.currency ? overrides.currency.toUpperCase() : region ? CURRENCY[region] ?? null : null;
+  const units: Units =
+    typeof overrides.units === "string" && ["metric", "imperial"].includes(overrides.units.toLowerCase())
+      ? (overrides.units.toLowerCase() as Units)
+      : region && IMPERIAL.has(region) ? "imperial" : "metric";
+  const fmt = (opts: Intl.DateTimeFormatOptions, cal = calendar) => {
+    try {
+      return new Intl.DateTimeFormat(`${tag}-u-ca-${cal}`, { ...opts, timeZone }).format(now);
+    } catch {
+      return new Intl.DateTimeFormat("en", { ...opts, timeZone }).format(now);
+    }
+  };
+  return {
+    tag,
+    language: lang,
+    region,
+    currency,
+    units,
+    calendar,
+    calendars: info.calendars.filter((c) => c !== calendar),
+    dateLocal: calendar === "gregory" ? null : fmt({ dateStyle: "long" }),
+    weekStart: info.weekStart,
+    weekend: info.weekend,
+    direction: info.direction,
+    hourCycle: info.hourCycle,
+    dateSample: fmt({ dateStyle: "medium" }, "gregory"),
+  };
+}
+
+/** The sentence block the prompt carries. Only what is true for this
+ *  locale; nothing hedged, nothing the model has to guess at. */
+export function localeProse(f: LocaleFacts, languageName: string, regionName: string | null): string {
+  const parts: string[] = [];
+  parts.push(`Language: ${languageName} (\`${f.language}\`)${regionName ? `. Region: ${regionName} (\`${f.region}\`)` : ""}.`);
+  if (f.currency) parts.push(`Currency: ${f.currency}.`);
+  parts.push(`Units: ${f.units}.`);
+  if (f.calendar !== "gregory") {
+    parts.push(`Calendar: ${f.calendar}${f.dateLocal ? ` — today is ${f.dateLocal}` : ""}${f.calendars.length ? ` (also ${f.calendars.join(", ")})` : ""}.`);
+  }
+  if (f.weekStart) {
+    parts.push(`Week starts ${dayName(f.weekStart)}; weekend ${f.weekend.map(dayName).join(" and ") || "unknown"}.`);
+  }
+  parts.push(`Dates read like ${f.dateSample}${f.hourCycle ? `; ${f.hourCycle === "h23" ? "24-hour" : "12-hour"} time` : ""}.`);
+  if (f.direction === "rtl") parts.push(`Text runs right to left: anything you render — HTML, email, PDF — needs dir="rtl".`);
+  return parts.join(" ");
+}
+
+export function regionName(code: string | null): string | null {
+  if (!code) return null;
+  try {
+    return new Intl.DisplayNames(["en"], { type: "region" }).of(code) ?? code;
+  } catch {
+    return code;
+  }
+}

package/src/mail.ts

@@ -0,0 +1,316 @@
+// Every email the platform sends, through one door.
+//
+// Mail used to leave from six places, each with its own fetch to Resend and
+// none of them asking whether the person reading it wanted it. A person who
+// was tired of "credits low" had one remedy — a filter — and a filter that
+// bins the low-balance warning bins the payment failure beside it.
+//
+// Now each send names a CATEGORY, and the category decides two things:
+//
+//   · whether the person may turn it off. Security, billing failures,
+//     invites and account notices may not: a password reset nobody receives
+//     is a locked-out person, and a payment failure nobody reads is an
+//     account that stops working with no warning. Everything else — run
+//     alerts, approval requests, low-balance warnings, product news — is the
+//     reader's to refuse, per workspace where the mail is about one.
+//
+//   · whether it carries a one-click unsubscribe (RFC 8058): a
+//     `List-Unsubscribe` URL with a signed token and `List-Unsubscribe-Post:
+//     List-Unsubscribe=One-Click`, so the mail client's own "Unsubscribe"
+//     turns that category off without a login. Gmail and Yahoo require it
+//     of bulk senders; a person deserves it from anyone.
+//
+// The preference is asked at send time, here, through platform.mailPreference
+// — the platform keeps them as records. A laptop has no preferences store and
+// sends everything, which is what it always did.
+
+import crypto from "node:crypto";
+import { platform } from "./platform.ts";
+import { installKey, publicUrl } from "./webhook.ts";
+
+export type MailCategory =
+  | "security"
+  | "invites"
+  | "billing"
+  | "account"
+  | "run-alerts"
+  | "approvals"
+  | "low-balance"
+  | "product-updates";
+
+export interface MailCategoryInfo {
+  id: MailCategory;
+  label: string;
+  /** Required mail cannot be turned off — see `why`. */
+  required: boolean;
+  /** Can be turned off for one workspace while the rest still send. */
+  perWorkspace: boolean;
+  /** What it is, for the settings page and `foldrun notifications`. */
+  description: string;
+  /** For a required category: why it cannot be refused. */
+  why?: string;
+}
+
+export const MAIL_CATEGORIES: readonly MailCategoryInfo[] = [
+  {
+    id: "security",
+    label: "Security",
+    required: true,
+    perWorkspace: false,
+    description: "Password resets, email confirmations, a login address changed, an account made for you.",
+    why: "these are how you get back into your account and how you hear that someone else tried to",
+  },
+  {
+    id: "invites",
+    label: "Invites",
+    required: true,
+    perWorkspace: false,
+    description: "An invitation to join an account. Sent once, to an address someone typed.",
+    why: "an invite is a one-off message someone asked to send you, not a subscription",
+  },
+  {
+    id: "billing",
+    label: "Billing failures",
+    required: true,
+    perWorkspace: false,
+    description: "A payment that failed, and the grace period before runs stop.",
+    why: "a failed payment you never hear about is an account that stops working without warning",
+  },
+  {
+    id: "account",
+    label: "Account notices",
+    required: true,
+    perWorkspace: false,
+    description: "Something about the account stopped working on its own — a notification webhook switched off after days of failures, a close request.",
+    why: "each one is the only message saying a thing you rely on has stopped",
+  },
+  {
+    id: "run-alerts",
+    label: "Run alerts",
+    required: false,
+    perWorkspace: true,
+    description: "A run failed, finished, or was blocked; a flow was quarantined, a run passed its SLA, a budget is nearly spent — mail from a workspace's notify: email.",
+  },
+  {
+    id: "approvals",
+    label: "Approval requests",
+    required: false,
+    perWorkspace: true,
+    description: "A run is waiting for a person, with approve and reject links. Off means you decide from the dashboard.",
+  },
+  {
+    id: "low-balance",
+    label: "Low-balance warnings",
+    required: false,
+    perWorkspace: false,
+    description: "Credits are below the warning level. Runs still stop at $0 whether or not you are told.",
+  },
+  {
+    id: "product-updates",
+    label: "Product updates",
+    required: false,
+    perWorkspace: false,
+    description: "What changed in foldrun. Rare.",
+  },
+];
+
+export function mailCategory(id: string): MailCategoryInfo | null {
+  return MAIL_CATEGORIES.find((c) => c.id === id) ?? null;
+}
+
+export function isRequiredCategory(id: string): boolean {
+  return mailCategory(id)?.required ?? false;
+}
+
+// ------------------------------------------------------------ unsubscribe
+
+/** How long a token in a mail keeps working. Long: a person unsubscribes
+ *  from a mail they kept, often months later, and an unsubscribe link that
+ *  has died is the one that sends them to the spam button instead. */
+export const UNSUBSCRIBE_TTL_MS = (Number(process.env.FOLDRUN_UNSUBSCRIBE_TTL_DAYS) || 180) * 86400_000;
+
+export interface UnsubscribeClaim {
+  tenant: string;
+  email: string;
+  category: MailCategory;
+  /** The workspace the mail was about, when its category is per workspace. */
+  workspace: string | null;
+  /** Epoch ms. */
+  expiresAt: number;
+}
+
+const b64 = (s: string) => Buffer.from(s, "utf8").toString("base64url");
+const sign = (payload: string) => crypto.createHmac("sha256", installKey()).update(`unsubscribe:${payload}`).digest("base64url").slice(0, 32);
+
+/**
+ * `<payload>.<signature>`: the payload is base64url JSON of who, what and
+ * until when; the signature is an HMAC under the install key, so the token
+ * is derived, never stored, and a key rotation kills every old one.
+ */
+export function unsubscribeToken(c: Omit<UnsubscribeClaim, "expiresAt"> & { expiresAt?: number }, now = Date.now()): string {
+  const claim = {
+    t: c.tenant,
+    e: c.email.trim().toLowerCase(),
+    c: c.category,
+    w: c.workspace ?? null,
+    x: Math.floor(c.expiresAt ?? now + UNSUBSCRIBE_TTL_MS),
+  };
+  const payload = b64(JSON.stringify(claim));
+  return `${payload}.${sign(payload)}`;
+}
+
+/** What a presented token says, or why it says nothing. */
+export function readUnsubscribeToken(
+  token: string | null | undefined,
+  now = Date.now(),
+): { claim: UnsubscribeClaim } | { error: string; status: 400 | 401 | 410 } {
+  if (!token || typeof token !== "string") return { error: "no token", status: 400 };
+  const [payload, sig, extra] = token.split(".");
+  if (!payload || !sig || extra !== undefined) return { error: "invalid token", status: 401 };
+  const want = sign(payload);
+  if (sig.length !== want.length || !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want))) {
+    return { error: "invalid token", status: 401 };
+  }
+  let raw: { t?: unknown; e?: unknown; c?: unknown; w?: unknown; x?: unknown };
+  try {
+    raw = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+  } catch {
+    return { error: "invalid token", status: 401 };
+  }
+  if (typeof raw.t !== "string" || typeof raw.e !== "string" || typeof raw.c !== "string" || typeof raw.x !== "number") {
+    return { error: "invalid token", status: 401 };
+  }
+  const cat = mailCategory(raw.c);
+  if (!cat) return { error: "invalid token", status: 401 };
+  if (raw.x < now) return { error: "this unsubscribe link has expired — change what you receive from Profile → Notifications", status: 410 };
+  return {
+    claim: { tenant: raw.t, email: raw.e, category: cat.id, workspace: typeof raw.w === "string" ? raw.w : null, expiresAt: raw.x },
+  };
+}
+
+/** The page a person opens, and the URL a mail client POSTs to. Null when
+ *  the install does not know its own address — then there is no link. */
+export function unsubscribeLinks(claim: Omit<UnsubscribeClaim, "expiresAt">, now = Date.now()): { page: string; oneClick: string } | null {
+  const base = publicUrl();
+  if (!base) return null;
+  const token = encodeURIComponent(unsubscribeToken(claim, now));
+  return { page: `${base}/unsubscribe?token=${token}`, oneClick: `${base}/api/unsubscribe?token=${token}` };
+}
+
+/** The RFC 8058 pair, for a mail whose category may be turned off. */
+export function unsubscribeHeaders(claim: Omit<UnsubscribeClaim, "expiresAt">, now = Date.now()): Record<string, string> {
+  const links = unsubscribeLinks(claim, now);
+  if (!links) return {};
+  return { "List-Unsubscribe": `<${links.oneClick}>`, "List-Unsubscribe-Post": "List-Unsubscribe=One-Click" };
+}
+
+// ------------------------------------------------------------------- send
+
+export interface MailMessage {
+  tenant: string;
+  /** The Resend key and sender — platformMail(), accountMail() or notifyMail(). */
+  mail: { key: string; from: string };
+  to: string | string[];
+  subject: string;
+  text: string;
+  html?: string;
+  category: MailCategory;
+  /** The workspace the mail is about, for per-workspace preferences. */
+  workspace?: string | null;
+}
+
+export interface MailResult {
+  /** True when every recipient who wanted it was handed to the provider —
+   *  and when nobody wanted it, which is not a failure. */
+  ok: boolean;
+  /** The HTTP status of the last send, when one was made. */
+  status?: number;
+  /** The provider's own words on a refusal, trimmed. */
+  error?: string;
+  sent: string[];
+  /** Recipients who turned this category off. */
+  suppressed: string[];
+}
+
+const recipients = (to: string | string[]) =>
+  (Array.isArray(to) ? to : to.split(","))
+    .map((s) => s.trim())
+    .filter(Boolean);
+
+/** Does this person take this category of mail? Required mail: always. */
+export async function mailWanted(tenant: string, email: string, category: MailCategory, workspace: string | null = null): Promise<boolean> {
+  if (isRequiredCategory(category)) return true;
+  try {
+    return await platform.mailPreference(tenant, email.trim().toLowerCase(), category, workspace);
+  } catch (err) {
+    // A preferences store that cannot be read sends: a missed alert is
+    // worse than one unwanted mail, and the next send asks again.
+    console.error(`[foldrun] mail: preference for ${category} unreadable, sending:`, err instanceof Error ? err.message : err);
+    return true;
+  }
+}
+
+/**
+ * Send one message, honouring each recipient's preference for its
+ * category. Optional mail is sent one recipient at a time so each copy
+ * carries that reader's own unsubscribe token; required mail goes as one.
+ * Never throws: a mail that fails is an `ok: false` with the reason.
+ */
+export async function sendMail(m: MailMessage): Promise<MailResult> {
+  const all = recipients(m.to);
+  const required = isRequiredCategory(m.category);
+  const workspace = m.workspace ?? null;
+  const sent: string[] = [];
+  const suppressed: string[] = [];
+  let status: number | undefined;
+  let error: string | undefined;
+
+  const post = async (to: string[], headers: Record<string, string>, footer: string) => {
+    try {
+      const res = await fetch("https://api.resend.com/emails", {
+        method: "POST",
+        headers: { authorization: `Bearer ${m.mail.key}`, "content-type": "application/json" },
+        body: JSON.stringify({
+          from: m.mail.from,
+          to: to.length === 1 ? to[0] : to,
+          subject: m.subject,
+          text: m.text + footer,
+          ...(m.html ? { html: m.html } : {}),
+          ...(Object.keys(headers).length ? { headers } : {}),
+        }),
+        signal: AbortSignal.timeout(8000),
+      });
+      status = res.status;
+      if (!res.ok) {
+        error = (await res.text().catch(() => "")).replace(/\s+/g, " ").slice(0, 300) || `HTTP ${res.status}`;
+        return false;
+      }
+      sent.push(...to);
+      return true;
+    } catch (err) {
+      error = err instanceof Error ? err.message : String(err);
+      return false;
+    }
+  };
+
+  if (required) {
+    if (all.length) await post(all, {}, "");
+    return { ok: all.length > 0 && sent.length === all.length, status, error, sent, suppressed };
+  }
+
+  for (const to of all) {
+    if (!(await mailWanted(m.tenant, to, m.category, workspace))) {
+      suppressed.push(to);
+      continue;
+    }
+    const claim = { tenant: m.tenant, email: to, category: m.category, workspace: mailCategory(m.category)?.perWorkspace ? workspace : null };
+    const links = unsubscribeLinks(claim);
+    const label = mailCategory(m.category)?.label.toLowerCase() ?? m.category;
+    const footer = links
+      ? `\n\n—\nStop ${label}${claim.workspace ? ` from ${claim.workspace}` : ""}: ${links.page}\n`
+      : "";
+    await post([to], unsubscribeHeaders(claim), footer);
+  }
+  const wanted = all.length - suppressed.length;
+  return { ok: sent.length === wanted, status, error, sent, suppressed };
+}

package/src/model-probe.ts

@@ -34,6 +34,9 @@ export interface ProbeReport {
   durationMs: number;
   /** The reply itself, for the human reading a failure. */
   reply: string | null;
+  /** Why the last turn ended — end_turn on a healthy probe; max_tokens,
+   *  refusal or model_context_window_exceeded say why one failed. */
+  stopReason: string | null;
 }
 
 const PROBE_TIMEOUT_SEC = 120;
@@ -105,6 +108,7 @@ export async function probeModel(
       costUsd: outcome.costUsd,
       durationMs: Date.now() - started,
       reply: outcome.result,
+      stopReason: outcome.stopReason ?? null,
     };
   } finally {
     fs.rmSync(scratch, { recursive: true, force: true });