@foldrun/core 0.2.0

package/dist/src/providers.js

@@ -0,0 +1,114 @@
+// The providers this runtime knows by name.
+//
+//   provider:
+//     name: groq
+//     token: ${GROQ_API_KEY}
+//     models: { fast: llama-3.3-70b-versatile }
+//
+// A name resolves to three facts: which wire format the endpoint speaks,
+// where it is, and which header the key travels in. Everything here is
+// bring-your-own-key — the platform never holds a provider credential on a
+// customer's behalf — and a name is a convenience over `base_url:` +
+// `format:` + `auth:`, never a requirement: an endpoint this table has
+// never heard of works the same way by spelling those three out.
+//
+// Three formats. `responses` is OpenAI's newer API — the same translator
+// with a second pair of mappings, for an OpenAI key that wants what only
+// that shape carries (a PDF as input, the reasoning knobs). Nobody else
+// implements it, so no preset defaults to it; a block asks for it by name.
+// Two formats, deliberately. `anthropic` is what the runtime speaks, so
+// those endpoints are reached directly. `openai` endpoints are reached
+// through the runtime's own translator (translator.ts), which runs on
+// localhost inside the run sandbox and rewrites Anthropic Messages to Chat
+// Completions and back. Every provider without an Anthropic-shaped endpoint
+// speaks Chat Completions — OpenAI, Gemini, xAI, Groq, Mistral, Hugging
+// Face, Cloudflare's own models — so one translation reaches all of them.
+//
+// URLs and header shapes were checked against each provider's own
+// documentation on 2026-09-02 and again on 2026-09-06 (see docs/providers.md). `verified` says
+// whether a tool loop was actually driven through the endpoint from here,
+// which is the only claim that matters for an agent runtime; a name without
+// it is documented, not proven.
+export const PROVIDERS = [
+    // ------------------------------------------------ Anthropic-shaped, direct
+    { name: "anthropic", title: "Anthropic", format: "anthropic", baseUrl: "https://api.anthropic.com", auth: "x-api-key", verified: true,
+        note: "Models newer than Opus 4.6 reject top_k with a 400; the runtime never sends it unless a params: block does." },
+    { name: "openrouter", title: "OpenRouter", format: "anthropic", baseUrl: "https://openrouter.ai/api", auth: "bearer", verified: true,
+        note: "Hundreds of models behind one key. Its own docs disagree on how well non-Anthropic models hold a tool loop on this endpoint — probe the model you mean to use." },
+    { name: "deepseek", title: "DeepSeek", format: "anthropic", baseUrl: "https://api.deepseek.com/anthropic", auth: "x-api-key",
+        note: "Ignores top_k, cache_control and thinking budgets; Claude model names are remapped to DeepSeek's." },
+    { name: "kimi", title: "Moonshot Kimi", format: "anthropic", baseUrl: "https://api.moonshot.ai/anthropic", auth: "bearer",
+        note: "Own model ids only. Known bug (2026-09): K3 reuses one tool_use id across separate calls, which breaks a tool loop." },
+    { name: "moonshot", title: "Moonshot Kimi", format: "anthropic", baseUrl: "https://api.moonshot.ai/anthropic", auth: "bearer",
+        note: "Same endpoint as kimi." },
+    { name: "zai", title: "z.ai (GLM)", format: "anthropic", baseUrl: "https://api.z.ai/api/anthropic", auth: "bearer" },
+    { name: "minimax", title: "MiniMax", format: "anthropic", baseUrl: "https://api.minimax.io/anthropic", auth: "bearer" },
+    { name: "qwen", title: "Alibaba Qwen (Model Studio)", format: "anthropic", auth: "x-api-key",
+        note: "base_url depends on the plan: pay-as-you-go https://<workspace>.<region>.maas.aliyuncs.com/apps/anthropic; Coding Plan https://coding-intl.dashscope.aliyuncs.com/apps/anthropic. Own model ids (qwen3.7-max …), no remap; no reasoning_effort, use thinking." },
+    { name: "fireworks", title: "Fireworks AI", format: "anthropic", baseUrl: "https://api.fireworks.ai/inference", auth: "bearer",
+        note: "No server-side tools; no adaptive thinking." },
+    { name: "deepinfra", title: "DeepInfra", format: "anthropic", baseUrl: "https://api.deepinfra.com/anthropic", auth: "bearer" },
+    { name: "sambanova", title: "SambaNova", format: "anthropic", baseUrl: "https://api.sambanova.ai", auth: "x-api-key",
+        note: "No server-side tools, base64 images only." },
+    { name: "vercel", title: "Vercel AI Gateway", format: "anthropic", baseUrl: "https://ai-gateway.vercel.sh", auth: "bearer",
+        note: "Model ids are namespaced, e.g. openai/gpt-5." },
+    { name: "litellm", title: "LiteLLM (yours)", format: "anthropic", auth: "x-api-key",
+        note: "base_url is your proxy, e.g. http://litellm.internal:4000. It presents an Anthropic endpoint and speaks anything behind it." },
+    { name: "cloudflare-gateway", title: "Cloudflare AI Gateway", format: "anthropic", auth: "x-api-key",
+        note: "base_url is https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/anthropic — a pass-through to Anthropic with logging; for Cloudflare's own models use name: cloudflare." },
+    { name: "ollama", title: "Ollama (local)", format: "anthropic", baseUrl: "http://localhost:11434", auth: "x-api-key",
+        note: "v0.14+. Ignores tool_choice and cache_control; accepts but does not enforce thinking budgets; base64 images only. Any key value is accepted." },
+    { name: "lmstudio", title: "LM Studio (local)", format: "anthropic", baseUrl: "http://localhost:1234", auth: "x-api-key" },
+    { name: "vllm", title: "vLLM (yours)", format: "anthropic", auth: "bearer",
+        note: "base_url is your server (default :8000). Start it with --enable-auto-tool-choice and a --tool-call-parser or no tool loop closes." },
+    // ------------------------------------------- Chat-Completions, translated
+    { name: "openai", title: "OpenAI", format: "openai", baseUrl: "https://api.openai.com/v1", auth: "bearer", verified: true,
+        maxTokensParam: "max_completion_tokens", reasoningEffort: true,
+        note: "Reached over Chat Completions, which OpenAI keeps supporting; the Responses API is not spoken here, so a reasoning model's reasoning does not carry across tool calls." },
+    { name: "gemini", title: "Google Gemini", format: "openai", baseUrl: "https://generativelanguage.googleapis.com/v1beta/openai", auth: "bearer",
+        note: "Google's OpenAI-compatible route. Unknown parameters are ignored silently; reasoning cannot be switched off on the newest models." },
+    { name: "xai", title: "xAI Grok", format: "openai", baseUrl: "https://api.x.ai/v1", auth: "bearer",
+        maxTokensParam: "max_completion_tokens", reasoningEffort: true },
+    { name: "groq", title: "Groq", format: "openai", baseUrl: "https://api.groq.com/openai/v1", auth: "bearer",
+        maxTokensParam: "max_completion_tokens", reasoningEffort: true },
+    { name: "mistral", title: "Mistral", format: "openai", baseUrl: "https://api.mistral.ai/v1", auth: "bearer" },
+    { name: "together", title: "Together AI", format: "openai", baseUrl: "https://api.together.ai/v1", auth: "bearer" },
+    { name: "cerebras", title: "Cerebras", format: "openai", baseUrl: "https://api.cerebras.ai/v1", auth: "bearer",
+        maxTokensParam: "max_completion_tokens", reasoningEffort: true },
+    { name: "huggingface", title: "Hugging Face", format: "openai", baseUrl: "https://router.huggingface.co/v1", auth: "bearer",
+        note: "The Inference Providers router; model ids are Hub ids, e.g. meta-llama/Llama-3.3-70B-Instruct." },
+    { name: "cloudflare", title: "Cloudflare Workers AI", format: "openai", auth: "bearer",
+        note: "base_url is https://api.cloudflare.com/client/v4/accounts/<account>/ai/v1" },
+    { name: "nebius", title: "Nebius Token Factory", format: "openai", baseUrl: "https://api.tokenfactory.nebius.com/v1", auth: "bearer" },
+    { name: "novita", title: "Novita", format: "openai", baseUrl: "https://api.novita.ai/openai", auth: "bearer",
+        note: "Also has an Anthropic-shaped route at https://api.novita.ai/anthropic — spell it out with format: anthropic to skip the translator (header shape unverified)." },
+    { name: "hyperbolic", title: "Hyperbolic", format: "openai", baseUrl: "https://api.hyperbolic.xyz/v1", auth: "bearer" },
+];
+/**
+ * Request fields `params:` may not set.
+ *
+ * These are not the provider's knobs, they are the conversation: the
+ * messages, the tools the agent declared, whether the reply streams, and
+ * which model the tier resolved to. A file that could overwrite them could
+ * silently break the agent loop — or make `model: fast` mean something else
+ * — from a line that looks like a tuning option. Everything else passes
+ * through untouched, because a vendor's own parameters are the vendor's
+ * business and this format will never model them.
+ */
+export const PROTECTED_PARAMS = ["messages", "tools", "stream", "stream_options", "model"];
+/** A preset by any spelling a person reaches for: case-insensitive, and
+ *  "z.ai" / "z-ai" / "hugging-face" all land. */
+export function providerPreset(name) {
+    if (typeof name !== "string")
+        return null;
+    const key = name.trim().toLowerCase().replace(/[^a-z0-9]/g, "");
+    if (!key)
+        return null;
+    return PROVIDERS.find((p) => p.name.replace(/[^a-z0-9]/g, "") === key) ?? null;
+}
+/** Does this URL look like a Chat-Completions endpoint a person pasted
+ *  without saying `format: openai`? The heuristic the checker uses to say
+ *  so before a run fails with a 404 from the wrong path. */
+export function looksOpenAiShaped(baseUrl) {
+    return /\/v1\/?$|\/chat\/completions|api\.openai\.com|\/openai\b/i.test(baseUrl);
+}

