@foldrun/core 0.4.0 → 0.5.0

package/dist/src/browser-pod.js

@@ -0,0 +1,284 @@
+// Slim browsing: a step whose only reason for the full runner image is that
+// it browses may run on the slim image and drive the account's browser pod
+// over Playwright's protocol. The pod can go away mid-step — a node drained,
+// the idle reaper, an OOM — and a slim step has no browser of its own to fall
+// back on. So:
+//
+//   1. The web tool reconnects first: a few tries, short backoff (the tool's
+//      run.mjs; each try is an event in FOLDRUN_BROWSER_POD_EVENTS).
+//   2. Still gone: the step stops, and what it has done so far decides.
+//      Only reads — re-run the whole step from the start on the full image,
+//      and say so on the run ("browser pod lost; re-ran on full").
+//   3. Anything written — fail the step: "browser pod died after the step had
+//      written <what>". Doing it again could send, post or charge twice, so
+//      retry:, on-fail: or a person decides.
+//
+// Read or write is decided from the calls the step made, as the model asked
+// for them (step-exec.ts keeps the ledger). When a call could be either it
+// counts as a write: the cost of being wrong that way is a failed step a
+// retry can redo; the other way it is a duplicate email.
+//
+// Steps that act outward (a tool marked `outward: true`) never run slim; nor
+// does anything the step start can already see needs a browser in the step
+// (lightpanda, obscura, live sessions, extensions) — slimBrowseBlocker.
+/** Set by the platform on a step it put on the slim image to browse
+ *  through the pod. The web tool then never launches a browser of its own. */
+export const POD_ONLY_ENV = "FOLDRUN_BROWSER_POD_ONLY";
+/** Where the web tool appends one JSON line per reconnect, and the line
+ *  that says the pod is lost or the call needs the full image. */
+export const POD_EVENTS_ENV = "FOLDRUN_BROWSER_POD_EVENTS";
+/** The file, inside the step's sandbox. */
+export const POD_EVENTS_FILE = "/tmp/foldrun-browser-pod.jsonl";
+/** The note the run carries when the fallback was taken. Worded once. */
+export const RERAN_ON_FULL = "browser pod lost; re-ran on full";
+/**
+ * Browse actions that can change something beyond the page in front of the
+ * model: anything that types, picks, submits, signs in, uploads, runs script
+ * or pays. A click is here because a click can submit and nothing before
+ * the click can tell. The web tool's run.mjs carries a copy (it decides
+ * whether a dropped call may be repeated); the gallery test holds the two
+ * equal.
+ */
+export const BROWSE_WRITE_ACTIONS = [
+    "click", "dblclick", "rightclick", "tap", "swipe", "mouse", "drag",
+    "fill", "type", "insert", "paste", "press", "keyboard", "keydown", "keyup", "clear",
+    "select", "check", "uncheck", "upload", "dialog", "login", "eval", "webmcp", "solve",
+];
+/** Call arguments of web action=browse that are writes whatever the actions:
+ *  page script, a paid captcha solver, a confirmation of a credential step. */
+const BROWSE_WRITE_ARGS = ["js", "captcha", "captcha_solver", "confirm"];
+/** Web actions that only read — when foldrun's own answers them. A paid
+ *  provider answering one (FOLDRUN_WEB_<ACTION>_VIA) makes it a write: doing
+ *  it twice is paying twice. `monitor` keeps state, so it always writes. */
+const WEB_READ_ACTIONS = new Set(["search", "fetch", "browse", "crawl", "map", "extract", "answer"]);
+/** Built-ins that read and change nothing. */
+const READ_BUILTINS = new Set(["Read", "Glob", "Grep", "WebSearch", "WebFetch", "TodoWrite", "LS", "NotebookRead"]);
+/** The platform's own tool groups that only read. Consults are a toolless
+ *  answer; a delegation's own calls come through on their own. */
+const READ_SERVERS = new Set(["foldrun_search", "foldrun_history", "foldrun_desks", "foldrun_agents"]);
+const DELEGATE = new Set(["Agent", "Task"]);
+/** The browse actions a call asked for, nested `if` branches included. */
+export function browseActionNames(actions) {
+    let steps = actions;
+    if (typeof steps === "string") {
+        try {
+            steps = JSON.parse(steps);
+        }
+        catch {
+            return ["(unreadable actions)"];
+        }
+    }
+    const out = [];
+    const walk = (v, depth) => {
+        if (depth > 8 || v === null || typeof v !== "object")
+            return;
+        if (Array.isArray(v)) {
+            for (const x of v)
+                walk(x, depth + 1);
+            return;
+        }
+        for (const [k, x] of Object.entries(v)) {
+            out.push(k);
+            walk(x, depth + 1);
+        }
+    };
+    walk(steps, 0);
+    return out;
+}
+/** What a browse call's arguments would write, or null when it only reads. */
+export function browseWrites(input) {
+    const names = browseActionNames(input.actions);
+    if (names.includes("(unreadable actions)"))
+        return "browse actions it could not read";
+    const writes = [...new Set(names.filter((n) => BROWSE_WRITE_ACTIONS.includes(n)))];
+    if (writes.length)
+        return `browse ${writes.join("/")}`;
+    const arg = BROWSE_WRITE_ARGS.find((a) => input[a] !== undefined && input[a] !== null && input[a] !== "" && input[a] !== false);
+    if (arg)
+        return `browse ${arg}=`;
+    return null;
+}
+/**
+ * Whether one tool call can have changed anything outside the model's head,
+ * and if so, a few words saying what. Pure.
+ */
+export function classifyCall(tool, input, ctx = {}) {
+    const args = input ?? {};
+    const write = (what) => ({ write: true, what });
+    if (READ_BUILTINS.has(tool) || DELEGATE.has(tool))
+        return { write: false };
+    if (tool === "Write" || tool === "Edit" || tool === "MultiEdit" || tool === "NotebookEdit") {
+        const raw = String(args.file_path ?? args.notebook_path ?? args.path ?? "");
+        const file = raw.startsWith("/workspace/") ? raw.slice("/workspace/".length) : raw.split("/").slice(-3).join("/");
+        return write(file ? `${file} (${tool})` : `a file (${tool})`);
+    }
+    if (tool === "Bash")
+        return write("a shell command");
+    const mcp = /^mcp__(.+?)__(.+)$/.exec(tool);
+    if (!mcp)
+        return write(tool); // unknown: a write until shown otherwise
+    const [, server, name] = mcp;
+    if (READ_SERVERS.has(server))
+        return { write: false };
+    if (server === "foldrun_ask")
+        return write("a question to a person");
+    if (server === "foldrun_scripts") {
+        if (name !== "web")
+            return write(`script ${name}`);
+        const action = String(args.action ?? "").trim().toLowerCase();
+        if (!WEB_READ_ACTIONS.has(action))
+            return write(action === "monitor" ? "web monitor state" : `web ${action || "call"}`);
+        const paid = ctx.paidWeb?.[action];
+        if (paid)
+            return write(`a paid ${paid} ${action}`);
+        if (action === "browse") {
+            const w = browseWrites(args);
+            if (w)
+                return write(w);
+        }
+        return { write: false };
+    }
+    if (server === "foldrun_apis") {
+        const method = String(name.startsWith("call_") ? (args.method ?? "GET") : (ctx.methods?.[tool] ?? "")).toUpperCase();
+        const api = name.replace(/^call_/, "");
+        if (method === "GET" || method === "HEAD")
+            return { write: false };
+        return write(`${api} ${method || "call"}`);
+    }
+    // Any other MCP server: its tools could do anything.
+    return write(`${server} ${name}`);
+}
+/** Paid web actions, from a step's env (FOLDRUN_WEB_<ACTION>_VIA=provider). */
+export function paidWebActions(env) {
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        const m = /^FOLDRUN_WEB_([A-Z]+)_VIA$/.exec(k);
+        if (m && v)
+            out[m[1].toLowerCase()] = v;
+    }
+    if (env.FOLDRUN_BROWSER_VENDOR)
+        out.browse = env.FOLDRUN_BROWSER_VENDOR;
+    return out;
+}
+/** ", at 10:15:15Z" from a pod log line's `at`; empty when it has none. */
+export function podAt(at) {
+    if (typeof at !== "string")
+        return "";
+    const t = Date.parse(at);
+    return Number.isNaN(t) ? "" : `, at ${new Date(t).toISOString().slice(11, 19)}Z`;
+}
+/** Lines of the pod log from byte `offset` on, and where the next read
+ *  starts. A torn last line waits for the next read. */
+export function readPodEvents(text, offset) {
+    const chunk = text.slice(offset);
+    const end = chunk.lastIndexOf("\n");
+    if (end < 0)
+        return { events: [], next: offset };
+    const events = [];
+    for (const line of chunk.slice(0, end).split("\n")) {
+        try {
+            const e = JSON.parse(line);
+            if (e && (e.kind === "reconnect" || e.kind === "lost" || e.kind === "needs-full"))
+                events.push(e);
+        }
+        catch {
+            // not ours
+        }
+    }
+    return { events, next: offset + end + 1 };
+}
+/** "a.md (Write), crm POST and 2 more". */
+export function describeWrites(writes) {
+    const uniq = [...new Set(writes)];
+    if (uniq.length > 3)
+        return `${uniq.slice(0, 3).join(", ")} and ${uniq.length - 3} more`;
+    if (uniq.length <= 1)
+        return uniq[0] ?? "something";
+    return `${uniq.slice(0, -1).join(", ")} and ${uniq.at(-1)}`;
+}
+/** The decision, once the pod is gone: re-run on full, or fail and say why. */
+export function podLossDecision(pod) {
+    const writes = pod.writes ?? [];
+    const cause = pod.lost?.cause === "needs-full" ? `a call needed a browser in the step (${pod.lost.detail})` : `browser pod lost (${pod.lost?.detail ?? "connection closed"})`;
+    if (!writes.length)
+        return { rerun: true, note: `${RERAN_ON_FULL} — ${cause}; the step had only read, so it ran again from the start on the full image` };
+    const head = pod.lost?.cause === "needs-full"
+        ? `a call needed a browser in the step after the step had written ${describeWrites(writes)}`
+        : `browser pod died after the step had written ${describeWrites(writes)}`;
+    return { rerun: false, message: `${head} — not re-run, since doing it again could repeat that; retry:, on-fail: or a person decides (${pod.lost?.detail ?? "connection closed"})` };
+}
+/**
+ * Why a browsing step must have a browser in its own sandbox, from what the
+ * step start can see (the agent's `web.browse` block, as env), or null when
+ * the account's pod can serve every call it could make by default. A call
+ * that picks an in-step engine itself is caught at the call (needs-full).
+ */
+export function slimBrowseBlocker(env) {
+    if (env.FOLDRUN_BROWSER_VENDOR)
+        return `web.browse names ${env.FOLDRUN_BROWSER_VENDOR}`;
+    if (env.FOLDRUN_BROWSER_LIVE === "1")
+        return "web.browse live: sessions run in the step";
+    const engine = (env.FOLDRUN_BROWSER_ENGINE ?? "").trim().toLowerCase();
+    if (engine === "lightpanda" || engine === "obscura")
+        return `engine ${engine} runs in the step`;
+    if (env.FOLDRUN_BROWSER_EXTENSIONS)
+        return "extensions load into a browser in the step";
+    return null;
+}
+/** The outcome as it crosses back from the sandbox, checked field by field
+ *  (the done line is the pod's word); null when absent or not this shape. */
+export function parseBrowserPod(v) {
+    if (!v || typeof v !== "object")
+        return null;
+    const o = v;
+    const n = (x) => (typeof x === "number" && Number.isFinite(x) && x >= 0 ? Math.floor(x) : 0);
+    const out = { reconnects: n(o.reconnects), reconnected: n(o.reconnected) };
+    if (n(o.closedAgain))
+        out.closedAgain = n(o.closedAgain);
+    const lost = o.lost;
+    if (lost && typeof lost === "object" && (lost.cause === "lost" || lost.cause === "needs-full")) {
+        out.lost = { cause: lost.cause, detail: String(lost.detail ?? "").slice(0, 300) };
+        out.writes = Array.isArray(o.writes) ? o.writes.slice(0, 50).map((w) => String(w).slice(0, 120)) : [];
+    }
+    return out;
+}
+/** One line for a person: "2 reconnects (2 got through)", "browser pod
+ *  lost; re-ran on full", or the failure. What the run page, `foldrun
+ *  report` and an attempt row say. A pod that was lost in the end is never
+ *  said to have let a reconnect through — "1 reconnect (1 got through); pod
+ *  lost" read live as a contradiction — and a reconnect that reached the pod
+ *  only for the call to drop again says that. */
+export function browserPodLine(p) {
+    const count = `${p.reconnects} reconnect${p.reconnects === 1 ? "" : "s"}`;
+    const tries = !p.reconnects
+        ? "no reconnects"
+        : !p.lost
+            ? `${count} (${p.reconnected} got through)`
+            : p.closedAgain
+                ? `${count}, ${p.reconnects === 1 ? "which" : "the last"} reached the pod but it closed again`
+                : count;
+    if (p.failure)
+        return `${tries}; ${p.failure}`;
+    if (p.fallback)
+        return `${tries}; ${p.fallback}${p.lost ? ` (${p.lost.detail})` : ""}`;
+    if (p.lost)
+        return `${tries}; ${p.lost.cause === "needs-full" ? "needed a browser in the step" : "pod lost"}: ${p.lost.detail}`;
+    return tries;
+}
+/** A step's tries in one line when the browser pod was lost under one of
+ *  them — "slim · lost · $0.0040 → full · completed · $0.0060" — so the run
+ *  page and `foldrun report` show the slim go and the full re-run apart.
+ *  `#n` leads each try when the step had more than one attempt. Null when
+ *  no try was lost. */
+export function podTriesLine(tries) {
+    if (!tries?.some((t) => t.status === "lost"))
+        return null;
+    const many = new Set(tries.map((t) => t.n)).size > 1;
+    return tries
+        .map((t) => [
+        `${many ? `#${t.n} ` : ""}${t.image ?? "?"}`,
+        t.status,
+        typeof t.costUsd === "number" ? `$${t.costUsd.toFixed(4)}` : null,
+    ].filter(Boolean).join(" · "))
+        .join(" → ");
+}

