@foldrun/core 0.2.0

package/dist/src/agents-md.js

@@ -0,0 +1,83 @@
+// Editing AGENTS.md frontmatter one key at a time, in place.
+//
+// AGENTS.md is a file people write by hand — comments, spacing, key order
+// are theirs. A settings form that re-serialised the whole frontmatter
+// would erase all of that on the first Save. So a key is replaced
+// textually: its block (the `key:` line and the indented lines under it)
+// is cut out, and the new block is appended where it stood. Everything
+// else in the file is untouched. Null removes the key.
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+const FRONT = /^(---\r?\n)([\s\S]*?)(\r?\n---)(\r?\n|$)/;
+/** The frontmatter of a directory's AGENTS.md (or project.md), or {}. */
+export function readAgentsMdKeys(dir) {
+    for (const name of ["AGENTS.md", "project.md"]) {
+        const file = path.join(dir, name);
+        if (!fs.existsSync(file))
+            continue;
+        try {
+            return (matter(fs.readFileSync(file, "utf8")).data ?? {});
+        }
+        catch {
+            return {};
+        }
+    }
+    return {};
+}
+/** One key as YAML lines, the way gray-matter writes frontmatter — the same
+ *  serialiser that already reads these files, so nothing new to disagree. */
+function dumpKey(key, value) {
+    const block = matter.stringify("", { [key]: value });
+    const m = block.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    return (m ? m[1] : `${key}: ${String(value)}`).trimEnd().split("\n");
+}
+/** The text of `content` with each key in `patch` replaced (or removed for
+ *  null), everything else byte for byte as it was. A file with no
+ *  frontmatter gets one. */
+export function patchFrontmatter(content, patch) {
+    const m = content.match(FRONT);
+    let open = "---\n";
+    let body = "";
+    let close = "\n---";
+    let rest = content;
+    if (m) {
+        [, open, body, close] = m;
+        rest = content.slice(m[0].length - (m[4] ?? "").length);
+    }
+    else {
+        rest = content.startsWith("\n") ? content : `\n${content}`;
+    }
+    let lines = body === "" ? [] : body.split("\n");
+    for (const [key, value] of Object.entries(patch)) {
+        const at = lines.findIndex((l) => new RegExp(`^${key.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*:`).test(l));
+        let end = at;
+        if (at !== -1) {
+            end = at + 1;
+            // The block continues while lines are indented or blank-inside-block.
+            while (end < lines.length && (/^[ \t]/.test(lines[end]) || lines[end].trim() === ""))
+                end++;
+            // A blank line at the block's foot belongs to what follows.
+            while (end > at + 1 && lines[end - 1].trim() === "")
+                end--;
+        }
+        const replacement = value === null || value === undefined ? [] : dumpKey(key, value);
+        if (at === -1)
+            lines = [...lines, ...replacement];
+        else
+            lines = [...lines.slice(0, at), ...replacement, ...lines.slice(end)];
+    }
+    const front = lines.length ? `${open}${lines.join("\n")}${close}` : "";
+    if (!front)
+        return rest.replace(/^(\r?\n)+/, "");
+    return `${front}${m ? m[4] ?? "\n" : "\n"}${rest.replace(/^\r?\n/, m ? "" : "")}`;
+}
+/** Apply a frontmatter patch to a directory's AGENTS.md, creating the file
+ *  when the directory has none. Returns the new content. */
+export function setAgentsMdKeys(dir, patch) {
+    const file = path.join(dir, "AGENTS.md");
+    const before = fs.existsSync(file) ? fs.readFileSync(file, "utf8") : "";
+    const after = patchFrontmatter(before, patch);
+    fs.writeFileSync(file, after);
+    return after;
+}

package/dist/src/api-tools.d.ts

