@foldrun/core 0.5.0 → 0.7.0

package/dist/src/run-container.d.ts

@@ -201,6 +201,11 @@ export declare function applyContainerChanges(hostWs: string, containerWs: strin
  * that fills it.
  */
 export declare const RUNTIME_CACHE = "/home/agent/.foldrun/runner/.runtimes";
+/** Starts the install helper as root, in the background, before the drop to
+ *  the agent user: the root half of the `install` tool (install-helper.ts).
+ *  The agent reaches it only through the socket; it installs only validated
+ *  Debian package names, and dies with the container. */
+export declare const INSTALL_HELPER_SH = "FOLDRUN_INSTALL_SOCKET=/opt/runner/job/install.sock; export FOLDRUN_INSTALL_SOCKET\nnode /opt/runner/node_modules/@foldrun/core/dist/src/install-helper.js \"$FOLDRUN_INSTALL_SOCKET\" /home/agent/.foldrun/runner/.runtimes >/dev/null 2>&1 &";
 /**
  * Where the platform's shared runtime layer is mounted, read-only, in a run
  * pod — and read-write, one entry at a time, in the pod that builds an entry
@@ -271,7 +276,7 @@ export declare const RETRY_SH = "retry() { what=$1; shift; n=1; until \"$@\"; do
  *  The digest names the multi-arch index, so the one pin serves amd64 and
  *  arm64 alike. */
 export declare const NODE_BASE = "node:22-trixie-slim@sha256:b26b04c123d9ff8ab646ceb18b9d75a1173acf64b9a401094b906d27b29338d4";
-export declare const DOCKERFILE = "FROM node:22-trixie-slim@sha256:b26b04c123d9ff8ab646ceb18b9d75a1173acf64b9a401094b906d27b29338d4 AS base\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends python3 python3-venv ca-certificates bash util-linux tar openssh-client sshpass git curl \\\n && rm -rf /var/lib/apt/lists/* \\\n && useradd -m -u 10001 agent\n# uv builds the declared python environments (runtime.ts): a fraction of\n# pip's time, and it can fetch a pinned python the image does not carry.\nCOPY --from=ghcr.io/astral-sh/uv:0.11.25 /uv /uvx /usr/local/bin/\nENV PLAYWRIGHT_BROWSERS_PATH=/opt/browser NODE_PATH=/usr/local/lib/node_modules\n\nFROM base AS slim\n# Fonts, because a step that draws text without a browser still needs them:\n# the full image gets 51 from Playwright's --with-deps, slim had none, so from\n# 2026-09-29 (when non-browsing steps moved to slim) every resvg/sharp diagram\n# rendered its labels as empty boxes \u2014 expert-witness-desk's validator failed\n# four passes on a post image that was \"three empty boxes\". DejaVu covers\n# Latin, Greek and Cyrillic in a few MB; fontconfig is how renderers find it.\n# DejaVu alone still drew emoji, Chinese, Japanese, Korean, Devanagari and\n# Thai as empty boxes (reproduced 2026-10-01 with resvg-js 2.6 and sharp\n# 0.34), so four more, the smallest set that drew all of them \u2014 8 MB:\n#   Symbola     emoji and symbols, as outlines. NOT Noto Color Emoji (10 MB):\n#               resvg draws nothing from its bitmap glyphs, so a resvg\n#               diagram kept its empty boxes.\n#   WenQuanYi Micro Hei   Chinese, Japanese kana and Korean Hangul, one file.\n#   Lohit Devanagari, Loma   Hindi and Thai.\n# Here, not in base, so the full image's browser layers stay cached.\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends fonts-dejavu-core fontconfig fonts-symbola fonts-wqy-microhei fonts-lohit-deva fonts-tlwg-loma-otf \\\n && rm -rf /var/lib/apt/lists/* \\\n && fc-cache -f >/dev/null\n# The Playwright client only, the same pinned version as the browser pod's\n# server (the wire protocol is version-locked), so a tool that imports it\n# still loads; there is nothing here for it to launch.\n# npm's download cache is dropped in the same layer: it was 190 MB of every\n# image, read by nothing after the build.\nRUN npm install -g playwright@1.63.0 axe-core@4.13.0 >/dev/null && npm cache clean --force >/dev/null 2>&1\nWORKDIR /opt/runner\nCOPY foldrun-core.tgz driver.mjs entry.sh ./\nRUN npm init -y >/dev/null && npm install ./foldrun-core.tgz --omit=dev \\\n && npm cache clean --force >/dev/null 2>&1 \\\n && mkdir -p /workspace /library /opt/runner/job /home/agent/.foldrun/runner/.runtimes /opt/foldrun-runtimes/shared/.runtimes \\\n && chown -R agent:agent /workspace /library /opt/runner /home/agent/.foldrun /opt/foldrun-runtimes \\\n && chmod +x /opt/runner/entry.sh\nENTRYPOINT [\"/opt/runner/entry.sh\"]\n\nFROM base AS browsers\n# Real browsers, because directories and portals increasingly render with\n# JavaScript and a plain fetch sees only the empty shell. Chromium is the one the\n# browser tool drives by default; Firefox and WebKit (Safari's engine) are\n# there for an agent asked to see a page the way those render it. Installed\n# to a fixed path the agent user can read (the default cache would be\n# root's HOME). The browsers' own sandboxes are disabled at launch time \u2014 in\n# this platform the container/gVisor IS the sandbox, and the two fight.\n# Pinned exactly, not @1: web browse's numbered elements use ariaSnapshot's\n# \"ai\" mode (1.59+), and the per-account browser pod runs this same image, so\n# a floating version would move both under a working tool on any rebuild.\n# Raise it on purpose, with the gallery tests and one real call.\n# axe-core beside it is web browse's mode=a11y: one file the tool injects\n# into the page; without it the mode falls back to its own shorter checks.\n# Xvfb by name: the browser pod starts it at boot and web browse starts one\n# per call for headless: false. It used to arrive only as one of Playwright's\n# --with-deps packages, so a Playwright bump that dropped it would have\n# broken every windowed browser without a word. No xauth: nothing here runs\n# xvfb-run, and Xvfb started without -auth takes the local client as it is.\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends xvfb \\\n && rm -rf /var/lib/apt/lists/*\n# Google Chrome and Chrome beta come from Google's apt repository, which\n# Playwright adds; each is tried ENGINE_DOWNLOAD_ATTEMPTS times. Only on\n# x86_64: Google ships no Linux Chrome for arm64, so there it is not tried.\nRUN npm install -g playwright@1.63.0 axe-core@4.13.0 >/dev/null \\\n && playwright install --with-deps chromium firefox webkit >/dev/null \\\n && retry() { what=$1; shift; n=1; until \"$@\"; do if [ \"$n\" -ge 3 ]; then echo \"runner image: $what - download failed $n times, giving up\" >&2; return 1; fi; echo \"runner image: $what - download failed (attempt $n of 3), retrying in $((n * 15))s\" >&2; sleep $((n * 15)); n=$((n + 1)); done; } \\\n && if [ \"$(uname -m)\" = x86_64 ]; then \\\n      retry chrome playwright install --with-deps chrome >/dev/null || echo \"runner image: chrome not installed - engine: chrome would fall back to chromium\" >&2; \\\n      retry chrome-beta playwright install --with-deps chrome-beta >/dev/null || echo \"runner image: chrome-beta not installed\" >&2; \\\n    else echo \"runner image: no Google Chrome for $(uname -m) - engine: chrome falls back to chromium\"; fi \\\n && chmod -R a+rX /opt/browser \\\n && npm cache clean --force >/dev/null 2>&1\n# Lightpanda (engine: lightpanda): a browser that runs the JavaScript and\n# never draws \u2014 a fraction of Chromium's memory for reading and filling\n# pages. Its own program, which web browse starts beside a call and drives\n# over the DevTools protocol; shipped unmodified (AGPL-3.0). Pinned by\n# checksum (GitHub's own asset digests, checked again here). 0.4.1 since the\n# move to Debian 13: 0.3.7 on wants glibc 2.38, and Debian 12's 2.36 held it\n# at 0.3.6. An arch without a build leaves the engine out, and the tool says\n# so when asked for it. Each download (with its checksum) is tried\n# ENGINE_DOWNLOAD_ATTEMPTS times before the engine is left out.\n# Raise it on purpose: the new release's two sha256s, then one\n# engine=lightpanda call on each arch.\nRUN arch=$(uname -m) \\\n && case \"$arch\" in \\\n      x86_64) sum=1d40801e72c0bc61b2cbd3f3562bcfc46de7b79e0568f33f686b64f2e587610a ;; \\\n      aarch64) sum=664775c7f5ab69cc3189954c7f9345e25c167cb4dace016173e629f9a5e82c42 ;; \\\n      *) sum= ;; \\\n    esac \\\n && mkdir -p /opt/browser/lightpanda \\\n && retry() { what=$1; shift; n=1; until \"$@\"; do if [ \"$n\" -ge 3 ]; then echo \"runner image: $what - download failed $n times, giving up\" >&2; return 1; fi; echo \"runner image: $what - download failed (attempt $n of 3), retrying in $((n * 15))s\" >&2; sleep $((n * 15)); n=$((n + 1)); done; } \\\n && fetch() { curl -fsSL -o /opt/browser/lightpanda/lightpanda \"https://github.com/lightpanda-io/browser/releases/download/0.4.1/lightpanda-$arch-linux\" \\\n      && echo \"$sum  /opt/browser/lightpanda/lightpanda\" | sha256sum -c - >/dev/null; } \\\n && if [ -n \"$sum\" ] && retry lightpanda fetch; then \\\n      chmod a+rx /opt/browser/lightpanda/lightpanda && /opt/browser/lightpanda/lightpanda version; \\\n    else rm -f /opt/browser/lightpanda/lightpanda; echo \"runner image: lightpanda not installed for $arch - engine: lightpanda says so when asked\" >&2; fi\n# Obscura (engine: obscura): a headless browser in Rust around V8 that does\n# draw \u2014 screenshots, a raster PDF, a screencast \u2014 light like Lightpanda.\n# Apache-2.0. The plain build, not -stealth: this platform does not help a\n# page not see automation. Two binaries, obscura and obscura-worker, which\n# must sit side by side. Pinned by checksum; glibc 2.35 is its floor, so\n# Debian 13 (2.41) runs it. As above, a download is tried\n# ENGINE_DOWNLOAD_ATTEMPTS times, then a failed one leaves the engine out.\nRUN arch=$(uname -m) \\\n && case \"$arch\" in \\\n      x86_64) sum=1534d1e6ddaf3d080ec4091eb41d0a4d8cc042a48b607d3c410fc13b482a9eec ;; \\\n      aarch64) sum=5ecf980bca3060236a7a86ec7ed83d943e6598ee87caa46d20325d90bc75f979 ;; \\\n      *) sum= ;; \\\n    esac \\\n && mkdir -p /opt/browser/obscura \\\n && retry() { what=$1; shift; n=1; until \"$@\"; do if [ \"$n\" -ge 3 ]; then echo \"runner image: $what - download failed $n times, giving up\" >&2; return 1; fi; echo \"runner image: $what - download failed (attempt $n of 3), retrying in $((n * 15))s\" >&2; sleep $((n * 15)); n=$((n + 1)); done; } \\\n && fetch() { curl -fsSL -o /tmp/obscura.tgz \"https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.3/obscura-$arch-linux.tar.gz\" \\\n      && echo \"$sum  /tmp/obscura.tgz\" | sha256sum -c - >/dev/null; } \\\n && if [ -n \"$sum\" ] && retry obscura fetch \\\n      && tar -xzf /tmp/obscura.tgz -C /opt/browser/obscura obscura obscura-worker; then \\\n      chmod a+rx /opt/browser/obscura/obscura /opt/browser/obscura/obscura-worker && /opt/browser/obscura/obscura --version; \\\n    else rm -rf /opt/browser/obscura/*; echo \"runner image: obscura not installed for $arch - engine: obscura says so when asked\" >&2; fi \\\n && rm -f /tmp/obscura.tgz\n# What this image actually has, written down: /opt/browser/engines.json, one\n# entry per engine (its path and version, or null when the install above\n# left it out) plus Xvfb. Chromium's version is its own --version (dotted,\n# so FOLDRUN_RUNNER_ENGINES carries it: a pinned user_agent on engine\n# chromium is compared with it, not with Google Chrome's) then the build.\n# web browse reads it for its \"built without\" answer, and the deploy reads\n# it to report the engines beside the version.\n# On x86_64 a missing engine FAILS the build: every engine ships for that\n# arch, so a gap there is a failed download, and an image that quietly lacks\n# the Chrome or Lightpanda a desk names would fail those runs instead. A\n# failed build leaves the previous image running and says why. Elsewhere\n# (arm64 has no Google Chrome) the gap is recorded and the image ships.\nRUN node -e ' \\\n  const fs = require(\"fs\"), cp = require(\"child_process\"), pw = require(\"playwright\"); \\\n  const at = (p) => (p && fs.existsSync(p) ? p : null); \\\n  const ver = (bin, args) => { try { return cp.execFileSync(bin, args, { timeout: 30000, stdio: [\"ignore\", \"pipe\", \"ignore\"] }).toString().trim().split(\"\\n\")[0] || null; } catch { return null; } }; \\\n  const one = (p, v) => (p ? { path: p, version: v } : null); \\\n  const pwBuild = (p) => (p ? (p.match(/(chromium|firefox|webkit)-(\\d+)/) || [])[0] || null : null); \\\n  const lp = at(\"/opt/browser/lightpanda/lightpanda\"); \\\n  const cr = at(pw.chromium.executablePath()); \\\n  const ob = at(\"/opt/browser/obscura/obscura-worker\") && at(\"/opt/browser/obscura/obscura\"); \\\n  const engines = { \\\n    chromium: one(cr, cr && [ver(cr, [\"--version\"]), pwBuild(cr)].filter(Boolean).join(\" \")), \\\n    chrome: one(at(\"/opt/google/chrome/chrome\"), ver(\"/opt/google/chrome/chrome\", [\"--version\"])), \\\n    \"chrome-beta\": one(at(\"/opt/google/chrome-beta/chrome\"), ver(\"/opt/google/chrome-beta/chrome\", [\"--version\"])), \\\n    firefox: one(at(pw.firefox.executablePath()), pwBuild(pw.firefox.executablePath())), \\\n    webkit: one(at(pw.webkit.executablePath()), pwBuild(pw.webkit.executablePath())), \\\n    lightpanda: one(lp, lp && ver(lp, [\"version\"])), \\\n    obscura: one(ob, ob && ver(ob, [\"--version\"])), \\\n  }; \\\n  const xvfb = ver(\"sh\", [\"-c\", \"command -v Xvfb\"]); \\\n  const arch = cp.execFileSync(\"uname\", [\"-m\"]).toString().trim(); \\\n  const manifest = { arch, playwright: require(\"playwright/package.json\").version, engines, xvfb }; \\\n  fs.writeFileSync(\"/opt/browser/engines.json\", JSON.stringify(manifest, null, 2) + \"\\n\"); \\\n  console.log(JSON.stringify(manifest)); \\\n  const missing = [\"chromium\", \"chrome\", \"firefox\", \"webkit\", \"lightpanda\", \"obscura\"].filter((e) => !engines[e]).concat(xvfb ? [] : [\"Xvfb\"]); \\\n  if (missing.length && arch === \"x86_64\") { \\\n    console.error(\"runner image: MISSING ENGINES on x86_64: \" + missing.join(\", \")); \\\n    console.error(\"runner image: every engine ships for x86_64, so a missing one is a failed download (the retry lines above say which) - failing the build\"); \\\n    process.exit(1); \\\n  } \\\n  if (missing.length) console.error(\"runner image: built without \" + missing.join(\", \") + \" on \" + arch); \\\n ' \\\n && chmod a+r /opt/browser/engines.json\n\nFROM browsers AS full\nWORKDIR /opt/runner\nCOPY foldrun-core.tgz driver.mjs entry.sh ./\nRUN npm init -y >/dev/null && npm install ./foldrun-core.tgz --omit=dev \\\n && npm cache clean --force >/dev/null 2>&1 \\\n && mkdir -p /workspace /library /opt/runner/job /home/agent/.foldrun/runner/.runtimes /opt/foldrun-runtimes/shared/.runtimes \\\n && chown -R agent:agent /workspace /library /opt/runner /home/agent/.foldrun /opt/foldrun-runtimes \\\n && chmod +x /opt/runner/entry.sh\nENTRYPOINT [\"/opt/runner/entry.sh\"]\n";
+export declare const DOCKERFILE = "FROM node:22-trixie-slim@sha256:b26b04c123d9ff8ab646ceb18b9d75a1173acf64b9a401094b906d27b29338d4 AS base\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends python3 python3-venv ca-certificates bash util-linux tar openssh-client sshpass git curl \\\n && rm -rf /var/lib/apt/lists/* \\\n && useradd -m -u 10001 agent\n# uv builds the declared python environments (runtime.ts): a fraction of\n# pip's time, and it can fetch a pinned python the image does not carry.\nCOPY --from=ghcr.io/astral-sh/uv:0.11.25 /uv /uvx /usr/local/bin/\nENV PLAYWRIGHT_BROWSERS_PATH=/opt/browser NODE_PATH=/usr/local/lib/node_modules\n\nFROM base AS core\nWORKDIR /opt/runner\nCOPY foldrun-core.tgz ./\nRUN npm init -y >/dev/null && npm install ./foldrun-core.tgz --omit=dev \\\n && npm cache clean --force >/dev/null 2>&1 \\\n && rm -f foldrun-core.tgz node_modules/@foldrun/core/README.md\n\nFROM base AS slim\n# Fonts, because a step that draws text without a browser still needs them:\n# the full image gets 51 from Playwright's --with-deps, slim had none, so from\n# 2026-09-29 (when non-browsing steps moved to slim) every resvg/sharp diagram\n# rendered its labels as empty boxes \u2014 expert-witness-desk's validator failed\n# four passes on a post image that was \"three empty boxes\". DejaVu covers\n# Latin, Greek and Cyrillic in a few MB; fontconfig is how renderers find it.\n# DejaVu alone still drew emoji, Chinese, Japanese, Korean, Devanagari and\n# Thai as empty boxes (reproduced 2026-10-01 with resvg-js 2.6 and sharp\n# 0.34), so four more, the smallest set that drew all of them \u2014 8 MB:\n#   Symbola     emoji and symbols, as outlines. NOT Noto Color Emoji (10 MB):\n#               resvg draws nothing from its bitmap glyphs, so a resvg\n#               diagram kept its empty boxes.\n#   WenQuanYi Micro Hei   Chinese, Japanese kana and Korean Hangul, one file.\n#   Lohit Devanagari, Loma   Hindi and Thai.\n# Here, not in base, so the full image's browser layers stay cached.\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends fonts-dejavu-core fontconfig fonts-symbola fonts-wqy-microhei fonts-lohit-deva fonts-tlwg-loma-otf \\\n && rm -rf /var/lib/apt/lists/* \\\n && fc-cache -f >/dev/null\n# The Playwright client only, the same pinned version as the browser pod's\n# server (the wire protocol is version-locked), so a tool that imports it\n# still loads; there is nothing here for it to launch.\n# npm's download cache is dropped in the same layer: it was 190 MB of every\n# image, read by nothing after the build.\nRUN npm install -g playwright@1.63.0 axe-core@4.13.0 >/dev/null && npm cache clean --force >/dev/null 2>&1\nWORKDIR /opt/runner\nCOPY --from=core --chown=agent:agent /opt/runner/ ./\nCOPY --chown=agent:agent driver.mjs entry.sh ./\nRUN mkdir -p /workspace /library /opt/runner/job /home/agent/.foldrun/runner/.runtimes /opt/foldrun-runtimes/shared/.runtimes \\\n && chown agent:agent /opt/runner \\\n && chown -R agent:agent /workspace /library /opt/runner/job /home/agent/.foldrun /opt/foldrun-runtimes \\\n && chmod +x /opt/runner/entry.sh\nENTRYPOINT [\"/opt/runner/entry.sh\"]\n\nFROM base AS browsers\n# Real browsers, because directories and portals increasingly render with\n# JavaScript and a plain fetch sees only the empty shell. Chromium is the one the\n# browser tool drives by default; Firefox and WebKit (Safari's engine) are\n# there for an agent asked to see a page the way those render it. Installed\n# to a fixed path the agent user can read (the default cache would be\n# root's HOME). The browsers' own sandboxes are disabled at launch time \u2014 in\n# this platform the container/gVisor IS the sandbox, and the two fight.\n# Pinned exactly, not @1: web browse's numbered elements use ariaSnapshot's\n# \"ai\" mode (1.59+), and the per-account browser pod runs this same image, so\n# a floating version would move both under a working tool on any rebuild.\n# Raise it on purpose, with the gallery tests and one real call.\n# axe-core beside it is web browse's mode=a11y: one file the tool injects\n# into the page; without it the mode falls back to its own shorter checks.\n# Xvfb by name: the browser pod starts it at boot and web browse starts one\n# per call for headless: false. It used to arrive only as one of Playwright's\n# --with-deps packages, so a Playwright bump that dropped it would have\n# broken every windowed browser without a word. No xauth: nothing here runs\n# xvfb-run, and Xvfb started without -auth takes the local client as it is.\nRUN apt-get update \\\n && apt-get install -y --no-install-recommends xvfb \\\n && rm -rf /var/lib/apt/lists/*\n# Google Chrome and Chrome beta come from Google's apt repository, which\n# Playwright adds; each is tried ENGINE_DOWNLOAD_ATTEMPTS times. Only on\n# x86_64: Google ships no Linux Chrome for arm64, so there it is not tried.\nRUN npm install -g playwright@1.63.0 axe-core@4.13.0 >/dev/null \\\n && playwright install --with-deps chromium firefox webkit >/dev/null \\\n && retry() { what=$1; shift; n=1; until \"$@\"; do if [ \"$n\" -ge 3 ]; then echo \"runner image: $what - download failed $n times, giving up\" >&2; return 1; fi; echo \"runner image: $what - download failed (attempt $n of 3), retrying in $((n * 15))s\" >&2; sleep $((n * 15)); n=$((n + 1)); done; } \\\n && if [ \"$(uname -m)\" = x86_64 ]; then \\\n      retry chrome playwright install --with-deps chrome >/dev/null || echo \"runner image: chrome not installed - engine: chrome would fall back to chromium\" >&2; \\\n      retry chrome-beta playwright install --with-deps chrome-beta >/dev/null || echo \"runner image: chrome-beta not installed\" >&2; \\\n    else echo \"runner image: no Google Chrome for $(uname -m) - engine: chrome falls back to chromium\"; fi \\\n && chmod -R a+rX /opt/browser \\\n && npm cache clean --force >/dev/null 2>&1\n# Lightpanda (engine: lightpanda): a browser that runs the JavaScript and\n# never draws \u2014 a fraction of Chromium's memory for reading and filling\n# pages. Its own program, which web browse starts beside a call and drives\n# over the DevTools protocol; shipped unmodified (AGPL-3.0). Pinned by\n# checksum (GitHub's own asset digests, checked again here). 0.4.1 since the\n# move to Debian 13: 0.3.7 on wants glibc 2.38, and Debian 12's 2.36 held it\n# at 0.3.6. An arch without a build leaves the engine out, and the tool says\n# so when asked for it. Each download (with its checksum) is tried\n# ENGINE_DOWNLOAD_ATTEMPTS times before the engine is left out.\n# Raise it on purpose: the new release's two sha256s, then one\n# engine=lightpanda call on each arch.\nRUN arch=$(uname -m) \\\n && case \"$arch\" in \\\n      x86_64) sum=1d40801e72c0bc61b2cbd3f3562bcfc46de7b79e0568f33f686b64f2e587610a ;; \\\n      aarch64) sum=664775c7f5ab69cc3189954c7f9345e25c167cb4dace016173e629f9a5e82c42 ;; \\\n      *) sum= ;; \\\n    esac \\\n && mkdir -p /opt/browser/lightpanda \\\n && retry() { what=$1; shift; n=1; until \"$@\"; do if [ \"$n\" -ge 3 ]; then echo \"runner image: $what - download failed $n times, giving up\" >&2; return 1; fi; echo \"runner image: $what - download failed (attempt $n of 3), retrying in $((n * 15))s\" >&2; sleep $((n * 15)); n=$((n + 1)); done; } \\\n && fetch() { curl -fsSL -o /opt/browser/lightpanda/lightpanda \"https://github.com/lightpanda-io/browser/releases/download/0.4.1/lightpanda-$arch-linux\" \\\n      && echo \"$sum  /opt/browser/lightpanda/lightpanda\" | sha256sum -c - >/dev/null; } \\\n && if [ -n \"$sum\" ] && retry lightpanda fetch; then \\\n      chmod a+rx /opt/browser/lightpanda/lightpanda && /opt/browser/lightpanda/lightpanda version; \\\n    else rm -f /opt/browser/lightpanda/lightpanda; echo \"runner image: lightpanda not installed for $arch - engine: lightpanda says so when asked\" >&2; fi\n# Obscura (engine: obscura): a headless browser in Rust around V8 that does\n# draw \u2014 screenshots, a raster PDF, a screencast \u2014 light like Lightpanda.\n# Apache-2.0. The plain build, not -stealth: this platform does not help a\n# page not see automation. Two binaries, obscura and obscura-worker, which\n# must sit side by side. Pinned by checksum; glibc 2.35 is its floor, so\n# Debian 13 (2.41) runs it. As above, a download is tried\n# ENGINE_DOWNLOAD_ATTEMPTS times, then a failed one leaves the engine out.\nRUN arch=$(uname -m) \\\n && case \"$arch\" in \\\n      x86_64) sum=1534d1e6ddaf3d080ec4091eb41d0a4d8cc042a48b607d3c410fc13b482a9eec ;; \\\n      aarch64) sum=5ecf980bca3060236a7a86ec7ed83d943e6598ee87caa46d20325d90bc75f979 ;; \\\n      *) sum= ;; \\\n    esac \\\n && mkdir -p /opt/browser/obscura \\\n && retry() { what=$1; shift; n=1; until \"$@\"; do if [ \"$n\" -ge 3 ]; then echo \"runner image: $what - download failed $n times, giving up\" >&2; return 1; fi; echo \"runner image: $what - download failed (attempt $n of 3), retrying in $((n * 15))s\" >&2; sleep $((n * 15)); n=$((n + 1)); done; } \\\n && fetch() { curl -fsSL -o /tmp/obscura.tgz \"https://github.com/h4ckf0r0day/obscura/releases/download/v0.2.3/obscura-$arch-linux.tar.gz\" \\\n      && echo \"$sum  /tmp/obscura.tgz\" | sha256sum -c - >/dev/null; } \\\n && if [ -n \"$sum\" ] && retry obscura fetch \\\n      && tar -xzf /tmp/obscura.tgz -C /opt/browser/obscura obscura obscura-worker; then \\\n      chmod a+rx /opt/browser/obscura/obscura /opt/browser/obscura/obscura-worker && /opt/browser/obscura/obscura --version; \\\n    else rm -rf /opt/browser/obscura/*; echo \"runner image: obscura not installed for $arch - engine: obscura says so when asked\" >&2; fi \\\n && rm -f /tmp/obscura.tgz\n# What this image actually has, written down: /opt/browser/engines.json, one\n# entry per engine (its path and version, or null when the install above\n# left it out) plus Xvfb. Chromium's version is its own --version (dotted,\n# so FOLDRUN_RUNNER_ENGINES carries it: a pinned user_agent on engine\n# chromium is compared with it, not with Google Chrome's) then the build.\n# web browse reads it for its \"built without\" answer, and the deploy reads\n# it to report the engines beside the version.\n# On x86_64 a missing engine FAILS the build: every engine ships for that\n# arch, so a gap there is a failed download, and an image that quietly lacks\n# the Chrome or Lightpanda a desk names would fail those runs instead. A\n# failed build leaves the previous image running and says why. Elsewhere\n# (arm64 has no Google Chrome) the gap is recorded and the image ships.\nRUN node -e ' \\\n  const fs = require(\"fs\"), cp = require(\"child_process\"), pw = require(\"playwright\"); \\\n  const at = (p) => (p && fs.existsSync(p) ? p : null); \\\n  const ver = (bin, args) => { try { return cp.execFileSync(bin, args, { timeout: 30000, stdio: [\"ignore\", \"pipe\", \"ignore\"] }).toString().trim().split(\"\\n\")[0] || null; } catch { return null; } }; \\\n  const one = (p, v) => (p ? { path: p, version: v } : null); \\\n  const pwBuild = (p) => (p ? (p.match(/(chromium|firefox|webkit)-(\\d+)/) || [])[0] || null : null); \\\n  const lp = at(\"/opt/browser/lightpanda/lightpanda\"); \\\n  const cr = at(pw.chromium.executablePath()); \\\n  const ob = at(\"/opt/browser/obscura/obscura-worker\") && at(\"/opt/browser/obscura/obscura\"); \\\n  const engines = { \\\n    chromium: one(cr, cr && [ver(cr, [\"--version\"]), pwBuild(cr)].filter(Boolean).join(\" \")), \\\n    chrome: one(at(\"/opt/google/chrome/chrome\"), ver(\"/opt/google/chrome/chrome\", [\"--version\"])), \\\n    \"chrome-beta\": one(at(\"/opt/google/chrome-beta/chrome\"), ver(\"/opt/google/chrome-beta/chrome\", [\"--version\"])), \\\n    firefox: one(at(pw.firefox.executablePath()), pwBuild(pw.firefox.executablePath())), \\\n    webkit: one(at(pw.webkit.executablePath()), pwBuild(pw.webkit.executablePath())), \\\n    lightpanda: one(lp, lp && ver(lp, [\"version\"])), \\\n    obscura: one(ob, ob && ver(ob, [\"--version\"])), \\\n  }; \\\n  const xvfb = ver(\"sh\", [\"-c\", \"command -v Xvfb\"]); \\\n  const arch = cp.execFileSync(\"uname\", [\"-m\"]).toString().trim(); \\\n  const manifest = { arch, playwright: require(\"playwright/package.json\").version, engines, xvfb }; \\\n  fs.writeFileSync(\"/opt/browser/engines.json\", JSON.stringify(manifest, null, 2) + \"\\n\"); \\\n  console.log(JSON.stringify(manifest)); \\\n  const missing = [\"chromium\", \"chrome\", \"firefox\", \"webkit\", \"lightpanda\", \"obscura\"].filter((e) => !engines[e]).concat(xvfb ? [] : [\"Xvfb\"]); \\\n  if (missing.length && arch === \"x86_64\") { \\\n    console.error(\"runner image: MISSING ENGINES on x86_64: \" + missing.join(\", \")); \\\n    console.error(\"runner image: every engine ships for x86_64, so a missing one is a failed download (the retry lines above say which) - failing the build\"); \\\n    process.exit(1); \\\n  } \\\n  if (missing.length) console.error(\"runner image: built without \" + missing.join(\", \") + \" on \" + arch); \\\n ' \\\n && chmod a+r /opt/browser/engines.json\n\nFROM browsers AS full\nWORKDIR /opt/runner\nCOPY --from=core --chown=agent:agent /opt/runner/ ./\nCOPY --chown=agent:agent driver.mjs entry.sh ./\nRUN mkdir -p /workspace /library /opt/runner/job /home/agent/.foldrun/runner/.runtimes /opt/foldrun-runtimes/shared/.runtimes \\\n && chown agent:agent /opt/runner \\\n && chown -R agent:agent /workspace /library /opt/runner/job /home/agent/.foldrun /opt/foldrun-runtimes \\\n && chmod +x /opt/runner/entry.sh\nENTRYPOINT [\"/opt/runner/entry.sh\"]\n";
 /** Which build target of the runner image (see DOCKERFILE). */
 export type RunnerVariant = "full" | "slim";
 export declare function runnerImageTag(variant?: RunnerVariant): string;

package/dist/src/run-container.js

@@ -23,9 +23,9 @@ import path from "node:path";
 import crypto from "node:crypto";
 import { spawn, spawnSync } from "node:child_process";
 import { isPlatformPath } from "./store.js";
-import { divertedSummary, isDivertedPath } from "./test-mode.js";
+import { divertedSummary, isDivertedPath, overlayTestWrites } from "./test-mode.js";
 import { isFileValue, fileContent } from "./secrets.js";
-import { safeTenantSegment } from "./runtime.js";
+import { safeTenantSegment, systemInstallSh, SYSTEM_FROM_INPUT_SH, INSTALL_SOCKET } from "./runtime.js";
 import { isOperatorEvent } from "./operator.js";
 import { parseBrowserPod } from "./browser-pod.js";
 /**
@@ -173,19 +173,39 @@ export function mergeAppends(was, host, next) {
     const max = Math.min(h.length, n.length);
     while (common < max && h.charCodeAt(common) === n.charCodeAt(common))
         common++;
-    for (let end = common; end >= 0; end--) {
-        if (end > 0 && h[end - 1] !== "\n")
-            continue;
-        const prefix = h.slice(0, end);
-        const matches = typeof was === "string" ? sha(Buffer.from(prefix, "utf8")) === was : Buffer.from(prefix, "utf8").equals(was);
-        if (!matches)
-            continue;
-        const hostAdded = h.slice(end);
-        const stepAdded = n.slice(end);
-        const joined = hostAdded && !hostAdded.endsWith("\n") ? hostAdded + "\n" : hostAdded;
-        return Buffer.from(prefix + joined + stepAdded, "utf8");
+    // One pass over the shared prefix. Rebuilding and hashing the prefix at
+    // every line boundary, from the longest down, was quadratic: on 6 Oct 2026
+    // a conflicted file of a few MB held the worker's event loop for minutes,
+    // the liveness probe killed it every 4.5 minutes, and every step on the box
+    // lost its model connection.
+    let end = -1;
+    if (typeof was === "string") {
+        const run = crypto.createHash("sha256");
+        if (run.copy().digest("hex") === was)
+            end = 0;
+        let from = 0;
+        for (let nl = h.indexOf("\n"); nl !== -1 && nl < common; nl = h.indexOf("\n", nl + 1)) {
+            run.update(h.slice(from, nl + 1), "utf8");
+            from = nl + 1;
+            if (run.copy().digest("hex") === was)
+                end = from;
+        }
     }
-    return null;
+    else {
+        // The base's bytes are known, so it can only end at their length.
+        const base = was.toString("utf8");
+        if (base.length <= common &&
+            (base.length === 0 || base.endsWith("\n")) &&
+            h.startsWith(base) &&
+            Buffer.from(base, "utf8").equals(was))
+            end = base.length;
+    }
+    if (end < 0)
+        return null;
+    const hostAdded = h.slice(end);
+    const stepAdded = n.slice(end);
+    const joined = hostAdded && !hostAdded.endsWith("\n") ? hostAdded + "\n" : hostAdded;
+    return Buffer.from(h.slice(0, end) + joined + stepAdded, "utf8");
 }
 export function applyContainerChanges(hostWs, containerWs, baseline, note, divert) {
     const applied = [];
@@ -283,6 +303,12 @@ export function applyContainerChanges(hostWs, containerWs, baseline, note, diver
  * that fills it.
  */
 export const RUNTIME_CACHE = "/home/agent/.foldrun/runner/.runtimes";
+/** Starts the install helper as root, in the background, before the drop to
+ *  the agent user: the root half of the `install` tool (install-helper.ts).
+ *  The agent reaches it only through the socket; it installs only validated
+ *  Debian package names, and dies with the container. */
+export const INSTALL_HELPER_SH = `FOLDRUN_INSTALL_SOCKET=${INSTALL_SOCKET}; export FOLDRUN_INSTALL_SOCKET
+node /opt/runner/node_modules/@foldrun/core/dist/src/install-helper.js "$FOLDRUN_INSTALL_SOCKET" ${RUNTIME_CACHE} >/dev/null 2>&1 &`;
 /**
  * Where the platform's shared runtime layer is mounted, read-only, in a run
  * pod — and read-write, one entry at a time, in the pod that builds an entry
@@ -420,6 +446,25 @@ try {
   // meet the packages its runtime declared, not the image's bare python.
   Object.assign(env, runtime.env);
 
+  // install: what the agent finds it needs mid-step. apt goes through the
+  // root start-up's helper (install-helper.ts); pip and npm land in a
+  // directory of this container's own, on the paths from the first turn.
+  const { buildInstallTool, INSTALL_TOOL } = await import("@foldrun/core/install-tool");
+  const { stepInstallEnv, INSTALL_SOCKET } = await import("@foldrun/core/runtime");
+  const installDir = "/home/agent/.foldrun/step";
+  const installing = (input.allowed ?? []).includes(INSTALL_TOOL);
+  if (installing) Object.assign(env, stepInstallEnv(installDir, env));
+  const install = installing
+    ? buildInstallTool({
+        dir: installDir,
+        socket: env.FOLDRUN_INSTALL_SOCKET || INSTALL_SOCKET,
+        cacheRoot: "${RUNTIME_CACHE}",
+        python: env.VIRTUAL_ENV ? env.VIRTUAL_ENV + "/bin/python" : "python3",
+        env,
+        emit,
+      })
+    : { server: null };
+
   // API and script tools, rebuilt in here from their specs. Secrets were
   // substituted into API headers before the input crossed the boundary, so
   // buildApiTools gets an already-resolved environment. verify: gets the
@@ -470,6 +515,7 @@ try {
       ...(history.server ? { foldrun_history: history.server } : {}),
       ...(desks.server ? { foldrun_desks: desks.server } : {}),
       ...(ask.server ? { foldrun_ask: ask.server } : {}),
+      ...(install.server ? { foldrun_install: install.server } : {}),
       ...input.mcpServers,
     },
     ...(inbox ? { inbox } : {}),
@@ -489,7 +535,7 @@ try {
     // through the account's pod, and named the file the web tool logs its
     // reconnects to. A lost pod stops the step; what it wrote decides what
     // the runner does next (browser-pod.ts).
-    ...(env.FOLDRUN_BROWSER_POD_EVENTS ? { browserPod: { events: env.FOLDRUN_BROWSER_POD_EVENTS, methods: api.methods ?? {}, paidWeb: paidWebActions(env) } } : {}),
+    ...(env.FOLDRUN_BROWSER_POD_EVENTS ? { browserPod: { events: env.FOLDRUN_BROWSER_POD_EVENTS, methods: api.methods ?? {}, paidWeb: paidWebActions(env), ...(env.FOLDRUN_BROWSER_INIT ? { browseInit: env.FOLDRUN_BROWSER_INIT } : {}) } } : {}),
     // The container is the boundary; the SDK's own bash sandbox here would
     // only block declared network use (SSH, curl) for no added safety.
     sandboxBash: false,
@@ -518,17 +564,29 @@ try {
   process.exit(0);
 }
 `;
+// Core itself is installed in a stage of its own (CORE_STAGE) and only the
+// result is copied in: the tarball and the package README — which explains
+// foldrun to a person reading the repo, and which no step reads — stay in
+// that stage and never become a layer of the image. Owner rule, 2026-10-02:
+// foldrun's own docs live in git, not in containers.
+const CORE_STAGE = `FROM base AS core
+WORKDIR /opt/runner
+COPY foldrun-core.tgz ./
+RUN npm init -y >/dev/null && npm install ./foldrun-core.tgz --omit=dev \\
+ && npm cache clean --force >/dev/null 2>&1 \\
+ && rm -f foldrun-core.tgz node_modules/@foldrun/core/README.md
+`;
 // docker cp writes root-owned files, so the entrypoint starts as root for
 // exactly two commands — chown the copied-in trees, drop to the agent user —
 // and the run flags grant only the three capabilities those two commands
 // need. By the time any model-directed code executes, the process is uid
 // 10001 with no capabilities at all.
 const CORE_INSTALL = `WORKDIR /opt/runner
-COPY foldrun-core.tgz driver.mjs entry.sh ./
-RUN npm init -y >/dev/null && npm install ./foldrun-core.tgz --omit=dev \\
- && npm cache clean --force >/dev/null 2>&1 \\
- && mkdir -p /workspace /library /opt/runner/job ${RUNTIME_CACHE} ${SHARED_RUNTIMES} \\
- && chown -R agent:agent /workspace /library /opt/runner /home/agent/.foldrun /opt/foldrun-runtimes \\
+COPY --from=core --chown=agent:agent /opt/runner/ ./
+COPY --chown=agent:agent driver.mjs entry.sh ./
+RUN mkdir -p /workspace /library /opt/runner/job ${RUNTIME_CACHE} ${SHARED_RUNTIMES} \\
+ && chown agent:agent /opt/runner \\
+ && chown -R agent:agent /workspace /library /opt/runner/job /home/agent/.foldrun /opt/foldrun-runtimes \\
  && chmod +x /opt/runner/entry.sh
 ENTRYPOINT ["/opt/runner/entry.sh"]
 `;
@@ -590,6 +648,7 @@ RUN apt-get update \\
 COPY --from=ghcr.io/astral-sh/uv:${UV_VERSION} /uv /uvx /usr/local/bin/
 ENV PLAYWRIGHT_BROWSERS_PATH=/opt/browser NODE_PATH=/usr/local/lib/node_modules
 
+${CORE_STAGE}
 FROM base AS slim
 # Fonts, because a step that draws text without a browser still needs them:
 # the full image gets 51 from Playwright's --with-deps, slim had none, so from
@@ -744,7 +803,14 @@ RUN node -e ' \\
 
 FROM browsers AS full
 ${CORE_INSTALL}`;
+// runtime: system: — apt as root, before the drop (runtime.ts systemInstallSh).
+// set -e is off around it: a failed install is reported by the driver, which
+// reads the status file and fails the step with apt's own words.
 const ENTRY = `#!/bin/sh
+set +e
+${SYSTEM_FROM_INPUT_SH}
+${systemInstallSh(RUNTIME_CACHE)}
+${INSTALL_HELPER_SH}
 set -e
 chown -R agent:agent /workspace /library /opt/runner/job
 # The runtime cache, when one is mounted. NOT recursive: a warm cache is tens
@@ -1100,6 +1166,13 @@ export async function runStepInContainer(args) {
             preserveTimestamps: true,
             filter: (src) => !isPlatformPath(path.relative(args.workspaceRoot, src)),
         });
+        // A test run: what its earlier steps wrote, over the real files (the
+        // copy is the baseline too, so only this step's own writes come back).
+        if (args.divert) {
+            const laid = overlayTestWrites(wsIn, args.divert.to);
+            if (laid.length)
+                args.emit("info", `test: this step sees ${laid.length} file${laid.length === 1 ? "" : "s"} earlier steps of this run wrote`);
+        }
         const libIn = path.join(staging, "library");
         if (args.galleryRoot && fs.existsSync(args.galleryRoot))
             fs.cpSync(args.galleryRoot, libIn, { recursive: true });

package/dist/src/runner.d.ts

@@ -1,7 +1,10 @@
 import { type SubagentSpec } from "./subagents.ts";
 import { type FlowStep, type RunRecord, type StepRecord } from "./store.ts";
 import { type Catalog } from "./catalog.ts";
+import { type SearchRoot, type RunDigest } from "./context-tools.ts";
+import { type ScriptSpec } from "./script-tools.ts";
 import { type RuntimeSpec } from "./runtime.ts";
+import type { McpServerConfig } from "@anthropic-ai/claude-agent-sdk";
 import { type LanguageChoice } from "./language.ts";
 import { type RegionChoice } from "./locale.ts";
 import { type ClockChoice } from "./clock.ts";
@@ -190,6 +193,163 @@ export declare function applicableSkills<T extends {
  */
 export declare function saysUntilMarker(result: string | null, until: string): boolean;
 export declare function resolveDocLinks(text: string, workspaceRoot: string): string;
+export declare function agentContext(agentDir: string, tenant: string, tags?: string[], 
+/** Who is running, so scripts can stamp what they write with its provenance. */
+identity?: {
+    runId?: string;
+    agent?: string;
+}, 
+/** The flow's own `timezone:`, when this step belongs to one. Between the
+ *  agent's frontmatter and the workspace's AGENTS.md in the cascade. */
+flowTimezone?: string | null, 
+/** Only what the agent is granted — no runtime prepared. For a sub-agent,
+ *  whose tools are cut to its parent's and run in the parent's runtime. */
+grantsOnly?: boolean): {
+    front: {
+        [key: string]: any;
+    };
+    clockEnv: {
+        FOLDRUN_LANGUAGE: string;
+        FOLDRUN_REGION?: string | undefined;
+        FOLDRUN_CURRENCY?: string | undefined;
+        FOLDRUN_UNITS: import("./locale.ts").Units;
+        FOLDRUN_CALENDAR: string;
+        FOLDRUN_DATE_LOCAL?: string | undefined;
+        FOLDRUN_RTL: string;
+        TZ: string;
+        FOLDRUN_DATE: string;
+        FOLDRUN_SEARCH_URL?: string | undefined;
+        FOLDRUN_API_URL?: string | undefined;
+        FOLDRUN_WEB_SEARCH_VIA?: string | undefined;
+        FOLDRUN_WEB_SEARCH_SECRET?: string | undefined;
+        FOLDRUN_WEB_FETCH_VIA?: string | undefined;
+        FOLDRUN_WEB_FETCH_SECRET?: string | undefined;
+        FOLDRUN_WEB_ACTIONS?: string | undefined;
+        FOLDRUN_BROWSER_VENDOR?: string | undefined;
+        FOLDRUN_BROWSER_SECRET?: string | undefined;
+        FOLDRUN_BROWSER_VENDOR_SESSION?: string | undefined;
+        FOLDRUN_BROWSER_SESSION?: string | undefined;
+        FOLDRUN_BROWSER_ENGINE?: "chrome" | "chromium" | "firefox" | "lightpanda" | "obscura" | "webkit" | undefined;
+        FOLDRUN_BROWSER_USER_AGENT?: string | undefined;
+        FOLDRUN_BROWSER_DEVICE?: string | undefined;
+        FOLDRUN_BROWSER_LOCALE?: string | undefined;
+        FOLDRUN_BROWSER_TIMEZONE?: string | undefined;
+        FOLDRUN_BROWSER_COOKIES?: string | undefined;
+        FOLDRUN_BROWSER_COOKIE_DOMAIN?: string | undefined;
+        FOLDRUN_BROWSER_STORAGE?: string | undefined;
+        FOLDRUN_BROWSER_STORAGE_ORIGIN?: string | undefined;
+        FOLDRUN_BROWSER_IDENTITIES?: string | undefined;
+        FOLDRUN_BROWSER_HEADLESS?: string | undefined;
+        FOLDRUN_BROWSER_VERSION?: string | undefined;
+        FOLDRUN_BROWSER_LIVE?: string | undefined;
+        FOLDRUN_BROWSER_ALLOWED_DOMAINS?: string | undefined;
+        FOLDRUN_BROWSER_DENY?: string | undefined;
+        FOLDRUN_BROWSER_BOUNDARIES?: string | undefined;
+        FOLDRUN_BROWSER_INIT?: string | undefined;
+        FOLDRUN_BROWSER_EXTENSIONS?: string | undefined;
+        FOLDRUN_BROWSER_WEBGPU?: string | undefined;
+        FOLDRUN_BROWSER_IGNORE_HTTPS_ERRORS?: string | undefined;
+        FOLDRUN_BROWSER_STATE_KEY?: string | undefined;
+        FOLDRUN_BROWSER_VIDEO?: string | undefined;
+        FOLDRUN_BROWSER_LIVE_VIEW?: string | undefined;
+    };
+    /** The zone, where it came from, and anything unreadable on the way —
+     *  reported by the step, not here, so it lands in the run's trace. */
+    clock: ClockChoice;
+    systemPrompt: string;
+    allowed: string[];
+    disabled: string[];
+    unknownTools: string[];
+    shadowed: string[];
+    legacyUse: string[];
+    retiredTools: string[];
+    mcpServers: Record<string, McpServerConfig>;
+    mcpNames: string[];
+    apiTools: import("./api-tools.ts").ApiToolResult;
+    scriptTools: import("./script-tools.ts").ScriptToolResult;
+    apiSpecs: import("./store.ts").ApiSpec[];
+    scriptSpecs: ScriptSpec[];
+    outward: boolean;
+    searchRoots: SearchRoot[];
+    historyDigest: RunDigest[];
+    deskDigest: RunDigest[];
+    searchTools: import("./context-tools.ts").ContextToolResult;
+    historyTools: import("./context-tools.ts").ContextToolResult;
+    deskTools: import("./context-tools.ts").ContextToolResult;
+    ask: {
+        timeoutSec: number;
+    } | null;
+    runtime: {
+        log: string[];
+        error: string | null;
+        executor: import("./container.ts").Executor;
+        spec: RuntimeSpec | null;
+        dispose: (() => void) | undefined;
+    };
+    secretEnv: {
+        [x: string]: string;
+    };
+    formatWarning: string | null;
+    providerEnv: Record<string, string>;
+    providerLabel: string | null;
+    providerSecrets: Record<string, string>;
+    providerWarnings: string[];
+    fallbackEnv: Record<string, string> | null;
+    region: RegionChoice;
+    searchChoice: import("./providers.ts").SearchChoice;
+    fetchChoice: import("./providers.ts").SearchChoice;
+    actionChoices: ({
+        provider: null;
+        error?: undefined;
+        action: "answer" | "crawl" | "extract" | "map" | "monitor";
+    } | {
+        provider: string;
+        secret: string;
+        host: string;
+        error?: undefined;
+        action: "answer" | "crawl" | "extract" | "map" | "monitor";
+    } | {
+        provider: null;
+        error: string;
+        action: "answer" | "crawl" | "extract" | "map" | "monitor";
+    })[];
+    web: {
+        actions: import("./providers.ts").WebAction[] | null;
+        raw: Record<import("./providers.ts").WebAction, unknown>;
+        problems: string[];
+    };
+    language: LanguageChoice;
+    translator: {
+        upstreamBase: string;
+        wire?: import("./translator.ts").TranslatorWire;
+        upstreamKey: string;
+        headers?: Record<string, string>;
+        maxTokensParam?: "max_tokens" | "max_completion_tokens";
+        reasoningEffort?: boolean;
+        params?: Record<string, unknown>;
+        label?: string;
+        egress?: string;
+        timezone: string;
+    } | null;
+    fallbackTranslator: {
+        upstreamBase: string;
+        wire?: import("./translator.ts").TranslatorWire;
+        upstreamKey: string;
+        headers?: Record<string, string>;
+        maxTokensParam?: "max_tokens" | "max_completion_tokens";
+        reasoningEffort?: boolean;
+        params?: Record<string, unknown>;
+        label?: string;
+        egress?: string;
+        timezone: string;
+    } | null;
+    apiWarnings: string[];
+    secretScopes: Record<string, import("./secrets.ts").SecretScope>;
+    missingTools: string[];
+    size: "heavy" | "large" | "small";
+    brokenTools: string[];
+    missingSecrets: string[];
+};
 export declare function repriced(catalog: Catalog | null, model: string, usage: {
     inputTokens: number;
     outputTokens: number;
@@ -214,6 +374,28 @@ attempt: number, status: "completed" | "failed", startedAt: string, eventsBefore
 /** The attempt re-attached to a sandbox a previous driver left: same
  *  attempt, so its row is replaced rather than repeated. */
 reattach?: boolean): void;
+/**
+ * What the person at the gate said, framed for the step's prompt — or "".
+ *
+ * The note is the freshest instruction the step has — later than the flow
+ * file, aimed at this exact run. When the gate asked a question (ask:), the
+ * note IS the answer and is framed as one.
+ *
+ * Both halves go through resolveDocLinks for the same reason the
+ * instruction does: this is authored text on its way to becoming a prompt,
+ * and the rule is that ALL of it expands. A person answering "which list?"
+ * with [[dead-ends]] was sending the model two literal brackets — the one
+ * reference syntax the workspace teaches, and the one place it silently did
+ * nothing. The previous step's results are NOT resolved, deliberately: that
+ * is model output, and a model that happens to emit [[brackets]] must not
+ * thereby name a file.
+ *
+ * An ask: gate approved with no note still says so. It used to add nothing,
+ * so the step never learned its question had been answered: gbp-desk's
+ * rivals sender, told "a plain approval means all offices", saw no answer
+ * at all and stopped BLOCKED (run-muu6r18y-417e, 2026-10-05).
+ */
+export declare function operatorBlock(step: Pick<StepRecord, "ask" | "approvalNote" | "approvedAt">, workspaceRoot: string): string;
 /**
  * Did this attempt call its tools and then fail only on the check after —
  * `verify:`, `output: json`, a schema? For a step whose tools act outward
@@ -244,6 +426,11 @@ export declare function actedThenFailedCheck(events: {
  * happened to create it.
  */
 export declare function copyTreeBytes(from: string, to: string): void;
+/** A refusal of the credential itself, in any of the wordings Claude Code
+ *  has used. "Failed to authenticate: OAuth token revoked" (9 Oct 2026, a
+ *  step started one second before the 09:07:52Z refresh) matched none of the
+ *  older two, so the step failed instead of waiting for the new token. */
+export declare function isAuthRefusal(text: string): boolean;
 /**
  * Wait, briefly, for the mounted credential to become one we have not
  * already been refused on. Returns the new value, or null when the window
@@ -251,6 +438,24 @@ export declare function copyTreeBytes(from: string, to: string): void;
  * wrong", not "this key is stale".
  */
 export declare function awaitRotatedCredential(before: string | undefined, now?: () => number, read?: () => string | undefined, waitMs?: number, pollMs?: number): Promise<string | null>;
+/** A step's own model connection cut: the egress proxy or the worker it
+ *  runs through went away. Only the run's final error, never a tool's — a
+ *  WebFetch that could not connect is the step's business, not ours. */
+export declare function isModelConnectionLost(text: string): boolean;
+/** A tool call written out as text rather than made: the model's last
+ *  message holds `<invoke name=…>` / `<function_calls>` markup. Only the tail
+ *  counts — a reply that quotes such markup mid-way and goes on is fine. */
+export declare function wroteToolCallAsText(text: string): boolean;
+/** Runs again after a tool call written as text. */
+export declare const TEXT_CALL_RETRIES = 1;
+export declare const TEXT_CALL_NOTE: string;
+/** How many times a step whose model connection was cut runs again. */
+export declare const DROP_RETRIES = 2;
+/** May a step whose connection dropped run again? Yes, unless its tools can
+ *  act outward and one ran in this attempt (actedThenFailedCheck's rule). */
+export declare function dropRetrySafe(canActOutward: boolean, attemptEvents: {
+    type: string;
+}[]): boolean;
 /** How many times a busy provider is given another moment, and the longest
  *  any one wait may be. Three is the industry's habit and the point where
  *  waiting longer stops being kinder than failing. */
@@ -408,3 +613,37 @@ export declare function waitForRun(tenant: string, workspace: string, runId: str
  * nothing is what makes `?wait=true` useful rather than merely blocking.
  */
 export declare function runResult(run: RunRecord): string | null;
+/**
+ * What a Docker-run script sees of the workspace and the account: their
+ * scripts/ and their tools/, read-only. A folder tool's code lives in its
+ * tools/<name>/ folder, not in scripts/ — without those two mounts every
+ * folder tool (the hello template's wordcount among them) was handed a host
+ * path the container did not have, and failed on every call. A gallery tool
+ * nobody installed runs from the gallery's own shelf, so that is mounted too
+ * when there is one. A folder that does not exist is skipped by the copy.
+ */
+export declare function scriptMounts(agentDir: string, tenant: string): Record<string, string>;
+/**
+ * The skills an agent can see, nearest first, each with the path the agent
+ * is told to read it at. Own skills, then the workspace's, then the
+ * workspace's `.agents/skills/` (the cross-client convention, scanned after
+ * the native location so a foldrun-native skill wins a name clash), then the
+ * account library. The nearest definition of a name wins.
+ *
+ * The workspace's are written `workspace/skills/…`, the one spelling for the
+ * workspace root, which the file tools expand themselves. `../../skills/…`
+ * left the model to resolve it against a path it had to guess, and on the
+ * hello template it climbed one level too far and was refused.
+ */
+export declare function skillsInScope(agentDir: string, tenant: string): DiscoveredSkill[];
+/**
+ * The interpreters a set of scripts needs, read from what they are: the
+ * extension of `run:` (or of inline code), or an explicit `interpreter:`.
+ * Docker's script image is built from the runtime spec, and the base one is
+ * Python only, so a JavaScript tool that declared no `runtime:` (the demo's
+ * inline crm-upload, any folder tool's run.mjs) failed with no node to run
+ * it. Python is named too whenever a .py script is present, because asking
+ * for node alone builds on node:22-slim, which has no python3. Null when
+ * nothing beyond the default is needed.
+ */
+export declare function scriptLanguages(scripts: ScriptSpec[]): RuntimeSpec | null;