@foldrun/core 0.3.0 → 0.5.0

package/dist/src/platform.d.ts

@@ -1,22 +1,95 @@
-import type { FlowStep, RunRecord } from "./store.ts";
+import type { FlowInfo, FlowStep, RunRecord } from "./store.ts";
 import type { RunInContainerArgs, ContainerStepOutcome } from "./run-container.ts";
 import type { EgressHooks } from "./egress.ts";
 export type IsolatedStepRunner = (args: RunInContainerArgs) => Promise<ContainerStepOutcome>;
+/** Who this install is for. `hosted` means someone is paying the operator
+ *  for it — a wallet, a plan, a bill. `self-hosted` is everything else: a
+ *  laptop, a company's own box, the open-source download. */
+export type Edition = "self-hosted" | "hosted";
+/** What a trigger gate decided. `admit: false` is never an error: the
+ *  trigger was received and understood, and the flow's own file says this
+ *  one does not become a run. `detail` is what the sender and the log are
+ *  told, because a silent drop reads exactly like a broken hook. */
+export type TriggerAdmission = {
+    admit: true;
+} | {
+    admit: false;
+    reason: "duplicate" | "throttled" | "quarantined" | "paused" | "debounced";
+    detail: string;
+    firesAt?: number;
+};
 export interface PlatformHooks {
+    /** Is this a hosted install? The ONE question every commercial surface —
+     *  the wallet, top-ups, plan limits, whatever is added next that assumes
+     *  a customer — asks before it renders or answers. Default: self-hosted,
+     *  which is what a process that never registered a platform is, and what
+     *  the open-source image is unless its operator configures billing. One
+     *  predicate, one place, so "does the community build show X" is a test
+     *  and not an audit. */
+    edition(): Edition;
     /** Put a flow run where a worker will pick it up. Default: start it here, now. */
-    enqueueFlowRun(tenant: string, workspace: string, steps: FlowStep[], flowName: string, modelOverride?: string | null, tags?: string[]): Promise<RunRecord>;
+    enqueueFlowRun(tenant: string, workspace: string, steps: FlowStep[], flowName: string, modelOverride?: string | null, tags?: string[], 
+    /** The person who asked, when one did — their email. A schedule, a
+     *  webhook and a chained flow leave it unset, which is what makes
+     *  "nobody approves their own run" a rule the record can enforce. */
+    startedBy?: string | null, 
+    /** `test: true` marks the run a test run (see test-mode.ts). Unset
+     *  lets the platform decide — a preview workspace's runs are tests
+     *  unless the flow says `live: true`. */
+    opts?: {
+        test?: boolean;
+    }): Promise<RunRecord>;
     /** A parked run was approved and has no driver; line it up. Default: nothing —
      *  locally the starter that parked it is still polling the record. */
     enqueueResume(tenant: string, workspace: string, runId: string): Promise<void>;
+    /**
+     * What a run has spent so far, in the money the customer is actually
+     * billed — tokens AND the sandbox seconds behind them.
+     *
+     * `budget:` says "the most one run may spend", and for a long time it
+     * only ever compared token cost. A step that called no model — a script
+     * looping on a page that never loads, a browser waiting on a selector
+     * that never appears — spent nothing by that reading and was capped by
+     * nothing, while the sandbox billed by the second. The platform has no
+     * clock of its own by design, so the cap is the only backstop there is,
+     * and it has to count the whole bill for that to be true.
+     *
+     * Default: token cost, which is the entire bill on an install that
+     * prices no compute.
+     */
+    runSpend(run: RunRecord): number;
+    /**
+     * Should a trigger become a run? The flow file's `idempotency:`,
+     * `throttle:`, `debounce:` and `disable_after:` are all answered here,
+     * because all four need state that outlives one delivery — what has been
+     * seen, when the last run started, what is still being waited out.
+     *
+     * Default: yes, always. A laptop has no fleet to protect and no duplicate
+     * deliveries to remember; the local runner is the one asking, and it asked
+     * because a person did.
+     */
+    admitTrigger(tenant: string, workspace: string, flow: FlowInfo, opts?: {
+        deliveryKey?: string | null;
+        body?: string;
+        tag?: string;
+    }): Promise<TriggerAdmission>;
+    /** An admitted trigger whose start then threw. Undoes what admitTrigger
+     *  recorded — the delivery as seen, the throttle window — so the sender's
+     *  retry is a fresh event rather than a "duplicate" of a run that never
+     *  existed. Default: nothing, because the default gate records nothing. */
+    rollbackTrigger(tenant: string, workspace: string, flow: FlowInfo, opts?: {
+        deliveryKey?: string | null;
+        reason?: string;
+    }): Promise<void>;
     /** Step executors by FOLDRUN_RUN_ISOLATION value, beyond the `container`
      *  one core ships. The platform adds `k8s`. */
     isolation: Record<string, IsolatedStepRunner>;
     /** Destroy whatever sandboxes a stopped run still has. Default: nothing to destroy. */
     killRunSandboxes(runId: string): void;
     /** Publish storage/public/ as share links after a run. Default: no links. */
-    syncPublicShares(tenant: string, workspace: string): {
+    syncPublicShares(tenant: string, workspace: string): Promise<{
         added: string[];
-    };
+    }>;
     /** The workspace a preview was branched from, for inherited secrets. Default: none. */
     previewSourceOf(tenant: string, workspace: string): string | null;
     /** This account's own data key, or null to use the install key. */
@@ -34,9 +107,76 @@ export interface PlatformHooks {
      *  on its record is resumed rather than destroyed and run again. Default:
      *  nothing is. */
     sandboxResumable(kind: string): boolean;
+    /**
+     * Where the platform's built-in tools sit on disk, materialised at boot —
+     * a shelf every account reads, beneath its own library. A name found in
+     * the workspace wins, then the account's copy, then this. Default: none,
+     * which is what a laptop has; there the gallery is a dashboard feature and
+     * not a directory, and an agent grants only what it or its account owns.
+     */
+    galleryDir(): string | null;
+    /**
+     * An oauth2 secret was just refreshed — `error` null when it worked, the
+     * provider's reason when it did not. The platform keeps each connection's
+     * health, emails once when a grant is dead, and answers with the one-click
+     * reconnect address, which the failing step's error then quotes. Default:
+     * nothing to say, which is a laptop.
+     */
+    noteOAuthRefresh(ctx: {
+        tenant: string;
+        workspace?: string;
+    }, name: string, error: string | null): Promise<string | undefined>;
+    /**
+     * fetch() for a URL a tenant chose — a webhook, an OAuth token endpoint,
+     * a provider base URL, an OpenAPI source. On a platform these run on the
+     * worker or web tier, which can reach what a sandbox cannot, so the
+     * platform refuses private and cluster addresses. Default: plain fetch,
+     * which is a laptop calling its own LAN on purpose. Core calls this only
+     * through untrusted-fetch.ts, once per hop with `redirect: "manual"`, so
+     * every redirect target is checked here like the first URL was.
+     */
+    fetchUntrusted(url: string, init?: RequestInit): Promise<Response>;
+    /**
+     * Hand a notify: webhook to whatever delivers it. The platform records
+     * the delivery, makes the first attempt now and retries on a backoff from
+     * the worker (`retry: true`); `retry: false` is one attempt, recorded —
+     * the test button. Default: one attempt now, recorded nowhere, which is a
+     * laptop: there is no worker to retry from and nobody to read the log.
+     */
+    deliverWebhook(tenant: string, workspace: string, delivery: {
+        event: string;
+        body: string;
+        retry: boolean;
+    }): Promise<WebhookDeliveryOutcome>;
+    /**
+     * Does this person take this optional category of mail — for this
+     * workspace, when the category is per workspace? Asked by mail.ts at send
+     * time, never for required mail. Default: yes; a laptop keeps no
+     * preferences and sends what it always sent.
+     */
+    mailPreference(tenant: string, email: string, category: string, workspace: string | null): Promise<boolean>;
+}
+/** What handing a webhook over came to: the delivery's id (the
+ *  X-Foldrun-Delivery header) and its first attempt, when one was made. */
+export interface WebhookDeliveryOutcome {
+    ok: boolean;
+    deliveryId: string;
+    statusCode: number | null;
+    /** The receiver's words or the error, trimmed — what the test reports. */
+    detail: string;
+    /** True when a failed first attempt has later ones scheduled. */
+    retrying?: boolean;
 }
 export declare const platform: PlatformHooks;
 /** Install the platform's implementations. Partial: what is not given keeps its local default. */
 export declare function registerPlatform(hooks: Partial<PlatformHooks>): void;
+/**
+ * Does a platform own the queue? True once something registered its own
+ * enqueueFlowRun — whatever process asks. An eval used to decide this from
+ * FOLDRUN_ROLE === "web", so on a worker it started the run in-process and
+ * walked around the queue the platform was counting on (the account cap,
+ * the lanes, the per-pod lease). The seam is the fact; the role is a guess.
+ */
+export declare function platformQueues(): boolean;
 /** Back to the local defaults — for tests that register and must not leak. */
 export declare function resetPlatform(): void;

package/dist/src/platform.js

@@ -12,20 +12,34 @@
 // and calls registerPlatform() once at boot. A process that forgets to is a
 // local install — which is exactly the failure that is safe.
 const local = {
-    async enqueueFlowRun(tenant, workspace, steps, flowName, modelOverride, tags = []) {
+    edition: () => "self-hosted",
+    async enqueueFlowRun(tenant, workspace, steps, flowName, modelOverride, tags = [], startedBy = null, opts = {}) {
         // Imported here, not at the top: runner.ts imports this file.
         const { startFlowRun } = await import("./runner.js");
-        return startFlowRun(tenant, workspace, steps, flowName, modelOverride ?? null, tags);
+        return startFlowRun(tenant, workspace, steps, flowName, modelOverride ?? null, tags, null, startedBy, opts);
     },
     async enqueueResume() { },
+    admitTrigger: async () => ({ admit: true }),
+    async rollbackTrigger() { },
+    runSpend: (run) => run.steps.reduce((sum, s) => sum + (s.costUsd ?? 0), 0),
     isolation: {},
     killRunSandboxes() { },
-    syncPublicShares: () => ({ added: [] }),
+    syncPublicShares: async () => ({ added: [] }),
     previewSourceOf: () => null,
     tenantKey: () => null,
     egress: { lease: async () => null },
     workspaceChanged() { },
     sandboxResumable: () => false,
+    galleryDir: () => null,
+    noteOAuthRefresh: async () => undefined,
+    fetchUntrusted: (url, init) => fetch(url, init),
+    async deliverWebhook(tenant, workspace, delivery) {
+        const { attemptWebhook, newDeliveryId } = await import("./notify.js");
+        const deliveryId = newDeliveryId();
+        const a = await attemptWebhook(tenant, workspace, { id: deliveryId, event: delivery.event, body: delivery.body, attempt: 1 });
+        return { ok: a.ok, deliveryId, statusCode: a.statusCode, detail: a.error ?? a.response ?? "" };
+    },
+    mailPreference: async () => true,
 };
 // One object per PROCESS, not per module instance. A bundler that compiles
 // the boot file and each route handler separately (Next does) gives every
@@ -44,6 +58,16 @@ export function registerPlatform(hooks) {
         isolation: { ...platform.isolation, ...(hooks.isolation ?? {}) },
     });
 }
