@foldrun/core 0.2.0

package/dist/src/step-exec.js

@@ -0,0 +1,391 @@
+// The model loop, extracted to run in two places: the server process (the
+// classic path) and the runner container's driver (the isolated path). One
+// implementation, because the moment these fork, the sandboxed path becomes
+// the less-tested one — backwards from its whole purpose.
+//
+// Everything here takes values, not stores: the caller resolves secrets,
+// assembles the system prompt and builds MCP servers, then hands this the
+// results. That is what lets the same function run somewhere the vault, the
+// library and the account do not exist.
+import fs from "node:fs";
+import path from "node:path";
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { spawn } from "node:child_process";
+import { checkPaths, checkBash, isFilesystemTool } from "./confine.js";
+/** Conservative per-token rates for a model the catalogue cannot price —
+ *  Opus-class — so a ceiling still means something on an unknown gateway. */
+export const FALLBACK_PRICE = { input: 15e-6, output: 75e-6 };
+/**
+ * What one assistant turn cost. Cache traffic is counted as input at the
+ * input rate, which over-approximates on gateways with cheaper cache reads
+ * — on the money side, the honest direction to be wrong in. Pure.
+ */
+export function priceTurn(u, price) {
+    const inTok = (u.input_tokens ?? 0) + (u.cache_creation_input_tokens ?? 0) + (u.cache_read_input_tokens ?? 0);
+    const outTok = u.output_tokens ?? 0;
+    const p = price ?? FALLBACK_PRICE;
+    return inTok * p.input + outTok * p.output;
+}
+/**
+ * Each step launched together gets an equal share of what is left of the
+ * run's budget: the shares sum to the remainder, so a group cannot end
+ * over the cap however many steps it fans out to. No budget, no ceiling.
+ */
+export function stepCeiling(budgetUsd, spentUsd, launching) {
+    if (!budgetUsd || budgetUsd <= 0)
+        return null;
+    return Math.max(0, budgetUsd - spentUsd) / Math.max(1, launching);
+}
+export async function executeStep(opts) {
+    const { agentDir, workspaceRoot, libraryRoot, emit } = opts;
+    let status = "running";
+    let costUsd = null;
+    let usage = null;
+    const texts = [];
+    fs.mkdirSync(path.join(agentDir, "outputs"), { recursive: true });
+    fs.mkdirSync(path.join(agentDir, "memory"), { recursive: true });
+    const q = query({
+        prompt: opts.prompt,
+        options: {
+            cwd: agentDir,
+            model: opts.model,
+            // Omitted, not passed as undefined-with-a-default: an unset effort
+            // should mean "whatever this model does normally", which is not a
+            // level we can name — it moves as models ship.
+            ...(opts.effort ? { effort: opts.effort } : {}),
+            systemPrompt: opts.systemPrompt,
+            // Restrict the toolset itself, not just approval: an agent that
+            // declares no tools gets none, instead of seeing the full Claude
+            // Code toolset and burning turns on denied calls.
+            tools: opts.allowed,
+            // Deliberately NOT allowedTools: listing them there auto-approves and
+            // skips canUseTool entirely, which is where confinement happens. The
+            // toolset is still restricted by `tools` above.
+            settingSources: [],
+            // Sandbox the shell — but only when the shell would otherwise run in a
+            // process worth protecting. In an isolated run the container IS the
+            // boundary (non-root, cap-dropped, host-less, icc-disabled network),
+            // so the SDK's own bash sandbox is redundant there and actively harms:
+            // it blocks outbound network, which a declared SSH or curl step
+            // legitimately needs. So the container relaxes it (opts.sandboxBash =
+            // false) and the container's walls do the containing; the in-process
+            // path (the CLI on someone's laptop, and the host executor) keeps it,
+            // because there a shell escape reaches the real machine.
+            sandbox: {
+                enabled: opts.sandboxBash !== false,
+                // Must stay false. Auto-allowing bash because it's sandboxed skips
+                // canUseTool entirely — and the OS sandbox blocks writes outside the
+                // tree but still permits reads, so `cat ../../secrets.json` walked
+                // straight out. Verified by probe: true leaks, false denies.
+                autoAllowBashIfSandboxed: false,
+                failIfUnavailable: false,
+            },
+            env: opts.env,
+            mcpServers: opts.mcpServers,
+            canUseTool: async (toolName, input) => {
+                // The toolset was already narrowed to what the agent declared, so
+                // anything outside it is a denial with a reason the model can act on.
+                const fromGrantedServer = opts.mcpNames.some((n) => toolName.startsWith(`mcp__${n}__`));
+                if (!opts.allowed.includes(toolName) && !fromGrantedServer) {
+                    return {
+                        behavior: "deny",
+                        message: `Tool ${toolName} is not enabled for this agent.`,
+                    };
+                }
+                const verdict = toolName === "Bash"
+                    ? checkBash(String(input.command ?? ""))
+                    : isFilesystemTool(toolName)
+                        ? checkPaths(toolName, input, { agentDir, workspaceRoot, libraryRoot })
+                        : { ok: true };
+                if (!verdict.ok) {
+                    emit("error", verdict.reason);
+                    return { behavior: "deny", message: verdict.reason };
+                }
+                return { behavior: "allow", updatedInput: verdict.updatedInput ?? input };
+            },
+        },
+    });
+    const deadline = opts.timeoutSec ? Date.now() + opts.timeoutSec * 1000 : null;
+    // The hard cap. Spend is counted as each assistant turn arrives — its
+    // usage is in the message — so the step can stop at the ceiling rather
+    // than learn afterwards that it crossed it. Cache traffic is counted as
+    // input at the input rate, which over-approximates: on the money side
+    // that is the honest direction to be wrong in.
+    const ceiling = typeof opts.budgetUsd === "number" && opts.budgetUsd > 0 ? opts.budgetUsd : null;
+    let spentUsd = 0;
+    // Open tool calls, by the provider's id, so the result can be paired with
+    // its call and the trace can say how long each tool ran.
+    const openCalls = new Map();
+    for await (const message of q) {
+        if (deadline && Date.now() > deadline) {
+            emit("error", `step exceeded its ${opts.timeoutSec}s timeout`);
+            status = "failed";
+            break;
+        }
+        if (message.type === "assistant") {
+            const u = message.message.usage;
+            if (ceiling && u) {
+                spentUsd += priceTurn(u, opts.price ?? null);
+                if (spentUsd >= ceiling) {
+                    emit("error", `over budget — this step reached $${spentUsd.toFixed(4)} of its $${ceiling.toFixed(4)} ceiling mid-turn and was stopped (budget: in the flow file)`);
+                    status = "failed";
+                    break;
+                }
+            }
+            for (const block of message.message.content) {
+                if (block.type === "text" && block.text.trim()) {
+                    texts.push(block.text);
+                    emit("text", block.text);
+                }
+                else if (block.type === "tool_use") {
+                    openCalls.set(block.id, { name: block.name, at: Date.now() });
+                    emit("tool", block.name, { call: block.id });
+                }
+            }
+        }
+        else if (message.type === "user") {
+            // Tool results ride back as user turns. The completion event closes
+            // the span the call opened; the runner's journal keeps both.
+            const content = message.message.content;
+            if (Array.isArray(content)) {
+                for (const block of content) {
+                    if (block.type !== "tool_result")
+                        continue;
+                    const open = openCalls.get(block.tool_use_id);
+                    if (!open)
+                        continue;
+                    openCalls.delete(block.tool_use_id);
+                    emit("tool", open.name, {
+                        call: block.tool_use_id,
+                        ms: Date.now() - open.at,
+                        ...(block.is_error ? { err: true } : {}),
+                    });
+                }
+            }
+        }
+        else if (message.type === "result") {
+            status = message.subtype === "success" ? "completed" : "failed";
+            costUsd = "total_cost_usd" in message ? (message.total_cost_usd ?? null) : null;
+            if ("usage" in message && message.usage) {
+                const u = message.usage;
+                usage = {
+                    // Cache traffic is input the provider still bills (at its own
+                    // rates); folding it into the input count over-approximates for
+                    // gateways with cheaper cache reads, which errs on the honest side.
+                    inputTokens: (u.input_tokens ?? 0) +
+                        (u.cache_creation_input_tokens ?? 0) +
+                        (u.cache_read_input_tokens ?? 0),
+                    outputTokens: u.output_tokens ?? 0,
+                };
+            }
+        }
+    }
+    // The SDK ends a healthy run with a `result` message. A stream that just
+    // stops — subprocess OOM-killed, crashed, or torn down — used to fall
+    // through as "completed", which reported a run that produced nothing as a
+    // success. Silence is not success.
+    if (status === "running") {
+        status = "failed";
+        emit("error", "the model stream ended without a result — the model process likely died (out of memory?)");
+    }
+    const result = texts.join("\n").trim() || null;
+    // A step's reply is not one message: the model narrates ("Now let me read
+    // the outputs…"), calls tools, and answers last. Joining those and reading
+    // the first line — which is what the run summary did — reports the plan
+    // and never the outcome. The final block is the answer; keep it so the
+    // summary has something true to read.
+    const conclusion = texts.at(-1)?.trim() || null;
+    // output: json — the declared shape is a contract, checked here where both
+    // executors run. A reply with no JSON in it is not "done with a caveat";
+    // it is the failure the next step would otherwise inherit as garbage.
+    let data = undefined;
+    if (status === "completed" && opts.output === "json") {
+        const extracted = extractJson(result);
+        if (extracted.ok) {
+            data = extracted.value;
+            emit("info", `output: json — ${describeJson(data)}`);
+        }
+        else {
+            emit("error", `output: json — ${extracted.reason}`);
+            status = "failed";
+        }
+    }
+    // "Done" should mean a check passed, not that the model stopped talking.
+    if (status === "completed" && opts.verify) {
+        const verdict = await checkVerify(agentDir, opts.verify, {
+            env: opts.verifyEnv ?? {},
+            result,
+            conclusion,
+            data,
+            modelEnv: opts.env,
+        });
+        emit(verdict.ok ? "info" : "error", `verify \`${opts.verify}\` → ${verdict.headline}`);
+        if (verdict.detail.trim())
+            emit(verdict.ok ? "info" : "error", verdict.detail.slice(0, 1000));
+        if (!verdict.ok)
+            status = "failed";
+    }
+    return { status, result, conclusion, ...(opts.output ? { data } : {}), costUsd, usage };
+}
+// ------------------------------------------------------------ output: json
+/**
+ * The one JSON value a reply carries. A ```json fence wins — it is what the
+ * step was asked to write — and the LAST one at that, because a model that
+ * shows its working often quotes an earlier draft first. Without a fence,
+ * the reply's trailing `{…}` or `[…]` is tried, so a model that answered
+ * with bare JSON is not failed for good behaviour.
+ */
+export function extractJson(result) {
+    const text = (result ?? "").trim();
+    if (!text)
+        return { ok: false, reason: "the reply was empty" };
+    const fences = [...text.matchAll(/```(?:json|JSON)?\s*\n([\s\S]*?)\n\s*```/g)].map((m) => m[1].trim());
+    const candidates = fences.length ? fences.reverse() : [];
+    if (!candidates.length) {
+        // The largest trailing bracketed span: walk back from the end to the
+        // last closing bracket, then forward to the matching opener.
+        const close = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
+        if (close !== -1) {
+            const opener = text[close] === "}" ? "{" : "[";
+            for (let i = text.indexOf(opener); i !== -1 && i < close; i = text.indexOf(opener, i + 1)) {
+                candidates.push(text.slice(i, close + 1));
+            }
+        }
+    }
+    let lastError = "no JSON value found in the reply";
+    for (const c of candidates) {
+        try {
+            return { ok: true, value: JSON.parse(c) };
+        }
+        catch (err) {
+            lastError = `could not parse: ${err instanceof Error ? err.message : String(err)}`;
+        }
+    }
+    return { ok: false, reason: lastError };
+}
+function describeJson(value) {
+    if (Array.isArray(value))
+        return `an array of ${value.length}`;
+    if (value && typeof value === "object")
+        return `an object with keys ${Object.keys(value).slice(0, 8).join(", ")}`;
+    return `a ${typeof value}`;
+}
+// ----------------------------------------------------------------- verify:
+/** The eval vocabulary a `verify:` may borrow. Anything else is a shell command. */
+const VERIFY_ASSERTION = /^(contains|not-contains|matches|file|judge):\s*([\s\S]+)$/;
+/**
+ * Decide a `verify:`. Two dialects, one key: an eval assertion, when the
+ * value starts with one of the eval file's assertion words, or a shell
+ * command. The assertion form exists so that a flow and an eval share a
+ * vocabulary — "the output must mention the price" is the same sentence in
+ * both places — and so that the commonest checks need no shell at all.
+ */
+export async function checkVerify(agentDir, verify, ctx) {
+    const m = verify.trim().match(VERIFY_ASSERTION);
+    if (!m) {
+        const { code, out } = await runVerify(agentDir, verify, ctx.env, ctx.data);
+        return { ok: code === 0, headline: `exit ${code ?? "error"}`, detail: out };
+    }
+    const [, kind, rawValue] = m;
+    const value = rawValue.trim().replace(/^["']|["']$/g, "");
+    const output = (kind === "judge" ? ctx.result : (ctx.conclusion ?? ctx.result)) ?? "";
+    const hay = output.toLowerCase();
+    switch (kind) {
+        case "contains": {
+            const ok = hay.includes(value.toLowerCase());
+            return { ok, headline: ok ? "found" : `"${value}" not in the reply`, detail: "" };
+        }
+        case "not-contains": {
+            const ok = !hay.includes(value.toLowerCase());
+            return { ok, headline: ok ? "absent" : `"${value}" appeared in the reply`, detail: "" };
+        }
+        case "matches": {
+            try {
+                const ok = new RegExp(value, "i").test(output);
+                return { ok, headline: ok ? "matched" : "no match", detail: "" };
+            }
+            catch {
+                return { ok: false, headline: "invalid regular expression", detail: "" };
+            }
+        }
+        case "file": {
+            const target = path.resolve(agentDir, value);
+            if (!target.startsWith(path.resolve(agentDir) + path.sep)) {
+                return { ok: false, headline: "path escapes the agent directory", detail: "" };
+            }
+            const ok = fs.existsSync(target) && fs.statSync(target).size > 0;
+            return { ok, headline: ok ? "present and non-empty" : `${value} is missing or empty`, detail: "" };
+        }
+        case "judge": {
+            const verdict = await judgeReply(value, output, ctx.modelEnv ?? {});
+            const ok = /^\s*PASS\b/i.test(verdict);
+            return { ok, headline: ok ? "PASS" : "FAIL", detail: verdict.slice(0, 300) };
+        }
+    }
+    return { ok: false, headline: `unknown check "${kind}"`, detail: "" };
+}
+/**
+ * A toolless, fast-tier grading call: does the reply satisfy the sentence?
+ * Same shape as the eval judge, and answered with one word first so the
+ * verdict is a prefix test rather than a reading.
+ */
+async function judgeReply(rubric, output, env) {
+    const texts = [];
+    try {
+        const q = query({
+            prompt: `You are grading a reply against one requirement. Answer with PASS or FAIL as the ` +
+                `first word, then one sentence of reason.\n\nRequirement: ${rubric}\n\n` +
+                `<reply>\n${output.slice(0, 40_000)}\n</reply>`,
+            options: {
+                model: "haiku",
+                systemPrompt: "You grade text against a stated requirement. Be strict and literal.",
+                tools: [],
+                settingSources: [],
+                env,
+                maxTurns: 1,
+            },
+        });
+        for await (const message of q) {
+            if (message.type === "assistant") {
+                for (const block of message.message.content) {
+                    if (block.type === "text")
+                        texts.push(block.text);
+                }
+            }
+        }
+    }
+    catch (err) {
+        return `FAIL — the judge could not run: ${err instanceof Error ? err.message : String(err)}`;
+    }
+    return texts.join("\n").trim();
+}
+// Verification runs in the agent's directory with its secrets available, so
+// a check can be as simple as `npm run build` or `test -s outputs/report.md`.
+function runVerify(agentDir, command, env, data) {
+    return new Promise((resolve) => {
+        // No clock of the platform's: a verify like `npm run build` takes what
+        // it takes, and the step's own `timeout:` is the bound if the flow set one.
+        const child = spawn("bash", ["-lc", command], {
+            cwd: agentDir,
+            env: { ...process.env, ...env },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        // An `output: json` step's data arrives on stdin, so a check can be
+        // `jq -e '.total > 0'` — arithmetic in a real tool, reading the value
+        // the step actually returned rather than re-parsing its prose.
+        child.stdin.on("error", () => { });
+        if (data !== undefined)
+            child.stdin.end(JSON.stringify(data));
+        else
+            child.stdin.end();
+        let out = "";
+        const append = (c) => {
+            if (out.length < 4000)
+                out += c.toString();
+        };
+        child.stdout.on("data", append);
+        child.stderr.on("data", append);
+        child.on("error", (e) => resolve({ code: null, out: e.message }));
+        child.on("close", (code) => resolve({ code, out }));
+    });
+}

package/dist/src/storage.d.ts

@@ -0,0 +1,123 @@
+import { STORAGE_DIR } from "./store.ts";
+/** The directory a run sees, and the one this module mirrors into it.
+ *  Declared in store.ts, where saveWorkspace also needs it; re-exported so
+ *  callers of this module do not need to know that. */
+export { STORAGE_DIR };
+export interface FileRecord {
+    /** Path under storage/, forward-slashed. The primary key: it is also exactly
+     *  what the agent typed, which is why the record is keyed by it and not by
+     *  a generated id nobody could reach from inside a run. */
+    path: string;
+    /** Content hash. Blobs are stored under it, so re-uploading the same bytes
+     *  under a second name costs nothing and a rename moves no data. */
+    sha: string;
+    size: number;
+    mime: string;
+    updatedAt: string;
+    /** Provenance: `user:<email>` or `run:<runId>:<agent>`. The reason the
+     *  dashboard can answer "which run produced this?" without a join table. */
+    by: string;
+}
+interface Index {
+    version: 1;
+    files: FileRecord[];
+}
+/**
+ * Hosted only. On a laptop `storage/` is just a folder in the user's own
+ * project — they can see it, open it, and put a PDF in it with Finder — and
+ * an index plus a second hardlinked copy under data/ would be bookkeeping
+ * for a problem nobody has. The store exists to give many tenants a shared
+ * bucket and a provenance trail; one person with one directory has neither
+ * question to answer.
+ *
+ * Everything public here checks this first and does nothing, so the CLI runs
+ * the same driveRun the platform does and simply skips the mirror.
+ */
+export declare function fileStoreEnabled(): boolean;
+/** The object key. Tenant-first so a bucket policy can be written per tenant,
+ *  and content-addressed so objects are immutable — no cache invalidation,
+ *  no partially-overwritten object, and a repeated upload is a no-op. */
+export declare function blobKey(tenant: string, workspace: string, sha: string): string;
+/**
+ * Reject anything that isn't a plain relative path under storage/.
+ *
+ * This runs on names that came from an upload form *and* on paths harvested
+ * out of a container, so it is the boundary for both directions. `..` is the
+ * obvious one; a leading slash and a Windows drive letter are the two that
+ * path.normalize alone will happily keep.
+ */
+export declare function assertFilePath(rel: string): string;
+export declare function mimeFor(rel: string): string;
+export declare function readIndex(tenant: string, workspace: string): Index;
+export declare function listStorage(tenant: string, workspace: string): FileRecord[];
+export declare function getFile(tenant: string, workspace: string, rel: string): FileRecord | null;
+export declare function usedBytes(tenant: string, workspace: string): number;
+export interface Driver {
+    kind: "fs" | "s3";
+    put(key: string, body: Buffer, mime: string): Promise<void>;
+    get(key: string): Promise<Buffer>;
+    has(key: string): Promise<boolean>;
+    remove(key: string): Promise<void>;
+    /** A URL a browser can GET directly, or null when the driver has no such
+     *  thing (fs) and the route must stream the bytes itself. */
+    presignGet(key: string, filename: string, mime: string, ttlSec?: number): Promise<string | null>;
+    /** A URL a browser can PUT directly to, so upload bytes never transit the
+     *  dashboard process. Null on fs, where the route takes the body. */
+    presignPut(key: string, mime: string, ttlSec?: number): Promise<string | null>;
+}
+/** Where the fs driver keeps a blob. Exported because the run mirror
+ *  hardlinks straight to it rather than reading and rewriting the bytes. */
+export declare function blobPath(tenant: string, workspace: string, sha: string): string;
+interface S3Config {
+    endpoint: string;
+    bucket: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    pathStyle: boolean;
+}
+export declare function s3Config(): S3Config | null;
+/**
+ * The driver in force. `fs` unless S3 is both selected and configured —
+ * a half-set environment falls back rather than failing at the first upload,
+ * because a dashboard that boots and stores locally beats one that 500s.
+ */
+export declare function driverFor(tenant: string, workspace: string): Driver;
+export declare function putFile(tenant: string, workspace: string, rel: string, body: Buffer, by: string): Promise<FileRecord>;
+/** Register bytes a browser PUT straight to the bucket. Same bookkeeping as
+ *  putFile, minus the bytes — the platform never saw them. */
+export declare function registerUpload(tenant: string, workspace: string, rel: string, sha: string, size: number, by: string): Promise<FileRecord>;
+export declare function readFileBytes(tenant: string, workspace: string, rel: string): Promise<Buffer | null>;
+export declare function deleteFile(tenant: string, workspace: string, rel: string): Promise<boolean>;
+/** A link the browser can follow, or null when the route must stream it. */
+export declare function downloadUrl(tenant: string, workspace: string, record: FileRecord): Promise<string | null>;
+/** A link the browser can PUT to, plus the key it will land at. Null on fs. */
+export declare function uploadUrl(tenant: string, workspace: string, rel: string, sha: string): Promise<string | null>;
+/**
+ * Put the workspace's files on disk under `<workspace>/storage/`, where a run
+ * copies them into its container like any other directory.
+ *
+ * On the fs driver this is a hardlink: the blob and the mirror are the same
+ * inode, so a 2GB corpus costs 2GB once, not twice. On s3 it is a download,
+ * and the mirror is a cache — a second run over the same files fetches
+ * nothing.
+ *
+ * Not pruned. A workspace that churns hundreds of large files will hold a
+ * copy of each on the PVC until someone deletes the record, and the quota is
+ * what stops that becoming a full disk. Pruning wants an LRU that knows no
+ * run is currently reading the file it is about to remove, and that bookkeeping
+ * is worth writing when a workspace actually outgrows its quota, not before.
+ */
+export declare function materializeFiles(tenant: string, workspace: string): Promise<string[]>;
+/**
+ * Take what the run left in `storage/` back into the store, stamped with the
+ * run that wrote it.
+ *
+ * Compares against the index rather than a pre-run snapshot: the mirror is
+ * derived from the index, so anything on disk that the index does not already
+ * describe with the same size and hash is, by construction, new work.
+ */
+export declare function harvestFiles(tenant: string, workspace: string, by: string): Promise<{
+    saved: string[];
+    errors: string[];
+}>;