@foldrun/core 0.2.0

package/dist/src/tool-test.js

@@ -0,0 +1,335 @@
+// Call a tool once, now, and say what happened.
+//
+// Without this, the first time anyone finds out a tool is misconfigured is
+// mid-flow, inside an agent's turn, as a tool error the model paraphrases into
+// something vague. A wrong `base:`, a secret that was never set, a script path
+// with a typo — all of them look identical from the outside: the agent just
+// doesn't use the tool and says something plausible instead.
+//
+// So each transport gets a real exercise, not a syntax check:
+//
+//   http    an actual request to the declared base URL
+//   script  actually runs it, with the workspace's secrets in the environment
+//   mcp     actually starts the server and completes an MCP handshake
+//
+// Nothing here returns a secret value. Missing secrets are reported by *name*,
+// because "which one didn't you set" is the useful half and the value is not.
+import { spawn } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveSecrets } from "./secrets.js";
+import { listAgents, workspaceDir } from "./store.js";
+import { libraryDir } from "./library.js";
+import { secretsUsedByApi } from "./api-tools.js";
+import { commandFor, resolveRunPath } from "./script-tools.js";
+import { parseRuntime, prepareRuntime } from "./runtime.js";
+const MAX_DETAIL = 4000;
+const TIMEOUT_MS = 15_000;
+// A tool test runs tenant-authored code directly on the host — real runs are
+// containerized, this is not — so it must NOT inherit the dashboard's full
+// process.env. That env holds FOLDRUN_SECRET_KEY (the global install key that
+// signs every tenant's webhook tokens and git-push secrets), plus the S3/DB/
+// Stripe/GitHub credentials: handing them to a `console.log(process.env)`
+// script tool is cross-tenant compromise. The child instead starts from a
+// minimal host base — only enough for an interpreter to be found and run —
+// and gets the tool's own declared secrets layered on top by the callers.
+const HOST_BASE_ENV_KEYS = [
+    "PATH", "HOME", "TMPDIR", "TMP", "TEMP", "LANG", "LANGUAGE",
+    "LC_ALL", "LC_CTYPE", "TZ", "TERM", "SHELL", "USER", "LOGNAME",
+    "NODE_ENV", // not a secret; some interpreters/tools read it.
+    // Windows equivalents, harmless elsewhere.
+    "SYSTEMROOT", "COMSPEC", "PATHEXT", "WINDIR",
+];
+function hostSafeBaseEnv() {
+    const base = {};
+    for (const k of HOST_BASE_ENV_KEYS) {
+        const v = process.env[k];
+        if (v !== undefined)
+            base[k] = v;
+    }
+    return base;
+}
+const clip = (s) => s.length > MAX_DETAIL ? `${s.slice(0, MAX_DETAIL)}\n… truncated` : s;
+/** `${NAME}` → value, for headers and query. Same rule the runtime uses. */
+const substitute = (v, env) => v.replace(/\$\{([A-Z0-9_]+)\}/g, (_, k) => env[k] ?? "");
+export async function testTool(tenant, workspace, def, input = {}) {
+    const probePath = input.path ?? "";
+    const started = Date.now();
+    const done = (r) => ({ ...r, ms: Date.now() - started });
+    if (def.kind === "http") {
+        const api = def.spec;
+        const needed = secretsUsedByApi(api);
+        const { env, missing } = resolveSecrets(tenant, needed, workspace);
+        try {
+            const rel = probePath.startsWith("/") || probePath === "" ? probePath : `/${probePath}`;
+            const url = new URL(api.base + rel);
+            // Same confinement the agent gets: a probe can't reach another host.
+            if (!url.href.startsWith(api.base)) {
+                return done({
+                    ok: false, transport: "http", missingSecrets: missing,
+                    summary: "that path escapes the declared base URL",
+                    detail: `base: ${api.base}\npath: ${probePath}`,
+                });
+            }
+            for (const [k, v] of Object.entries(api.query))
+                url.searchParams.set(k, substitute(v, env));
+            const headers = {};
+            for (const [k, v] of Object.entries(api.headers))
+                headers[k] = substitute(v, env);
+            const method = api.methods.includes("GET") ? "GET" : api.methods[0];
+            const res = await fetch(url, {
+                method,
+                headers,
+                signal: AbortSignal.timeout(TIMEOUT_MS),
+            });
+            const body = await res.text();
+            // An unset secret means the tool cannot authenticate, so it is not
+            // working — whatever a permissive endpoint chose to return. Reporting
+            // ok on a request that went out with no credentials is how you ship a
+            // tool that 401s the first time it meets the real API.
+            return done({
+                ok: res.ok && missing.length === 0,
+                transport: "http",
+                missingSecrets: missing,
+                summary: missing.length > 0
+                    ? `${method} ${url.pathname} → ${res.status}, but sent without ${missing.join(", ")}`
+                    : `${method} ${url.pathname} → ${res.status} ${res.statusText}`,
+                detail: clip(body),
+            });
+        }
+        catch (err) {
+            return done({
+                ok: false, transport: "http", missingSecrets: missing,
+                summary: err instanceof Error ? err.message : String(err),
+                // A missing secret usually surfaces as a 401 rather than an error, so
+                // say it here too — it is the likeliest cause of both.
+                detail: missing.length ? `unset secrets: ${missing.join(", ")}` : "",
+            });
+        }
+    }
+    if (def.kind === "script") {
+        const run = String(def.spec.run ?? "");
+        // A run's working directory is the calling AGENT's folder, not the
+        // workspace root — and scripts rely on that. `path.resolve(cwd, "..",
+        // "..", "state", f)` is the ordinary way to reach workspace state, and
+        // testing one directory too high sent it to <data>/<tenant>/state: a
+        // real file read from the wrong place, reported as an empty result
+        // rather than an error. The tester now stands where a run stands.
+        //
+        // Which agent: one that granted this tool, so the test is the call that
+        // would actually happen; any agent otherwise, since only the DEPTH
+        // changes what a relative path resolves to.
+        const dir = workspaceDir(tenant, workspace);
+        const agents = listAgents(tenant, workspace);
+        const caller = agents.find((a) => a.ownTools.includes(def.name)) ?? agents[0] ?? null;
+        // With no agents at all there is nothing at that depth to stand in; the
+        // workspace root is wrong but it exists, and the note says so rather
+        // than failing a test over a workspace that cannot run anything yet.
+        const cwd = caller ? path.join(dir, "agents", caller.name) : dir;
+        const file = resolveRunPath(path.join(dir, "agents", "_probe"), run, libraryDir(tenant, "scripts"));
+        if (!fs.existsSync(file)) {
+            return done({
+                ok: false, transport: "script", missingSecrets: [],
+                summary: `no such script: ${run}`,
+                detail: `looked for ${file}\n\nThis is the commonest way to get a tool that silently never loads.`,
+            });
+        }
+        const names = Array.isArray(def.spec.secrets) ? def.spec.secrets.map(String) : [];
+        const { env, missing } = resolveSecrets(tenant, names, workspace);
+        // The runtime's own choice of interpreter, not a second table beside it.
+        const interpreter = typeof def.spec.interpreter === "string" ? def.spec.interpreter : undefined;
+        // Declared args become long flags, exactly as the runtime passes them.
+        const declared = def.spec.args && typeof def.spec.args === "object"
+            ? Object.keys(def.spec.args)
+            : [];
+        const flags = [];
+        for (const [k, v] of Object.entries(input.args ?? {})) {
+            if (v !== "" && /^[a-z][a-z0-9_]*$/i.test(k))
+                flags.push(`--${k}`, v);
+        }
+        // The tool's own dependencies, built (or reused) the way a run builds
+        // them. Without this a tool declaring `runtime: { packages: [requests] }`
+        // ran fine in a flow and failed the Test button with "no module named
+        // requests" — the one place a developer goes to find out if it works.
+        const toolRuntime = prepareRuntime(tenant, parseRuntime(def.spec.runtime));
+        if (toolRuntime.error) {
+            return done({
+                ok: false, transport: "script", missingSecrets: missing,
+                summary: "its runtime could not be built",
+                detail: [toolRuntime.error, ...toolRuntime.log].join("\n"),
+            });
+        }
+        const { cmd, args } = commandFor({ interpreter, run: run, name: "", description: "", args: {} }, file, toolRuntime.interpreters);
+        const { code, out } = await runOnce(cmd, [...args, ...flags], cwd, {
+            ...hostSafeBaseEnv(),
+            ...toolRuntime.env,
+            ...env,
+        });
+        // A script that needs arguments and got none has not failed — it has not
+        // been tested. Saying "exited 2" would send someone looking for a bug.
+        const untested = code !== 0 && declared.length > 0 && flags.length === 0;
+        return done({
+            ok: code === 0,
+            transport: "script",
+            missingSecrets: missing,
+            summary: untested
+                ? `needs ${declared.map((a) => `--${a}`).join(", ")} — fill them in and test again`
+                : code === 0 ? "exited 0" : `exited ${code ?? "with an error"}`,
+            detail: clip((caller
+                ? `ran from agents/${caller.name}/, where a run runs\n\n`
+                : `ran from the workspace root — there is no agent to stand in for, so a script that reaches ../../ will look one level too high\n\n`) +
+                (out || "(no output)")),
+        });
+    }
+    // ---- mcp: start the server and complete a handshake ----
+    const spec = def.spec;
+    if (spec.url) {
+        // A remote server: the honest check we can make without a full client is
+        // that the endpoint answers.
+        try {
+            const res = await fetch(spec.url, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+            return done({
+                ok: res.ok,
+                transport: "mcp",
+                missingSecrets: [],
+                summary: `${spec.url} → ${res.status} ${res.statusText}`,
+                detail: "Endpoint reachable. This does not verify the MCP handshake — only a local (command) server is started and spoken to.",
+            });
+        }
+        catch (err) {
+            return done({
+                ok: false, transport: "mcp", missingSecrets: [],
+                summary: err instanceof Error ? err.message : String(err),
+                detail: "",
+            });
+        }
+    }
+    if (!spec.command) {
+        return done({
+            ok: false, transport: "mcp", missingSecrets: [],
+            summary: "no command: or url: — this tool cannot load",
+            detail: "",
+        });
+    }
+    const named = Object.entries(spec.env ?? {})
+        .map(([, v]) => String(v).match(/^\$\{([A-Z0-9_]+)\}$/)?.[1])
+        .filter((n) => Boolean(n));
+    const { env, missing } = resolveSecrets(tenant, named, workspace);
+    const childEnv = { ...hostSafeBaseEnv() };
+    for (const [k, v] of Object.entries(spec.env ?? {}))
+        childEnv[k] = substitute(String(v), env);
+    const handshake = await mcpHandshake(spec.command, spec.args ?? [], childEnv);
+    return done({
+        ok: handshake.ok,
+        transport: "mcp",
+        missingSecrets: missing,
+        summary: handshake.summary,
+        detail: clip(handshake.detail),
+    });
+}
+/** Run a command to completion, capturing both streams together. */
+function runOnce(cmd, args, cwd, env) {
+    return new Promise((resolve) => {
+        let out = "";
+        let child;
+        try {
+            child = spawn(cmd, args, { cwd, env, stdio: ["ignore", "pipe", "pipe"] });
+        }
+        catch (err) {
+            resolve({ code: null, out: err instanceof Error ? err.message : String(err) });
+            return;
+        }
+        const timer = setTimeout(() => child.kill("SIGKILL"), TIMEOUT_MS);
+        child.stdout?.on("data", (d) => (out += d));
+        child.stderr?.on("data", (d) => (out += d));
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            resolve({ code: null, out: `${out}${err.message}` });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ code, out });
+        });
+    });
+}
+/**
+ * Start a stdio MCP server and complete `initialize` + `tools/list`.
+ *
+ * This is the whole point of testing an MCP tool: "the binary exists" tells you
+ * nothing, and the failure people actually hit is a server that starts and then
+ * exposes nothing useful.
+ */
+function mcpHandshake(command, args, env) {
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(command, args, { env, stdio: ["pipe", "pipe", "pipe"] });
+        }
+        catch (err) {
+            resolve({ ok: false, summary: `could not start ${command}`, detail: String(err), });
+            return;
+        }
+        let buf = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            child.kill("SIGKILL");
+            resolve(r);
+        };
+        const timer = setTimeout(() => finish({
+            ok: false,
+            summary: "the server did not answer in time",
+            detail: stderr || "No response to initialize within 15s.",
+        }), TIMEOUT_MS);
+        const send = (msg) => child.stdin?.write(`${JSON.stringify(msg)}\n`);
+        child.on("error", (err) => finish({ ok: false, summary: `could not start ${command}`, detail: err.message }));
+        child.stderr?.on("data", (d) => (stderr += d));
+        child.stdout?.on("data", (d) => {
+            buf += d;
+            // One JSON-RPC message per line.
+            for (const line of buf.split("\n").slice(0, -1)) {
+                if (!line.trim())
+                    continue;
+                let msg;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (msg.error) {
+                    finish({ ok: false, summary: msg.error.message ?? "the server returned an error", detail: line });
+                    return;
+                }
+                if (msg.id === 1) {
+                    send({ jsonrpc: "2.0", method: "notifications/initialized" });
+                    send({ jsonrpc: "2.0", id: 2, method: "tools/list", params: {} });
+                }
+                else if (msg.id === 2) {
+                    const tools = msg.result?.tools ?? [];
+                    finish({
+                        ok: true,
+                        summary: `connected — ${tools.length} tool${tools.length === 1 ? "" : "s"}`,
+                        detail: tools.map((t) => `• ${t.name}`).join("\n") || "The server exposes no tools.",
+                    });
+                    return;
+                }
+            }
+            buf = buf.slice(buf.lastIndexOf("\n") + 1);
+        });
+        send({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "initialize",
+            params: {
+                protocolVersion: "2024-11-05",
+                capabilities: {},
+                clientInfo: { name: "foldrun-tool-test", version: "0.1.0" },
+            },
+        });
+    });
+}

