toolroll 0.9.69 → 0.9.70

package/dist/flow-actions.d.ts

@@ -75,4 +75,5 @@ export declare function toolWaiting(store: Store, stage: FlowStage, repo: string
 export declare function useTool(store: Store, stage: FlowStage, card: FlowCardRow, repo: string, io: {
     callTool?: ToolCaller;
     toolHome?: string;
+    fenceAvailable?: () => boolean;
 }): Promise<ActionOutcome>;

package/dist/flow-actions.js

@@ -25,7 +25,7 @@ import { googleAccessToken, googleConnected } from "./google-mail.js";
 import { ADDRESS, readEmailSettings } from "./email-settings.js";
 import { readFlowSecrets, scrubSecrets } from "./flow-secrets.js";
 export { readEmailSettings, saveEmailSettings } from "./email-settings.js";
-import { callProjectTool, projectToolsOf, readToolSecrets } from "./project-tools.js";
+import { callProjectTool, projectToolsOf, readToolSecrets, toolServerFor } from "./project-tools.js";
 import { ALL_CREDENTIAL_ENV } from "./provider.js";
 const clip = (text, cap) => text.length <= cap ? text : `${text.slice(0, cap - 1)}…`;
 const blank = (text) => redactSecretAssignments(redactSecretLines(text, scanForSecrets(text)));
@@ -189,7 +189,8 @@ export async function useTool(store, stage, card, repo, io) {
     const text = { title: card.title, description: card.description, note: card.note, outputs: card.outputs };
     const args = fillJson(JSON.parse(call.args), one => fillFlowText(one, text));
     const values = readToolSecrets(repo, tool.name, io.toolHome);
-    const answer = await (io.callTool ?? ((spec, secrets, name, given) => callProjectTool(spec, secrets, name, given, { timeoutMs: 120_000, omitEnv: ALL_CREDENTIAL_ENV })))(tool.spec, values, call.name, args);
+    const answer = await (io.callTool ?? ((spec, secrets, name, given) => callProjectTool(spec, secrets, name, given, { timeoutMs: 120_000, omitEnv: ALL_CREDENTIAL_ENV,
+        server: toolServerFor(store, repo, { ...(io.toolHome === undefined ? {} : { home: io.toolHome }), ...(io.fenceAvailable === undefined ? {} : { available: io.fenceAvailable }) }) })))(tool.spec, values, call.name, args);
     if (!answer.ok)
         return { state: "retry", said: `${call.server}: ${answer.problem}` };
     const said = blank(scrub(clip(answer.text, 64_000), values));

package/dist/flow-code.d.ts

@@ -1,5 +1,6 @@
 import type { Runner } from "./backend.js";
-import type { FlowScriptRow } from "./store.js";
+import { type FencePolicy, type LaunchFence } from "./agent-fence.js";
+import type { FlowScriptRow, Store } from "./store.js";
 import { projectFile } from "./project-file.js";
 export { projectFile };
 export { LANGUAGE_WORDS, SCRIPT_LANGUAGES, type ScriptLanguage } from "./flows.js";
@@ -17,7 +18,9 @@ export type CodeRun = {
     secrets: Record<string, string>;
     scratch: string;
     shell: Runner;
-    fence: readonly string[];
+    /** Where it runs from (flowLaunch): its fence, and the launch folder its input and an inline script are written to;
+     * null only where there is nothing to fence (a store with no database file). */
+    launch: FlowLaunch | null;
 };
 /** `printed`: everything it printed (secrets blanked), for a trigger to read items from; `output` is what a card keeps. */
 export type CodeResult = {
@@ -49,3 +52,29 @@ export declare function cardsFromOutput(stdout: string): {
     title: string;
     description: string | null;
 }[];
+/**
+ * Where one flow launch runs (docs/plans/sandbox-parity.md C1): the fence `fenceFor` makes for a flow's setup, script
+ * or trigger, around `folder` (a copy of the card's work, bound to its project, or a clean folder), with a launch folder
+ * of its own for its input, an inline script and its temp files; writes as the project's writes setting allows (its
+ * folder, the copy's Git data, its project's caches); the scratch pool denied around its own folder; and its network
+ * open, as flows' scripts have always had it (they reach the services their secrets are for; no approval seals a
+ * network for them). The fence is required: where this machine can't confine it, it runs only when an instance operator
+ * allowed unconfined agents, and otherwise nothing runs and the card says why.
+ */
+export type FlowLaunch = {
+    folder: string;
+    env: Record<string, string>;
+    fence?: LaunchFence;
+    dispose(): void;
+};
+export declare function flowLaunch(store: Store, options: {
+    repo: string;
+    folder: string;
+    scratch: string;
+    copy: boolean;
+    available?: () => boolean;
+    policy?: FencePolicy;
+    home?: string;
+}): FlowLaunch | null | {
+    problem: string;
+};

package/dist/flow-code.js

@@ -15,9 +15,13 @@
  *   keys are out of reach), under a time limit, with the setup's plain
  *   environment rather than this process's.
  */
-import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
 import { randomBytes } from "node:crypto";
-import { join } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { buildCacheEnv, buildCacheFolder, checkLaunchRoot, fenceFor, linuxFenceAvailable, macosFenceAvailable, runFolders, taskBoundary, trustedWorktreeBinding, writeAllowlist } from "./agent-fence.js";
+import { readDenyPath } from "./project-sandbox.js";
+import { poolRootOf } from "./worktree.js";
 import { SETUP_ENV_ALLOWLIST, SETUP_ENV_DENYLIST } from "./builder.js";
 import { redactSecretLines, scanForSecrets } from "./evidence.js";
 import { scrubSecrets } from "./flow-secrets.js";
@@ -51,7 +55,10 @@ export async function runCode(run) {
     const language = script.language;
     const tag = randomBytes(6).toString("hex");
     mkdirSync(run.scratch, { recursive: true });
-    const inputFile = join(run.scratch, `flow-input-${tag}.json`);
+    // The input and an inline script live in the launch's own folder, the one place beside its working folder its fence
+    // gives back (every other launch folder, and every other flow copy in the scratch pool, stay out of reach).
+    const files = run.launch?.folder ?? run.scratch;
+    const inputFile = join(files, `flow-input-${tag}.json`);
     let scriptFile = null;
     try {
         writeFileSync(inputFile, JSON.stringify(run.input), { mode: 0o600 });
@@ -61,7 +68,7 @@ export async function runCode(run) {
                 return { state: "failed", exitCode: null, output: "", printed: "", goTo: null, log: "", said: `${script.name} runs ${script.file}, which isn't a file in the project.` };
         }
         else {
-            const own = join(run.scratch, `flow-script-${tag}.${EXTENSION[language]}`);
+            const own = join(files, `flow-script-${tag}.${EXTENSION[language]}`);
             writeFileSync(own, `${script.body}\n`, { mode: 0o700 });
             chmodSync(own, 0o700);
             scriptFile = own;
@@ -71,7 +78,7 @@ export async function runCode(run) {
         // first without breaking anything. Only our own paths are in the command; the card is only data.
         const ran = await run.shell("/bin/sh", ["-c", 'exec "$@" < "$FLOW_INPUT"', "flow-script", runtime.file, ...runtime.args], {
             cwd: run.cwd, timeoutMs: script.timeoutMinutes * 60_000, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST, processGroup: true,
-            env: { ...run.env, ...run.secrets, FLOW_INPUT: inputFile }, fence: run.fence,
+            env: { ...run.env, ...run.secrets, ...(run.launch?.env ?? {}), FLOW_INPUT: inputFile }, ...(run.launch?.fence ?? {}),
         });
         const printed = codeOutput(ran.stdout, run.secrets);
         const all = scrubSecrets(ran.stdout.slice(0, 1_000_000), run.secrets);
@@ -148,3 +155,48 @@ export function cardsFromOutput(stdout) {
         return asItem(trimmed);
     }).filter((one) => one !== null);
 }
+export function flowLaunch(store, options) {
+    const databaseFile = store.databaseFile();
+    if (databaseFile === null || databaseFile === "" || databaseFile === ":memory:")
+        return null;
+    const available = options.available ?? (() => macosFenceAvailable() || linuxFenceAvailable());
+    const fenced = available();
+    // Asked first: a launch with no fence of its own (an instance operator allowed it, as inside another sandbox) makes
+    // its folder in the temp folder it was given, never among the fenced launches' (which an outer sandbox may hold).
+    if (!fenced && !store.unfencedAgentsAllowed()) {
+        return { problem: "This machine can't confine the flow's script (no macOS sandbox, no working bubblewrap), so it didn't run. Install bubblewrap, socat and ripgrep (Linux), or an instance operator allows unconfined agents with `toolroll config unconfined-agents allow`." };
+    }
+    let own;
+    try {
+        own = realpathSync(mkdtempSync(join(fenced ? checkLaunchRoot() : tmpdir(), "so-cmd-")));
+    }
+    catch (error) {
+        return { problem: `The flow's launch folder couldn't be made, so nothing ran: ${error instanceof Error ? error.message : String(error)}` };
+    }
+    const dispose = () => rmSync(own, { recursive: true, force: true });
+    const temp = join(own, "tmp");
+    mkdirSync(temp, { mode: 0o700 });
+    const env = { TMPDIR: temp, TMP: temp, TEMP: temp };
+    if (!fenced)
+        return { folder: own, env, dispose };
+    try {
+        const poolRoots = [join(dirname(databaseFile), "worktrees"), options.scratch, ...store.listWorktrees().map(record => poolRootOf(record.path, record.repo))];
+        // Its scratch folder is a pool root (so another flow's copy is out of reach) and sealed: never read, at any policy.
+        // A copy is held to its project by the plane's own record of the repository, never what the copy says.
+        const binding = options.copy ? trustedWorktreeBinding(options.repo, options.folder, poolRoots) : null;
+        // The policy its flow sealed; nothing sealed is v1 (the home configuration denied), never a wider one implicitly.
+        const home = options.home ?? homedir();
+        const boundary = taskBoundary({ worktree: options.folder, provider: "command", home, binding, policy: options.policy ?? 1 });
+        const cache = buildCacheFolder(options.repo, home);
+        const allowed = store.projectWrites(options.repo) !== "workspace" ? null : writeAllowlist({ provider: "command", home, worktree: options.folder, binding, launchFolder: own, cache });
+        // The project's read denies apply to flows as to builds (read live: a flow seals no list, and these only narrow).
+        const readDeny = store.projectSandbox(options.repo).readDeny.map(one => readDenyPath(one, home));
+        const fence = fenceFor("flow", { databaseFile, worktree: options.folder, home, boundary, readDeny, policy: options.policy ?? 1, scratchRoots: [options.scratch], binding, runFolders: runFolders(own), poolRoots, extra: allowed?.deny ?? [],
+            writes: allowed === null ? null : { writes: allowed.writes, readOnly: allowed.readOnly }, network: { mode: "open" } });
+        return { folder: own, env: { ...env, ...(allowed === null ? {} : buildCacheEnv(cache)) }, fence, dispose };
+    }
+    catch {
+        dispose();
+        return { problem: "The flow's copy couldn't be bound to its project, so nothing ran." };
+    }
+}

package/dist/flow-steps.d.ts

@@ -14,6 +14,10 @@ export type StepIo = {
     dir: string | null;
     /** Where temporary copies of a card's work are made. */
     scratch: string;
+    /** Whether this machine can confine a script (tests only; default: the macOS sandbox or bubblewrap is here). */
+    fenceAvailable?: () => boolean;
+    /** The home folder a launch is fenced around (tests only; default: this user's). */
+    home?: string;
     evidenceRoot?: string;
     /** The branch a card with no result yet is checked against. */
     base: string;

package/dist/flow-steps.js

@@ -35,8 +35,7 @@ import { JEV_MODEL, askJev, readJevAnswers, sortLog, sortRequest, sortState, sor
 import { claudeDraftRunner, DRAFT_CHARS, DRAFT_TIMEOUT, draftPrompt, wholeDraft } from "./flow-draft.js";
 import { overruns, passOn, TEXT_LIMITS, writeWithin } from "./text-limits.js";
 import { readFlowSecrets, sendingReady, runRequest, sendEmail, toolWaiting, useTool } from "./flow-actions.js";
-import { cleanFolder, runCode } from "./flow-code.js";
-import { agentFence } from "./agent-fence.js";
+import { cleanFolder, flowLaunch, runCode } from "./flow-code.js";
 import { readProviderKey } from "./keys.js";
 import { replyInChannel } from "./chat-inbox.js";
 import { recordSent, threadOf } from "./flow-replies.js";
@@ -362,13 +361,16 @@ async function runCheck(store, flow, stage, script, card, now, io) {
         if (added.code !== 0)
             return { state: "retry", said: `Couldn't make a copy of${where}: ${added.stderr.trim().split("\n")[0]?.slice(0, 160) ?? "git refused"}.` };
     }
+    const launch = flowLaunch(store, { repo: flow.repo, folder: path, scratch: io.scratch, copy, policy: store.flowFencePolicy(flow.id), ...(io.fenceAvailable === undefined ? {} : { available: io.fenceAvailable }), ...(io.home === undefined ? {} : { home: io.home }) });
     try {
-        const fence = agentFence({ databaseFile: store.databaseFile(), worktree: path });
+        if (launch !== null && "problem" in launch)
+            return { state: "failed", said: launch.problem };
         let log = "";
         const setup = copy ? store.liveWorktreeSetup(flow.repo) : null;
         if (setup !== null) {
             const shell = approvedCommandShell(setup.command);
-            const prepared = await io.shell(shell.file, shell.args, { cwd: path, timeoutMs: setup.timeoutMs, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST, processGroup: true, fence });
+            const prepared = await io.shell(shell.file, shell.args, { cwd: path, timeoutMs: setup.timeoutMs, envAllowlist: SETUP_ENV_ALLOWLIST, omitEnv: SETUP_ENV_DENYLIST, processGroup: true,
+                ...(launch === null ? {} : { env: launch.env, ...(launch.fence ?? {}) }) });
             log += `$ ${setup.command}\n${prepared.stdout}${prepared.stderr}\n`;
             if (prepared.code !== 0)
                 return { state: "failed", said: `The project's setup failed before ${script.name} ran (exit ${prepared.code}).\n${tail(`${prepared.stdout}\n${prepared.stderr}`)}`, log, exitCode: prepared.code };
@@ -383,7 +385,7 @@ async function runCheck(store, flow, stage, script, card, now, io) {
             answers: (stage.routes ?? []).map(one => one.answer),
         };
         const env = { FLOW_NAME: flow.name, FLOW_CARD_ID: String(card.id), FLOW_CARD_TITLE: card.title, FLOW_COMMIT: commit ?? "", FLOW_SCRIPT: script.name, FLOW_PROJECT: flow.repo };
-        const ran = await runCode({ script, cwd: path, root: copy ? path : flow.repo, input, env, secrets, scratch: io.scratch, shell: io.shell, fence });
+        const ran = await runCode({ script, cwd: path, root: copy ? path : flow.repo, input, env, secrets, scratch: io.scratch, shell: io.shell, launch });
         log += ran.log;
         const output = ran.output === "" ? undefined : ran.output;
         // Where it ran goes at the end of the first line: "run-tests failed (exit 1) on main."
@@ -398,6 +400,8 @@ async function runCheck(store, flow, stage, script, card, now, io) {
         return { state: "passed", said: `${script.name} ran${where} and picked ${route.answer}.`, log, exitCode: 0, to: route.to, ...(output === undefined ? {} : { output }) };
     }
     finally {
+        if (launch !== null && !("problem" in launch))
+            launch.dispose();
         if (copy)
             await io.git("git", ["-C", flow.repo, "worktree", "remove", "--force", path], { timeoutMs: 60_000 }).catch(() => undefined);
         rmSync(path, { recursive: true, force: true });

package/dist/flow-triggers.d.ts

@@ -141,6 +141,10 @@ export type TriggerIo = {
     /** v90: how a schedule's script runs (default: the same runner as gh) and where (default: beside the database). */
     shell?: Runner;
     scratch?: string;
+    /** Whether this machine can confine a script (tests only; default: the macOS sandbox or bubblewrap is here). */
+    fenceAvailable?: () => boolean;
+    /** The home folder a launch is fenced around (tests only; default: this user's). */
+    home?: string;
 };
 export type TriggerPass = {
     added: number;

package/dist/flow-triggers.js

@@ -859,21 +859,26 @@ async function fireScript(store, trigger, config, now, io, scheduled) {
     if (missing.length > 0)
         return done(false, `${script.name} needs the secret${missing.length === 1 ? "" : "s"} ${missing.join(", ")}. Save ${missing.length === 1 ? "it" : "them"} on the flow first.`);
     // Loaded when a script first runs: the runner reaches the builder's modules, which reach back to these triggers.
-    const { cardsFromOutput, cleanFolder, runCode } = await import("./flow-code.js");
-    const { agentFence } = await import("./agent-fence.js");
+    const { cardsFromOutput, cleanFolder, flowLaunch, runCode } = await import("./flow-code.js");
     const scratch = io.scratch ?? join(io.dir ?? tmpdir(), "flow-scratch");
     const folder = cleanFolder(scratch, `flow-trigger-${trigger.id}`);
     // Its cards run on their own only if it ran the very code a grant signed: pinned just before and just after the run.
     const pin = scheduled && grantSignsScriptOf(store, flow.id, trigger.id, now) ? () => scriptProvenanceOf(store, flow.repo, script.name) : null;
     const before = pin === null ? null : await pin();
     let ran;
+    // A full boundary around its clean folder, though it has no checkout (flow-code.ts flowLaunch).
+    const launch = flowLaunch(store, { repo: flow.repo, folder, scratch, copy: false, policy: store.flowFencePolicy(flow.id), ...(io.fenceAvailable === undefined ? {} : { available: io.fenceAvailable }), ...(io.home === undefined ? {} : { home: io.home }) });
     try {
+        if (launch !== null && "problem" in launch)
+            return done(false, launch.problem);
         ran = await runCode({ script, cwd: folder, root: flow.repo, scratch, shell: io.shell ?? io.gh,
             input: { flow: { id: flow.id, name: flow.name }, trigger: trigger.id, lastRun: trigger.lastAt }, secrets: Object.fromEntries((config.secrets ?? []).map(name => [name, saved[name]])),
             env: { FLOW_NAME: flow.name, FLOW_TRIGGER_ID: String(trigger.id), FLOW_PROJECT: flow.repo, FLOW_LAST_RUN: trigger.lastAt ?? "" },
-            fence: agentFence({ databaseFile: store.databaseFile(), worktree: folder }) });
+            launch });
     }
     finally {
+        if (launch !== null && !("problem" in launch))
+            launch.dispose();
         rmSync(folder, { recursive: true, force: true });
     }
     if (ran.state === "failed")

package/dist/invoke.d.ts

@@ -23,7 +23,7 @@ import type { RunOptions } from "./exec.js";
 import type { Runner } from "./worktree.js";
 import { type NetworkFence, type SignInGrants } from "./agent-fence.js";
 import { type CheckAccess } from "./check-access.js";
-import { type WritesMode } from "./agent-fence.js";
+import { type WritesMode, type LaunchSandbox, type FenceGrants } from "./agent-fence.js";
 import { type NetworkProfile } from "./egress.js";
 export type { ProviderRunner } from "./provider.js";
 export type ProviderUsage = {
@@ -111,6 +111,7 @@ export declare function invokeAgent(store: Store, runId: number, spec: AgentSpec
     accumulateUsage?: boolean;
     network?: LaunchNetwork;
     writes?: WritesMode;
+    sandbox?: LaunchSandbox;
 }): Promise<InvokeResult>;
 /**
  * A build's setup and check commands, run in its fence (arc 2): the same denies as its agent's (Toolroll's state,
@@ -119,20 +120,20 @@ export declare function invokeAgent(store: Store, runId: number, spec: AgentSpec
  * Their network stays as it was. A machine without an OS fence runs them as before; a fence that can't be prepared
  * (a checkout whose binding no longer proves) runs nothing.
  */
-export declare function fencedCommands(store: Store, runId: number, writes: WritesMode, inner: Runner, available?: () => boolean, access?: CheckAccess, network?: NetworkProfile): Runner;
+export declare function fencedCommands(store: Store, runId: number, writes: WritesMode, inner: Runner, available?: () => boolean, access?: CheckAccess, network?: NetworkProfile, sandbox?: LaunchSandbox): Runner;
 /**
  * A project's checks run in a checkout of a result's commit made for them (result-follow-ups.ts, batch-checks.ts), in
  * the same fence as a build's commands: Toolroll's state, credentials, other projects and runs denied; under the
  * project's writes setting, only that checkout, its Git data, its own temp folder, the project's caches and its check
  * database writable. Where nothing can confine them, they run only when an instance operator allowed unconfined agents.
  */
-export declare function fencedCheckoutCommands(store: Store, repo: string, checkout: string, inner: Runner, available?: () => boolean, access?: CheckAccess, network?: NetworkProfile): Runner;
+export declare function fencedCheckoutCommands(store: Store, repo: string, checkout: string, inner: Runner, available?: () => boolean, access?: CheckAccess, network?: NetworkProfile, sandbox?: LaunchSandbox): Runner;
 /**
- * A `sign-ins` check's launch (check-access.ts): its exact sign-in files and its own transcript folder
- * (agent-fence.ts signInGrants), Codex's config and sign-in copied into a home of the launch's own (private, gone with
- * the launch; ~/.codex itself stays fenced), gh pointed at its own folder, and the network the check runs under:
- * open, or its allowlist through a proxy of its own (on Linux, carried in by a bridge). Nothing about it is started
- * unless all of it is.
+ * A `sign-ins` check's launch (check-access.ts, sandbox parity C10): its exact sign-in files, read by the check itself
+ * through its sandbox (agent-fence.ts signInGrants: nothing privileged reads or copies one), its own transcript folder
+ * and Codex's session and log folders; Codex, gh and XDG pointed at the real folders; and the network the check runs
+ * under: open, or its allowlist through a proxy of its own (on Linux, relayed in by the sandbox runtime). Nothing about it is
+ * started unless all of it is.
  */
 export declare function signInsLaunch(store: Store, own: string, temp: string, checkout: string, policy: NetworkProfile, gitPaths: readonly string[], platform?: NodeJS.Platform): Promise<{
     grants: SignInGrants;
@@ -162,3 +163,12 @@ export declare const ranAtLine: (level: CheckAccess) => string | null;
 /** A saved result's check command runner (batch-checks.ts, result-follow-ups.ts): its level and network worked out right
  * now (checkoutLaunchOf), and how it actually runs told to `ran`. */
 export declare function checkoutRunner(store: Store, repo: string, checkout: string, inner: Runner, runIds: readonly number[], ran: (level: CheckAccess) => void, platform?: NodeJS.Platform): Runner;
+/**
+ * A saved result's checks' sandbox terms (sandbox parity C9), never wider than any of those results' own approvals nor
+ * the project now: v2 only when every result's approval sealed v2; every read deny any of them sealed or the project
+ * lists now; mach services only those all of them sealed and the project still lists. A result with
+ * no readable approval counts as v1 with nothing listed.
+ */
+export declare function checkoutSandboxOf(store: Store, repo: string, runIds: readonly number[]): LaunchSandbox;
+/** The digest of a launch's whole fence (its denied paths and grants, canonical), as stamped on its run (C11). */
+export declare function fenceDigest(fence: readonly string[], grants: FenceGrants): string;