package/dist/src/refs.d.ts

@@ -0,0 +1,20 @@
+/** One entry of a file-naming list. `mode` is the value of a map-form
+ *  entry — `{bash: ask}` — and null for a plain name. */
+export interface Ref {
+    name: string;
+    linked: boolean;
+    mode: string | null;
+}
+/** The name inside `[[…]]`, with `flow:` and surrounding space kept. */
+export declare function stripLink(raw: string): {
+    name: string;
+    linked: boolean;
+};
+/**
+ * Every entry of a list field, in order, empty names dropped. Accepts the
+ * shapes a file can carry: an inline or block list of names, links or maps;
+ * a single name; or Claude Code's comma string (`tools: Read, Grep`).
+ */
+export declare function refList(raw: unknown): Ref[];
+/** Just the names — for a reader that does not care how they were spelt. */
+export declare function refNames(raw: unknown): string[];

package/dist/src/refs.js

@@ -0,0 +1,78 @@
+// A frontmatter list that names files — `tools:`, `skills:`, `agents:`,
+// `after:` — read the same way whether an entry is bare or a `[[link]]`.
+//
+// `[[name]]` is the format's one reference syntax, and until now the
+// frontmatter was the last place a name had to be bare. The rule is one
+// sentence: if it names a file, you can link it. Agents, flows, skills,
+// tools, knowledge and memory are files; secrets, model and size are values.
+//
+// YAML is the complication. To YAML, `- [[site_repo]]` is a nested list
+// (`[["site_repo"]]`), and `tools: [read, [[site_repo]]]` is a list holding
+// a string and a list. So an entry that arrives as an array IS a link — the
+// brackets were consumed by the parser — and one that arrives as the string
+// "[[x]]" (quoted, or from a step option line) is the same link. Both read
+// as the name with `linked: true`; a bare string reads as `linked: false`.
+// The distinction matters once: a linked name can only mean one of the
+// author's files, so `[[search]]` is your tool and `search` is the runtime's
+// group. Everywhere else the two are the same name.
+/** The name inside `[[…]]`, with `flow:` and surrounding space kept. */
+export function stripLink(raw) {
+    const s = raw.trim();
+    const m = s.match(/^\[\[(.*)\]\]$/);
+    return m ? { name: m[1].trim(), linked: true } : { name: s, linked: false };
+}
+/** The first string anywhere inside a nested array — what YAML made of
+ *  `[[x]]`. Deeper nesting (`[[[x]]]`) collapses to the same name. */
+function innermost(value) {
+    if (typeof value === "string" || typeof value === "number")
+        return String(value);
+    if (Array.isArray(value)) {
+        for (const v of value) {
+            const s = innermost(v);
+            if (s !== null)
+                return s;
+        }
+    }
+    return null;
+}
+/**
+ * Every entry of a list field, in order, empty names dropped. Accepts the
+ * shapes a file can carry: an inline or block list of names, links or maps;
+ * a single name; or Claude Code's comma string (`tools: Read, Grep`).
+ */
+export function refList(raw) {
+    if (raw === undefined || raw === null)
+        return [];
+    const entries = Array.isArray(raw) ? raw : typeof raw === "string" && raw.includes(",") ? raw.split(",") : [raw];
+    const out = [];
+    for (const entry of entries) {
+        if (entry === null || entry === undefined)
+            continue;
+        if (Array.isArray(entry)) {
+            const name = innermost(entry);
+            if (name !== null) {
+                const inner = stripLink(name);
+                if (inner.name)
+                    out.push({ name: inner.name, linked: true, mode: null });
+            }
+            continue;
+        }
+        if (typeof entry === "object") {
+            const [key, value] = Object.entries(entry)[0] ?? [];
+            if (!key)
+                continue;
+            const { name, linked } = stripLink(key);
+            if (name)
+                out.push({ name, linked, mode: value === undefined || value === null ? null : String(value) });
+            continue;
+        }
+        const { name, linked } = stripLink(String(entry));
+        if (name)
+            out.push({ name, linked, mode: null });
+    }
+    return out;
+}
+/** Just the names — for a reader that does not care how they were spelt. */
+export function refNames(raw) {
+    return refList(raw).map((r) => r.name);
+}