package/dist/src/translator.d.ts

@@ -0,0 +1,159 @@
+type Json = Record<string, unknown>;
+export type TranslatorWire = "chat" | "responses";
+export interface TranslatorSpec {
+    /** The provider's base, e.g. https://api.openai.com/v1 — `/chat/completions`
+     *  or `/responses` is appended, by `wire`. */
+    upstreamBase: string;
+    /** Which OpenAI shape the endpoint speaks. Default chat. */
+    wire?: TranslatorWire;
+    /** Already resolved. Sent as `Authorization: Bearer`. */
+    upstreamKey: string;
+    /** Extra headers the provider wants, already resolved. */
+    headers?: Record<string, string>;
+    maxTokensParam?: "max_tokens" | "max_completion_tokens";
+    /** Map Anthropic `thinking:` to OpenAI `reasoning_effort`; off drops it. */
+    reasoningEffort?: boolean;
+    /** The provider block's `params:` — merged into the outgoing body after
+     *  the translation, so a file can set what this format does not model. */
+    params?: Record<string, unknown>;
+    /** How the endpoint is named in the trace. */
+    label?: string;
+    /** The step's egress lease, when the sandbox must not hold the key: the
+     *  upstream request goes through it, and `upstreamKey` is a placeholder
+     *  the proxy fills. */
+    egress?: string;
+}
+export interface RunningTranslator {
+    port: number;
+    /** The key the SDK must present — random per translator, so nothing but
+     *  this step's SDK process can use the localhost door. */
+    key: string;
+    baseUrl: string;
+    /** The env that points the SDK here. Overrides whatever provider env the
+     *  caller assembled: the translator is now the endpoint. */
+    env: Record<string, string>;
+    /** One line per request, drained by the caller into the run trace. */
+    drainLog: () => string[];
+    close: () => Promise<void>;
+}
+interface Dropped {
+    add(what: string): void;
+    lines(): string[];
+}
+/**
+ * Whether a model is one OpenAI's own endpoint refuses a reasoning-effort
+ * parameter for ("Unsupported parameter: 'reasoning.effort'" on gpt-4o-mini).
+ * A gateway in front of it ignored the field, which is how the preset's
+ * reasoningEffort shipped untested against the origin. The families that do
+ * not reason are the ones named — anything else (o-series, gpt-5, grok,
+ * gemini, deepseek-r, qwen thinking) keeps getting the knob, because on a
+ * gateway the id alone cannot say and an ignored field costs nothing.
+ */
+export declare function modelRejectsReasoning(model: string): boolean;
+/**
+ * An Anthropic Messages request as a Chat Completions request. Pure.
+ *
+ * Message order matters to the other side: a tool result must directly
+ * follow the assistant turn that called the tool. Anthropic puts results
+ * inside the next user message, so those blocks become `tool` messages
+ * first and whatever else the user said follows as a user message.
+ */
+export declare function toChatCompletions(req: Json, opts: {
+    maxTokensParam?: "max_tokens" | "max_completion_tokens";
+    reasoningEffort?: boolean;
+    stream: boolean;
+    /** Merged in last, so the file wins over the translation. */
+    params?: Record<string, unknown>;
+}, drop?: Dropped): Json;
+/**
+ * An Anthropic Messages request as a Responses request. Pure.
+ *
+ * The Responses shape is flatter than Chat Completions: the system prompt
+ * is `instructions`, a tool call and its result are top-level items rather
+ * than an assistant field and a `tool` role, and a document is an input
+ * file the model reads itself. Order is preserved as written: a
+ * function_call item, then its function_call_output, then whatever else the
+ * user said.
+ */
+export declare function toResponses(req: Json, opts: {
+    reasoningEffort?: boolean;
+    stream: boolean;
+    params?: Record<string, unknown>;
+}, drop?: Dropped): Json;
+/** A finished Chat Completion as an Anthropic message. Pure. */
+export declare function fromChatCompletion(res: Json, requestedModel: string): Json;
+/**
+ * The streaming half: Chat-Completions chunks in, Anthropic SSE events out.
+ * A state machine because the two streams disagree about structure — one
+ * is a flat sequence of deltas, the other is blocks with explicit starts and
+ * stops — and a tool call's arguments arrive as fragments that the other
+ * side wants as `input_json_delta`s inside one open block.
+ */
+export declare class StreamTranslator {
+    private started;
+    private nextIndex;
+    private textIndex;
+    /** Chat-Completions tool index → Anthropic block index. */
+    private tools;
+    private finish;
+    private usage;
+    private id;
+    private readonly model;
+    constructor(model: string);
+    private event;
+    private start;
+    private closeText;
+    /** One parsed chunk in, zero or more SSE events out. */
+    feed(chunk: Json): string[];
+    /** The stream ended: close what is open, say why, and stop. */
+    finishStream(): string[];
+}
+/** A finished Response as an Anthropic message. Pure. */
+export declare function fromResponses(res: Json, requestedModel: string): Json;
+/**
+ * The Responses stream as Anthropic SSE. Simpler than the Chat-Completions
+ * machine because the other side already speaks in items: an output item
+ * is added, its text or arguments arrive as deltas, it is done. Each item
+ * becomes one Anthropic block; `response.completed` carries the usage and
+ * the reason.
+ */
+export declare class ResponsesStreamTranslator {
+    private started;
+    private nextIndex;
+    /** Responses output_index → Anthropic block index and kind. */
+    private blocks;
+    private usage;
+    private incomplete;
+    private sawTool;
+    private id;
+    private readonly model;
+    constructor(model: string);
+    private event;
+    private start;
+    /** One parsed event in, zero or more SSE events out. */
+    feed(ev: Json): string[];
+    /** The stream ended: close what is still open, say why, and stop. */
+    finishStream(): string[];
+}
+/**
+ * Start the translator for one step. Binds an ephemeral port on loopback,
+ * mints the key the SDK will present, and returns the env that points the
+ * SDK at it. Close it when the step is over.
+ */
+export declare function startTranslator(spec: TranslatorSpec): Promise<RunningTranslator>;
+/**
+ * What a provider block needs from the translator, or null when the block
+ * speaks Anthropic and needs none. Values only — this crosses into the run
+ * container as JSON.
+ */
+export declare function translatorSpecFor(spec: {
+    format: string;
+    baseUrl: string;
+    token: string;
+    headers: Record<string, string>;
+    params?: Record<string, unknown>;
+    name?: string | null;
+    maxTokensParam?: "max_tokens" | "max_completion_tokens";
+    reasoningEffort?: boolean;
+}): TranslatorSpec | null;
+export {};