foldrun 17.1.1 → 18.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/docs/checks.md CHANGED
@@ -223,6 +223,23 @@ it. The finding never repeats the value, and neither does any answer that
223
223
  shows the setting (notify's test send names the secret, or says it is not a
224
224
  name).
225
225
 
226
+ ### secret/reserved-env-name
227
+
228
+ *warn · ASI03, ASI05.* An agent's or a tool's `secrets:` names a variable
229
+ that steers programs rather than carries data: `LD_PRELOAD` and every other
230
+ `LD_*`, `PATH`, `IFS`, `HOME`, `SHELL`, `BASH_ENV`, `ENV`, `CDPATH`,
231
+ `NODE_OPTIONS`, `PYTHONPATH`, `PYTHONSTARTUP`, `PERL5OPT`, `RUBYOPT`,
232
+ `GCONV_PATH` and their like. A secret reaches the sandbox as an environment
233
+ variable of its own name, so one called `LD_PRELOAD` loads its value into
234
+ every program the agent starts, and one called `PATH` decides which program
235
+ answers to `python3`. That is almost never what was meant, and a value that
236
+ points into a folder the agent writes runs whatever is put there.
237
+
238
+ The platform does not depend on it: the part of a step's start-up that runs
239
+ as root never reads the step's environment, so it is the agent's own
240
+ sandbox at stake. Give the secret a name of its own (`STRIPE_KEY`,
241
+ `CRM_TOKEN`) and have the script read that.
242
+
226
243
  ### content/hidden-unicode
227
244
 
228
245
  *warn · ASI01, ASI04, ASI06.* Zero-width characters, bidirectional overrides
package/docs/network.md CHANGED
@@ -124,13 +124,43 @@ step's list and checks every connection against it:
124
124
  - a site **on the list** is a tunnel: the bytes pass through and the proxy
125
125
  never reads them;
126
126
  - a site a **secret is bound to** is intercepted, so the secret can be filled
