@foldrun/core 0.2.0

package/dist/src/confine.js

@@ -0,0 +1,298 @@
+// Filesystem confinement for an agent's own tools.
+//
+// Scripts already run in containers. The agent's *built-in* tools —
+// Read/Write/Edit/Glob/Grep and friends — do not: they execute in the server
+// process with its full permissions. A run proved this is not theoretical: an
+// agent told to write `outputs/SHIPPED.txt` created it two directories up and
+// invented a whole phantom workspace on the way.
+//
+// The boundary is the WORKSPACE, not the agent. Agents in one workspace are a
+// team — a reviewer legitimately reads what the writer produced — while the
+// workspace is the isolation unit for everything else in the platform, so it
+// is the honest place to draw the line.
+//
+// Inside that boundary, three things are still off limits:
+//   · secrets.json — the encrypted store; an agent gets secrets as env vars,
+//     never as a file it can exfiltrate wholesale
+//   · runs/ — the run journal is the audit trail, and a step that can rewrite
+//     its own history makes every other guarantee unverifiable
+//   · index.md and log.md inside a knowledge/ or memory/ bundle — generated by
+//     the platform on every write. An agent scribbling on one would be undone
+//     by the next syncBundleFor, but until then the index says whatever it was
+//     told to say, and log.md is provenance for the same reason runs/ is.
+//
+// There is no curated index beside the generated one. A bundle has exactly the
+// two reserved files OKF defines, and both are generated.
+//
+// The bundle scoping matters. An earlier draft denied any index.md anywhere,
+// which would have blocked an agent writing outputs/index.md — a perfectly
+// ordinary deliverable — so the rule names the two directories it applies to.
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * A path with its symlinks resolved, as far as it exists.
+ *
+ * Both sides of the containment check have to be resolved the same way or the
+ * comparison is between two spellings of one place. On macOS `/var` is a
+ * symlink to `/private/var`, so a workspace under a system temp directory was
+ * handed to the runtime as `/var/folders/…` while every path the agent
+ * produced came back as `/private/var/folders/…`. `path.relative` then said
+ * `..`, and the agent was told its own workspace was outside the workspace —
+ * on every write, for the whole run, while the run still reported success
+ * because the agent gave up politely.
+ *
+ * Falls back a level at a time because the path may not exist yet: a Write
+ * creating a file needs the directory resolved, not the file.
+ */
+function real(p) {
+    try {
+        return fs.realpathSync.native(p);
+    }
+    catch {
+        const parent = path.dirname(p);
+        return parent === p ? p : path.join(real(parent), path.basename(p));
+    }
+}
+/** Tool argument names that carry a filesystem path. */
+const PATH_KEYS = [
+    "file_path",
+    "path",
+    "notebook_path",
+    "filePath",
+    "edits", // NotebookEdit-style payloads are checked via file_path too
+];
+const DENIED_WITHIN = [
+    /(^|\/)secrets\.json$/,
+    /(^|\/)runs(\/|$)/,
+];
+/**
+ * Generated, and therefore not an agent's to edit — but very much an agent's
+ * to read.
+ *
+ * These were denied outright, and a run proved what that costs: an agent told
+ * to start from the index asked for `knowledge/index.md`, was refused, and
+ * spent a turn recovering. The index is the navigational artifact the whole
+ * progressive-disclosure design rests on; refusing to let a reader open it is
+ * the opposite of the intent. The reason they are protected is that a
+ * generated file an agent can edit is one that can lie — which is an argument
+ * about writing, and only about writing.
+ */
+const READ_ONLY_WITHIN = [/(^|\/)(knowledge|memory)\/(.*\/)?(index|log)\.md$/];
+// Skills are announced to the agent with virtual prefixes — `workspace/skills/…`
+// for the workspace's, `library/skills/…` for the account's — because a skill
+// at either scope lives outside the agent's own folder. Symlinking them in
+// was tried and reverted: it recursed into the workspace's own file listing.
+// Expanding the prefix here instead keeps one honest path per skill, with no
+// duplication on disk.
+// Two prefixes, named after the two scopes above an agent. There used to be
+// three — `workspace/` meant the workspace root while `shared/` meant the
+// workspace's *scripts*, which is exactly the kind of near-synonym that gets
+// mis-typed. The old spellings still resolve so nothing existing breaks.
+const VIRTUAL = [
+    { prefix: "account/", root: (r) => r.libraryRoot, readOnly: true },
+    { prefix: "workspace/", root: (r) => r.workspaceRoot, readOnly: false },
+    // legacy, still accepted
+    { prefix: "library/", root: (r) => r.libraryRoot, readOnly: true },
+    { prefix: "workspace/", root: (r) => r.workspaceRoot, readOnly: false },
+];
+const WRITE_TOOLS = new Set(["Write", "Edit", "MultiEdit", "NotebookEdit"]);
+// Only the built-in filesystem tools get path checks. foldrun's own MCP tools
+// are already confined at their own layer — script paths by resolveRunPath,
+// APIs by their declared base URL — and their arguments are not filesystem
+// paths at all: `call_<api>` takes a *URL* path like "/uuid", which this
+// check would otherwise reject as an escape.
+const FS_TOOLS = new Set([
+    "Read",
+    "Write",
+    "Edit",
+    "MultiEdit",
+    "NotebookEdit",
+    "NotebookRead",
+    "Glob",
+    "Grep",
+    "LS",
+]);
+export const isFilesystemTool = (toolName) => FS_TOOLS.has(toolName);
+/**
+ * The path the agent probably meant. Most escapes are one of three guesses —
+ * an invented `/tmp/outputs/…`, an absolute spelling of a workspace
+ * directory, or a directory a tool made outside the workspace — and a
+ * refusal that names the correction is taken on the next turn, where a
+ * generic one is followed by two more wrong guesses. Nothing here is
+ * enforced; it is advice in the error text.
+ */
+export function suggestPath(raw) {
+    const posix = raw.split(path.sep).join("/");
+    const m = posix.match(/(?:^|\/)(outputs|storage|state|memory|knowledge)\/(.+)$/);
+    if (m) {
+        const [, dir, rest] = m;
+        return dir === "outputs"
+            ? `Did you mean outputs/${rest} (relative to your agent directory)?`
+            : `Did you mean workspace/${dir}/${rest}?`;
+    }
+    if (/^\/tmp\//.test(posix)) {
+        return (`There is no /tmp for you. If a tool cloned or built something there, reach it through that tool ` +
+            `(for example its read or find action); scratch files go to outputs/.`);
+    }
+    return `Use a path relative to your agent directory, or workspace/<dir>/… for the workspace root (workspace/storage/, workspace/state/).`;
+}
+/** Expand a virtual prefix to a real absolute path, or null if it has none. */
+export function expandVirtual(raw, roots) {
+    for (const v of VIRTUAL) {
+        if (raw.startsWith(v.prefix)) {
+            return { abs: path.resolve(v.root(roots), raw.slice(v.prefix.length)), readOnly: v.readOnly };
+        }
+    }
+    return null;
+}
+export function checkPaths(toolName, input, roots) {
+    const workspace = real(path.resolve(roots.workspaceRoot));
+    const library = real(path.resolve(roots.libraryRoot));
+    const isWrite = WRITE_TOOLS.has(toolName);
+    let rewritten;
+    // Grep's `pattern` is a REGEX, not a location — Grep says where to look
+    // with `path`. Checking it as a path denied an agent searching for the
+    // literal text "/dev/null", reporting a workspace escape for a string it
+    // wanted to find inside the workspace. Glob's `pattern` really is a path
+    // shape, so it stays checked.
+    const keys = [...PATH_KEYS, "glob", ...(toolName === "Grep" ? [] : ["pattern"])];
+    for (const key of keys) {
+        const raw = input[key];
+        if (typeof raw !== "string" || !raw.trim())
+            continue;
+        // Glob patterns and grep's file filter are only paths when anchored.
+        if ((key === "glob" || key === "pattern") && !raw.startsWith("/") && !expandVirtual(raw, roots)) {
+            continue;
+        }
+        const virtual = expandVirtual(raw, roots);
+        const abs = real(virtual ? virtual.abs : path.resolve(roots.agentDir, raw));
+        // Knowledge is given, not learned: an agent that rewrites the price list
+        // it was handed has corrupted its own source of truth. What it discovers
+        // goes to memory/, which it owns.
+        if (isWrite && /(^|\/)knowledge\//.test(abs.split(path.sep).join("/"))) {
+            return {
+                ok: false,
+                reason: `${toolName} was denied: knowledge/ is reference material maintained by people, not by ` +
+                    `you. If you learned something new, write it to memory/ instead.`,
+            };
+        }
+        if (virtual?.readOnly && isWrite) {
+            return {
+                ok: false,
+                reason: `${toolName} was denied: "${raw}" is in the shared library, which is read-only from a ` +
+                    `run. Change it in the dashboard under Shared, or write your own copy in this workspace.`,
+            };
+        }
+        const inWorkspace = !path.relative(workspace, abs).startsWith("..");
+        const inLibrary = !path.relative(library, abs).startsWith("..");
+        if (!inWorkspace && !inLibrary) {
+            return {
+                ok: false,
+                reason: `${toolName} was denied: "${raw}" is outside this workspace. Agents may only read and ` +
+                    `write inside their own workspace. ${suggestPath(raw)}`,
+            };
+        }
+        const within = path.relative(inLibrary ? library : workspace, abs).split(path.sep).join("/");
+        if (DENIED_WITHIN.some((re) => re.test(within))) {
+            return {
+                ok: false,
+                reason: `${toolName} was denied: "${raw}" is a protected platform file. Secrets reach you as ` +
+                    `environment variables, and the run journal is not yours to read or rewrite.`,
+            };
+        }
+        if (isWrite && READ_ONLY_WITHIN.some((re) => re.test(within))) {
+            return {
+                ok: false,
+                reason: `${toolName} was denied: "${raw}" is generated from the files around it and will be ` +
+                    `rewritten on the next write. Read it freely — to change what it says, change a ` +
+                    `concept file instead.`,
+            };
+        }
+        // Hand the real path back to the tool, so the virtual prefix the prompt
+        // advertises is one the agent can actually open.
+        if (virtual)
+            rewritten = { ...(rewritten ?? input), [key]: abs };
+    }
+    return { ok: true, updatedInput: rewritten };
+}
+// A shell can defeat any argument-level path check, so Bash is handled
+// separately: it runs under the SDK sandbox, and these patterns are a second
+// layer that catches the obvious escapes with a clear message rather than a
+// confusing sandbox error.
+const BASH_ESCAPES = [
+    /\.\.\/\.\.\/\.\.\/\.\.\/\.\.\//, // five levels up leaves even the account
+    /(^|[\s;|&(<>])cd\s+(\/|~)/, // cd to an absolute path or home
+    // `~` was guarded only for `cd`, so `cat ~/.ssh/id_rsa` and
+    // `cp ~/.aws/credentials .` walked straight past — the exact "obvious
+    // escape" this layer exists to name before the sandbox does.
+    /(^|[\s;|&(<>=:"'])~\//, // a home-relative path, whatever the command
+    /(^|[\s;|&(<>])[a-z_]+\s+\/(etc|root|home|Users|var|proc|dev)\b/, // absolute system paths
+    /secrets\.json/,
+    /\.secret-key/,
+    // Don't let a command *print* a credential out — but only that. This used
+    // to match any reference to a secret env var, which denied the entire
+    // point of secrets: `ssh -i "$SSH_KEY"`, `curl -H "Authorization: $TOKEN"`
+    // and `sshpass -e ssh …` all use a credential without emitting it, and all
+    // were being refused. Now only an output builtin fronting the variable is
+    // blocked; the journal redaction layer is the backstop for the rest.
+    /\b(echo|printf|print|cat|head|tail|env|printenv)\b[^\n|;&]*\$\{?[A-Z_]*(TOKEN|KEY|SECRET|PASSWORD)/,
+];
+/**
+ * Shapes that modify a file, as opposed to reading one.
+ *
+ * Bash cannot be checked the way a tool call can — there is no path argument,
+ * only a string — so the protections checkPaths applies to Write and Edit have
+ * to be recognised here from the command's shape. That is why `knowledge/` is
+ * matched only alongside one of these: reading the price list is the entire
+ * reason it exists, and a blanket rule would have banned `cat`.
+ */
+const WRITES_TO_A_FILE = /(>>?|\btee\b|\bsed\b[^]*?\s-i\b|\b(rm|mv|cp|truncate|dd|install|ln|chmod|chown|mkdir|rmdir|touch)\b)/;
+/** Protections that mirror checkPaths, per command segment. */
+const PROTECTED_BASH = [
+    {
+        re: /(^|[\s'"(/])knowledge\//,
+        writeOnly: true,
+        reason: "knowledge/ is reference material maintained by people, not by you. If you learned " +
+            "something new, write it to memory/ instead.",
+    },
+    {
+        // Not write-only: checkPaths denies reading the journal too, and a rule
+        // that differs by tool is a rule an agent can shop around for.
+        re: /(^|[\s'"(/])runs(\/|$)/,
+        writeOnly: false,
+        reason: "the run journal is the audit trail for this run, and is not yours to read or rewrite.",
+    },
+    {
+        re: /(^|[\s'"(/])(knowledge|memory)\/(\S*\/)?(index|log)\.md/,
+        // Write-only, matching checkPaths. A rule that differs by tool is a rule
+        // an agent can shop around for — and reading the index is the point of it.
+        writeOnly: true,
+        reason: "index.md and log.md are generated from the files around them — write the concept file " +
+            "instead.",
+    },
+];
+export function checkBash(command) {
+    for (const re of BASH_ESCAPES) {
+        if (re.test(command)) {
+            return {
+                ok: false,
+                reason: `Bash was denied: this command reaches outside the workspace. Work with paths relative ` +
+                    `to your agent directory.`,
+            };
+        }
+    }
+    // Per segment, so `cat knowledge/prices.md && echo done` is judged on the
+    // part that touches the path rather than on the whole line.
+    for (const segment of command.split(/[;|&]+|\n/)) {
+        if (!segment.trim())
+            continue;
+        const writes = WRITES_TO_A_FILE.test(segment);
+        for (const rule of PROTECTED_BASH) {
+            if (rule.writeOnly && !writes)
+                continue;
+            if (rule.re.test(segment))
+                return { ok: false, reason: `Bash was denied: ${rule.reason}` };
+        }
+    }
+    return { ok: true };
+}

package/dist/src/container.d.ts

@@ -0,0 +1,30 @@
+import type { RuntimeSpec } from "./runtime.ts";
+export type Executor = "docker" | "sandbox";
+export declare function dockerAvailable(): boolean;
+export declare function chooseExecutor(): Executor;
+export declare function imageTag(spec: RuntimeSpec | null): string;
+export interface ImageResult {
+    tag: string;
+    built: boolean;
+    error: string | null;
+    log: string[];
+}
+export declare function ensureImage(spec: RuntimeSpec | null): ImageResult;
+export interface ContainerRunOptions {
+    /** Host directory mounted at /workspace — the agent's own folder. */
+    agentDir: string;
+    /** Extra read-only mounts: host path → container path. */
+    readOnly?: Record<string, string>;
+    image: string;
+    argv: string[];
+    env: Record<string, string>;
+    /** Only when the tool.md set one — the platform has no clock of its own. */
+    timeoutMs?: number;
+    /** Allow outbound network (agents that declared APIs need it). */
+    network: boolean;
+    maxOutput: number;
+}
+export declare function runInContainer(opts: ContainerRunOptions): Promise<{
+    code: number | null;
+    out: string;
+}>;

package/dist/src/container.js

@@ -0,0 +1,172 @@
+// Container execution for scripts.
+//
+// The isolation boundary is the run: one container image per runtime
+// declaration (keyed by the same fingerprint the host path uses), and every
+// script call in a run executes inside a container from that image with the
+// agent's directory mounted. Scripts therefore cannot read other tenants'
+// data, the key file, or anything else on the host.
+//
+// Falls back to host execution when Docker isn't available, so local
+// development keeps working with zero configuration.
+import fs from "node:fs";
+import path from "node:path";
+import { dataRoot } from "./paths.js";
+import { spawnSync, spawn } from "node:child_process";
+import { fingerprint } from "./runtime.js";
+const BUILD_TIMEOUT_MS = 600_000;
+const IMAGE_PREFIX = "foldrun-runtime";
+// Any Docker-compatible CLI works — Docker Engine, colima, Podman, nerdctl,
+// OrbStack. Copying files in and out (rather than bind-mounting) is what
+// makes that portability real: no host path has to be shared with a VM.
+const CLI = process.env.FOLDRUN_CONTAINER_CLI ?? "docker";
+let cachedAvailability = null;
+export function dockerAvailable() {
+    if (process.env.FOLDRUN_EXECUTOR === "host" || process.env.FOLDRUN_EXECUTOR === "sandbox")
+        return false;
+    if (cachedAvailability !== null)
+        return cachedAvailability;
+    const res = spawnSync(CLI, ["info", "--format", "{{.ServerVersion}}"], {
+        encoding: "utf8",
+        timeout: 15_000,
+    });
+    cachedAvailability = res.status === 0;
+    return cachedAvailability;
+}
+export function chooseExecutor() {
+    return dockerAvailable() ? "docker" : "sandbox";
+}
+export function imageTag(spec) {
+    return `${IMAGE_PREFIX}:${spec ? fingerprint(spec) : "base"}`;
+}
+function imageExists(tag) {
+    return spawnSync(CLI, ["image", "inspect", tag], { timeout: 20_000 }).status === 0;
+}
+// A minimal image carrying just the declared runtimes and packages.
+function dockerfileFor(spec) {
+    const wantsNode = spec ? spec.node !== undefined || spec.npm.length > 0 : false;
+    const pyVersion = typeof spec?.python === "string" ? spec.python : "3.12";
+    const lines = [];
+    if (wantsNode && !spec?.packages.length && spec?.python === undefined) {
+        lines.push("FROM node:22-slim");
+    }
+    else {
+        lines.push(`FROM python:${pyVersion}-slim`);
+        if (wantsNode) {
+            lines.push("RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm && rm -rf /var/lib/apt/lists/*");
+        }
+    }
+    if (spec?.packages.length) {
+        lines.push(`RUN pip install --no-cache-dir ${spec.packages.map((p) => `'${p}'`).join(" ")}`);
+    }
+    if (spec?.npm.length) {
+        lines.push("WORKDIR /opt/npm");
+        lines.push(`RUN npm install --no-fund --no-audit ${spec.npm.map((p) => `'${p}'`).join(" ")}`);
+        lines.push("ENV NODE_PATH=/opt/npm/node_modules");
+    }
+    // Scripts run as a non-root user with no write access outside the mount.
+    lines.push("RUN useradd -m -u 10001 agent");
+    lines.push("USER agent");
+    lines.push("WORKDIR /workspace");
+    return lines.join("\n") + "\n";
+}
+export function ensureImage(spec) {
+    const tag = imageTag(spec);
+    if (imageExists(tag))
+        return { tag, built: false, error: null, log: [`image ${tag}: cached`] };
+    // dataRoot() may not exist yet on a brand-new install or a fresh workspace
+    // whose first-ever step is a script tool — mkdtemp does not create parents,
+    // so without this the first script build dies with ENOENT and the whole run
+    // fails on nothing the author did wrong.
+    fs.mkdirSync(dataRoot(), { recursive: true });
+    const dir = fs.mkdtempSync(path.join(dataRoot(), ".build-"));
+    try {
+        fs.writeFileSync(path.join(dir, "Dockerfile"), dockerfileFor(spec));
+        const res = spawnSync(CLI, ["build", "-q", "-t", tag, dir], {
+            encoding: "utf8",
+            timeout: BUILD_TIMEOUT_MS,
+        });
+        if (res.status !== 0) {
+            return {
+                tag,
+                built: false,
+                error: `image build failed: ${`${res.stderr ?? ""}`.slice(-400)}`,
+                log: [],
+            };
+        }
+        return { tag, built: true, error: null, log: [`image ${tag}: built`] };
+    }
+    finally {
+        fs.rmSync(dir, { recursive: true, force: true });
+    }
+}
+// Files are copied in and out rather than bind-mounted. Bind mounts need the
+// host path to be inside Docker's shared-paths configuration, which fails
+// silently (the mount appears empty) on Docker Desktop for directories it
+// isn't allowed to share. Copying is what CI systems do, needs no host
+// configuration, and has the side benefit that a script cannot corrupt the
+// source tree — only the copy it was given.
+export async function runInContainer(opts) {
+    const docker = (args, timeout = 60_000) => spawnSync(CLI, args, { encoding: "utf8", timeout });
+    const createArgs = [
+        "create",
+        "-i",
+        "--workdir",
+        "/workspace",
+        // Guard rails: no privilege escalation, bounded CPU/memory/processes.
+        "--security-opt",
+        "no-new-privileges",
+        "--cap-drop",
+        "ALL",
+        "--pids-limit",
+        "256",
+        "--memory",
+        "1g",
+        "--cpus",
+        "1",
+    ];
+    if (!opts.network)
+        createArgs.push("--network", "none");
+    for (const [k, v] of Object.entries(opts.env))
+        createArgs.push("-e", `${k}=${v}`);
+    createArgs.push(opts.image, ...opts.argv);
+    const created = docker(createArgs);
+    if (created.status !== 0) {
+        return { code: null, out: `container create failed: ${(created.stderr ?? "").slice(-300)}` };
+    }
+    const cid = (created.stdout ?? "").trim();
+    try {
+        // The agent's own directory becomes /workspace…
+        const copied = docker(["cp", `${opts.agentDir}/.`, `${cid}:/workspace`], 120_000);
+        if (copied.status !== 0) {
+            return { code: null, out: `copy in failed: ${(copied.stderr ?? "").slice(-300)}` };
+        }
+        // …and any shared directories land at their declared paths.
+        for (const [host, mount] of Object.entries(opts.readOnly ?? {})) {
+            if (fs.existsSync(host))
+                docker(["cp", `${host}/.`, `${cid}:${mount}`], 120_000);
+        }
+        const result = await new Promise((resolve) => {
+            const child = spawn(CLI, ["start", "-a", cid], { timeout: opts.timeoutMs });
+            let out = "";
+            const append = (chunk) => {
+                if (out.length < opts.maxOutput)
+                    out += chunk.toString();
+            };
+            child.stdout.on("data", append);
+            child.stderr.on("data", append);
+            child.on("error", (err) => resolve({ code: null, out: `container failed: ${err.message}` }));
+            child.on("close", (code) => resolve({
+                code,
+                out: out.length > opts.maxOutput
+                    ? `${out.slice(0, opts.maxOutput)}\n…[truncated]`
+                    : out || "(no output)",
+            }));
+        });
+        // Bring deliverables back so outputs/ behaves the same either way.
+        docker(["cp", `${cid}:/workspace/outputs/.`, path.join(opts.agentDir, "outputs")], 120_000);
+        return result;
+    }
+    finally {
+        docker(["rm", "-f", cid], 30_000);
+    }
+}

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

@@ -0,0 +1,81 @@
+import { createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
+import type { RunRecord } from "./store.ts";
+export interface SearchRoot {
+    /** How the agent should name the place: "knowledge/", "../../memory/". */
+    label: string;
+    /** The directory, absolute. */
+    dir: string;
+}
+/**
+ * The inverted index over a set of roots, scored BM25's way — term
+ * frequency saturating, rare terms weighing more, long documents not
+ * winning by bulk — with the frontmatter head counted three times, because
+ * a memory file's name and description are what its author thought it was
+ * about. `refresh()` walks the tree (a
+ * stat per file — cheap), re-reads only files whose size or mtime moved,
+ * drops the ones that went, and rebuilds the postings from the per-file
+ * token maps it already holds. `search()` touches only the query terms'
+ * postings.
+ */
+export declare class SearchIndex {
+    private docs;
+    private postings;
+    private avg;
+    /** How many files the last refresh read from disk — what a test watches. */
+    lastRead: number;
+    private roots;
+    constructor(roots: SearchRoot[]);
+    refresh(): this;
+    private rebuild;
+    get size(): number;
+    search(query: string, limit?: number): SearchHit[];
+}
+export interface SearchHit {
+    path: string;
+    score: number;
+    snippet: string;
+}
+export declare function searchRoots(roots: SearchRoot[], query: string, limit?: number): SearchHit[];
+export interface ContextToolResult {
+    server: ReturnType<typeof createSdkMcpServer> | null;
+    toolNames: string[];
+    promptLines: string[];
+}
+export declare function buildSearchTools(roots: SearchRoot[]): ContextToolResult;
+export interface RunDigest {
+    /** Which workspace it ran in. Absent for this workspace's own history,
+     *  where naming it every line would be noise. */
+    workspace?: string;
+    id: string;
+    flow: string;
+    status: string;
+    startedAt: string;
+    finishedAt: string | null;
+    summary: string | null;
+    costUsd: number;
+    tags: string[];
+    steps: {
+        agent: string;
+        status: string;
+        result: string | null;
+    }[];
+}
+/** The digest of a workspace's recent runs — host-side, from the records. */
+export declare function digestRuns(runs: RunRecord[], limit?: number, exceptRunId?: string): RunDigest[];
+export declare function buildHistoryTools(digest: RunDigest[]): ContextToolResult;
+/**
+ * The same two verbs across the account's OTHER workspaces.
+ *
+ * A digest agent has to read what six desks concluded this week, and it
+ * cannot: a run pod's network policy denies the platform's own API, and the
+ * account library is mounted read-only, so there is no path from inside a
+ * sandbox to another workspace's files. This is that path, built the way
+ * `history` already is — the host gathers the records, the values cross the
+ * boundary as JSON, and the container serves them. Nothing new is reachable
+ * from a run; what crosses is what the host decided to send.
+ *
+ * Read-only and summary-shaped on purpose: run records, not files. An agent
+ * that needs another desk's *file* is asking for something this platform
+ * deliberately does not have.
+ */
+export declare function buildDeskTools(digest: RunDigest[]): ContextToolResult;