+/**
+ * Does a platform own the queue? True once something registered its own
+ * enqueueFlowRun — whatever process asks. An eval used to decide this from
+ * FOLDRUN_ROLE === "web", so on a worker it started the run in-process and
+ * walked around the queue the platform was counting on (the account cap,
+ * the lanes, the per-pod lease). The seam is the fact; the role is a guess.
+ */
+export function platformQueues() {
+    return platform.enqueueFlowRun !== local.enqueueFlowRun;
+}
 /** Back to the local defaults — for tests that register and must not leak. */
 export function resetPlatform() {
     Object.assign(platform, local, { isolation: {} });

package/dist/src/provider-health.d.ts

@@ -0,0 +1,55 @@
+import { type ProviderSpec } from "./store.ts";
+export type HealthVerdict = "ok" | "credential" | "not-found" | "busy" | "unreachable" | "provider-error";
+export interface ProviderCheck {
+    /** How this provider is written in the file: its preset name, or its host. */
+    provider: string;
+    /** The model id actually asked for — what a run would send. */
+    model: string;
+    verdict: HealthVerdict;
+    ok: boolean;
+    status: number | null;
+    ms: number;
+    /** One sentence a person can act on, in the provider's own words where
+     *  they said anything useful. */
+    detail: string;
+}
+/**
+ * One request at the provider, in the wire format it speaks, asking for a
+ * single token. Never throws: an unreachable host is a verdict, not an
+ * exception, because this runs on a tick.
+ */
+export declare function checkProvider(tenant: string, workspace: string | null, spec: ProviderSpec, model: string): Promise<ProviderCheck>;
+/** A provider block in use, and where it is declared — because "which file
+ *  do I edit" is the next question after "this key is dead". */
+export interface ProviderInUse {
+    spec: ProviderSpec;
+    /** The workspace whose vault resolves this block's secrets. Null for the
+     *  account's own block, which resolves against the account vault. */
+    workspace: string | null;
+    /** Human-readable origin: "account", "rank-desk", "rank-desk/writer". */
+    declaredIn: string;
+    /** The model id a run would send for the cheapest tier, which is what a
+     *  health check should spend. */
+    model: string;
+}
+/**
+ * Every distinct provider block this account would actually use, read from
+ * the same three places a run reads them: the account, each workspace, each
+ * agent.
+ *
+ * Deduplicated by endpoint and token, because ten agents sharing one gateway
+ * are one credential and checking it ten times spends ten times as much to
+ * learn the same fact. The origin recorded is the first one seen, which is
+ * the broadest — an account block covers everything under it.
+ */
+export declare function providersInUse(tenant: string): ProviderInUse[];
+/**
+ * Check every provider this account uses, one at a time.
+ *
+ * Serial on purpose: this is housekeeping on a tick, the whole point is that
+ * it is cheap, and firing twelve model requests at once to save eight
+ * seconds nobody is waiting for would be a strange trade.
+ */
+export declare function checkAccountProviders(tenant: string): Promise<(ProviderCheck & {
+    declaredIn: string;
+})[]>;

package/dist/src/provider-health.js

@@ -0,0 +1,233 @@
+// Is the key still good?
+//
+// A customer's own model key can be revoked, expire, run out of credit or
+// have its base URL moved, and today the platform finds out the way the
+// customer does: a desk fails at five in the morning. Twenty-seven of the
+// thirty provider presets have never had an agent run through them from
+// this runtime at all, so "it worked when we set it up" is doing a lot of
+// work in that sentence.
+//
+// This is deliberately NOT the tool-loop probe next door. `foldrun probe`
+// asks "can this model drive an agent", which is a question about a model
+// and is asked once. This asks "does this endpoint still take our key",
+// which is a question about a credential and has to be asked repeatedly —
+// so it has to be cheap. One request, one token of output, no SDK, no tool
+// loop, no agent. A fraction of a cent, and it answers the thing that
+// actually breaks.
+//
+// It reads the same provider block a run reads, resolved the same way, so a
+// pass here means a run would reach the same place with the same key.
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import { getSecret } from "./secrets.js";
+import { noteSecretUse, healthKey } from "./secret-health.js";
+import { accountDir, workspaceDir, listWorkspaces, listAgents, parseProvider } from "./store.js";
+import { fetchUntrusted } from "./untrusted-fetch.js";
+/** How long to wait. A provider slower than this is not one a step should
+ *  be waiting on either, and the check must never hold a tick. */
+const TIMEOUT_MS = 15_000;
+/** What each status means for a credential, and what a person does about
+ *  it. Kept as a table because the mapping IS the feature: "401" tells you
+ *  nothing you can act on, "the key is no longer accepted" tells you
+ *  everything. */
+function verdictFor(status) {
+    if (status >= 200 && status < 300)
+        return { verdict: "ok", detail: "the key was accepted and the model answered" };
+    if (status === 401 || status === 403) {
+        return { verdict: "credential", detail: "the key is no longer accepted — revoked, rotated, or wrong for this endpoint" };
+    }
+    if (status === 402)
+        return { verdict: "credential", detail: "the account behind this key is out of credit" };
+    if (status === 404) {
+        return { verdict: "not-found", detail: "the endpoint or the model id does not exist there — check base_url and models:" };
+    }
+    if (status === 429) {
+        // Not a health problem. A busy provider is a provider that is working,
+        // and reporting it as broken would train people to ignore the alert.
+        return { verdict: "busy", detail: "rate limited right now — the key is fine" };
+    }
+    if (status >= 500)
+        return { verdict: "provider-error", detail: "the provider is failing at its end" };
+    return { verdict: "provider-error", detail: `unexpected HTTP ${status}` };
+}
+/** `${SECRET}` in a token or header, filled from this account's vault. */
+function resolve(tenant, workspace, raw) {
+    return raw.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => {
+        const hit = getSecret(tenant, name, workspace ?? undefined);
+        return hit ? hit.value : whole;
+    });
+}
+/**
+ * One request at the provider, in the wire format it speaks, asking for a
+ * single token. Never throws: an unreachable host is a verdict, not an
+ * exception, because this runs on a tick.
+ */
+export async function checkProvider(tenant, workspace, spec, model) {
+    const label = spec.name || (() => {
+        try {
+            return new URL(spec.baseUrl).host;
+        }
+        catch {
+            return spec.baseUrl || "provider";
+        }
+    })();
+    const began = Date.now();
+    const fail = (verdict, detail, status = null) => ({
+        provider: label,
+        model,
+        verdict,
+        ok: false,
+        status,
+        ms: Date.now() - began,
+        detail,
+    });
+    const token = resolve(tenant, workspace, spec.token);
+    if (!token || token.includes("${")) {
+        return fail("credential", `the secret named in provider.token is not in this account's vault (${spec.token})`);
+    }
+    if (!spec.baseUrl)
+        return fail("unreachable", "this provider block has no base_url");
+    // The three wire formats, each asking for the smallest possible answer.
+    const base = spec.baseUrl.replace(/\/+$/, "");
+    const anthropic = spec.format === "anthropic";
+    const url = anthropic
+        ? `${base}/v1/messages`
+        : spec.format === "responses"
+            ? `${base}/responses`
+            : `${base}/chat/completions`;
+    const body = anthropic
+        ? { model, max_tokens: 1, messages: [{ role: "user", content: "hi" }] }
+        : spec.format === "responses"
+            ? { model, max_output_tokens: 16, input: "hi" }
+            : { model, max_tokens: 1, messages: [{ role: "user", content: "hi" }] };
+    const headers = { "content-type": "application/json" };
+    // An Anthropic-format endpoint takes the key in whichever header its
+    // `auth:` says; everything else is a bearer token.
+    if (anthropic && spec.auth === "x-api-key") {
+        headers["x-api-key"] = token;
+        headers["anthropic-version"] = "2023-06-01";
+    }
+    else {
+        headers.authorization = `Bearer ${token}`;
+        if (anthropic)
+            headers["anthropic-version"] = "2023-06-01";
+    }
+    for (const [k, v] of Object.entries(spec.headers ?? {}))
+        headers[k.toLowerCase()] = resolve(tenant, workspace, v);
+    try {
+        const res = await fetchUntrusted(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        }, { sameOrigin: true });
+        const { verdict, detail } = verdictFor(res.status);
+        // The check is itself a use of the credential, and the most informative
+        // one there is: it was made for exactly this purpose.
+        const named = spec.token.match(/^\$\{([A-Z][A-Z0-9_]*)\}$/)?.[1];
+        if (named) {
+            let host = spec.baseUrl;
+            try {
+                host = new URL(spec.baseUrl).host;
+            }
+            catch {
+                // an unparseable base_url is its own problem, reported above
+            }
+            const hit = getSecret(tenant, named, workspace ?? undefined);
+            noteSecretUse(tenant, healthKey(named, hit?.scope === "workspace" ? "workspace" : "account", workspace), { host, status: res.status });
+        }
+        // The provider's own words when it refused. They are the difference
+        // between "fix your key" and "fix your model id", and they are only
+        // ever in the body.
+        let said = "";
+        if (!res.ok) {
+            said = (await res.text().catch(() => "")).replace(/\s+/g, " ").slice(0, 300);
+        }
+        return {
+            provider: label,
+            model,
+            verdict,
+            // Busy counts as healthy: the key worked, the provider is simply full.
+            ok: verdict === "ok" || verdict === "busy",
+            status: res.status,
+            ms: Date.now() - began,
+            detail: said ? `${detail} — ${said}` : detail,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return fail("unreachable", /timeout|aborted/i.test(message) ? `no answer within ${TIMEOUT_MS / 1000}s` : message);
+    }
+}
+/** The cheapest tier's id for a provider block: what it calls `fast`, or
+ *  our own fast model when it remaps nothing. */
+function cheapestModel(spec) {
+    return spec.models.fast || spec.models.default || spec.models.max || "claude-haiku-4-5-20251001";
+}
+function frontmatterOf(file) {
+    try {
+        return (matter(fs.readFileSync(file, "utf8")).data ?? {});
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Every distinct provider block this account would actually use, read from
+ * the same three places a run reads them: the account, each workspace, each
+ * agent.
+ *
+ * Deduplicated by endpoint and token, because ten agents sharing one gateway
+ * are one credential and checking it ten times spends ten times as much to
+ * learn the same fact. The origin recorded is the first one seen, which is
+ * the broadest — an account block covers everything under it.
+ */
+export function providersInUse(tenant) {
+    const out = [];
+    const seen = new Set();
+    const add = (raw, workspace, declaredIn) => {
+        const spec = parseProvider(raw);
+        if (!spec || !spec.baseUrl)
+            return;
+        // The token is part of the identity: the same gateway with two different
+        // keys is two credentials, and either can die on its own.
+        const key = `${workspace ?? ""}|${spec.baseUrl}|${spec.token}|${cheapestModel(spec)}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        out.push({ spec, workspace, declaredIn, model: cheapestModel(spec) });
+    };
+    add(frontmatterOf(path.join(accountDir(tenant), "AGENTS.md")).provider, null, "account");
+    for (const ws of safeList(() => listWorkspaces(tenant))) {
+        const dir = workspaceDir(tenant, ws.name);
+        add(frontmatterOf(path.join(dir, "AGENTS.md")).provider, ws.name, ws.name);
+        for (const agent of safeList(() => listAgents(tenant, ws.name))) {
+            add(frontmatterOf(path.join(dir, "agents", agent.name, "agent.md")).provider, ws.name, `${ws.name}/${agent.name}`);
+        }
+    }
+    return out;
+}
+function safeList(fn) {
+    try {
+        return fn();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Check every provider this account uses, one at a time.
+ *
+ * Serial on purpose: this is housekeeping on a tick, the whole point is that
+ * it is cheap, and firing twelve model requests at once to save eight
+ * seconds nobody is waiting for would be a strange trade.
+ */
+export async function checkAccountProviders(tenant) {
+    const results = [];
+    for (const use of providersInUse(tenant)) {
+        const check = await checkProvider(tenant, use.workspace, use.spec, use.model);
+        results.push({ ...check, declaredIn: use.declaredIn });
+    }
+    return results;
+}