@foldrun/core 0.2.0

package/dist/src/notify.js

@@ -0,0 +1,252 @@
+// 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.js";
+import { accountDir, workspaceDir, runCost } from "./store.js";
+import { getSecret } from "./secrets.js";
+import { approveToken, publicUrl } from "./webhook.js";
+/**
+ * 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) {
+    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) {
+    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) {
+    return accountMail(tenant) ?? platformMail(tenant);
+}
+const DEFAULT_EVENTS = ["failed", "awaiting-approval"];
+export function notifyConfig(tenant, workspace) {
+    const raw = readAgentsMd(workspaceDir(tenant, workspace))?.data.notify ??
+        readAgentsMd(accountDir(tenant))?.data.notify;
+    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;
+        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, workspace, runId) {
+    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) {
+    return /^(eval|adhoc):/.test(flow);
+}
+export async function sendRunNotification(tenant, workspace, run) {
+    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) => 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/dist/src/oauth-presets.d.ts

@@ -0,0 +1,13 @@
+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 declare const OAUTH_PRESETS: Record<string, OAuthPreset>;
+export declare const OAUTH_PRESET_NAMES: string[];

package/dist/src/oauth-presets.js

@@ -0,0 +1,39 @@
+// 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 const OAUTH_PRESETS = {
+    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);

package/dist/src/okf.d.ts

@@ -0,0 +1,220 @@
+export declare const OKF_VERSION = "0.2";
+/** This producer's actor string, in the spec's `<producer>/<version>` form. */
+export declare const PRODUCER = "foldrun/0.1.0";
+/**
+ * Our stand-in when a v0.1 document carries only `timestamp`. Not an actor —
+ * it says we don't know who, which is different from knowing it was a machine.
+ */
+export declare const UNKNOWN_ACTOR = "unknown (v0.1 timestamp)";
+/**
+ * §7 defines three actor forms, and only one of them is a person:
+ *
+ *   human:<id>              a person          →  human
+ *   <producer>/<version>    an agent or tool  →  machine
+ *   process:<id>            an automated job  →  machine
+ *
+ * So the test is for `human:`, not for any machine form. Testing the other way
+ * round meant matching a literal "producer/" prefix — but the producer's *name*
+ * is the first segment, so the spec's own `reference_agent/gemini-2.5-pro` did
+ * not match, `process:` did not match, and neither did this platform's own
+ * PRODUCER. The mark existed and fired for nothing real.
+ */
+export declare const isHumanActor: (actor: string) => boolean;
+export type TrustTier = "unverified" | "machine-confirmed" | "human-reviewed";
+export type OkfStatus = "draft" | "stable" | "deprecated";
+export interface OkfSource {
+    resource: string;
+    id?: string;
+    title?: string;
+    author?: string;
+    usageCount?: number;
+    lastModified?: string;
+    /** Per-entry override of the shared window, per §sources. */
+    usageWindow?: {
+        from?: string;
+        to?: string;
+    };
+}
+/**
+ * An `Attested Computation` contract. The spec binds a named computation to
+ * typed parameters and names an attester that mechanically checks the run
+ * matched the declaration — no signatures, just deterministic comparison.
+ *
+ * The runtime half (receipt and verdict wire formats, the lifecycle around a
+ * run) is explicitly deferred to a future spec revision, so no consumer can
+ * evaluate a verdict yet. What a consumer CAN do today is what the spec
+ * already requires: surface an unattested computation rather than presenting
+ * its output as though it had been checked.
+ */
+export interface OkfComputation {
+    runtime: string;
+    parameters: {
+        name: string;
+        type: string;
+        required: boolean;
+    }[];
+    computation: string | null;
+    executorResource: string | null;
+    receiptFields: string[];
+    attesterResource: string | null;
+    /** Why this contract can't be attested right now, if it can't. */
+    attestationIssues: string[];
+}
+export interface OkfDoc {
+    /** Path within the bundle — the spec makes the path the identity, so a
+     *  nested concept is `tables/orders.md`, not `orders.md`. */
+    file: string;
+    type: string;
+    title: string;
+    description: string;
+    tags: string[];
+    status: OkfStatus;
+    staleAfter: string | null;
+    stale: boolean;
+    generatedBy: string | null;
+    /** When it was produced, from `generated.at`. */
+    generatedAt: string | null;
+    /** Every `verified` entry, with its timestamp where one was given. */
+    verified: OkfActor[];
+    /** Just the actors — what the trust tier is computed from. */
+    verifiedBy: string[];
+    /** The most recent verification, or null if nobody dated theirs. */
+    verifiedAt: string | null;
+    trust: TrustTier;
+    /** Recommended v0.1 fields. */
+    resource: string | null;
+    timestamp: string | null;
+    sources: OkfSource[];
+    /** Present only on `type: Attested Computation` concepts. */
+    computation: OkfComputation | null;
+}
+/**
+ * The signals that decide whether a concept is worth opening: who produced it,
+ * and whether anyone has confirmed it.
+ *
+ * v0.2's argument for putting these in frontmatter is that most interactions
+ * with a concept never reach its body — a consumer first has to judge relevance
+ * and trustworthiness, and should be able to do that without paying for prose.
+ * That only works if the signals actually reach the index. `generated` was
+ * parsed and stored here and then surfaced nowhere, so on disk an agent's
+ * invention and a person's verified note were distinguishable and at the moment
+ * of choosing between them they were not — which is the problem the field was
+ * added to solve.
+ *
+ * Only the machine case is named. A person writing is the default assumption,
+ * and a mark on every line costs tokens on the one thing whose whole job is to
+ * be cheap to scan.
+ *
+ * One definition, used by both index builders. They render different prose
+ * around it on purpose — the memory index speaks to a model mid-run — but they
+ * must not disagree about what the signals *are*.
+ */
+export declare function provenanceMarks(doc: Pick<OkfDoc, "generatedBy" | "trust"> & {
+    verifiedAt?: string | null;
+}): string[];
+/** Derived, never stored — the spec is explicit that consumers compute this. */
+export declare function trustTier(verifiedBy: string[]): TrustTier;
+/**
+ * An actor and when it acted — `{ by: human:kliu@acme, at: 2026-07-01T16:00Z }`.
+ *
+ * `at` is the difference between a fact somebody checked last week and one
+ * somebody checked in 2019. Both used to read as "human-reviewed", which makes
+ * the tier answer a weaker question than it appears to: not "can I rely on
+ * this" but "did anyone ever look".
+ */
+export interface OkfActor {
+    by: string;
+    at: string | null;
+}
+/** The most recent `at` among these actors, or null if none carried one. */
+export declare function latestAt(list: OkfActor[]): string | null;
+export declare function readDoc(dir: string, file: string, today?: Date): OkfDoc | null;
+/**
+ * Every concept in a bundle, including nested directories — Google's own
+ * example is a tree (`sales/tables/orders.md`), and the path is the identity.
+ * @param depth guards against a pathological tree; bundles are documentation,
+ *              not filesystems.
+ */
+export declare function readBundle(dir: string, today?: Date, prefix?: string, depth?: number): OkfDoc[];
+/**
+ * Files that would fail somebody else's conformance check, with the reason.
+ *
+ * Deliberately walks the directory rather than readBundle(): readBundle answers
+ * "what should this platform show", and the two questions differ by exactly the
+ * files we chose not to display. A validator that isn't ours applies the spec's
+ * reserved set, so this one has to as well — otherwise the check agrees with us
+ * about a bundle a consumer will reject.
+ */
+export declare function conformanceIssues(dir: string, prefix?: string, depth?: number): {
+    file: string;
+    issue: string;
+}[];
+/**
+ * The bundle's index.md. Progressive disclosure, per the spec: headings and
+ * bulleted links with descriptions, and no frontmatter — except `okf_version`
+ * at a bundle root, which is the only place the spec permits it.
+ */
+export declare function buildIndex(docs: OkfDoc[], title: string, isRoot: boolean, children?: string[]): string;
+/**
+ * Write index.md for a bundle and for every directory inside it. The spec puts
+ * an index at each level, so a nested bundle is navigable without a full walk.
+ */
+export declare function syncIndex(dir: string, title: string, isRoot?: boolean, depth?: number): void;
+/**
+ * Dates the platform had to drop, with where they were.
+ *
+ * Deliberately not part of conformanceIssues. That function answers one
+ * question — would an outside validator accept this bundle — and the spec's
+ * three rules say nothing about the *shape* of a date, so a bad one is
+ * conformant and still unusable here. Two questions, two functions, and the
+ * conformance answer stays exactly the spec's.
+ */
+export declare function dateIssues(dir: string, prefix?: string, depth?: number): {
+    file: string;
+    field: string;
+    value: string;
+}[];
+/**
+ * Stamp provenance on every concept in a bundle an agent has just written to.
+ *
+ * Recursive, and it skips the spec's reserved names. Doing this by hand with a
+ * flat readdir and an `!== "index.md"` filter missed every concept in a nested
+ * section, and — worse — stamped `log.md`, writing a concept's frontmatter onto
+ * a reserved file that §9 gives its own structure. Nothing reported that,
+ * because a conformance check skips reserved names by definition: the file
+ * ends up malformed in a way only its readers notice.
+ *
+ * Returns the bundle-relative paths it stamped, so the caller can record each
+ * one in the log. Returning a bare boolean meant the caller had nothing to
+ * name, so it re-synced the index and wrote no log entry at all — and a run
+ * that taught the agent something left no trace in the one file whose job is
+ * to say what changed and when.
+ */
+export declare function stampBundle(dir: string, agent: string | null, at?: Date, prefix?: string, depth?: number): string[];
+/**
+ * Make every OKF bundle in a workspace a bundle.
+ *
+ * A concept file with a `type` is conformant on its own, but a *bundle* is
+ * only self-describing once its root index.md exists to carry `okf_version`.
+ * Both scaffold paths wrote their starter files straight to disk, so a new
+ * workspace's knowledge/ was a directory of valid concepts and nothing that
+ * said which version of the format they were written against — the one thing
+ * a consumer reads first.
+ *
+ * An agent's own pair is nested rather than a root, so it gets an index
+ * without a version, which is what the spec permits.
+ */
+export declare function syncWorkspaceBundles(root: string): void;
+/**
+ * log.md — the bundle's change history. The spec asks for date-grouped
+ * entries, newest first, ISO 8601 headings, with the **Creation** / **Update**
+ * convention. Appending here means the history is a real artifact rather than
+ * something you reconstruct from git.
+ */
+export declare function appendLog(dir: string, file: string, kind: "Creation" | "Update", at?: Date): void;
+/**
+ * Stamp provenance on a file that doesn't declare it. Used after a run so a
+ * memory an agent wrote is attributable — without this, a fact the model
+ * invented and a fact a person verified are indistinguishable on disk.
+ */
+export declare function stampGenerated(file: string, agent: string | null, at?: Date): boolean;