package/dist/src/run-container.d.ts

@@ -0,0 +1,227 @@
+import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
+import { type ApiSpec, type Effort } from "./store.ts";
+import type { EventExtra } from "./step-exec.ts";
+import { type RuntimeSpec } from "./runtime.ts";
+import type { ScriptSpec } from "./script-tools.ts";
+import type { ConsultSpec } from "./agent-tools.ts";
+import type { SearchRoot, RunDigest } from "./context-tools.ts";
+import type { TranslatorSpec } from "./translator.ts";
+/** What crosses the boundary. Everything in here is values — pre-resolved
+ *  secrets in headers, assembled prompt, serializable MCP configs. */
+export interface ContainerStepInput {
+    agentRel: string;
+    prompt: string;
+    model: string;
+    effort?: Effort | null;
+    systemPrompt: string;
+    allowed: string[];
+    mcpNames: string[];
+    /** http/stdio configs only — in-process servers are rebuilt inside. */
+    mcpServers: Record<string, McpServerConfig>;
+    apis: ApiSpec[];
+    scripts: ScriptSpec[];
+    /** The agent's `runtime:` declaration — the driver builds the venv/npm
+     *  prefix inside the container, where the network is. Without this,
+     *  dependency-using scripts worked locally and failed only in production
+     *  isolation, which is the worst place for a difference. */
+    runtime: RuntimeSpec | null;
+    /** Colleagues this agent may consult — persona + model, gathered from
+     *  their agent.md files host-side. The driver rebuilds the consult tools
+     *  in here; the callees run toolless, so nothing else need cross. */
+    consults: ConsultSpec[];
+    timeoutSec?: number;
+    /** The step's spend ceiling and the model's per-token price — see
+     *  step-exec.ts. Values, so the driver can enforce them in the pod. */
+    budgetUsd?: number | null;
+    price?: {
+        input: number;
+        output: number;
+    } | null;
+    verify?: string;
+    /** `output: json` — checked inside, where the reply is. */
+    output?: "json";
+    /** tools: [search] — the directories to search, as paths INSIDE the
+     *  container (/workspace/…, /library/…). */
+    search?: SearchRoot[];
+    /** tools: [history] — the workspace's recent runs, gathered host-side. */
+    history?: RunDigest[];
+    /** tools: [desks] — the account's other workspaces' runs, gathered host-side. */
+    desks?: RunDigest[];
+    /** A Chat-Completions provider: the driver starts the runtime's translator
+     *  on loopback and points the SDK at it. Null or absent: the env's
+     *  ANTHROPIC_BASE_URL is spoken to directly. */
+    translator?: TranslatorSpec | null;
+}
+/**
+ * How long the sandbox actually existed, measured host-side — the driver
+ * cannot time its own cold start, because it isn't running yet.
+ *
+ * The split is where the two executors differ, so read it per executor:
+ * `sandboxMs` is scheduling and admission (docker `create` returns almost
+ * at once; a gVisor pod's Ready is the real cold-start number), and
+ * `firstOutputMs` is guest boot to the driver's first line (for docker
+ * that's where the cold start actually lands, since `start` is when the
+ * container boots). `totalMs` is what the platform rented either way, and
+ * is the only one billing should ever use.
+ */
+export interface StepTiming {
+    sandboxMs: number;
+    firstOutputMs: number | null;
+    totalMs: number;
+}
+export interface StepActuals {
+    busyCpuSecs: number | null;
+    peakMemBytes: number | null;
+    rxBytes: number | null;
+    txBytes: number | null;
+}
+export interface ContainerStepOutcome {
+    status: "completed" | "failed";
+    result: string | null;
+    /** The model's final text block — see StepRecord.conclusion. Crosses the
+     *  boundary with the rest of the outcome; the driver spreads it. */
+    conclusion?: string | null;
+    /** The parsed JSON of an `output: json` step, crossing back as a value. */
+    data?: unknown;
+    costUsd: number | null;
+    usage?: {
+        inputTokens: number;
+        outputTokens: number;
+    } | null;
+    /** What the sandbox actually touched — see the driver's readActuals. */
+    res?: StepActuals | null;
+    /** Set by the isolated executors only — an in-process step rents no
+     *  sandbox, so it has no compute seconds to bill. */
+    timing?: StepTiming | null;
+}
+/**
+ * The one place the timing line is worded, so the docker and k8s traces
+ * read the same and a cold-start regression is greppable across both.
+ */
+export declare function timingLine(t: StepTiming): string;
+/** Should this container-side path be applied back to the host workspace? */
+export declare function allowedBack(rel: string): boolean;
+/**
+ * Apply what the STEP changed onto the real workspace — additive and
+ * overwriting, never deleting: an agent organising its own files gains
+ * nothing from deleting on the host that it can't get by writing, and a bug
+ * in a deletion sync destroys authored work.
+ *
+ * `baseline` is the copy that was handed to the container at the start of the
+ * step. Without it this function compares the container against the HOST, and
+ * that is a different question with a worse answer: a file the step never
+ * touched, edited on the host while the step ran, differs — so it was written
+ * back from the container's stale copy and the edit vanished. It happened on
+ * 2026-09-03: a tool.md fixed mid-run was reverted eight minutes later by a
+ * step that had never read it, and the repository kept the fix while the
+ * workspace lost it.
+ *
+ * With the baseline the rule is simply: identical to what we handed in means
+ * the step did not touch it, so it is not ours to write back. Concurrent
+ * edits survive, and a step that genuinely changed a file still wins.
+ */
+export declare function applyContainerChanges(hostWs: string, containerWs: string, baseline?: string): string[];
+/**
+ * Where the driver builds venvs and npm prefixes, as an absolute path *inside*
+ * the runner. Fixed, and it has to be: a venv bakes its own absolute path into
+ * every shebang and into pyvenv.cfg, so a cache reused across containers is
+ * only valid if it is mounted at the identical path every time. It is the same
+ * path prepareRuntime picks on its own — FOLDRUN_DATA is /home/agent/.foldrun
+ * in the driver, and the in-container tenant is "runner" — so mounting here
+ * turns the existing cache into a persistent one with no change to the code
+ * that fills it.
+ */
+export declare const RUNTIME_CACHE = "/home/agent/.foldrun/runner/.runtimes";
+/**
+ * The per-tenant directory backing that mount, or null when there is none.
+ *
+ * Per-tenant, not shared. A shared cache would store one copy of pandas
+ * instead of one per account, but it would also be mutable state that one
+ * tenant's step writes and another tenant's step then *executes* — a poisoned
+ * venv arriving as a trusted local file, which is precisely the path gVisor,
+ * the capability drop and the egress policy all exist to close. Disk is the
+ * cheaper thing to spend. If the duplication ever stops being cheap, the fix
+ * is a read-only mount filled by a trusted builder, not a writable shared one.
+ *
+ * Deliberately NOT under `<tenant>/.runtimes`, which is the *host* cache: the
+ * venvs there carry host absolute paths and would be unusable inside a runner.
+ * Two roots, so a hit is always a real hit.
+ */
+export declare function runtimeCacheDir(tenant: string | undefined): string | null;
+export declare function runnerImageTag(): string;
+/**
+ * Build the runner image if this exact (core version, driver, dockerfile)
+ * has not been built before. `npm pack` of the installed core, so the image
+ * runs the same bytes the server does.
+ */
+export declare function ensureRunnerImage(): {
+    tag: string;
+    log: string[];
+};
+export declare function parseDriverLine(line: string): {
+    e: "event";
+    type: "text" | "tool" | "info" | "error";
+    text: string;
+    call?: string;
+    ms?: number;
+    err?: boolean;
+} | {
+    e: "done";
+} & ContainerStepOutcome | null;
+export interface RunInContainerArgs {
+    workspaceRoot: string;
+    libraryRoot: string;
+    /** The account this step belongs to — the key for its dependency cache.
+     *  Optional so an embedder that has no tenancy simply gets no cache. */
+    tenant?: string;
+    input: ContainerStepInput;
+    /** Secret + provider env — crosses as an env file, never argv. */
+    env: Record<string, string>;
+    emit: (type: "text" | "tool" | "info" | "error", text: string, extra?: EventExtra) => void;
+    /** The run this step belongs to. Stamped on the sandbox as a label so a
+     *  person stopping the run can reach the thing actually burning money —
+     *  without it, "stop" could only mean "stop after this step", and a
+     *  browser step has fifteen minutes left to spend. */
+    runId?: string;
+    /** The reservation class — which limits this step's sandbox holds. */
+    size?: "small" | "large" | "heavy";
+}
+/** The limits a size class reserves. Large is the install's configured
+ *  limits unchanged, so existing installs bill and behave identically;
+ *  small defaults to a quarter-ish slice and is env-tunable. */
+/**
+ * A memory figure Kubernetes will accept.
+ *
+ * `sizeLimits` speaks Docker, because that is who asked first: `--memory 2g`.
+ * Kubernetes wants a quantity — `2Gi` — and rejects the lowercase form with
+ * "quantities must match the regular expression", which names neither the
+ * field nor the value. The default size returns `2g`, so every default-size
+ * step failed to create a pod on any install that had not overridden
+ * FOLDRUN_RUNNER_MEMORY. These manifests do override it, which is why this
+ * survived: it broke for self-hosters and for nobody testing here.
+ *
+ * Docker's suffixes are binary, so `g` is `Gi` and not `G`. A value that is
+ * already a Kubernetes quantity passes through, and an unrecognised one is
+ * handed over unchanged so the cluster's own error is the one you read.
+ *
+ * Case decides, because one suffix is ambiguous: `k` is a legal Kubernetes
+ * decimal suffix AND Docker's kibibytes. Everything this is given comes from
+ * sizeLimits, which speaks Docker, so lowercase is read as Docker's — the
+ * difference is 2.4% on a memory limit and the alternative is silently
+ * misreading the default.
+ */
+export declare function k8sMemory(value: string): string;
+export declare function sizeLimits(size?: "small" | "large" | "heavy"): {
+    cpus: string;
+    memory: string;
+};
+/** The label both executors stamp, so one name means one thing. */
+export declare const RUN_LABEL = "foldrun-run-id";
+/**
+ * Destroy any sandbox still running for this run. Best effort by design:
+ * the step may have finished a moment ago, the daemon may be unreachable,
+ * and neither is a reason to refuse to stop a run. Returns how many it
+ * removed, which is what the trace reports.
+ */
+export declare function killRunSandboxes(runId: string): number;
+export declare function runStepInContainer(args: RunInContainerArgs): Promise<ContainerStepOutcome>;