foldrun 2.5.0 → 2.7.0

package/docs/flows.md

@@ -106,7 +106,7 @@ begins.
 | `schema:` | with `output: json` — the JSON Schema the value must satisfy: one-line JSON, a YAML block under the key, or a file under the workspace |
 | `model:` | override the tier for this step |
 | `effort:` | override how hard it thinks for this step |
-| `retry:` | attempts after the first, clamped to 5. Each retry waits — 15 s, 30 s, 1 m, 2 m, 4 m, jittered — holding no sandbox while it waits; a stop ends the wait. An attempt the cluster ended for want of memory or disk (OOMKilled, Evicted) is retried one `size:` class up. An `outward` step whose check failed after its tools ran is not retried — the retry would send again; `check` and `deploy` warn on `retry:` on an outward step, because a failure mid-send is still retried |
+| `retry:` | attempts after the first, clamped to 5. Each retry waits — 15 s, 30 s, 1 m, 2 m, 4 m, jittered — holding no sandbox while it waits; a stop ends the wait. An attempt the cluster ended for want of memory or disk (OOMKilled, Evicted) is retried one `size:` class up. A step refused because the model usage cap is reached is not retried: the window resets in hours, not within the waits. An `outward` step whose check failed after its tools ran is not retried — the retry would send again; `check` and `deploy` warn on `retry:` on an outward step, because a failure mid-send is still retried |
 | `timeout:` | seconds, or `90s` / `15m` / `4h` / `3d` — **the only clock there is** |
 | `max_turns:` | the most model turns before the step is stopped (1 to 500) — the third bound beside `budget:` and `timeout:` |
 | `limits:` | this step's call limits, on one line — `limits: {web.search: 10, calls: 50}` — over the agent's, key by key. A call past one is refused, never run ([Tools](tools#limits--how-many-calls-a-step-may-make)) |
@@ -115,7 +115,7 @@ begins.
 | `ask:` | the same gate carrying a question; the typed answer reaches the prompt (a plain approval with no note reaches it as "approved with no note") |
 | `preview:` | what the gate shows: paths under `storage/` (a `workspace/storage/` prefix is accepted), comma-separated, globs allowed — `draft/*.mdx, draft/images/*.webp`; at most 12 files |
 | `wait:` | `3d` (`s`/`m`/`h`/`d`, capped at 30 days) or `event` — the run page shows the event URL and can release it with a payload, recorded as released by you (approve with `payload`) |
-| `on-fail:` | another agent takes the step over, with the failure as context — and, for a gated step, the person's approval and answer, which it acts within. The rescuer owes what the step owed: its `verify:`, its `output:`, and a `loop:` step's `until:` marker (a loop that runs out of cycles goes to its rescuer too). A `verify:` that accepts `BLOCKED` never fails, so it never reaches the rescuer |
+| `on-fail:` | another agent takes the step over, with the failure as context — and, for a gated step, the person's approval and answer, which it acts within. The rescuer owes what the step owed: its `verify:`, its `output:`, and a `loop:` step's `until:` marker (a loop that runs out of cycles goes to its rescuer too). A `verify:` that accepts `BLOCKED` never fails, so it never reaches the rescuer. A step refused by the model supply itself — a spent usage window, a credential refused — is not handed to a rescuer on the same supply (the same `provider:`, or both on the workspace's): it would be refused the same way, and the issue is filed as the cap or the credential |
 | `delegate:` | the step's agent picks who runs next, from this set |
 
 ### What is retried without a `retry:`
@@ -329,6 +329,7 @@ normal outcome, recorded as one.
 | `path` | the `storage/` prefix to watch, for `trigger: storage` |
 | `url` / `every` | what to poll and how often (default 15m), for `trigger: watch` |
 | `signature` / `signing_secret` | `github` \| `stripe` \| `slack` \| `hmac`, and the vault entry to check it against |
+| `filter` | for a `webhook`, `email`, `flow` or `storage` trigger: the fields a delivery must have to start a run — see [Which deliveries start a run](#which-deliveries-start-a-run) |
 | `model` / `effort` | defaults for every step |
 | `budget` | the most one run may spend, in USD — a number, or `unlimited`; unset is no limit |
 | `overlap` | `skip` or `queue` when a run is already live |
@@ -398,6 +399,66 @@ A flow may not chain on itself. First sightings for `watch` record without
 firing, and a `once` instant more than six hours gone at first sighting is
 recorded and never fired.
 
+### Which deliveries start a run
+
+`filter:` says which deliveries are this flow's. A GitHub hook for pull
+requests posts for drafts, bot pushes and label changes alike; without a
+filter each one is a run whose first step only says "not this one". With
+one, a delivery that does not match starts nothing — no sandbox, no model
+call — and the Triggers page lists it as *did not match the filter*, with the
+condition that held it back.
+
+```yaml
+trigger: webhook
+filter:
+  action: [opened, reopened]        # any of these values
+  pull_request:
+    draft: false                    # exactly this value
+    base:
+      ref: { starts_with: release/ } # text tests: starts_with, ends_with, contains
+  sender:
+    type: { not_in: [Bot] }         # none of these
+```
+
+What it is matched against depends on the trigger:
+
+| trigger | the fields |
+|---|---|
+| `webhook` | the request's JSON body — a body that is not JSON matches no filter |
+| `email` | `from`, `to`, `subject`, `text` |
+| `flow` | `run`, `flow`, `status`, `ending` (`completed`, `failed` or `blocked`), `verdict`, `summary` |
+| `storage` | `by` (who wrote), `paths` (the files that landed under `path:`) |
+
+The rules, all of them:
+
+- Every key must match. A nested map matches the nested field.
+- A list is the values allowed — any of them. A plain value is the one value.
+- An operator map says it explicitly: `in`, `not_in`, `exists` (`true` or
+  `false`), and the text tests `starts_with`, `ends_with` and `contains`.
+  There are no regular expressions: a sender controls the body, and a
+  pattern it could make backtrack has no place before a run starts.
+- Strings compare exactly and case-sensitively; numbers numerically (`1`
+  equals `1.0`; the text `"1"` does not); `true`, `false` and `null` as
+  themselves.
+- A missing field fails a value, `in` and the text tests, and passes
+  `not_in`. `exists: false` passes only when it is missing.
+- A list in the delivery: a nested map matches when any element does;
+  `in` when any element is allowed, `not_in` when none is.
+- It fails closed. A filter `foldrun check` cannot read is a check error,
+  and if one reaches the platform it matches nothing — a typo holds
+  deliveries back instead of letting all of them through. At most 10 levels
+  deep, 64 conditions, 32 values in a list.
+
+A filtered delivery counts toward nothing: not `idempotency:`, not
+`throttle:`, not `debounce:`, not `disable_after:`. A paused account or
+workspace is still told it is paused first. `filter:` on a `schedule`,
+`once`, `watch` or `manual` flow does nothing, and `foldrun check` says so.
+
+Try a delivery without sending one: the Triggers page has a **Test filter**
+box for each filtered flow, `foldrun flow filter <flow> --payload body.json`
+reads the local file (add `--to <workspace>` for the deployed one), and the
+API is `POST …/flows/<flow>/filter { payload }`.
+
 ### How many of those starts are real
 
 A trigger says what happens. These four say how much of it becomes a run,

package/docs/four-jobs.md

@@ -38,7 +38,7 @@ top. Either way works, and the two can be mixed in one file.
 | File | `governance:` | `guardrail:` | `observability:` | `evaluation:` |
 |---|---|---|---|---|
 | `AGENTS.md` | `owner`, `budget`, `priority`, `concurrency`, `deploy_block` | `limits`, `network`, `network_enforce`, `hooks` | `alerts`, `telemetry`, `notify`, `capture` | `judge` |
-| an agent | `owner`, `budget` | `limits`, `network`, `hooks`, `disallowedTools`, `permissionMode`, `secrets` | — | — |
+| an agent | `owner`, `budget` | `limits`, `network`, `hooks`, `disallowedTools`, `permissionMode`, `secrets`, `sandbox` | — | — |
 | a flow | `owner`, `approvers`, `approve_within`, `budget`, `priority` | `throttle`, `debounce`, `overlap`, `disable_after`, `live` | `issues`, `sla` | — |
 
 A field that does none of the four, such as `name`, `model`, `tools`,

package/docs/hooks.md

@@ -105,8 +105,8 @@ hook can narrow what an agent does but never widen it.
 ## What a hook does not see
 
 Tools the model provider runs on its own side never pass foldrun's dispatch.
-With `web: {search: anthropic}` (or another provider's search, or
-`fetch: anthropic`) the search runs at the provider, and a `tool.call` hook
+With `web: {search: anthropic}` (or another provider's search) the search
+runs at the provider, and a `tool.call` hook
 cannot refuse or rewrite it. foldrun's own `web` tool, the default, goes
 through hooks like every other tool. `foldrun check` warns when an agent with
 a `tool.call` hook uses a provider's own search.

package/docs/network.md

@@ -110,8 +110,12 @@ Every program in the sandbox reaches the internet through the **egress
 proxy**: the pod's `HTTPS_PROXY` and `HTTP_PROXY` name it, with the step's
 own lease as the password, and `NODE_USE_ENV_PROXY=1` turns that on for Node.
 curl, Python's `requests` and `httpx`, pip, npm, git, apt and the Agent SDK
-all read those variables. The proxy holds the step's list and checks every
-connection against it:
+all read those variables. A browser your own script launches does not:
+Chromium ignores a password written in the proxy variable, so every page
+fails `ERR_INVALID_AUTH_CREDENTIALS`. Hand Playwright the proxy yourself —
+read `HTTPS_PROXY` with `new URL()` and pass `proxy: { server, username,
+password }` to `launch()` (the `web` tool's browsers already do). The proxy
+holds the step's list and checks every connection against it:
 
 - a site **off the list** is refused — `403`, saying which site and what to
   add — and the refusal is a line in the run trace;

package/docs/runs.md

@@ -266,6 +266,34 @@ Each agent also has an **Activity** page: every step it has ever run, across
 flows and direct runs, with that step's own headline. It is where "how has
 this agent been going" is answered without opening runs one at a time.
 
+## Your inbox
+
+**Inbox**, top right and under View in the account's sidebar, is what waits
+on *you*, across every workspace you may see, in one list: gates to approve,
+questions agents are asking, open [issues](#issues), [proposed
+fixes](evals#proposed-fixes) to review, and your own runs that went wrong.
+
+Three tabs that never mix:
+
+| tab | what is in it |
+|---|---|
+| **For me** | assigned to you: you are named in the flow's `approvers:`, you own the flow or agent (`owner:`, down to the workspace's and the account's), or you asked for the proposal |
+| **Started by me** | runs you started: one that failed or ended BLOCKED or BAD in the last week, a gate on one (someone else must decide it — your own approval is refused), a question one is asking |
+| **Team** | everything else waiting in your workspaces, for whoever picks it up — a gate anyone may decide, an issue nobody owns |
+
+Nothing is kept in it: each item is read from where it lives and leaves on
+its own when it is done there — the gate decided, the issue resolved, the
+fix applied. A gate you may not decide (`approvers:` names others) is not in
+yours at all. What *is* kept is what you did to your own view: an item you
+opened is read, and **Set aside** hides one from you — it is still waiting
+for everyone else, and the gate is not decided. An item names its occurrence,
+so an issue that happens again after you set it aside comes back. The count
+on the top bar is what is unread in For me and Started by me.
+
+`foldrun inbox` prints the same (`--team`, `--all`, `--kind approval`); a key
+reads the inbox of the person who minted it, within the key's own workspaces.
+The API is `GET /api/me/inbox`.
+
 ## Gates
 
 A step marked `2!` or carrying `approve: true` / `ask: <question>` parks the

package/docs/secrets.md

@@ -201,7 +201,14 @@ the result as an `oauth2` secret; the platform refreshes it. An agent names
 it in `secrets:` like any other.
 
 You bring the OAuth app: register it once with the provider (its client id
-and secret, and the redirect URL the form shows), save it, and connect. Every
+and secret, and the redirect URL the form shows), save it, and connect. The
+form asks for the provider's own authorize and token URLs — foldrun keeps no
+list of providers — and **Extra authorize parameters**, one `name=value` per
+line, for whatever else the provider's docs say its authorize URL takes:
+Google issues a refresh token only with `access_type=offline` and
+`prompt=consent`, and without one the connection stops when the first access
+token expires. The flow's own parameters (`client_id`, `redirect_uri`,
+`state`, `scope`, PKCE) cannot be set there. Every
 later connection can use the same saved app — choose it under **App** and
 type the scopes this connection needs, as the provider spells them. Each
 connection keeps its own scopes, so one app serves any number of APIs from

package/docs/tools.md

@@ -594,7 +594,7 @@ web:
 | `parallel` | extract | full-page markdown; handles JavaScript pages and PDFs | up to 20 | `PARALLEL_API_KEY` |
 | `zyte` | **unblocker** | the page rendered in a real browser behind a proxy pool; pays per success | 1 | `ZYTE_API_KEY_BASIC` |
 | `scrapingbee` | **unblocker** | the page rendered in a real browser (`render_js`) behind a proxy pool; credits per call | 1 | `SCRAPINGBEE_API_KEY` |
-| `anthropic` | model provider | a small model's reading of the page, on Anthropic's servers | 1 | — |
+| `anthropic` | ours | accepted, and answered by foldrun's own fetch: Claude Code's `WebFetch` it used to hand over to fails its domain check behind the egress proxy | 1, or up to 20 with `urls=` | — |
 
 A provider answers `markdown`, `text` and `html`. The modes only a raw read
 can answer — `meta`, `links`, `raw` — are always read directly, and the tool

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "foldrun",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "description": "Agents are just folders. Write them, check them, run them — on your machine.",
   "license": "SEE LICENSE IN LICENSE",
   "type": "module",
@@ -11,7 +11,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@foldrun/core": "^2.7.0"
+    "@foldrun/core": "^2.11.0"
   },
   "files": [
     "bin",
@@ -21,7 +21,7 @@
   ],
   "scripts": {
     "e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
-    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts",
+    "test": "FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-test-XXXXXX) node --test tests/cli-account.test.ts tests/model-credential.test.ts tests/cli-approvals.test.ts tests/cli-issues.test.ts tests/cli-capture.test.ts tests/cli-stop.test.ts tests/cli-account-settings.test.ts tests/cli-schedule.test.ts tests/cli-billing.test.ts tests/cli-storage.test.ts tests/cli-scaffold.test.ts tests/cli-secrets.test.ts tests/cli-site-login.test.ts tests/cli-check-library.test.ts tests/cli-check-timezone.test.ts tests/cli-check-frontmatter.test.ts tests/cli-agent-import.test.ts tests/cli-check-subagents.test.ts tests/cli-connect.test.ts tests/cli-accounts.test.ts tests/cli-remote.test.ts tests/cli-stream.test.ts tests/cli-doctor.test.ts tests/cli-tool-test.test.ts tests/cli-agent-run.test.ts tests/cli-check-remote.test.ts tests/cli-shares.test.ts tests/cli-triggers.test.ts tests/cli-providers.test.ts tests/cli-rerun-put.test.ts tests/cli-guide.test.ts tests/cli-runtimes.test.ts tests/cli-deploy-safety.test.ts tests/cli-operator.test.ts tests/cli-flow-patterns.test.ts tests/cli-flow-rm-step.test.ts tests/cli-flow-dup-step.test.ts tests/cli-flow-write-stale.test.ts tests/cli-agent-link-stale.test.ts tests/cli-agent-link-isolated.test.ts tests/cli-parity.test.ts tests/cli-invoke-inputs.test.ts tests/cli-audit-keys.test.ts tests/cli-version.test.ts tests/cli-check-web-warnings.test.ts tests/cli-report-image.test.ts tests/cli-report-cache.test.ts tests/cli-check-workspace-paths.test.ts tests/cli-parity-dashboard.test.ts tests/cli-api-standards.test.ts tests/cli-backups-onboarding.test.ts tests/cli-check-limits.test.ts tests/cli-gallery.test.ts tests/cli-status-platform.test.ts tests/cli-webhooks-notifications.test.ts tests/cli-flags.test.ts tests/cli-api-coverage.test.ts tests/cli-hooks.test.ts tests/cli-release.test.ts tests/cli-terminal.test.ts tests/cli-network.test.ts tests/cli-assistant.test.ts tests/cli-check-scan.test.ts tests/cli-published.test.ts tests/cli-init-target.test.ts tests/cli-flow-filter.test.ts tests/cli-eval-grades.test.ts tests/cli-eval-compare.test.ts tests/cli-proposals.test.ts tests/cli-inbox.test.ts",
     "release": "node scripts/release.mjs",
     "typecheck": "tsc -p tsconfig.json",
     "docs:sync": "node scripts/sync-docs.mjs",
@@ -47,5 +47,8 @@
     "@types/node": "^26.6.4",
     "gray-matter": "^4.0.3",
     "typescript": "^6.0.3"
+  },
+  "overrides": {
+    "zod": "4.6.7"
   }
 }