@@ -0,0 +1,38 @@
+import { createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import type { ApiSpec } from "./store.ts";
+export declare function secretsUsedByApi(api: ApiSpec): string[];
+/**
+ * A token bucket: `count` tokens, refilled at `perSec`. `take()` resolves
+ * when a token is available, in arrival order — a caller never learns "no",
+ * only "not yet". Lives as long as the tool set does, which is one step.
+ */
+export declare class TokenBucket {
+    private readonly count;
+    private readonly perSec;
+    private tokens;
+    private last;
+    private chain;
+    constructor(count: number, perSec: number);
+    private refill;
+    /** Resolves with the milliseconds waited. */
+    take(): Promise<number>;
+}
+/** `<api>_<operation>`, held under the MCP cap: a long name keeps its head
+ *  and gains a hash tail, so two long names never collapse into one. */
+export declare function typedToolName(apiName: string, opId: string): string;
+export interface ApiToolResult {
+    /** Passed to the SDK as an in-process MCP server (the agent just sees tools). */
+    server: ReturnType<typeof createSdkMcpServer> | null;
+    /** Tool names to allow, e.g. mcp__foldrun_apis__call_google_ads. */
+    toolNames: string[];
+    /** Secrets referenced but not set — surfaced as run warnings. */
+    missingSecrets: string[];
+    /** Human-readable lines describing each API, appended to the system prompt. */
+    promptLines: string[];
+    /** Called after the run to collect a log of every request made. */
+    drainLog: () => string[];
+}
+export declare function buildApiTools(tenant: string, apis: ApiSpec[], workspace?: string, resolved?: {
+    env: Record<string, string | undefined>;
+    missing: string[];
+}): ApiToolResult;

package/dist/src/api-tools.js

@@ -0,0 +1,313 @@
+// Turns an agent's `apis:` declarations into real tools it can call.
+//
+// One generic tool per API, named `call_<api>`: the agent supplies a method,
+// path, optional query and body. When the API declares an `openapi:`
+// document, each of its operations becomes a typed tool of its own,
+// `<api>_<operationId>`, whose arguments are the parameters the document
+// declares — path parameters filled into the template by the platform,
+// query and header parameters routed to where they belong.
+//
+// Either way the platform resolves ${SECRET} placeholders from the encrypted
+// store, enforces the declared base URL and method allowlist, and returns
+// status + body. Credentials never enter the agent's context — it sees the
+// tool, not the token. A `rate:` on the API is a token bucket per step:
+// a call over the limit waits for its turn rather than failing.
+import crypto from "node:crypto";
+import { EGRESS_ENV, viaEgress } from "./egress.js";
+import { z } from "zod";
+import { createSdkMcpServer, tool } from "@anthropic-ai/claude-agent-sdk";
+import { resolveSecrets, materializeSecrets } from "./secrets.js";
+const MAX_BODY_CHARS = 20_000;
+/** MCP tool names are capped; ours also carry the server prefix on the wire. */
+const MAX_TOOL_NAME = 64;
+/** How many typed tools the prompt lists by name before summarising. */
+const PROMPT_LIST_CAP = 40;
+/** A wait shorter than this is not worth a word in the log. */
+const LOG_WAIT_MS = 1000;
+function substitute(value, env) {
+    return value.replace(/\$\{([A-Z][A-Z0-9_]*)\}/g, (whole, name) => env[name] ?? whole);
+}
+// Which secret names does this API's config reference?
+export function secretsUsedByApi(api) {
+    const found = new Set();
+    for (const value of [...Object.values(api.headers), ...Object.values(api.query)]) {
+        for (const m of value.matchAll(/\$\{([A-Z][A-Z0-9_]*)\}/g))
+            found.add(m[1]);
+    }
+    return [...found];
+}
+/**
+ * A token bucket: `count` tokens, refilled at `perSec`. `take()` resolves
+ * when a token is available, in arrival order — a caller never learns "no",
+ * only "not yet". Lives as long as the tool set does, which is one step.
+ */
+export class TokenBucket {
+    count;
+    perSec;
+    tokens;
+    last = Date.now();
+    chain = Promise.resolve();
+    constructor(count, perSec) {
+        this.count = count;
+        this.perSec = perSec;
+        this.tokens = count;
+    }
+    refill() {
+        const now = Date.now();
+        this.tokens = Math.min(this.count, this.tokens + ((now - this.last) / 1000) * this.perSec);
+        this.last = now;
+    }
+    /** Resolves with the milliseconds waited. */
+    take() {
+        const started = Date.now();
+        const turn = this.chain.then(async () => {
+            for (;;) {
+                this.refill();
+                if (this.tokens >= 1) {
+                    this.tokens -= 1;
+                    return;
+                }
+                const wait = Math.ceil(((1 - this.tokens) / this.perSec) * 1000);
+                await new Promise((r) => setTimeout(r, Math.max(1, wait)));
+            }
+        });
+        // The queue must survive one caller's failure (there is none today, but
+        // a rejected link would freeze every later call behind it).
+        this.chain = turn.catch(() => { });
+        return turn.then(() => Date.now() - started);
+    }
+}
+/** `<api>_<operation>`, held under the MCP cap: a long name keeps its head
+ *  and gains a hash tail, so two long names never collapse into one. */
+export function typedToolName(apiName, opId) {
+    const full = `${apiName}_${opId}`;
+    if (full.length <= MAX_TOOL_NAME)
+        return full;
+    const hash = crypto.createHash("sha256").update(full).digest("hex").slice(0, 8);
+    return `${full.slice(0, MAX_TOOL_NAME - hash.length - 1)}_${hash}`;
+}
+/**
+ * The one request path both tool shapes share: rate limit, secrets made
+ * live, base-URL confinement, the API's own headers and query, the timeout,
+ * the truncation, the log line. Typed and generic tools differ only in how
+ * they arrive at a Request.
+ */
+async function performRequest(api, env, bucket, log, req) {
+    const started = Date.now();
+    try {
+        const waited = bucket ? await bucket.take() : 0;
+        const waitNote = waited >= LOG_WAIT_MS ? ` [waited ${(waited / 1000).toFixed(1)}s for rate limit]` : "";
+        // Per call, not per build: an oauth2 secret's recipe becomes a
+        // live access token here, so a step that runs for an hour keeps
+        // getting fresh tokens (the exchange is cached until near expiry)
+        // — and a recipe can never end up inside a header.
+        const live = await materializeSecrets(env);
+        const path = req.path.startsWith("/") ? req.path : `/${req.path}`;
+        const url = new URL(api.base + path);
+        // Base-URL confinement: a path can't escape the declared host.
+        if (!url.href.startsWith(api.base)) {
+            throw new Error(`path escapes the declared base URL (${api.base})`);
+        }
+        for (const [k, v] of Object.entries(api.query)) {
+            url.searchParams.set(k, substitute(v, live));
+        }
+        for (const [k, v] of Object.entries(req.query))
+            url.searchParams.set(k, v);
+        const headers = {};
+        for (const [k, v] of Object.entries(api.headers))
+            headers[k] = substitute(v, live);
+        for (const [k, v] of Object.entries(req.headers))
+            headers[k] = v;
+        if (req.body && !headers["content-type"] && !headers["Content-Type"]) {
+            headers["content-type"] = "application/json";
+        }
+        // Through the egress proxy when this sandbox was given one: the header
+        // still says ${NAME}, and the worker fills it for this host. Without
+        // one, straight to the API with the value the env held — the CLI, tests,
+        // and an install with no proxy.
+        const res = await fetch(viaEgress(env[EGRESS_ENV], url.href), {
+            method: req.method,
+            headers,
+            body: req.body,
+            // The tool.md's `timeout:` is the only clock; none set, none applied.
+            ...(api.timeout ? { signal: AbortSignal.timeout(api.timeout * 1000) } : {}),
+        });
+        const text = await res.text();
+        const truncated = text.length > MAX_BODY_CHARS
+            ? `${text.slice(0, MAX_BODY_CHARS)}\n…[truncated ${text.length - MAX_BODY_CHARS} chars]`
+            : text;
+        log.push(`${req.method} ${url.pathname}${url.search ? "?…" : ""} → ${res.status} (${Date.now() - started}ms)${waitNote}`);
+        return {
+            content: [{ type: "text", text: `HTTP ${res.status} ${res.statusText}\n\n${truncated}` }],
+            isError: !res.ok,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        log.push(`${req.method} ${req.path} → error: ${message}`);
+        return { content: [{ type: "text", text: `Request failed: ${message}` }], isError: true };
+    }
+}
+const rateSentence = (api) => api.rate
+    ? ` Rate limit: ${api.rate.count} call${api.rate.count === 1 ? "" : "s"} per ` +
+        `${api.rate.perSec === api.rate.count ? "second" : `${Math.round(api.rate.count / api.rate.perSec)}s`}, ` +
+        `shared by every call this step makes to ${api.name}; a call over the limit waits its turn.`
+    : "";
+/** Zod for one declared parameter, typed as the document says. */
+function paramSchema(p) {
+    const base = p.type === "integer" ? z.number().int() : p.type === "number" ? z.number() : p.type === "boolean" ? z.boolean() : z.string();
+    const described = base.describe(p.description || `${p.in} parameter ${p.name}`);
+    return p.required ? described : described.optional();
+}
+/** Argument keys must be identifiers the model can write; parameter names
+ *  need not be (`filter[status]`). Map one to the other, keeping a
+ *  collision between locations apart with a suffix. */
+function argKeys(op) {
+    const out = new Map();
+    for (const p of op.params) {
+        let key = p.name.replace(/[^a-zA-Z0-9_]+/g, "_").replace(/^_+|_+$/g, "") || p.in;
+        if (/^\d/.test(key))
+            key = `_${key}`;
+        if (out.has(key))
+            key = `${key}_${p.in}`;
+        let n = 2;
+        while (out.has(key))
+            key = `${key}_${n++}`;
+        out.set(key, p);
+    }
+    return out;
+}
+function typedTool(api, op, env, bucket, log) {
+    const keys = argKeys(op);
+    const shape = {};
+    for (const [key, p] of keys)
+        shape[key] = paramSchema(p);
+    if (op.hasBody) {
+        shape.body = z
+            .string()
+            .optional()
+            .describe(`Request body as a JSON string. ${op.bodyDescription}`.trim());
+    }
+    const description = `${op.summary} — ${op.method} ${op.path} on the ${api.name} API. ` +
+        `Authentication is added automatically — never ask the user for credentials.` +
+        rateSentence(api);
+    return tool(typedToolName(api.name, op.id), description, shape, async (args) => {
+        const values = args;
+        const query = {};
+        const headers = {};
+        const pathValues = {};
+        for (const [key, p] of keys) {
+            const v = values[key];
+            if (v === undefined || v === null)
+                continue;
+            const s = String(v);
+            if (p.in === "path")
+                pathValues[p.name] = s;
+            else if (p.in === "query")
+                query[p.name] = s;
+            else
+                headers[p.name] = s;
+        }
+        let missing = null;
+        const path = op.path.replace(/\{([^}]+)\}/g, (_, name) => {
+            if (!(name in pathValues)) {
+                missing ??= name;
+                return "";
+            }
+            return encodeURIComponent(pathValues[name]);
+        });
+        if (missing) {
+            log.push(`${op.method} ${op.path} → error: path parameter ${missing} not supplied`);
+            return {
+                content: [{ type: "text", text: `Request failed: path parameter "${missing}" is required` }],
+                isError: true,
+            };
+        }
+        return performRequest(api, env, bucket, log, {
+            method: op.method,
+            path,
+            query,
+            headers,
+            body: typeof values.body === "string" ? values.body : undefined,
+        });
+    });
+}
+function genericTool(api, env, bucket, log) {
+    const typed = api.resolvedOperations?.length
+        ? ` Prefer the typed ${api.name}_* tools; this one is the escape hatch for operations they do not cover.`
+        : "";
+    return tool(`call_${api.name}`, `Call the ${api.name} API. ${api.description} Base URL: ${api.base}. ` +
+        `Allowed methods: ${api.methods.join(", ")}. Provide only the path after the base URL. ` +
+        `Authentication is added automatically — never ask the user for credentials.` +
+        typed +
+        rateSentence(api), {
+        method: z.enum(api.methods).describe("HTTP method"),
+        path: z.string().describe("Path appended to the base URL, e.g. /customers/123/campaigns"),
+        query: z.record(z.string(), z.string()).optional().describe("Query parameters"),
+        body: z.string().optional().describe("Request body — JSON string for JSON APIs"),
+    }, (args) => performRequest(api, env, bucket, log, {
+        method: args.method,
+        path: args.path,
+        query: args.query ?? {},
+        headers: {},
+        body: args.body,
+    }));
+}
+export function buildApiTools(tenant, apis, workspace, 
+// The runner container passes this: secrets were resolved before the specs
+// crossed the boundary, and there is no vault in there to ask.
+resolved) {
+    if (apis.length === 0) {
+        return { server: null, toolNames: [], missingSecrets: [], promptLines: [], drainLog: () => [] };
+    }
+    const neededSecrets = [...new Set(apis.flatMap(secretsUsedByApi))];
+    const { env, missing } = resolved
+        ? {
+            env: Object.fromEntries(Object.entries(resolved.env).filter((entry) => typeof entry[1] === "string")),
+            missing: resolved.missing,
+        }
+        : resolveSecrets(tenant, neededSecrets, workspace);
+    const log = [];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- the SDK types its own list this way
+    const tools = [];
+    const toolNames = [];
+    const promptLines = [];
+    for (const api of apis) {
+        // One bucket per API per step: the limit is the vendor's, the scope is
+        // this process. Two steps on two workers each get their own.
+        const bucket = api.rate ? new TokenBucket(api.rate.count, api.rate.perSec) : null;
+        const ops = api.resolvedOperations ?? [];
+        // An explicit `operations:` list means "only these": no escape hatch.
+        const withGeneric = !(api.operations && ops.length);
+        const typedNames = [];
+        for (const op of ops) {
+            tools.push(typedTool(api, op, env, bucket, log));
+            typedNames.push(typedToolName(api.name, op.id));
+        }
+        if (withGeneric)
+            tools.push(genericTool(api, env, bucket, log));
+        const names = [...typedNames, ...(withGeneric ? [`call_${api.name}`] : [])];
+        toolNames.push(...names.map((n) => `mcp__foldrun_apis__${n}`));
+        const rateLine = api.rate ? ` Rate limit ${api.rate.count}/${Math.round(api.rate.count / api.rate.perSec)}s — over it, calls wait.` : "";
+        if (ops.length) {
+            const listed = ops.slice(0, PROMPT_LIST_CAP).map((op) => `  - \`${typedToolName(api.name, op.id)}\` — ${op.summary}`);
+            const more = ops.length > PROMPT_LIST_CAP ? [`  - …and ${ops.length - PROMPT_LIST_CAP} more`] : [];
+            promptLines.push(`- **${api.name}** — ${api.description} Base URL \`${api.base}\`. ` +
+                `${ops.length} typed tool${ops.length === 1 ? "" : "s"}` +
+                (withGeneric ? `, plus \`call_${api.name}\` for anything they do not cover` : "") +
+                `. Credentials are injected for you.${rateLine}`, ...listed, ...more);
+        }
+        else {
+            promptLines.push(`- **${api.name}** — call with the \`call_${api.name}\` tool. ${api.description} ` +
+                `Base URL \`${api.base}\`; allowed methods ${api.methods.join(", ")}. Credentials are injected for you.${rateLine}`);
+        }
+    }
+    const server = createSdkMcpServer({ name: "foldrun_apis", version: "1.0.0", tools });
+    return {
+        server,
+        toolNames,
+        missingSecrets: missing,
+        promptLines,
+        drainLog: () => log.splice(0, log.length),
+    };
+}

package/dist/src/approvals.d.ts

@@ -0,0 +1,39 @@
+import { type RunRecord } from "./store.ts";
+export interface ApprovalDecision {
+    decision: "approve" | "reject";
+    /** Guidance for the step being approved — rides the record into its prompt. */
+    note?: string;
+    /** Why a rejection, for the trace. Falls back to `note`, since a form has one box. */
+    reason?: string;
+    /** Decide only this step index; otherwise every step that is waiting. */
+    step?: number;
+    /** Who decided, as it reads after the verb: "by a human", "via emailed link". */
+    by: string;
+}
+/**
+ * Apply a decision to every step the run is waiting on, and line the run up
+ * again if a worker had parked it. Returns the record as written and which
+ * step indexes were decided.
+ *
+ * Throws with `status` 404 when the run does not exist and 409 when nothing
+ * is waiting — an emailed link is clicked twice, or after someone else
+ * already answered, and the second click must not be reported as success.
+ */
+export declare function decideApproval(tenant: string, workspace: string, runId: string, d: ApprovalDecision): Promise<{
+    run: RunRecord;
+    steps: number[];
+}>;
+/**
+ * Release a run parked on `wait: event` with what arrived. The payload is
+ * stored on the step — not as an approval note, which is a person's
+ * guidance and capped as such — and the release itself is an approval
+ * "by an external event", so the record reads the same way whichever door
+ * a park was opened through.
+ *
+ * Only steps waiting on an event are released: a run that is also asking a
+ * person a question keeps asking.
+ */
+export declare function deliverEvent(tenant: string, workspace: string, runId: string, payload: string): Promise<{
+    run: RunRecord;
+    steps: number[];
+}>;

package/dist/src/approvals.js

@@ -0,0 +1,103 @@
+// Deciding a run parked at an approval gate.
+//
+// The run record is the queue: the orchestrator polls it, so flipping a step
+// from awaiting-approval to pending (approve) or failed (reject) is the whole
+// decision. Nothing in memory has to survive a restart.
+//
+// Two doors lead here — the dashboard's approve button and the link in a
+// notification email — and they must do exactly the same thing to the record,
+// or a run approved from a phone would resume differently from one approved
+// at a desk. So the decision lives in core and the routes only say who made
+// it.
+import { readRun, writeRun } from "./store.js";
+import { platform } from "./platform.js";
+/** An error the HTTP layer can map straight to a status — see errorResponse. */
+class ApprovalError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/**
+ * Apply a decision to every step the run is waiting on, and line the run up
+ * again if a worker had parked it. Returns the record as written and which
+ * step indexes were decided.
+ *
+ * Throws with `status` 404 when the run does not exist and 409 when nothing
+ * is waiting — an emailed link is clicked twice, or after someone else
+ * already answered, and the second click must not be reported as success.
+ */
+export async function decideApproval(tenant, workspace, runId, d) {
+    const run = readRun(tenant, workspace, runId);
+    if (!run)
+        throw new ApprovalError("run not found", 404);
+    const waiting = run.steps
+        .map((s, i) => ({ s, i }))
+        .filter(({ s, i }) => s.status === "awaiting-approval" && (d.step === undefined || d.step === i));
+    if (waiting.length === 0)
+        throw new ApprovalError("nothing is awaiting approval", 409);
+    const note = typeof d.note === "string" ? d.note.trim() : "";
+    const reason = (typeof d.reason === "string" ? d.reason.trim() : "") || note;
+    const now = new Date().toISOString();
+    for (const { s } of waiting) {
+        s.status = d.decision === "approve" ? "pending" : "failed";
+        // Record the decision itself, not just its effect on status. `pending`
+        // is also what a step looks like before anyone was asked, so without
+        // this a run that was approved and then interrupted comes back asking
+        // the same person the same question.
+        if (d.decision === "approve") {
+            s.approvedAt = now;
+            // An approval can carry guidance — it rides the step record into the
+            // prompt (see runner.ts), so "yes, but…" is one gesture, not a yes
+            // followed by a chase.
+            if (note)
+                s.approvalNote = note.slice(0, 4000);
+        }
+        s.events.push({
+            t: now,
+            type: d.decision === "approve" ? "info" : "error",
+            text: d.decision === "approve"
+                ? `approved ${d.by} — continuing${note ? ` (with guidance: ${note.slice(0, 200)})` : ""}`
+                : `rejected ${d.by}${reason ? `: ${reason.slice(0, 200)}` : ""}`,
+        });
+    }
+    writeRun(tenant, workspace, run);
+    // A parked run has no process polling for this decision — the worker
+    // that was driving it gave its slot back at the gate. Line it up again.
+    // Runs without the marker still have their starter polling the file, and
+    // enqueueing those too would put two drivers on one record.
+    if (run.parkedAt && run.steps.every((s) => s.status !== "awaiting-approval")) {
+        await platform.enqueueResume(tenant, workspace, run.id);
+    }
+    return { run, steps: waiting.map(({ i }) => i) };
+}
+/**
+ * Release a run parked on `wait: event` with what arrived. The payload is
+ * stored on the step — not as an approval note, which is a person's
+ * guidance and capped as such — and the release itself is an approval
+ * "by an external event", so the record reads the same way whichever door
+ * a park was opened through.
+ *
+ * Only steps waiting on an event are released: a run that is also asking a
+ * person a question keeps asking.
+ */
+export async function deliverEvent(tenant, workspace, runId, payload) {
+    const run = readRun(tenant, workspace, runId);
+    if (!run)
+        throw new ApprovalError("run not found", 404);
+    const waiting = run.steps
+        .map((s, i) => ({ s, i }))
+        .filter(({ s }) => s.status === "awaiting-approval" && s.waitFor === "event");
+    if (waiting.length === 0)
+        throw new ApprovalError("this run is not waiting for an event", 409);
+    for (const { s } of waiting)
+        s.eventPayload = payload.slice(0, 20_000);
+    writeRun(tenant, workspace, run);
+    let decided = [];
+    for (const { i } of waiting) {
+        const out = await decideApproval(tenant, workspace, runId, { decision: "approve", step: i, by: "by an external event" });
+        decided = decided.concat(out.steps);
+    }
+    return { run: readRun(tenant, workspace, runId) ?? run, steps: decided };
+}

package/dist/src/arrange.d.ts

@@ -0,0 +1,8 @@
+export type Groups = number[][];
+/** Move `step` into the group that currently contains `anchor` — run in parallel. */
+export declare function joinGroup(groups: Groups, step: number, anchor: number): Groups;
+/**
+ * Move `step` out on its own at rail position `rail` — run sequentially.
+ * Rail 0 is above every group; rail N is below group N-1.
+ */
+export declare function splitToRail(groups: Groups, step: number, rail: number): Groups;

package/dist/src/arrange.js

@@ -0,0 +1,40 @@
+// Rearranging a flow's steps into groups.
+//
+// Pure functions, extracted from the drag-and-drop board so they can be
+// tested: when a drag produces an order you didn't expect, the first question
+// is whether the rule is wrong or the target was — and that should be
+// answerable without a browser.
+//
+// A `Groups` value is the arrangement: an array of groups, each holding
+// indices into the flow's parsed steps. Steps sharing a group run in parallel.
+function removeStep(groups, step) {
+    const next = groups.map((g) => g.filter((i) => i !== step));
+    const emptiedAt = next.findIndex((g) => g.length === 0);
+    return { next: next.filter((g) => g.length > 0), emptiedAt };
+}
+/** Move `step` into the group that currently contains `anchor` — run in parallel. */
+export function joinGroup(groups, step, anchor) {
+    if (step === anchor)
+        return groups;
+    const { next } = removeStep(groups, step);
+    const target = next.findIndex((g) => g.includes(anchor));
+    if (target === -1)
+        return groups;
+    next[target] = [...next[target], step];
+    return next;
+}
+/**
+ * Move `step` out on its own at rail position `rail` — run sequentially.
+ * Rail 0 is above every group; rail N is below group N-1.
+ */
+export function splitToRail(groups, step, rail) {
+    const { next, emptiedAt } = removeStep(groups, step);
+    // Removing the step may have collapsed a group above the target, which
+    // shifts every rail below it up by one.
+    let at = rail;
+    if (emptiedAt !== -1 && emptiedAt < rail)
+        at -= 1;
+    at = Math.max(0, Math.min(next.length, at));
+    next.splice(at, 0, [step]);
+    return next;
+}