@foldrun/core 0.2.0

package/src/notify.ts

@@ -0,0 +1,281 @@
+// Telling a person what their agents did while they were not looking.
+//
+// An agent that runs when the laptop is closed needs a way to say "I
+// finished", "I failed", and above all "I am waiting for you" — a parked
+// approval nobody hears about is a run that never happens. The channel is a
+// webhook out: one URL, declared in AGENTS.md frontmatter, POSTed a small
+// JSON body. Slack, Discord, ntfy, a phone-push relay and a plain inbox
+// service all speak that; building any one of them natively would just be
+// this plus vendor formatting.
+//
+//   notify:
+//     url: ${SLACK_WEBHOOK_URL}       # a secret name, or a literal URL
+//     events: [failed, awaiting-approval, completed]
+//
+// Or, for people who live in an inbox rather than a channel:
+//
+//   notify:
+//     email: ops@example.com          # sent via the RESEND_API_KEY connection
+//     events: [failed, completed]
+//
+// Email is the one vendor worth speaking natively: the platform already
+// holds a Resend connection for its email tool, and "just email me" is the
+// notification default for most of the world. Everything else stays a
+// webhook — one URL covers Slack, Discord, ntfy and every relay.
+//
+// Workspace config replaces account config whole, like provider: — a URL is
+// a destination, and merging two destinations sends half your alerts to a
+// channel you stopped reading.
+//
+// Defaults: failed and awaiting-approval. Completed is opt-in — a schedule
+// that works is the quiet kind of good news, and a channel that pings on
+// every success gets muted, which un-pings the failures too.
+
+import { readAgentsMd } from "./runner.ts";
+import { accountDir, workspaceDir, runCost, type RunRecord } from "./store.ts";
+import { getSecret } from "./secrets.ts";
+import { approveToken, publicUrl } from "./webhook.ts";
+
+/**
+ * The platform's own mail: an invite, a low balance.
+ *
+ * These are from foldrun, about the platform, to the account's owner — so
+ * they go through the platform's Resend key and sender (FOLDRUN_RESEND_API_KEY,
+ * FOLDRUN_EMAIL_FROM), never through anything the customer configured.
+ *
+ * Without a platform key — the CLI on a laptop, a test — the account's own
+ * key and EMAIL_FROM are the fallback.
+ */
+export function platformMail(tenant: string): { key: string; from: string } | null {
+  const key = process.env.FOLDRUN_RESEND_API_KEY;
+  if (key) return { key, from: process.env.FOLDRUN_EMAIL_FROM || "foldrun <hello@foldrun.io>" };
+  return accountMail(tenant);
+}
+
+/** The account's own Resend key and sender, or null when it has none. */
+export function accountMail(tenant: string): { key: string; from: string } | null {
+  const own = getSecret(tenant, "RESEND_API_KEY");
+  if (!own) return null;
+  const from = getSecret(tenant, "EMAIL_FROM")?.value?.trim() || "foldrun <onboarding@resend.dev>";
+  return { key: own.value, from };
+}
+
+/**
+ * A run notification is the account's mail, not the platform's: it is a
+ * desk telling its owner what it found, and the owner chose the sender —
+ * their RESEND_API_KEY and EMAIL_FROM on the account, the same connection
+ * their agents' `email` tool uses. So it comes from the address they
+ * expect, under their own domain's reputation and their own inbox rules;
+ * 2026-09-06, every notification from the platform's address was in the
+ * owner's bin. The platform's key is the fallback for an account that set
+ * none, so `notify:` works before anyone has configured mail at all.
+ */
+export function notifyMail(tenant: string): { key: string; from: string } | null {
+  return accountMail(tenant) ?? platformMail(tenant);
+}
+
+export interface NotifyConfig {
+  url?: string;
+  email?: string;
+  events: string[];
+}
+
+const DEFAULT_EVENTS = ["failed", "awaiting-approval"];
+
+export function notifyConfig(tenant: string, workspace: string): NotifyConfig | null {
+  const raw =
+    (readAgentsMd(workspaceDir(tenant, workspace))?.data.notify as unknown) ??
+    (readAgentsMd(accountDir(tenant))?.data.notify as unknown);
+  if (!raw) return null;
+  if (typeof raw === "string") {
+    // A bare string is whichever destination it looks like.
+    return raw.includes("@") && !raw.includes("/")
+      ? { email: raw, events: DEFAULT_EVENTS }
+      : { url: raw, events: DEFAULT_EVENTS };
+  }
+  if (typeof raw === "object" && raw !== null) {
+    const o = raw as { url?: unknown; email?: unknown; events?: unknown };
+    const url = typeof o.url === "string" ? o.url : undefined;
+    const email = typeof o.email === "string" ? o.email : undefined;
+    if (!url && !email) return null;
+    return {
+      url,
+      email,
+      events: Array.isArray(o.events) && o.events.length ? o.events.map(String) : DEFAULT_EVENTS,
+    };
+  }
+  return null;
+}
+
+// Said once per process, not once per run: the fix is one env edit, and a
+// line per parked run would bury the failures around it.
+let warnedNoPublicUrl = false;
+
+/**
+ * The approve/reject links for a run waiting on a person, or null when the
+ * install cannot say where it lives. A notification that only says "waiting
+ * for you" sends the reader to find a laptop; one that carries the decision
+ * lets them make it where they read it.
+ *
+ * The reject link goes to the same page with the choice pre-selected — a
+ * GET must not decide anything, because inbox link-checkers follow links.
+ */
+export function approvalLinks(
+  tenant: string,
+  workspace: string,
+  runId: string,
+): { approveUrl: string; rejectUrl: string } | null {
+  const base = publicUrl();
+  if (!base) {
+    if (!warnedNoPublicUrl) {
+      warnedNoPublicUrl = true;
+      console.error(
+        "[foldrun] notify: approval links need FOLDRUN_PUBLIC_URL (the install's public origin); sending without them",
+      );
+    }
+    return null;
+  }
+  const approveUrl = `${base}/api/approve/${tenant}/${workspace}/${runId}?token=${approveToken(tenant, workspace, runId)}`;
+  return { approveUrl, rejectUrl: `${approveUrl}&decision=reject` };
+}
+
+/**
+ * Fire the webhook for a run's state, if the workspace asked to hear about
+ * it. Failures are logged and swallowed — a broken Slack hook must never
+ * fail the run it is reporting on.
+ */
+/** Flows whose completion is nobody's news: eval cases and adhoc runs. */
+export function isQuietFlow(flow: string): boolean {
+  return /^(eval|adhoc):/.test(flow);
+}
+
+export async function sendRunNotification(
+  tenant: string,
+  workspace: string,
+  run: RunRecord,
+): Promise<boolean> {
+  const config = notifyConfig(tenant, workspace);
+  if (!config || !config.events.includes(run.status)) return false;
+  // A test is not news. An eval case or an adhoc single-agent run is started
+  // by a person who is watching it, and a desk that emails "completed" for
+  // every one of them buries the weekly verdict under two hundred of these —
+  // on 2026-09-06 the reader's inbox rule had sent the lot to the bin, the
+  // real reports with them. Failures and gates still send: a person asked.
+  if (run.status === "completed" && isQuietFlow(run.flow)) return false;
+
+  const failed = run.steps.filter((s) => s.status === "failed").map((s) => s.agent);
+  const waitingSteps = run.steps.filter((s) => s.status === "awaiting-approval");
+  const waiting = waitingSteps.map((s) => s.agent);
+  // A park on `wait: event` is not a question for the reader: the message
+  // says what the run is waiting for, so nobody hunts for a button that
+  // the outside world is meant to press.
+  const onEvent = waitingSteps.length > 0 && waitingSteps.every((s) => s.waitFor === "event");
+  const headline =
+    run.status === "completed"
+      ? `✓ ${run.flow} completed`
+      : run.status === "failed"
+        ? `✗ ${run.flow} failed${failed.length ? ` at ${failed.join(", ")}` : ""}`
+        : onEvent
+          ? `⏳ ${run.flow} is waiting for an external event${waiting.length ? ` (${waiting.join(", ")})` : ""}`
+          : `⏸ ${run.flow} is waiting for your approval${waiting.length ? ` (${waiting.join(", ")})` : ""}`;
+
+  // What the run concluded, if it concluded anything. This is the whole point
+  // of the message: "✓ health completed · $0.42" tells you a thing ran and
+  // what it cost, and nothing at all about what it found. A scheduled desk
+  // reporting only its own existence is a desk nobody reads by week three.
+  const summary = run.summary?.trim() || null;
+
+  const links = run.status === "awaiting-approval" ? approvalLinks(tenant, workspace, run.id) : null;
+  // At a gate the reader is being asked something; the question goes in the
+  // mail, and so does what the run has concluded so far — the last finished
+  // step's first line, which is the proposal's own summary ("… ·
+  // TARGETS-PROPOSAL: 1 change"). Without these a gate email said only
+  // that a step was waiting, and the decision meant opening the dashboard.
+  const asks = waitingSteps.map((s) => s.ask?.trim()).filter((a): a is string => Boolean(a));
+  const soFar =
+    run.status === "awaiting-approval" && !summary
+      ? [...run.steps].reverse().find((s) => s.status === "completed" && s.result?.trim())?.result?.trim().split("\n")[0] ?? null
+      : null;
+
+  const body = {
+    // `text` is what Slack-shaped receivers render; the rest is for anything
+    // that wants the data instead of the sentence.
+    text: summary
+      ? `${headline} — ${summary} · ${workspace}/${run.id} · $${runCost(run).toFixed(4)}`
+      : `${headline} — ${workspace}/${run.id} · $${runCost(run).toFixed(4)}`,
+    workspace,
+    runId: run.id,
+    flow: run.flow,
+    status: run.status,
+    summary,
+    costUsd: runCost(run),
+    startedAt: run.startedAt,
+    finishedAt: run.finishedAt,
+    ...(links ?? {}),
+  };
+
+  try {
+    if (config.email) {
+      const mail = notifyMail(tenant);
+      if (!mail) {
+        console.error(`[foldrun] notify: email configured but no mail credential — set RESEND_API_KEY (and EMAIL_FROM) on the account ${tenant}, or FOLDRUN_RESEND_API_KEY on the platform`);
+        return false;
+      }
+      const res = await fetch("https://api.resend.com/emails", {
+        method: "POST",
+        headers: { authorization: `Bearer ${mail.key}`, "content-type": "application/json" },
+        body: JSON.stringify({
+          from: mail.from,
+          to: config.email,
+          // The subject is the headline and what the run concluded, and
+          // nothing else. Ids and costs belong in the body: a subject line is
+          // read in a list, where the only useful question it can answer is
+          // whether this one needs opening.
+          subject: summary ? `${headline} — ${summary}`.slice(0, 160) : headline,
+          text:
+            `${headline}\n` +
+            (summary ? `\n${summary}\n` : soFar ? `\n${soFar}\n` : "") +
+            (asks.length ? `\n${asks.map((a) => `Question: ${a}`).join("\n")}\n` : "") +
+            `\nworkspace: ${workspace}\nrun: ${run.id}\nflow: ${run.flow}\n` +
+            `cost: $${runCost(run).toFixed(4)}\nstarted: ${run.startedAt}\nfinished: ${run.finishedAt ?? "-"}\n` +
+            (links ? `\nApprove: ${links.approveUrl}\nReject: ${links.rejectUrl}\n` : ""),
+        }),
+        signal: AbortSignal.timeout(8000),
+      });
+      if (!res.ok) {
+        // Resend's body says WHY — "domain not verified", "can only send to
+        // your own address" — and a status alone sent someone to the wrong
+        // dashboard for twenty minutes on 2026-09-06.
+        const why = (await res.text().catch(() => "")).replace(/\s+/g, " ").slice(0, 300);
+        console.error(`[foldrun] notify email: ${tenant}/${workspace} → HTTP ${res.status} ${why}`);
+        return false;
+      }
+      return true;
+    }
+
+    // ${SECRET} so the Slack URL — itself a credential — can live in the
+    // vault instead of in a file that gets committed.
+    const url = (config.url ?? "").replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => {
+      const hit = getSecret(tenant, name, workspace);
+      return hit ? hit.value : whole;
+    });
+    if (!url || url.includes("${")) {
+      console.error(`[foldrun] notify: secret in URL not set for ${tenant}/${workspace}`);
+      return false;
+    }
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(5000),
+    });
+    if (!res.ok) {
+      console.error(`[foldrun] notify: ${tenant}/${workspace} → HTTP ${res.status}`);
+      return false;
+    }
+    return true;
+  } catch (err) {
+    console.error(`[foldrun] notify: ${tenant}/${workspace} →`, err instanceof Error ? err.message : err);
+    return false;
+  }
+}