package/dist/src/catalog.js

@@ -22,6 +22,7 @@ import path from "node:path";
 import { dataRoot } from "./paths.js";
 import { resolveModel, resolveTier, MODEL_TIERS, EFFORT_LEVELS } from "./store.js";
 import { trimSlashes } from "./paths.js";
+import { fetchUntrusted } from "./untrusted-fetch.js";
 /** A day. Model lists move weekly, not hourly, and a stale price in an
  *  autocomplete hint is a smaller failure than a fetch on every keystroke. */
 const TTL_MS = 24 * 60 * 60 * 1000;
@@ -84,7 +85,7 @@ export async function loadCatalog(baseUrl) {
     if (cached && Date.now() - Date.parse(cached.fetchedAt) < TTL_MS)
         return cached;
     try {
-        const res = await fetch(`${trimSlashes(baseUrl)}/v1/models`, {
+        const res = await fetchUntrusted(`${trimSlashes(baseUrl)}/v1/models`, {
             signal: AbortSignal.timeout(10_000),
         });
         if (!res.ok)

package/dist/src/clock.d.ts

@@ -0,0 +1,49 @@
+/** A zone the runtime can actually use: the name Intl understands, and the
+ *  value to put in `TZ` for the shell and Node inside the sandbox. They are
+ *  the same for an IANA name and differ for a fixed offset. */
+export interface Zone {
+    /** What `Intl.DateTimeFormat({ timeZone })` is given. */
+    name: string;
+    /** What `TZ` is set to. */
+    tz: string;
+}
+/**
+ * Read a written timezone into something usable, or null if nothing can be.
+ *
+ * Two shapes are accepted, because both are what people type: an IANA name
+ * (`Australia/Sydney`) and a plain fixed offset (`UTC+10`, `+10:00`,
+ * `-05:30`, `GMT+5`, or `UTC` on its own).
+ */
+export declare function normalizeZone(raw: unknown): Zone | null;
+/** Is this a value `timezone:` may carry? Used by the lint, so `foldrun
+ *  check` refuses `Sydney/Australia` and `UTC+99` before a run does. */
+export declare function isTimezone(raw: unknown): boolean;
+/** The lint's sentence for a `timezone:` nobody can read. */
+export declare function timezoneProblem(raw: unknown): string | null;
+/** One level of the cascade: where the value was written, and what it said. */
+export interface ZoneLevel {
+    /** The word the trace uses: "agent", "flow", "workspace", "account". */
+    level: string;
+    value: unknown;
+}
+export interface ClockChoice {
+    /** The zone, ready for Intl. */
+    timezone: string;
+    /** The value for `TZ`. */
+    tz: string;
+    /** Which level set it — or "FOLDRUN_TIMEZONE", or "default". */
+    source: string;
+    /** One sentence per unusable value found on the way down. Reported as a
+     *  step event; never thrown, because a mistyped zone must not stop work. */
+    problems: string[];
+}
+/**
+ * Walk the levels, nearest first, and take the first zone that works.
+ *
+ * `FOLDRUN_TIMEZONE` is appended by the caller's level list or read here as
+ * the last written level; UTC is what remains when nothing said anything —
+ * the clock the pods actually run on.
+ */
+export declare function resolveClock(levels: ZoneLevel[], env?: string | undefined): ClockChoice;
+/** YYYY-MM-DD in a timezone — the date the step believes it is. */
+export declare function localDate(timeZone: string, now?: Date): string;

package/dist/src/clock.js

@@ -0,0 +1,121 @@
+// The clock an agent works to.
+//
+// A step used to run on whatever the pod's clock said, which is UTC, while
+// the flow that fired it was scheduled in Australia/Sydney. A run at 08:00
+// Sydney on the 16th wrote files stamped the 15th and the next step, looking
+// for today's files, found none. The schedule and the work disagreed about
+// what day it was.
+//
+// So the calendar is resolvable at every level, nearest wins:
+//
+//   agent frontmatter → flow frontmatter → workspace AGENTS.md →
+//   account AGENTS.md → FOLDRUN_TIMEZONE → UTC
+//
+// Leaving `timezone:` out inherits the next level up; setting it anywhere
+// wins for that level and everything under it. A value nothing can read
+// never fails a step — it falls through to the next level and says so once.
+/** `UTC+10`, `GMT-3:30`, `+10:00`, `-0530`, or a bare `UTC`/`GMT`. */
+const OFFSET_RE = /^(?:UTC|GMT)?\s*(?:([+-])\s*(\d{1,2})(?::?(\d{2}))?)?$/i;
+/**
+ * Read a written timezone into something usable, or null if nothing can be.
+ *
+ * Two shapes are accepted, because both are what people type: an IANA name
+ * (`Australia/Sydney`) and a plain fixed offset (`UTC+10`, `+10:00`,
+ * `-05:30`, `GMT+5`, or `UTC` on its own).
+ */
+export function normalizeZone(raw) {
+    const text = typeof raw === "string" ? raw.trim() : "";
+    if (!text)
+        return null;
+    const offset = text.match(OFFSET_RE);
+    if (offset) {
+        const [, sign, hh, mm] = offset;
+        // A bare UTC/GMT, or the empty match — no offset at all.
+        if (!sign)
+            return { name: "UTC", tz: "UTC" };
+        const hours = Number(hh);
+        const minutes = Number(mm ?? "0");
+        // The real range of civil offsets. `UTC+99` is a typo, not a zone.
+        if (hours > 14 || minutes > 59)
+            return null;
+        if (hours === 14 && minutes > 0)
+            return null;
+        const total = hours * 60 + minutes;
+        if (total === 0)
+            return { name: "UTC", tz: "UTC" };
+        const pad = (n) => String(n).padStart(2, "0");
+        const name = `${sign}${pad(hours)}:${pad(minutes)}`; // Intl reads this form
+        if (minutes === 0) {
+            // Etc/GMT zones have their sign INVERTED — POSIX counts degrees west of
+            // Greenwich as positive, so Etc/GMT-10 is ten hours AHEAD of UTC. It is
+            // worth the confusion: `Etc/GMT-10` is understood by ICU (so Node in
+            // the sandbox honours it) and by the shell's date, which the offset
+            // form `+10:00` is not.
+            return { name, tz: `Etc/GMT${sign === "+" ? "-" : "+"}${hours}` };
+        }
+        // No Etc zone exists for a half-hour offset, so `TZ` gets the POSIX
+        // spec — which the shell reads, and whose sign is inverted for the same
+        // reason. FOLDRUN_DATE is computed from `name` either way, so the date
+        // an agent is told is right whatever TZ a program makes of it.
+        const posix = `${sign === "+" ? "-" : "+"}${pad(hours)}:${pad(minutes)}`;
+        return { name, tz: `<${sign}${pad(hours)}${pad(minutes)}>${posix}` };
+    }
+    // Not an offset: an IANA name, if the platform knows it.
+    try {
+        new Intl.DateTimeFormat("en-CA", { timeZone: text });
+        return { name: text, tz: text };
+    }
+    catch {
+        return null;
+    }
+}
+/** Is this a value `timezone:` may carry? Used by the lint, so `foldrun
+ *  check` refuses `Sydney/Australia` and `UTC+99` before a run does. */
+export function isTimezone(raw) {
+    return normalizeZone(raw) !== null;
+}
+/** The lint's sentence for a `timezone:` nobody can read. */
+export function timezoneProblem(raw) {
+    if (raw === undefined || raw === null || raw === "")
+        return null;
+    if (isTimezone(raw))
+        return null;
+    return (`timezone: ${String(raw)} — not a zone; use an IANA name (Australia/Sydney) ` +
+        `or a fixed offset (UTC+10, +10:00, -05:30)`);
+}
+/**
+ * Walk the levels, nearest first, and take the first zone that works.
+ *
+ * `FOLDRUN_TIMEZONE` is appended by the caller's level list or read here as
+ * the last written level; UTC is what remains when nothing said anything —
+ * the clock the pods actually run on.
+ */
+export function resolveClock(levels, env = process.env.FOLDRUN_TIMEZONE) {
+    const problems = [];
+    const bad = [];
+    const all = [...levels, { level: "FOLDRUN_TIMEZONE", value: env }];
+    for (const { level, value } of all) {
+        const written = typeof value === "string" ? value.trim() : "";
+        if (!written)
+            continue;
+        const zone = normalizeZone(written);
+        if (zone) {
+            for (const b of bad)
+                problems.push(`${b} — using ${zone.name} (${level}) instead`);
+            return { timezone: zone.name, tz: zone.tz, source: level, problems };
+        }
+        bad.push(`timezone: "${written}" (${level}) is not a zone this runtime knows`);
+    }
+    for (const b of bad)
+        problems.push(`${b} — using UTC instead`);
+    return { timezone: "UTC", tz: "UTC", source: "default", problems };
+}
+/** YYYY-MM-DD in a timezone — the date the step believes it is. */
+export function localDate(timeZone, now = new Date()) {
+    return new Intl.DateTimeFormat("en-CA", {
+        timeZone,
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+    }).format(now);
+}

package/dist/src/completions.js

@@ -28,11 +28,14 @@ const EFFORTS = [
 // survive vendor renames — then the exact SDK names, accepted so a Claude Code
 // subagent runs here unchanged.
 const TOOL_GROUPS = [
+    // `files`, `bash` and `fetch` are retired (tool-names.ts) and not offered.
+    // `web` is our gallery tool, offered here because it is the one way onto
+    // the web.
     { label: "read", hint: "Read, Glob, Grep — may look, never write" },
-    { label: "files", hint: "Read, Write, Edit, Glob, Grep" },
-    { label: "web", hint: "WebSearch (Anthropic's servers, billed per search), WebFetch" },
-    { label: "fetch", hint: "WebFetch only — local; pair with the websearch tool" },
-    { label: "bash", hint: "Bash — arbitrary commands" },
+    { label: "write", hint: "Read, Write, Edit, Glob, Grep" },
+    { label: "code", hint: "Bash — runs anything in the sandbox" },
+    { label: "web", hint: "search, fetch, browse, crawl, map, extract, answer, monitor — providers under web:" },
+    { label: "ask", hint: "ask_person — ask the person running the desk mid-step, and wait for the answer" },
 ];
 const SDK_TOOL_NAMES = [
     { label: "Read", hint: "exact SDK name" },
@@ -41,8 +44,6 @@ const SDK_TOOL_NAMES = [
     { label: "Glob", hint: "exact SDK name" },
     { label: "Grep", hint: "exact SDK name" },
     { label: "Bash", hint: "exact SDK name" },
-    { label: "WebSearch", hint: "exact SDK name" },
-    { label: "WebFetch", hint: "exact SDK name" },
 ];
 const METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"].map((m) => ({ label: m }));
 const TRIGGERS = [
@@ -85,14 +86,17 @@ const FIELDS = {
         { label: "description", insert: "description: ", hint: "required — what it does, and when" },
         { label: "model", insert: "model: default" },
         { label: "effort", insert: "effort: high", hint: "how hard it thinks" },
-        { label: "tools", insert: "tools:\n  - files", hint: "what the runtime gives it" },
+        { label: "tools", insert: "tools:\n  - write", hint: "what the runtime gives it" },
         { label: "secrets", insert: "secrets:\n  - ", hint: "credentials it may spend" },
         { label: "skills", insert: "skills:\n  - ", hint: "allowlist; omit to inherit all" },
         { label: "scripts", insert: "scripts:\n  - name: \n    run: \n    description: " },
         { label: "runtime", insert: "runtime:\n  python: \"3\"\n  packages: []" },
         { label: "mcpServers", insert: "mcpServers:\n  " },
+        { label: "ask", insert: "ask:\n  timeout: 30m", hint: "tools: [ask] — how long ask_person waits for a person (max 24h)" },
         { label: "permissionMode", insert: "permissionMode: plan", hint: "plan = read-only" },
         { label: "disallowedTools", insert: "disallowedTools:\n  - " },
+        { label: "subagents", insert: "subagents:\n  - ", hint: "colleagues it may delegate a job to — own context, own tools, no wider than its own" },
+        { label: "limits", insert: "limits:\n  web.search: 40\n  calls: 300", hint: "per step: a call past a limit is refused, never run" },
         {
             label: "provider",
             insert: "provider:\n  name: \n  token: ${PROVIDER_TOKEN}",
@@ -151,6 +155,8 @@ const FIELDS = {
         { label: "trigger", insert: "trigger: manual" },
         { label: "schedule", insert: "schedule: \"0 6 * * MON\"" },
         { label: "timezone", insert: "timezone: Australia/Sydney" },
+        { label: "language", insert: "language: en-AU" },
+        { label: "region", insert: "region: au", hint: "currency, units, calendar, weekend and text direction follow" },
         { label: "model", insert: "model: fast", hint: "every step, unless the step says" },
         { label: "effort", insert: "effort: high", hint: "every step, unless the step says" },
     ],
@@ -475,7 +481,7 @@ export function completionsAt(path, text, cursor, vocab) {
             each: [
                 { label: "lines", hint: "one instance per line of the previous result" },
                 { label: "items", hint: "one per element of the previous output: json array" },
-                { label: "rows of ../../storage/x.csv", hint: "one per CSV row" },
+                { label: "rows of workspace/storage/x.csv", hint: "one per CSV row" },
             ],
         };
         const items = byKey[key];
@@ -500,6 +506,9 @@ export function completionsAt(path, text, cursor, vocab) {
             ],
             secrets: vocab.secrets.map((s) => ({ label: s, hint: "secret" })),
             skills: vocab.skills.map((s) => ({ label: s, hint: "skill" })),
+            // Colleagues: a consult (agents:) or a delegate (subagents:).
+            agents: vocab.agents.map((a) => ({ label: a, hint: "consult — answers, no tools" })),
+            subagents: vocab.agents.map((a) => ({ label: a, hint: "delegate — own context and tools" })),
             disallowedTools: [...TOOL_GROUPS, { label: "Bash" }, { label: "Write" }],
             when: [{ label: "schema" }, { label: "urgent" }],
             expect: ASSERTIONS.map((a) => ({ ...a, insert: `${a.label}: ` })),

package/dist/src/confine.d.ts

@@ -22,6 +22,16 @@ export declare const isFilesystemTool: (toolName: string) => boolean;
  * enforced; it is advice in the error text.
  */
 export declare function suggestPath(raw: string): string;
+/**
+ * A path an author wrote in a flow or an agent wrote in a tool call, as an
+ * absolute path: `workspace/…` from the workspace root, anything else from
+ * the agent's own folder (so the older `../../storage/x` lands in the same
+ * place as `workspace/storage/x`). Confinement is the caller's: this only
+ * says where the path points.
+ */
+export declare function resolveAgentPath(workspaceRoot: string, agentDir: string, raw: string): string;
+/** True when `abs` is `root` or under it. */
+export declare function isWithin(root: string, abs: string): boolean;
 /** Expand a virtual prefix to a real absolute path, or null if it has none. */
 export declare function expandVirtual(raw: string, roots: Roots): {
     abs: string;
@@ -29,3 +39,15 @@ export declare function expandVirtual(raw: string, roots: Roots): {
 } | null;
 export declare function checkPaths(toolName: string, input: Record<string, unknown>, roots: Roots): ConfineVerdict;
 export declare function checkBash(command: string): ConfineVerdict;
+export declare function linkWorkspace(agentDir: string, workspaceRoot: string): {
+    release: () => void;
+    note: string | null;
+};
+/**
+ * `env` plus what makes `node workspace/…` its own main module (above):
+ * the link's path(s) in FOLDRUN_WORKSPACE_LINK, the preload appended to
+ * NODE_OPTIONS — after what it held, or the host's when it held nothing.
+ * Idempotent, and harmless where no link exists: the preload matches only
+ * a path under it.
+ */
+export declare function workspaceLinkEnv<T extends Record<string, string | undefined>>(env: T, agentDir: string): T;