foldrun 0.5.0 → 0.7.2

package/docs/knowledge-and-memory.md

@@ -0,0 +1,85 @@
+# Knowledge, memory and state
+
+Four places hold what an agent knows, and they differ only by who may write.
+Getting the four right is most of what separates a desk that improves from
+one that repeats itself.
+
+| place | who writes | what belongs there |
+|---|---|---|
+| **knowledge/** | people | what you tell the agents: reference material, standards, the price list |
+| **memory/** | the agent | what it worked out: one fact per file, indexed |
+| **state/** | the workspace | the bookmark between runs: a cursor, an append-only history |
+| **storage/** | anyone | bytes a person reads — see [Storage and sharing](storage-and-sharing) |
+
+## Knowledge is given, not learned
+
+`knowledge/` at the workspace is read by every agent there; `knowledge/`
+inside an agent's folder by that agent alone; the account library's by
+every workspace. Writing to any of them is denied outright — through the
+file tools and through a script. An agent that rewrites the price list it was
+handed has corrupted its own source of truth; what it discovers goes to
+`memory/`.
+
+Knowledge files are **concepts** in the open OKF shape: a
+markdown file with frontmatter naming its `type:`, a title, and a
+description. The platform maintains `index.md` and `log.md` in each
+knowledge and memory directory — an index of what is there and a provenance
+log of who changed what — and refuses a push that adds a concept with no
+`type:`. Those two files are generated on every write; do not edit them.
+
+```markdown
+---
+type: Reference
+title: Target keywords
+description: The queries the business wants to win, and where each is measured.
+---
+| keyword | location | page |
+|---|---|---|
+| building inspection geelong | Geelong,Victoria,Australia | /vic/building-inspections-geelong |
+```
+
+## Memory is what the agent learned
+
+`memory/` is the one place an agent writes without an explicit `write`
+grant. One fact per file, with frontmatter the index can read. An agent that
+learns a customer's phone format, a site's quirk, a date that mattered,
+writes it there and finds it next run — and a deploy never overwrites memory
+a push does not mention, so what was learned survives the next edit to the
+prompt.
+
+Memory is per agent by default; the workspace's `memory/` is shared by the
+desk, and the library's by the account.
+
+## Finding it: search and history
+
+Two tool groups give an agent its own past at scale:
+
+- **`tools: [search]`** — `search_files(query)`: ranked full-text search over
+  knowledge, memory, state and storage, at the agent's, the workspace's and
+  the library's scope. Lexical (BM25), not embeddings — nothing leaves the
+  box, and the queries an agent makes are rare exact tokens where that
+  wins. Behind it is an inverted index built inside the step on the first
+  call and refreshed by mtime after that: a file the agent wrote to
+  `state/` a moment ago is found on the next search and is the only file
+  re-read, and nothing is persisted, so the index can never be stale across
+  a deploy or a hand edit. Search first, then read the hit.
+- **`tools: [history]`** — `recall_runs()` and `read_run(id)`: what this
+  workspace's earlier runs concluded and what their steps said. A reporter
+  that wants "what did last week's run find" asks, rather than being handed
+  every prior run.
+
+## State is the bookmark
+
+A cursor into a list that takes a fortnight to walk; a dated, append-only
+history line per run; last week's positions to diff against this week's.
+The next run reads it, a person rarely does. It travels with a deploy and a
+deploy never overwrites it. The one habit that keeps it useful: **append,
+never rewrite**, so a run that went wrong cannot erase the record of the runs
+that went right.
+
+## The rule to write by
+
+A value **regenerated** every run — a fetched list, a report — is `storage/`.
+A value **accumulated** across runs — dead ends, a history, a cursor — is
+`state/`. What the agent *learned* — a fact about the world — is `memory/`.
+What you *told* it is `knowledge/`.

package/docs/notifications.md

@@ -0,0 +1,320 @@
+# Notifications
+
+An agent that runs while the laptop is closed needs a way to say "I
+finished", "I failed", and above all "I am waiting for you". A run parked at
+an approval nobody hears about is a run that never happens. Notifications are
+one destination — an email address or a webhook URL — declared once in
+`AGENTS.md`, and a short list of the events that should reach it.
+
+## Declaring one
+
+```yaml
+notify:
+  email: ops@example.com
+  events: [failed, awaiting-approval, completed]
+```
+
+or, for people who live in a channel rather than an inbox:
+
+```yaml
+notify:
+  url: ${SLACK_WEBHOOK_URL}        # a secret name, or a literal URL
+  events: [failed, awaiting-approval]
+```
+
+A bare string is whichever destination it looks like: `notify: ops@example.com`.
+
+A webhook can also be signed, so the receiver can tell a real notification
+from anyone who learned the URL:
+
+```yaml
+notify:
+  url: ${OPS_WEBHOOK_URL}
+  signing_secret: OPS_WEBHOOK_SIGNING_KEY   # a secret NAME, never its value
+```
+
+Every delivery then carries `x-foldrun-timestamp` and
+`x-foldrun-signature: sha256=<hex>`, the hex HMAC-SHA256 of
+`"<timestamp>.<body>"` keyed by that secret. The timestamp is inside the
+signed string, so a captured delivery cannot be replayed later with a fresh
+one. Beside it, `x-signature` is the plain HMAC of the body — the scheme an
+inbound `signature: hmac` flow verifies — so one foldrun install can notify
+another's webhook flow and be accepted. Name no secret and nothing is
+signed, which is what every existing destination keeps doing. How to check
+it is under [Verifying a delivery](#verifying-a-delivery).
+
+The default events are `failed` and `awaiting-approval`. `completed` is
+opt-in on purpose: a schedule that works is the quiet kind of good news, and
+a channel that pings on every success gets muted — which un-pings the
+failures too. Turn it on when the run's headline is the thing you want to
+read each morning, which for a scheduled desk it usually is.
+
+Even with `completed` on, an eval case (`eval:<name>`) or an adhoc
+single-agent run (`adhoc:<agent>`) completing sends nothing: the person who
+started it is watching it, and a desk that emailed every test would bury
+its weekly verdict. A test that fails, or parks at a gate, still sends.
+
+## `blocked` — a run that finished but did nothing
+
+Every desk ends its last step on a verdict word: `GOOD`, `BAD`, `QUIET` or
+`BLOCKED`. The platform reads that word from the run's summary and records it
+beside the status. A run can be `completed` — every step ran, nothing
+crashed — and still be `BLOCKED`: the publisher checked, saw something
+wrong, and refused to push. That is a success of the machine and a failure
+of the work, and a green tick hid it.
+
+So a completed run whose verdict is `BLOCKED` is sent as its own event,
+`blocked`, with the headline `⛔ <flow> blocked` and `verdict: "BLOCKED"`
+in the body. **It follows `failed`**, like the alerts below: a destination
+that hears about failures hears about it, and a `completed`-only list does
+not. Name `blocked` alone to hear only those. Every run notification's body
+carries `verdict` — `GOOD`, `BAD`, `QUIET`, `BLOCKED`, or `null` when the
+summary leads with none.
+
+## The three that are about nothing happening
+
+`failed`, `completed`, `blocked` and `awaiting-approval` are all about a run. Three
+more events are about a run that **did not** happen, or has not finished,
+which is the class of failure that otherwise reaches nobody:
+
+| event | sent when |
+|---|---|
+| `quarantined` | a flow's `disable_after:` tripped and it has stopped firing |
+| `sla` | a run has passed its flow's `sla:` and is still going |
+| `budget` | a workspace has spent 80%, then 95%, of its `budget:` for the window — today, this week or this month |
+
+Each is sent once per occurrence, not once per check: an alarm that repeats
+every thirty seconds gets muted, and a muted alarm is the same as no alarm.
+The budget marks reset with the month, and a quarantine is forgotten as soon
+as the flow succeeds again, so the next outage is announced as its own.
+
+**They follow `failed`.** If a destination is told about failures it is told
+about these too, because each one is a failure that produces no failed run —
+and nobody thinks to opt in to hearing about something that has not
+happened. Naming one explicitly in `events:` also turns it on. To have none
+of them, leave `failed` out of the list.
+
+## Proving it arrives
+
+A notification path that has never been tested is not a notification path.
+Every message here is sent when nobody is watching, to a destination nobody
+has checked, through a mail domain nobody has verified — and on 2026-09-06
+every run email had been going to a bin for weeks, with silence as the only
+symptom. Silence looks exactly like nothing having gone wrong.
+
+Workspace settings has a button that sends one real message to the saved
+destination and reports what came back, including the provider's own words
+on a failure. Those words are the value: "domain not verified" and "you can
+only send to your own address" send you to two different pages, and a status
+code sends you to neither. `POST /api/workspaces/<ws>/notify/test` is the
+same thing.
+
+## Where it is set, and the rule that bites
+
+`notify:` lives in the account's `AGENTS.md` and every workspace inherits it.
+A workspace may declare its own — and when it does, its block **replaces**
+the account's whole, it does not merge. A workspace that wants the account's
+destination and events simply says nothing.
+
+## What arrives
+
+**The subject is the run's headline** — the first line of the last step's
+reply — followed by its summary. Ids and costs are in the body. The subject
+is meant to be read on a phone: "BAD — 3 targets fell out of the top 20" is
+the whole message; "run-mtmv20up-oote completed" is not.
+
+The body, and the webhook's JSON:
+
+```json
+{
+  "text": "BAD — 3 targets fell out of the top 20 · rank-desk/run-… · $1.01",
+  "workspace": "rank-desk", "runId": "run-…", "flow": "rankings",
+  "status": "completed", "summary": "…", "costUsd": 1.01,
+  "startedAt": "…", "finishedAt": "…",
+  "approveUrl": "…", "rejectUrl": "…",
+  "links": [{ "step": 3, "agent": "publisher", "approveUrl": "…", "rejectUrl": "…" }]
+}
+```
+
+`text` is what Slack, Discord and ntfy render as-is; the rest is for anything
+that wants the data. A webhook URL is the one integration: those services,
+and every phone-push relay, all accept a POST of that shape.
+
+## Webhook deliveries, retries and redelivery
+
+Every webhook send is a **delivery**: recorded first, attempted at once,
+and — when the receiver is down, slow or answers anything but 2xx — tried
+again on a backoff from the platform's worker:
+
+| attempt | when |
+|---|---|
+| 1 | at once |
+| 2 | 1 minute after the first failed |
+| 3 | 5 minutes after that |
+| 4 | 30 minutes |
+| 5 | 2 hours |
+| 6 | 6 hours |
+
+After the sixth the delivery is `failed` and stays in the log, one press
+from a redelivery. Each attempt has an 8-second timeout and is written down:
+the status code, how long it took, the first 500 characters of the answer
+and the error. The log is kept 30 days.
+
+Every attempt carries these headers:
+
+| header | |
+|---|---|
+| `X-Foldrun-Delivery` | the delivery's id, `dlv_…` — **the same on every attempt and every redelivery**. Dedupe on it: a receiver that took attempt 2 but timed out answering may see attempt 3 |
+| `X-Foldrun-Event` | `failed`, `completed`, `blocked`, `awaiting-approval`, `quarantined`, `sla`, `budget`, or `test` |
+| `X-Foldrun-Attempt` | 1, 2, … |
+| `X-Foldrun-Timestamp`, `X-Foldrun-Signature` | when `signing_secret:` is set — see below |
+
+The URL is read from `notify:` at each attempt, so fixing a typo in it is
+picked up by the next retry. The body is kept as first sent, so a retry is
+the same bytes.
+
+**Where to see it.** The workspace's Triggers page ends with *Outbound
+webhook deliveries*: every delivery, its status, its attempts, and a
+**Redeliver** button. From a terminal, `foldrun webhooks deliveries --to
+<ws>` (`--failed` for the ones that gave up) and `foldrun webhooks
+redeliver <id> --to <ws>`; over HTTP, `GET
+/api/workspaces/<ws>/notify/deliveries` and `POST
+…/deliveries/<id>/redeliver`. A redelivery is one attempt, now, with the
+same id and body, signed afresh. The log shows a gate's approve and
+reject links as `[redacted]`: they decide without a login, and every role
+can read the log. The receiver still gets them, on a redelivery too.
+
+**An endpoint that stays down is switched off.** When every attempt to a
+workspace's URL has failed for **3 days running** (the operator's
+`FOLDRUN_WEBHOOK_DISABLE_DAYS`), the next delivery to give up after all
+six attempts switches it off, and the platform emails the account's owner
+once. A first attempt that fails does not switch it off on its own, however
+old the last failure: its retries get their chance. Deliveries made while it is off are
+recorded as `skipped`, not attempted. To turn it back on, fix the receiver
+and press Redeliver, or send a test (`foldrun notify test --to <ws>`): the
+first accepted one switches it on. Changing the URL in `notify:` starts it
+fresh.
+
+A laptop install has no worker to retry from: there a webhook is one
+attempt, with the same headers, and no log.
+
+## Verifying a delivery
+
+With `signing_secret:` set, check every delivery before acting on it:
+
+1. Read `X-Foldrun-Timestamp` (Unix seconds) and refuse it when it is more
+   than five minutes from your clock — a captured delivery replayed later
+   carries an old one, and the timestamp is inside the signature, so it
+   cannot be swapped for a fresh one.
+2. Compute the hex HMAC-SHA256 of `"<timestamp>.<raw body>"` with the
+   secret's value, and compare it to `X-Foldrun-Signature` after its
+   `sha256=` prefix, in constant time. Use the raw bytes of the body —
+   re-serialised JSON will not match.
+3. Dedupe on `X-Foldrun-Delivery`.
+
+Node:
+
+```js
+import crypto from "node:crypto";
+
+export function verifyFoldrun(rawBody, headers, secret, toleranceSec = 300) {
+  const ts = headers["x-foldrun-timestamp"];
+  const sig = (headers["x-foldrun-signature"] ?? "").replace(/^sha256=/, "");
+  if (!ts || !sig) return false;
+  if (Math.abs(Date.now() / 1000 - Number(ts)) > toleranceSec) return false;
+  const want = crypto.createHmac("sha256", secret).update(`${ts}.${rawBody}`).digest("hex");
+  return sig.length === want.length && crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(want));
+}
+```
+
+Python:
+
+```python
+import hashlib, hmac, time
+
+def verify_foldrun(raw_body: bytes, headers, secret: str, tolerance=300) -> bool:
+    ts = headers.get("X-Foldrun-Timestamp")
+    sig = (headers.get("X-Foldrun-Signature") or "").removeprefix("sha256=")
+    if not ts or not sig or abs(time.time() - int(ts)) > tolerance:
+        return False
+    want = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body, hashlib.sha256).hexdigest()
+    return hmac.compare_digest(sig, want)
+```
+
+Answer 2xx as soon as it is verified and recorded; do the work after. A
+receiver that takes longer than 8 seconds is counted as failed and is
+sent the delivery again.
+
+## Approve and reject links
+
+A run parked on a person sends its notification with two links per waiting
+step — `links` carries every pair, `approveUrl`/`rejectUrl` the first.
+Clicking one opens a page that shows what is waiting and asks for the
+decision — it never decides on the GET, because inbox link-checkers follow
+links. The token in a link is bound to that one step, to a moment (the
+flow's `approve_within:`, else a week), and — when the mail went to an
+address in the flow's `approvers:` — to that person, so a forwarded mail
+decides as nobody. It is derived, never stored; a key rotation kills every
+old link at once, and a link that has decided is spent. A `wait: event` park
+gets no link: it is waiting for a machine.
+
+The links exist only when the install knows its own public address
+(`FOLDRUN_PUBLIC_URL`). Without it the notification goes out without them and
+the run is approved from the dashboard.
+
+## Email
+
+Notification email is **your mail**: a desk telling its owner what it
+found comes from the sender you chose. Set `RESEND_API_KEY` and
+`EMAIL_FROM` as account secrets — the same key an email tool of your own
+would use — and every notification goes out through your key, from your
+address, under your domain's reputation and your inbox's rules. `EMAIL_FROM`
+must be an address the Resend account behind that key may send from (a
+verified domain, or Resend's onboarding sender for testing).
+
+An account that has set neither still gets its notifications: they fall
+back to the platform's connection and come from `foldrun <hello@foldrun.io>`.
+An invite and a low-balance warning are the platform's own mail and always
+come from foldrun; the platform never sends those through your key.
+
+## Choosing what mail you get
+
+Every mail the platform sends belongs to a category, and each person
+chooses which they take — under **Profile → Notifications**, with `foldrun
+notifications` / `foldrun notifications set <category> on|off`, or through
+`GET`/`PATCH /api/me/notifications`. The choice is asked at the moment of
+sending, so it holds for every mail, from every part of the platform.
+
+| category | what | can be turned off |
+|---|---|---|
+| `security` | password resets, email confirmations, a login moved, an account made for you | no |
+| `invites` | an invitation to join an account | no |
+| `billing` | a payment failed, and the grace before runs stop | no |
+| `account` | a notification webhook switched off after days of failures; a close request | no |
+| `run-alerts` | a workspace's `notify:` email: failed, completed, blocked, quarantined, `sla`, `budget` | yes — per workspace |
+| `approvals` | a run waiting for you, with approve and reject links | yes — per workspace |
+| `low-balance` | credits below the warning level | yes |
+| `product-updates` | what changed in foldrun | yes |
+
+The four that cannot be turned off are how you get back into the account
+and how you hear that something you rely on has stopped; the page shows
+them, switched on and locked, with that reason. `run-alerts` and
+`approvals` can be off for one workspace and on for the rest (`foldrun
+notifications set run-alerts off --to seo-desk`).
+
+**Unsubscribing from a mail.** Every mail in an optional category carries a
+one-click unsubscribe, as RFC 8058 describes: `List-Unsubscribe:
+<https://…/api/unsubscribe?token=…>` and `List-Unsubscribe-Post:
+List-Unsubscribe=One-Click`, so the mail client's own Unsubscribe button
+works, plus a "Stop …" link at the bottom that opens a page asking first
+(opening a link never unsubscribes — inbox scanners open links). The token
+is signed by the install, names one address, one category and — for run
+alerts and approvals — one workspace, and works for 180 days. No login is
+needed, and the address need not belong to anyone with one: a `notify:
+email` that reaches a shared inbox can be unsubscribed by whoever reads it.
+A choice made this way shows on that person's Profile → Notifications, and
+is turned back on there.
+
+The links need the install to know its public address
+(`FOLDRUN_PUBLIC_URL`); without it mail goes out without them, and
+preferences are still honoured.

package/docs/providers.md

@@ -0,0 +1,241 @@
+# Providers, by name
+
+What `provider: { name: … }` resolves to. Mirrors `foldrun-core/src/providers.ts`,
+checked against each provider's own documentation on 2026-09-02 and again on
+2026-09-06; the table below is what the runtime believes, and
+`tests/providers.test.ts` fails if a name exists in the code and not here.
+
+**Three formats.** `anthropic` endpoints are spoken to directly. `openai`
+endpoints (Chat Completions) and `responses` endpoints (OpenAI's newer
+Responses API) are reached through the runtime's own translator, a loopback
+server inside the run sandbox that lives for one step — the same server,
+a second pair of mappings. No preset defaults to `responses`; a block asks
+for it by name (`name: openai` + `format: responses`). **Verified**
+means a tool loop was actually driven through the endpoint from this
+runtime. A name without it is **documented, not proven**: the address, wire
+format and header shape were read from the provider's own documentation and
+nobody here has watched an agent complete a run against it. Run
+`foldrun probe <model>` before a flow depends on one.
+
+Today that is **3 of 29**: only `anthropic`, `openrouter` and `openai` have
+ever run an agent from this runtime. Those counts and every `verified` mark
+in the table are checked against the code by `tests/providers.test.ts` — the
+figure above went stale once already, which is exactly the kind of claim
+that should not be maintained by hand.
+
+`params:` on the provider block reaches only `openai`- and `responses`-format
+endpoints, where the translator builds the request. An `anthropic`-shaped endpoint is spoken to
+directly by the SDK, so its knobs are set at the provider (an OpenRouter
+preset, say); the file warns if you try.
+
+| name | provider | format | base URL | key header | verified | note |
+|---|---|---|---|---|---|---|
+| `anthropic` | Anthropic | anthropic | `https://api.anthropic.com` | x-api-key | yes | Models newer than Opus 4.6 reject `top_k` with a 400; the runtime never sends it unless a `params:` block does. |
+| `openrouter` | OpenRouter | anthropic | `https://openrouter.ai/api` | bearer | yes | Hundreds of models behind one key. Its own docs disagree on how well non-Anthropic models hold a tool loop on this endpoint — probe the model you mean to use. |
+| `deepseek` | DeepSeek | anthropic | `https://api.deepseek.com/anthropic` | x-api-key |  | Ignores top_k, cache_control and thinking budgets; Claude model names are remapped to DeepSeek's. |
+| `kimi` | Moonshot Kimi | anthropic | `https://api.moonshot.ai/anthropic` | bearer |  | Own model ids only. Known bug (2026-09): K3 reuses one `tool_use` id across separate calls, which breaks a tool loop. |
+| `moonshot` | Moonshot Kimi | anthropic | `https://api.moonshot.ai/anthropic` | bearer |  | Same endpoint as `kimi`. |
+| `zai` | z.ai (GLM) | anthropic | `https://api.z.ai/api/anthropic` | bearer |  |  |
+| `minimax` | MiniMax | anthropic | `https://api.minimax.io/anthropic` | bearer |  |  |
+| `qwen` | Alibaba Qwen (Model Studio) | anthropic | `(per plan — set base_url)` | x-api-key |  | base_url depends on the plan: pay-as-you-go `https://<workspace>.<region>.maas.aliyuncs.com/apps/anthropic`; Coding Plan `https://coding-intl.dashscope.aliyuncs.com/apps/anthropic`. Own model ids, no remap; no `reasoning_effort`, use thinking. |
+| `fireworks` | Fireworks AI | anthropic | `https://api.fireworks.ai/inference` | bearer |  | No server-side tools; no adaptive thinking. |
+| `deepinfra` | DeepInfra | anthropic | `https://api.deepinfra.com/anthropic` | bearer |  |  |
+| `sambanova` | SambaNova | anthropic | `https://api.sambanova.ai` | x-api-key |  | No server-side tools, base64 images only. |
+| `vercel` | Vercel AI Gateway | anthropic | `https://ai-gateway.vercel.sh` | bearer |  | Model ids are namespaced, e.g. openai/gpt-5. |
+| `litellm` | LiteLLM (yours) | anthropic | `(per account — set base_url)` | x-api-key |  | base_url is your proxy, e.g. http://litellm.internal:4000. It presents an Anthropic endpoint and speaks anything behind it. |
+| `cloudflare-gateway` | Cloudflare AI Gateway | anthropic | `(per account — set base_url)` | x-api-key |  | base_url is https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/anthropic — a pass-through to Anthropic with logging; for Cloudflare's own models use name: cloudflare. |
+| `ollama` | Ollama (local) | anthropic | `http://localhost:11434` | x-api-key |  | v0.14+ (2026-01). Ignores `tool_choice` and `cache_control`; accepts but does not enforce thinking budgets; base64 images only. Any key value is accepted. |
+| `lmstudio` | LM Studio (local) | anthropic | `http://localhost:1234` | x-api-key |  |  |
+| `vllm` | vLLM (yours) | anthropic | `(per account — set base_url)` | bearer |  | base_url is your server (default :8000). Start it with `--enable-auto-tool-choice` and a `--tool-call-parser` or no tool loop closes. |
+| `openai` | OpenAI | openai | `https://api.openai.com/v1` | bearer | yes | Chat Completions by default, which OpenAI keeps supporting indefinitely. Add `format: responses` for the Responses API ("recommended for all new projects"): PDFs cross as input files and `reasoning.effort` is native; still every turn carries the whole conversation. |
+| `gemini` | Google Gemini | openai | `https://generativelanguage.googleapis.com/v1beta/openai` | bearer |  | Google's OpenAI-compatible route. Unknown parameters are ignored silently; reasoning cannot be switched off on the newest models. |
+| `xai` | xAI Grok | openai | `https://api.x.ai/v1` | bearer |  | Sends `max_completion_tokens` and `reasoning_effort`. |
+| `groq` | Groq | openai | `https://api.groq.com/openai/v1` | bearer |  | Sends `max_completion_tokens` and `reasoning_effort`. |
+| `mistral` | Mistral | openai | `https://api.mistral.ai/v1` | bearer |  |  |
+| `together` | Together AI | openai | `https://api.together.ai/v1` | bearer |  |  |
+| `cerebras` | Cerebras | openai | `https://api.cerebras.ai/v1` | bearer |  | Sends `max_completion_tokens` and `reasoning_effort`. |
+| `huggingface` | Hugging Face | openai | `https://router.huggingface.co/v1` | bearer |  | The Inference Providers router; model ids are Hub ids, e.g. meta-llama/Llama-3.3-70B-Instruct. |
+| `cloudflare` | Cloudflare Workers AI | openai | `(per account — set base_url)` | bearer |  | base_url is https://api.cloudflare.com/client/v4/accounts/<account>/ai/v1 |
+| `nebius` | Nebius Token Factory | openai | `https://api.tokenfactory.nebius.com/v1` | bearer |  |  |
+| `novita` | Novita | openai | `https://api.novita.ai/openai` | bearer |  | Also has an Anthropic-shaped route at `https://api.novita.ai/anthropic` — spell it out with `format: anthropic` to skip the translator (header shape unverified). |
+| `hyperbolic` | Hyperbolic | openai | `https://api.hyperbolic.xyz/v1` | bearer |  |  |
+
+**Not on the list, and why.** Vertex AI puts the model in the URL, so a base
+URL alone cannot reach it; Bedrock's legacy InvokeModel streams AWS events, not
+SSE — both are enterprise arrangements with their own gateways. xAI documents
+no Anthropic-shaped route (an earlier note that it was deprecated traced only
+to an unofficial mirror), so xAI is reached as `openai`. GitHub Models retired
+on 2026-07-30. OpenAI's Assistants API sunset on 2026-08-26 and was never
+targeted. Perplexity was removed on 2026-09-06: its Sonar chat route sunsets
+on 2026-09-27 ("Sonar will be supported until September 27, 2026") and the
+successor Agent API is not Chat-Completions-shaped, so there is nothing to
+spell out for it.
+
+**Chat Completions vs Responses.** Every non-OpenAI vendor in the `openai`
+rows speaks Chat Completions and none has retired it — OpenAI says it will
+support Chat Completions indefinitely; what it retires is the Assistants API
+(26 August 2026). Chat Completions stays the translation that reaches
+everyone. `format: responses` (added 2026-09-07) speaks the Responses API for
+the endpoints that have it — OpenAI, and xAI, Groq, Nebius, Cloudflare in
+various states of beta. What it carries that Chat Completions cannot: a
+`document` block crosses as an `input_file`, so a PDF an agent reads reaches
+the model instead of being dropped; `reasoning.effort` is the native knob;
+`store: false` is sent so nothing is kept on the provider's side. What it
+does not do: OpenAI's server-side tools (web search, file search, code
+interpreter) are still dropped — tools run on the box for every model —
+and `previous_response_id` is not used, so every turn carries the whole
+conversation, as it does everywhere else. Mapped against the shapes in
+OpenAI's own SDK (`openai@6`, `resources/responses`) and driven live on
+2026-09-07 through OpenRouter's Responses route (`base_url:
+https://openrouter.ai/api/v1`, `format: responses`): `foldrun probe
+openai/gpt-4o-mini` closed a streamed tool loop — tool call made, result
+read back, three requests, $0.0057. Then against OpenAI's own endpoint
+(`name: openai`, `format: responses`, no `base_url`) the same day:
+`gpt-4o-mini` closed the loop for $0.0059 and `gpt-5-mini` for $0.0311. The
+origin found two things the gateway had hidden: `safety_identifier` is
+capped at 64 characters, so a long tenant id is now sent hashed; and a
+model that does not reason (`gpt-4*`, `gpt-3*`, `chatgpt-*`, `gpt-5-chat-*`)
+refuses `reasoning.effort` outright — the translator leaves the knob off for
+those families on both wires and says so in the drop line. Every other id
+keeps it, because a gateway ignores a field it cannot use and an o-series,
+gpt-5, grok or deepseek-r model wants it.
+
+## Why a turn stopped
+
+Every model reply ends with a stop reason, and the model loop acts on it: run
+the tool, carry on, or stop. An Anthropic-shaped endpoint sends its own. For a
+translated one the translator reads what the provider said and gives the
+closest Anthropic word, because the loop only understands those:
+
+| stop reason | Chat Completions (`format: openai`) | Responses (`format: responses`) |
+|---|---|---|
+| `end_turn` | `stop`, or anything unrecognised | a completed response |
+| `max_tokens` | `length` | `incomplete_details.reason: max_output_tokens` |
+| `tool_use` | `tool_calls`, `function_call`, or any reply carrying a tool call | any reply carrying a function call |
+| `stop_sequence` | `stop` plus the matched string — vLLM's `stop_reason`, SGLang's `matched_stop` — when it is one of the request's `stop_sequences` | never: the Responses API has no stop sequences, and they are dropped |
+| `refusal` | `content_filter` (OpenAI, Azure, Gemini's safety block) | a `refusal` content part, or `incomplete_details.reason: content_filter` |
+| `model_context_window_exceeded` | Mistral's `model_length` | never: a full context is a 400 there, and the error crosses as one |
+| `pause_turn` | never | never — it belongs to Anthropic's server-side tools, which the translator drops |
+
+A cut-off reply beats a tool call: a `length` finish with half a tool call
+in it reads as `max_tokens`, so the loop does not run a truncated call. A
+refusal beats everything. Plain OpenAI says `stop` whether the model finished
+or hit a stop sequence, so on OpenAI itself a stop sequence reads as
+`end_turn`.
+
+`foldrun probe` prints the stop reason the model ended on. A healthy probe
+says `end_turn`; `max_tokens`, `refusal` or `model_context_window_exceeded`
+there names the failure a run would hit the same way.
+## Verified 2026-09-02
+
+The translator itself was driven end to end from `foldrun probe` against
+OpenRouter's Chat-Completions route (`format: openai`,
+`base_url: https://openrouter.ai/api/v1`) — the one OpenAI-shaped endpoint we
+hold a key for. A tool loop closed, streamed, on:
+
+| model | tool call | result read back | cost |
+|---|---|---|---|
+| `openai/gpt-4o-mini` | yes | yes | $0.0058 |
+| `meta-llama/llama-3.3-70b-instruct` | yes | yes | $0.0073 |
+
+`google/gemini-2.5-flash` was refused with a 402 by OpenRouter — the key's
+weekly limit could not reserve the 32,000 `max_tokens` the model loop asks
+for — and that refusal arrived as a well-formed Anthropic error with the
+provider's own words, which is the pass-through working. Gemini's own
+endpoint (`name: gemini`) awaits a Google key.
+
+## Is the key still good?
+
+A key can be revoked, expire, run out of credit or have its endpoint moved,
+and the platform used to find that out the way you would: a desk failing at
+five in the morning.
+
+Once a day, every provider block this account's files actually use — the
+account's, each workspace's, each agent's — is asked one minimal question:
+a single request, one token of output, at the endpoint a run would use, with
+the key a run would send. It costs a fraction of a cent, and a year of it
+costs less than one ordinary run. Blocks sharing an endpoint and a key are
+checked once, because they are one credential.
+
+This is not `foldrun probe`. That asks whether a model can drive an agent,
+which is a question about a model and is asked once. This asks whether an
+endpoint still takes your key, which is a question about a credential and
+has to be asked over and over — so it has to be cheap.
+
+| verdict | what it means |
+|---|---|
+| ok | the key was accepted and the model answered |
+| busy | rate limited, which means the key is fine — never reported as a fault |
+| credential | 401, 402 or 403: revoked, rotated, wrong for this endpoint, or out of credit |
+| not-found | the endpoint or the model id does not exist there — check `base_url` and `models:` |
+| unreachable | no answer, or a `base_url` that is not a URL |
+| provider-error | failing at their end |
+
+Only a newly broken provider is reported. A key that was dead yesterday and
+is dead today is not news, and an alert that arrives every morning is an
+alert people filter. `GET /api/account/providers` shows the last check and
+what would be checked; `POST` forces one, for the minute after rotating a
+key. From the terminal, `foldrun account providers` prints the same table
+(✓, ✗ with the verdict, or · for never checked) and `--check` forces one;
+a dead key is a non-zero exit, so a deploy script can refuse to continue.
+
+## When a provider says no, the run says why
+
+A refused model call used to leave two facts in the record and neither was
+the reason:
+
+```
+egress: POST api.anthropic.com/v1/messages → 401 × 4 [FOLDRUN_MODEL_KEY]
+API Error: 402 This request would exceed your available credits
+```
+
+That is a status code and a sentence written by an SDK. The actual cause —
+the subscription's five-hour window part used, with overage switched off for
+lack of credits, a state that clears by itself at a known minute — was in
+the response headers all along, and nothing read them.
+
+Now it does. On a refusal (401, 402, 403, 429) foldrun keeps the
+`anthropic-ratelimit-unified-*` headers and `retry-after` from that one
+response, and writes one line into the step's trace and onto the step's
+failure line — the line the run record shows, the desks' headlines quote and
+`foldrun report` reads:
+
+```
+the subscription refused this burst — the 5-hour window is 35% used but
+overage is off (out of credits); it resets at 14:00 Sydney — no second
+supply is configured
+```
+
+Reset times are told in the step's own timezone, resolved by the usual
+cascade (agent → flow → workspace → account → `FOLDRUN_TIMEZONE` → UTC), so
+a run scheduled in Sydney is not told when its quota returns in UTC.
+
+Three things the line is careful about:
+
+**A spent window is not a dead key.** A refusal that carries rate-limit
+headers is the supply — wait, or add credits. A 401 or 403 carrying *no*
+rate-limit headers at all is the credential itself, and says so:
+
+```
+the credential was refused (HTTP 401) and the response carried no
+rate-limit headers, so this is the key itself — invalid, revoked, or wrong
+for this endpoint — not a spent window
+```
+
+The two used to read identically, which is how an hour goes into proving a
+valid key was valid.
+
+**A wait is a number.** A 429 that named `retry-after` says how long — `and
+asked us to wait 30s` — and one that named nothing says that instead of
+implying a wait nobody promised.
+
+**Where the step can go next is part of the sentence.** Every refusal line
+ends with one of three states: `trying the second supply`, `the second
+supply refused it too`, or `no second supply is configured`. The last is a
+deliberate arrangement, not a gap — a workspace with one provider and no
+fallback is a normal thing to run — and it is said out loud so a step never
+ends in silence over it.
+
+Nothing else from the response's headers is kept. The list is an allow-list
+of the rate-limit headers above, not a prefix match, and no request header —
+so no credential — is read at all.