package/src/oauth-presets.ts

@@ -0,0 +1,54 @@
+// Prefills for the common OAuth providers: URLs and quirks, never
+// credentials. One list, read by the CLI (`foldrun connect`), the dashboard's
+// Connections form and the platform's consent callback, so a provider's
+// refresh-token quirk is written down once.
+//
+// What stays with the account is the OAuth *client* (id + secret): a consent
+// screen belongs to a registered app, so the developer brings those two
+// values from the provider's console and everything else is here.
+
+export interface OAuthPreset {
+  authorize_url: string;
+  token_url: string;
+  /** Extra authorize-URL params (Google: access_type=offline&prompt=consent). */
+  authorize_extra?: Record<string, string>;
+  /** Scopes to start from — every provider names them differently, and a
+   *  form with the right shape in it is worth more than a blank field. */
+  scopes_example?: string;
+  /** The one thing about this provider that costs an afternoon to learn. */
+  hint: string;
+}
+
+export const OAUTH_PRESETS: Record<string, OAuthPreset> = {
+  google: {
+    authorize_url: "https://accounts.google.com/o/oauth2/v2/auth",
+    token_url: "https://oauth2.googleapis.com/token",
+    authorize_extra: { access_type: "offline", prompt: "consent" },
+    scopes_example: "https://www.googleapis.com/auth/adwords",
+    hint: "Scopes are full URLs. Offline access is requested for you, so a refresh token comes back.",
+  },
+  github: {
+    authorize_url: "https://github.com/login/oauth/authorize",
+    token_url: "https://github.com/login/oauth/access_token",
+    scopes_example: "repo read:org",
+    hint: "GitHub issues long-lived tokens and no refresh token — stored as a static secret.",
+  },
+  microsoft: {
+    authorize_url: "https://login.microsoftonline.com/common/oauth2/v2.0/authorize",
+    token_url: "https://login.microsoftonline.com/common/oauth2/v2.0/token",
+    scopes_example: "offline_access https://graph.microsoft.com/.default",
+    hint: "Include offline_access in the scopes or no refresh token is issued.",
+  },
+  linkedin: {
+    authorize_url: "https://www.linkedin.com/oauth/v2/authorization",
+    token_url: "https://www.linkedin.com/oauth/v2/accessToken",
+    scopes_example: "openid profile r_organization_admin r_organization_social w_organization_social",
+    hint:
+      "Posting as a company page needs w_organization_social and a page admin signing in; r_organization_admin lets the token list the pages it may post to. " +
+      "Access tokens last 60 days; a refresh token is issued only to apps LinkedIn has enabled for it, " +
+      "otherwise the token is stored as is and you connect again when it expires. " +
+      "The redirect URL must match what the app registers exactly, and only localhost may be plain http.",
+  },
+};
+
+export const OAUTH_PRESET_NAMES = Object.keys(OAUTH_PRESETS);