@foldrun/core 0.4.0 → 0.5.0

package/src/browser-pod.ts

@@ -0,0 +1,313 @@
+// 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",
+] as const;
+
+/** 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"]);
+
+export type CallKind = { write: false } | { write: true; what: string };
+
+export interface ClassifyContext {
+  /** SDK tool name → HTTP method, for an API's typed operations (api-tools
+   *  builds the map; a generic call_<api> carries its method in the input). */
+  methods?: Record<string, string>;
+  /** Web actions a paid provider answers this step — from the env's
+   *  FOLDRUN_WEB_<ACTION>_VIA. */
+  paidWeb?: Record<string, string>;
+}
+
+/** The browse actions a call asked for, nested `if` branches included. */
+export function browseActionNames(actions: unknown): string[] {
+  let steps: unknown = actions;
+  if (typeof steps === "string") {
+    try { steps = JSON.parse(steps); } catch { return ["(unreadable actions)"]; }
+  }
+  const out: string[] = [];
+  const walk = (v: unknown, depth: number) => {
+    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 as Record<string, unknown>)) {
+      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: Record<string, unknown>): string | null {
+  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 as readonly string[]).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: string, input: Record<string, unknown> | undefined, ctx: ClassifyContext = {}): CallKind {
+  const args = input ?? {};
+  const write = (what: string): CallKind => ({ 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: Record<string, string | undefined>): Record<string, string> {
+  const out: Record<string, string> = {};
+  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;
+}
+
+/** One line of the web tool's pod log. */
+export interface PodEvent {
+  kind: "reconnect" | "lost" | "needs-full";
+  /** reconnect: which try, of how many, and whether it got through. */
+  attempt?: number;
+  of?: number;
+  ok?: boolean;
+  /** lost: whether the call ran on the pod at all before it was lost — a
+   *  call that never connected changed nothing, whatever it asked for. */
+  ran?: boolean;
+  error?: string;
+  why?: string;
+  /** When the web tool wrote the line (ISO). */
+  at?: string;
+}
+
+/** ", at 10:15:15Z" from a pod log line's `at`; empty when it has none. */
+export function podAt(at: unknown): string {
+  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: string, offset: number): { events: PodEvent[]; next: number } {
+  const chunk = text.slice(offset);
+  const end = chunk.lastIndexOf("\n");
+  if (end < 0) return { events: [], next: offset };
+  const events: PodEvent[] = [];
+  for (const line of chunk.slice(0, end).split("\n")) {
+    try {
+      const e = JSON.parse(line) as PodEvent;
+      if (e && (e.kind === "reconnect" || e.kind === "lost" || e.kind === "needs-full")) events.push(e);
+    } catch {
+      // not ours
+    }
+  }
+  return { events, next: offset + end + 1 };
+}
+
+/** What crosses back from a step that browsed through the pod. */
+export interface BrowserPodOutcome {
+  /** Reconnect tries the web tool made, and how many got through: the pod
+   *  answered and the call went on, rather than dropping again at once. */
+  reconnects: number;
+  reconnected: number;
+  /** Reconnects that reached the pod, after which the call dropped again at
+   *  once — a pod still answering while it shut down. Never "got through". */
+  closedAgain?: number;
+  /** Set when the step stopped because the pod was gone (or a call needed
+   *  a browser in the step, which slim does not have). */
+  lost?: { cause: "lost" | "needs-full"; detail: string };
+  /** What the step had written by then, worded — empty means reads only. */
+  writes?: string[];
+}
+
+/** "a.md (Write), crm POST and 2 more". */
+export function describeWrites(writes: string[]): string {
+  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: BrowserPodOutcome): { rerun: true; note: string } | { rerun: false; message: string } {
+  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: Record<string, string | undefined>): string | null {
+  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: unknown): BrowserPodOutcome | null {
+  if (!v || typeof v !== "object") return null;
+  const o = v as Record<string, unknown>;
+  const n = (x: unknown) => (typeof x === "number" && Number.isFinite(x) && x >= 0 ? Math.floor(x) : 0);
+  const out: BrowserPodOutcome = { reconnects: n(o.reconnects), reconnected: n(o.reconnected) };
+  if (n(o.closedAgain)) out.closedAgain = n(o.closedAgain);
+  const lost = o.lost as Record<string, unknown> | undefined;
+  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: BrowserPodOutcome & { fallback?: string; failure?: string }): string {
+  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;
+}
+
+/** What podTriesLine reads of a StepAttempt (store.ts) — structural, so
+ *  this module stays free of the store's imports for the CLI and the web. */
+export interface TryRow {
+  n: number;
+  status: string;
+  image?: string;
+  costUsd: number | null;
+}
+
+/** 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: readonly TryRow[] | null | undefined): string | null {
+  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/src/catalog.ts

@@ -24,6 +24,7 @@ import { dataRoot } from "./paths.ts";
 import { resolveModel, resolveTier, MODEL_TIERS, EFFORT_LEVELS, type Effort, type Tier, type FlowInfo } from "./store.ts";
 import type { FlowWarning } from "./flow-lint.ts";
 import { trimSlashes } from "./paths.ts";
+import { fetchUntrusted } from "./untrusted-fetch.ts";
 
 export interface CatalogModel {
   id: string;
@@ -116,7 +117,7 @@ export async function loadCatalog(baseUrl: string): Promise<Catalog | null> {
   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) throw new Error(`${res.status}`);

package/src/clock.ts

@@ -0,0 +1,149 @@
+// 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.
+
+/** 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;
+}
+
+/** `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: unknown): Zone | null {
+  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: number) => 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: unknown): boolean {
+  return normalizeZone(raw) !== null;
+}
+
+/** The lint's sentence for a `timezone:` nobody can read. */
+export function timezoneProblem(raw: unknown): string | null {
+  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)`
+  );
+}
+
+/** 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 function resolveClock(levels: ZoneLevel[], env = process.env.FOLDRUN_TIMEZONE): ClockChoice {
+  const problems: string[] = [];
+  const bad: string[] = [];
+  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: string, now = new Date()): string {
+  return new Intl.DateTimeFormat("en-CA", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  }).format(now);
+}

package/src/completions.ts

@@ -68,11 +68,14 @@ const EFFORTS: Completion[] = [
 // survive vendor renames — then the exact SDK names, accepted so a Claude Code
 // subagent runs here unchanged.
 const TOOL_GROUPS: Completion[] = [
+  // `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: Completion[] = [
@@ -82,8 +85,6 @@ const SDK_TOOL_NAMES: Completion[] = [
   { 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: Completion[] = ["GET", "POST", "PUT", "PATCH", "DELETE"].map((m) => ({ label: m }));
@@ -134,14 +135,17 @@ const FIELDS: Record<string, Completion[]> = {
     { 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}",
@@ -201,6 +205,8 @@ const FIELDS: Record<string, Completion[]> = {
     { 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" },
   ],
@@ -544,7 +550,7 @@ export function completionsAt(
       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];
@@ -569,6 +575,9 @@ export function completionsAt(
       ],
       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}: ` })),