127
- in on the way out ([Secrets](secrets#bound-to-sites)).
127
+ in on the way out ([Secrets](secrets#bound-to-sites)). That holds for a
128
+ WebSocket too: a `wss://` to such a site has its opening request filled
129
+ like any other (URL, headers, Basic auth), and once the site agrees the
130
+ messages pass both ways unread. The platform's own model keys are never
131
+ sent over one, and a [test run](runs#test-runs) may open one only to a site it
132
+ could not write to.
128
133
 
129
134
  On a cluster the pod's network policy backs this up. A step whose level is
130
- `trusted` or `none` runs in a pod that may reach the proxy and DNS and
131
- nothing else, so a program that ignores the proxy variables finds no route
132
- instead of going round the list; it cannot reach the account's browser or
133
- search pods either, which are the world fetched on a run's behalf.
135
+ `trusted` or `none` runs in a pod that may reach the proxy and nothing else,
136
+ so a program that ignores the proxy variables finds no route instead of
137
+ going round the list; it cannot reach the account's browser or search pods
138
+ either, which are the world fetched on a run's behalf.
139
+
140
+ ### DNS
141
+
142
+ A name is a message too: looking up `<anything>.example.net` reaches
143
+ example.net's nameserver, whatever the list says. So on a cluster that walls
144
+ it (`FOLDRUN_RUN_DNS_WALL=1`, on with foldrun's own manifests), a pod held to
145
+ its list has **no DNS of its own**: no resolver to ask, and the cluster's
146
+ resolver is not reachable from it. It does not need one. Every program sends
147
+ the proxy the name of the site it wants (`CONNECT api.example.com:443`), the
148
+ proxy looks up only a site the list allows, and the proxy's own address is
149
+ written into the pod. curl, Python's requests and httpx, Node, Go, git, apt,
150
+ pip, npm, the Claude CLI and the browser all work this way. The trace says
151
+ so:
152
+
153
+ ```
154
+ dns: this sandbox has no resolver of its own — every site is reached through the egress proxy by name, and the proxy looks up only sites on the list; a program that looks a name up itself (dig, an MX check, a client that resolves before it connects) fails here
155
+ ```
156
+
157
+ What fails there is what asks DNS directly: `dig`, `nslookup`, `ping` by
158
+ name, a mail-address check that looks up MX records, a library that resolves
159
+ a name before it connects. Give such an agent the site of a DNS-over-HTTPS
160
+ service in its list (`dns.google`, `cloudflare-dns.com`) and ask that over
161
+ HTTPS, or give it `network: open`. What the wall cannot hold is what the
162
+ list itself allows: the proxy looks up a name under an allowed wildcard
163
+ site (`*.example.com`), and a tunnel to an allowed host may use any port.
134
164
 
135
165
  The trace opens with the step's network:
136
166
 
@@ -167,7 +197,8 @@ then switch it on. The trace line `network: … — report only` says which
167
197
  mode a step ran in.
168
198
 
169
199
  On a cluster, a refused step's pod also loses its direct route to the
170
- world: the network policy gives it the proxy and DNS only.
200
+ world: the network policy gives it the proxy only (and DNS, on a cluster
201
+ that does not wall it).
171
202
 
172
203
  ### Where it is not held
173
204
 
@@ -184,16 +215,19 @@ A step that may **browse** with the `web` tool is held to its list where the
184
215
  platform can wall the step in: on a cluster whose operator has switched it
185
216
  on (`FOLDRUN_BROWSE_ENFORCE=1`), for a step whose list is restricted
186
217
  (`trusted` or `none`) and enforced. Such a step gets the proxy like any
187
- other, its pod is walled to the egress proxy and DNS, and the browser runs
188
- inside that pod — the step's own, shared with no other step. Whatever the
218
+ other, its pod is walled to the egress proxy (and, where the cluster walls
219
+ it, has no [DNS](#dns) of its own), and the browser runs inside that pod — the step's own, shared with no other step. Whatever the
189
220
  browser is told — another proxy, a new context with a proxy of its own, a
190
221
  page's script — the only way out is the egress proxy, which holds the list
191
222
  per connection, over IPv4 and IPv6, TCP and UDP alike. The trace says so —
192
223
 
193
224
  ```
194
- network: trusted (agent) — the trusted list (207 sites); added: example.com — enforced — hosted: the browser runs inside this step's sandbox, whose network reaches only the egress proxy (which holds the list) and DNS, so a page, a script or a changed proxy setting reaches no site off the list; DNS lookups themselves are not restricted.
225
+ network: trusted (agent) — the trusted list (207 sites); added: example.com — enforced — hosted: the browser runs inside this step's sandbox, whose network reaches only the egress proxy (which holds the list), so a page, a script or a changed proxy setting reaches no site off the list.
195
226
  ```
196
227
 
228
+ followed by the `dns:` line above, or, on a cluster that does not wall DNS,
229
+ one saying the sandbox can still look any name up.
230
+
197
231
  A site off the list fails in the browser as a failed tunnel
198
232
  (`ERR_TUNNEL_CONNECTION_FAILED`), and the trace names it with the usual
199
233
  advice: add just that site.
@@ -222,10 +256,9 @@ What a held step does differently:
222
256
  walled pod either; the trace says so. Name a search provider in `web:`
223
257
  (it goes through the proxy) or leave search out of that step.
224
258
 
225
- Not covered: DNS lookups through the cluster's resolver (the wall admits
226
- DNS, and nothing restricts the names asked), WebSocket upgrades to a host a
227
- secret is granted to (they fail), and — as for every tunnel — which origins
228
- a page loads inside a connection to an allowed site.
259
+ Not covered: DNS lookups on a cluster that does not wall them (see
260
+ [DNS](#dns)), and — as for every tunnel — which origins a page loads inside
261
+ a connection to an allowed site.
229
262
 
230
263
  Everywhere else — `foldrun run` on your machine, the single-container tier,
231
264
  an install without the switch, a report-only list, `network: open` — a
package/docs/security.md CHANGED
@@ -20,9 +20,12 @@ machine.
20
20
  What a sandbox keeps between steps is the account's runtime cache: the
21
21
  environments its `runtime:` declares, built once and reused. Steps write it,
22
22
  so nothing in it is trusted by the part of a step's start-up that runs as
23
- root. That part installs `runtime: system:` packages before the drop to the
24
- unprivileged agent user, in an environment with none of the step's variables
25
- but the proxy's, and touches the cache only as the agent user. The package
23
+ root. That part never holds the step's environment: secrets are exported
24
+ under the names their author chose, and one called `LD_PRELOAD` or `PATH`
25
+ pointing into the cache would otherwise steer what root runs. The step's
26
+ variables are read by the agent user's own shell, after the drop; root gets
27
+ only the proxy's, to install `runtime: system:` packages before that drop,
28
+ and touches the cache only as the agent user. The package
26
29
  snapshots it restores carry a seal made with a key per account that no step
27
30
  ever holds; a snapshot that does not match its seal is not restored, and even
28
31
  a sealed one can only write package files where packages go
@@ -216,6 +219,20 @@ It holds by construction, not by care:
216
219
  source of core, platform and web is scanned for any log call that prints
217
220
  more than a literal; and metrics may only have fixed names and labels.
218
221
 
222
+ Each run also has one **wide event** in the platform's database (5 Nov
223
+ 2026): when it was submitted, queued, picked up, when its first sandbox's
224
+ pod was ready, its tools were built and the model first answered, when it
225
+ finished; its runner image, size and model; what it held and used; its cost
226
+ and its error class. The figures the run record already has, and nothing
227
+ from its content — no prompt, reply, file or error text. It is what our run
228
+ SLOs (success rate, queue wait, pod-ready-to-first-output) are computed
229
+ from, and it goes with the run history (`runs.retention_days`) and with the
230
+ account. Its trace — the same funnel, one span per stage — goes to our
231
+ collector under the same rule as a log line: fixed span names, the fields
232
+ above in their shapes, an error as its class; the collector drops any span
233
+ that is not exactly that. It is not your `telemetry:` export, which sends
234
+ your run's own trace to your collector.
235
+
219
236
  The incident this answers: a judge's model process crashed, and the full
220
237
  text of its error — which carried prompt text — went to the server log.
221
238
  Today that line is `model.process_failed` with `errorClass: model_error`.
@@ -238,6 +255,7 @@ an install that sets neither keeps everything, as before 5 Nov 2026.
238
255
  | Your files | `storage/`, `knowledge/`, `memory/`, `state/`, your agents and flows | until you delete them | you (`foldrun storage rm`, a deploy that drops a file) |
239
256
  | **Audit log** — security evidence | sign-ins and refusals, keys, roles, invites, secrets set or deleted (by name, never a value), deploys, exports, support access, the operator's own actions | **365 days** on the hosted platform (`audit.retention_days`; unset: kept) | the daily pass |
240
257
  | The ledger | what each run and pod session was charged | for good — a financial record | never |
258
+ | A run's wide event | its funnel's timestamps, image, size, model, figures, cost and error class — metadata, never content | with run records (`runs.retention_days`) | the daily pass; closing the account |
241
259
  | The platform's own logs and metrics | ids, counts, classes — never your content ([above](#what-our-telemetry-carries)) | as the operations stack keeps them | the operations stack |
242
260
 
243
261
  Every period counts from when the record was written (a run: when it
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "17.1.1",
3
+ "version": "18.0.0",
4
4
  "description": "Agents are just folders. Write them, check them, run them — on your machine.",
5
5
  "license": "FSL-1.1-ALv2",
6
6
  "type": "module",
@@ -11,7 +11,7 @@
11
11
  "node": ">=22"
12
12
  },
13
13
  "dependencies": {
14
- "@foldrun/core": "^15.1.0"
14
+ "@foldrun/core": "^16.0.0"
15
15
  },
16
16
  "files": [
17
17
  "bin",