@foldrun/core 0.3.0 → 0.5.0

package/dist/src/budget.js

@@ -0,0 +1,177 @@
+// A budget is a number and a period — what may be spent, and over what.
+//
+// One grammar, read in four places: an agent's `budget:` (the most that
+// agent may spend in one run), a flow's (the most one run may spend), a
+// workspace's and the account's (a cap over a window of time). The value
+// was a bare number meaning "per month" in a workspace or account file and
+// "per run" in a flow; it still is, and it can now also say which:
+//
+//     budget: 60            a number alone: per run in a flow or an agent,
+//                           per month in a workspace or the account
+//     budget: 60/day        or 60/week, 60/month
+//     budget: unlimited     no cap — the same as leaving the key out
+//
+// Unset means no limit. That is the platform's rule, not an accident of
+// parsing: a customer who has not written a cap has not asked for one, and
+// nothing here invents a default they would then have to find and raise.
+//
+// Windows follow the account's calendar (`timezone:` in AGENTS.md), the
+// same one the scheduler and "today" already use, because a daily cap that
+// resets at 10am Sydney time is not a daily cap anyone meant.
+/** Words that mean "no cap", case-insensitively. */
+const UNLIMITED = new Set(["unlimited", "none", "no limit", "no-limit", "off", "-", "~"]);
+const PERIODS = {
+    run: "run",
+    day: "day",
+    daily: "day",
+    week: "week",
+    weekly: "week",
+    month: "month",
+    monthly: "month",
+};
+// `\d+(?:\.\d+)?` with an optional separator and one period word: every
+// part has one way to match, so a hostile string cannot make it backtrack.
+const FORM_RE = /^\$?(\d+(?:\.\d+)?)(?:\s*(?:\/|per|a|each)?\s*([a-z]+))?$/;
+/**
+ * The budget a frontmatter value declares, or null for "no cap".
+ *
+ * Lenient on purpose: a value nobody can read is treated as no cap rather
+ * than as a cap of zero, because refusing every run over a typo is the worse
+ * failure. `budgetProblem` is the strict reading, for lint and the editor.
+ */
+export function parseBudget(raw, defaultPeriod) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw === "number")
+        return Number.isFinite(raw) && raw > 0 ? { usd: raw, period: defaultPeriod } : null;
+    if (typeof raw !== "string")
+        return null;
+    const s = raw.trim().toLowerCase();
+    if (!s || UNLIMITED.has(s))
+        return null;
+    const m = FORM_RE.exec(s);
+    if (!m)
+        return null;
+    const usd = Number(m[1]);
+    if (!Number.isFinite(usd) || usd <= 0)
+        return null;
+    const period = m[2] ? PERIODS[m[2]] : defaultPeriod;
+    if (!period)
+        return null;
+    return { usd, period };
+}
+/**
+ * What is wrong with a `budget:` value, in a sentence, or null when it is
+ * fine. `allowed` names the periods this file may use — an agent's or a
+ * flow's budget is per run and nothing else; a workspace's or the account's
+ * is over time and never per run.
+ */
+export function budgetProblem(raw, allowed) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw === "number") {
+        if (!Number.isFinite(raw) || raw < 0)
+            return `budget: ${String(raw)} is not an amount in USD`;
+        return null;
+    }
+    if (typeof raw !== "string")
+        return `budget: must be a number, "<number>/<day|week|month>", or unlimited`;
+    const s = raw.trim().toLowerCase();
+    if (!s || UNLIMITED.has(s))
+        return null;
+    const m = FORM_RE.exec(s);
+    if (!m)
+        return `budget: "${raw}" is not a number, "<number>/<day|week|month>", or unlimited`;
+    if (m[2]) {
+        const period = PERIODS[m[2]];
+        if (!period)
+            return `budget: "${m[2]}" is not a period — day, week or month`;
+        if (!allowed.includes(period)) {
+            return period === "run"
+                ? `budget: is per run here already — write the number alone`
+                : `budget: "${period}" does not apply here — this cap is per run; a cap over time belongs in the workspace's or the account's AGENTS.md`;
+        }
+    }
+    return null;
+}
+/** "$60/day", "$500/month", "$6/run". */
+export function formatBudget(b) {
+    const usd = Number.isInteger(b.usd) ? String(b.usd) : b.usd.toFixed(2);
+    return `$${usd}/${b.period}`;
+}
+/** "today", "this week", "this month" — the window a spend is measured in. */
+export function windowName(period) {
+    return period === "day" ? "today" : period === "week" ? "this week" : period === "month" ? "this month" : "this run";
+}
+/** What to wait for when the cap is reached. */
+export function windowTurnsHint(period) {
+    return period === "day" ? "wait for tomorrow" : period === "week" ? "wait for next week" : "wait for the new month";
+}
+// ------------------------------------------------------------ the window
+function partsIn(timeZone, at) {
+    const f = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hourCycle: "h23",
+        year: "numeric",
+        month: "numeric",
+        day: "numeric",
+        hour: "numeric",
+        minute: "numeric",
+        second: "numeric",
+        weekday: "short",
+    });
+    const p = {};
+    for (const { type, value } of f.formatToParts(at))
+        p[type] = value;
+    const weekdays = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+    return {
+        y: Number(p.year),
+        m: Number(p.month),
+        d: Number(p.day),
+        h: Number(p.hour),
+        min: Number(p.minute),
+        s: Number(p.second),
+        weekday: weekdays.indexOf(p.weekday),
+    };
+}
+/** The zone's offset from UTC at an instant, in ms (positive east). */
+function offsetMs(timeZone, atMs) {
+    const p = partsIn(timeZone, new Date(atMs));
+    return Date.UTC(p.y, p.m - 1, p.d, p.h, p.min, p.s) - Math.floor(atMs / 1000) * 1000;
+}
+/** Midnight at the start of a local calendar date, as a UTC instant. */
+function localMidnightMs(timeZone, y, m, d) {
+    const naive = Date.UTC(y, m - 1, d);
+    let t = naive - offsetMs(timeZone, naive);
+    // Once more from the answer: across a DST change the first guess can be
+    // off by the shift, and the second pass lands on the real midnight.
+    const again = naive - offsetMs(timeZone, t);
+    if (again !== t)
+        t = again;
+    return t;
+}
+/**
+ * When the current window began, as a UTC instant — the moment spend is
+ * summed from. Today's midnight, Monday's midnight, or the first of the
+ * month, all in the given calendar. A per-run budget has no window.
+ */
+export function windowStartMs(period, timeZone, now = new Date()) {
+    if (period === "run")
+        return null;
+    let tz = timeZone;
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: tz });
+    }
+    catch {
+        tz = "UTC";
+    }
+    const p = partsIn(tz, now);
+    if (period === "day")
+        return localMidnightMs(tz, p.y, p.m, p.d);
+    if (period === "month")
+        return localMidnightMs(tz, p.y, p.m, 1);
+    // Monday. Walk back on the naive calendar, then take that date's midnight.
+    const back = (p.weekday + 6) % 7;
+    const monday = new Date(Date.UTC(p.y, p.m - 1, p.d - back));
+    return localMidnightMs(tz, monday.getUTCFullYear(), monday.getUTCMonth() + 1, monday.getUTCDate());
+}

package/dist/src/catalog.js

@@ -21,6 +21,8 @@ import fs from "node:fs";
 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;
@@ -83,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(`${baseUrl.replace(/\/+$/, "")}/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;