foldrun 13.1.1 → 13.2.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/api.md +1 -1
- package/docs/cli.md +1 -1
- package/docs/faq.md +1 -1
- package/docs/providers.md +5 -1
- package/package.json +1 -1
- package/src/commands.mjs +2 -2
package/docs/api.md
CHANGED
|
@@ -360,7 +360,7 @@ Reads return which secrets exist, never their values.
|
|
|
360
360
|
| `/api/team/transfer` | POST | hand the account to a member (`to`) — owner only, signed in, and re-proving it is them: `password` (the current one) and, when two-step sign-in is on, `code` (from the app, or a backup code). 400 without them, 401 when wrong, 6 tries in 15 minutes. You become an admin |
|
|
361
361
|
| `/api/usage/compute` | GET | the account's compute at every level (27 Oct 2026): `compute` is `{ vcpu, memGiB, diskGiB, stepVcpu, stepMemGiB, stepDiskGiB, source }` — the cores, GiB and GiB of disk all its running steps may hold together, the most one step may hold (each `null` for no cap), and where the pool came from (`plan`, `account` — its own `compute:` in AGENTS.md, which can only lower it — `install`, or `null`); `inUse` is `{ vcpu, memGiB, diskGiB, steps }`, what its running steps' sandboxes hold now, from their records (a step still waiting for room holds nothing; a caller scoped to some workspaces sees theirs); `workspaces` is each workspace's own `pool` (its AGENTS.md `compute:`, `null` figures for none) and `inUse`; `runs` is each live run with a pool of its own (its flow's `compute:`) or anything held, `{ workspace, runId, flow, pool, inUse }`; `waiting` lists the steps waiting for room, oldest first — `{ workspace, runId, flow, step, agent, since, why, cpus, memGiB, diskGiB, level?, runPool }`, `since` being when it first found none, its place in line, and `level` the cap that held it when it last looked. A step past any level waits, with no time limit, and starts in turn; one bigger than a level's whole cap or the step maximum fails at once ([four levels](budgets-and-billing#compute-at-four-levels), [waiting for room](budgets-and-billing#waiting-for-room)) |
|
|
362
362
|
| `/api/usage/history?days=` | GET | charged spend by flow, by agent and by workspace over time, read from the ledger rather than the run records — so it survives runs being pruned and reports what was billed rather than what was consumed. Buckets by week over three weeks, by day under. Each series carries its periods, its total, and the change between the last two COMPLETE periods, so a partial week never reads as a collapse. `unattributedUsd` is charges from before a line recorded its flow. A caller scoped to some workspaces sees only the charges in those; `days` 1–365, default 56 |
|
|
363
|
-
| `/api/account/model` | GET, PUT, DELETE | what every step runs on unless an agent, workspace or the account's AGENTS.md names a `provider:` — the account's own model key, or foldrun's models (the platform's keys for one provider, billed in credits at foldrun's price list; hosted only). GET: `{ set, provider, baseUrl, format, keyHint, runsOn, platformKeyAllowed, source, supply, choiceVersion, foldrunModels }` — never a key, only its last four characters; `runsOn` is `account` (its own key), `foldrun` (foldrun's models for `supply`), `platform` (the platform's credential, for the operator's accounts) or `none` (runs are refused until a key is set); `foldrunModels` is `{ offered, refused, providers: [{ name, title, available, reason, tiers }], prices: [{ provider, model, inputPerMTok, outputPerMTok, cacheReadPerMTok, cacheWritePerMTok }], dailyCapUsd, spentTodayUsd }`, the money in what the account pays. PUT `{ source: "foldrun", supply, ifVersion? }` chooses foldrun's models (`supply`: anthropic, openai, gemini or
|
|
363
|
+
| `/api/account/model` | GET, PUT, DELETE | what every step runs on unless an agent, workspace or the account's AGENTS.md names a `provider:` — the account's own model key, or foldrun's models (the platform's keys for one provider, billed in credits at foldrun's price list; hosted only). GET: `{ set, provider, baseUrl, format, keyHint, runsOn, platformKeyAllowed, source, supply, choiceVersion, foldrunModels }` — never a key, only its last four characters; `runsOn` is `account` (its own key), `foldrun` (foldrun's models for `supply`), `platform` (the platform's credential, for the operator's accounts) or `none` (runs are refused until a key is set); `foldrunModels` is `{ offered, refused, providers: [{ name, title, available, reason, tiers }], prices: [{ provider, model, inputPerMTok, outputPerMTok, cacheReadPerMTok, cacheWritePerMTok }], dailyCapUsd, spentTodayUsd }`, the money in what the account pays. PUT `{ source: "foldrun", supply, ifVersion? }` chooses foldrun's models (`supply`: anthropic, openai, gemini, deepseek or moonshot; a provider the platform cannot serve now, or an account refused them, is a 409; a stale `ifVersion` is a 409); `{ source: "own" }` goes back to the account's own key; a key alone never changes the choice; audited as model.source_set. PUT `{ provider, apiKey, baseUrl?, format? }` (needs `secrets:write`, as does the choice): `provider` is a preset name (anthropic, openrouter, openai, groq, … — see providers) or `custom` with an https `baseUrl` and a `format` (anthropic or openai); a Claude login token (sk-ant-oat…) is refused for any account not allowed the platform's credential. Stored as the account secrets `FOLDRUN_MODEL_PROVIDER`, `FOLDRUN_MODEL_API_KEY`, `FOLDRUN_MODEL_BASE_URL`, `FOLDRUN_MODEL_FORMAT`. DELETE removes them (the choice stays). Honours Idempotency-Key on PUT; audited as model.key_set / model.key_removed |
|
|
364
364
|
| `/api/account/providers` | GET, POST | GET: the model providers this account's files actually use — each one's preset name, where it is declared, the model a check would send — plus the last daily health check. POST forces one now, which spends one minimal request at each distinct endpoint, and needs the permission that runs and every workspace. A member or key scoped to some workspaces sees the account's provider blocks and its own workspaces' only, in `configured` and in the last check |
|
|
365
365
|
| `/api/usage` | GET | what has been spent, by meter; each bucket's tokens are `inputTokens` (all input), `outputTokens`, `cacheReadTokens` and `cacheWriteTokens` (the part of the input the prompt cache served and stored), and `cacheHitRate` — reads over `measuredInputTokens`, the input of steps that report the split, `null` when none do. A key or member scoped to some workspaces sees those workspaces, and totals over them; `ledger` is the account's `balanceUsd` and `chargedUsd` (all time), and `waived` the legs the account is not charged for — both `null` to a caller scoped to some workspaces, since they are the whole account's money. Since API version `2026-10-26` nothing else; earlier pins see `providerCostUsd` and `marginUsd` as `null` |
|
|
366
366
|
| `/api/approvals` | GET | every gate waiting on a person, across workspaces — one entry per waiting **step** (`workspace`, `runId`, `flow`, `step`, `agent`, `question`, `asked`, `waitingSince`), oldest first. By step status, not run status: a decided gate leaves the list at once, before the worker resumes the run. `wait: event` steps are not listed; no button answers them. Beside it, `questions`: every question an agent is asking mid-step in a running run (`kind: "question"`, `id`, `workspace`, `runId`, `flow`, `agent`, `question`, `options?`, `askedAt`) — answered with `…/runs/<id>/answer` |
|
package/docs/cli.md
CHANGED
|
@@ -160,7 +160,7 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
160
160
|
| `foldrun gallery` | the tools the platform ships to every account (`web`), and for each whether this account keeps its own copy and whether that copy still matches. `pull` lays the shelf down under `~/.foldrun/gallery/<host>/` for offline runs (`foldrun run` and `foldrun eval` refresh it themselves before each run); `upgrade <tool>` replaces the account's copy with the current gallery version, the old one a revision back |
|
|
161
161
|
| `foldrun identity` | keyless cloud identity: the issuer your cloud must trust and the subject each agent's tokens carry (`GET /api/identity`); `--to <workspace>` fills the workspace in, `--json` |
|
|
162
162
|
| `foldrun jobs` | the four jobs — governance, guardrail, observability, evaluation — and every `AGENTS.md` field of each, with what is set (`GET /api/account/jobs`). `--to <workspace>` shows the workspace's value beside the account's and how the two combine; `--json` the document. `account set <job>.<field>` and `workspace set <job>.<field>` refuse a field that scope cannot set and name the `AGENTS.md` to write it in. See [The four jobs](four-jobs) |
|
|
163
|
-
| `foldrun account` | the account's own defaults — the AGENTS.md frontmatter every workspace under it inherits: `timezone`, `notify`, `budget`, `concurrency`, `deploy_block`, `network_enforce`. `foldrun account set timezone Australia/Sydney`, `set notify email you@example.com` (`--events failed,awaiting-approval,completed`), `set notify url https://…`, `set budget 60/month`, `set concurrency 4`, `set compute vcpu 4 memory 8 disk 40` (GiB; any of them, merged over what is set — the account's own pool, lower than the plan's), `set deploy_block secrets` (`none`, `secrets` or `security` — what the scanner's findings do to a deploy), `set network_enforce on` (every workspace refuses a site off an agent's `network:` list; `off` reports only), `set owner <email or name>`, `set alerts <threshold> <value>` (merged into what is set; `off` removes one), `set judge model|effort <value>`. Any setting may be named by its job — `set governance.deploy_block secrets`, `set observability.alerts stale_days 30` — and one named under the wrong job is refused with the right one, `pause` (`--reason "…"`, `--stop` to also stop every run going now — asks, or `--yes`) and `resume`: the kill switch, no new run starts in any workspace while paused, `telemetry` — where each finished run goes as an OpenTelemetry trace: bare shows it, `set <url> --header authorization='${OTEL_TOKEN}'` (repeatable; a value is a vault secret's name), `clear`, `test` (one made-up run, and what the collector answered; exit 1 when not delivered), and `clear <key>` to unset one. `set notify` merges against what is there, because the platform replaces the whole block. `providers` lists the model providers the account's files use and the last daily key check — `--check` asks now, and a dead key is a non-zero exit. `model` is what every step runs on unless a `provider:` block names another — the account's own model key, or foldrun's models: `foldrun account model` shows it (never a key, only its last four; on foldrun's models, the provider, its tier map and today's spend against the daily cap; exit 1 when runs are refused — no key, or foldrun's models refused for the account), `model set <provider> --key <api key>` sets the key — a preset name (anthropic, openrouter, openai, groq, …) or `custom --base-url https://… --format anthropic|openai`, `--key -` reads the key from stdin — and `model remove` removes it (the choice stays); a Claude login token is refused for any account not allowed the platform's own credential. `model use foldrun --provider <anthropic|openai|gemini|
|
|
163
|
+
| `foldrun account` | the account's own defaults — the AGENTS.md frontmatter every workspace under it inherits: `timezone`, `notify`, `budget`, `concurrency`, `deploy_block`, `network_enforce`. `foldrun account set timezone Australia/Sydney`, `set notify email you@example.com` (`--events failed,awaiting-approval,completed`), `set notify url https://…`, `set budget 60/month`, `set concurrency 4`, `set compute vcpu 4 memory 8 disk 40` (GiB; any of them, merged over what is set — the account's own pool, lower than the plan's), `set deploy_block secrets` (`none`, `secrets` or `security` — what the scanner's findings do to a deploy), `set network_enforce on` (every workspace refuses a site off an agent's `network:` list; `off` reports only), `set owner <email or name>`, `set alerts <threshold> <value>` (merged into what is set; `off` removes one), `set judge model|effort <value>`. Any setting may be named by its job — `set governance.deploy_block secrets`, `set observability.alerts stale_days 30` — and one named under the wrong job is refused with the right one, `pause` (`--reason "…"`, `--stop` to also stop every run going now — asks, or `--yes`) and `resume`: the kill switch, no new run starts in any workspace while paused, `telemetry` — where each finished run goes as an OpenTelemetry trace: bare shows it, `set <url> --header authorization='${OTEL_TOKEN}'` (repeatable; a value is a vault secret's name), `clear`, `test` (one made-up run, and what the collector answered; exit 1 when not delivered), and `clear <key>` to unset one. `set notify` merges against what is there, because the platform replaces the whole block. `providers` lists the model providers the account's files use and the last daily key check — `--check` asks now, and a dead key is a non-zero exit. `model` is what every step runs on unless a `provider:` block names another — the account's own model key, or foldrun's models: `foldrun account model` shows it (never a key, only its last four; on foldrun's models, the provider, its tier map and today's spend against the daily cap; exit 1 when runs are refused — no key, or foldrun's models refused for the account), `model set <provider> --key <api key>` sets the key — a preset name (anthropic, openrouter, openai, groq, …) or `custom --base-url https://… --format anthropic|openai`, `--key -` reads the key from stdin — and `model remove` removes it (the choice stays); a Claude login token is refused for any account not allowed the platform's own credential. `model use foldrun --provider <anthropic|openai|gemini|deepseek|moonshot>` runs every step on foldrun's models — the platform's keys, billed in credits at foldrun's price list, hosted only; a provider the platform cannot serve now is refused — and `model use own` goes back to the account's own key, which is kept. `model prices` (`--provider <p>`, `--json`) lists foldrun's price list as the account pays it, USD per million tokens. `export` downloads everything the platform holds about the account — workspaces, runs, members and the whole ledger — as one JSON file (owner only; `--file <path>`, `--force`). Singular — `accounts` below is the list of logins on this machine |
|
|
164
164
|
| `foldrun workspace` | one deployed workspace's own settings (`--to <workspace>`): description, timezone, budget and notify, read from its `AGENTS.md` — unset means the account's. `set timezone <tz>`, `set budget 20/week`, `set compute vcpu 2 memory 4 disk 20` (this workspace's own pool, inside the account's; any of them), `set notify email <address>` / `set notify url <https://…>` (`--events`; merged with what the file says), `set network_enforce on` (refuse a site off an agent's `network:` list here; `off` or `clear` goes back to the account's), `set owner`, `set alerts <threshold> <value>`, `set judge model|effort <value>`, and `<job>.<field>` as on `account`, `pause` (`--reason`, `--stop`) and `resume` — this workspace's kill switch, `set description "…"`, `set name <new>` — a rename changes every webhook URL, so it asks first and names the flows whose URLs changed — and `clear <key>`. Singular — `workspaces` is the list |
|
|
165
165
|
| `foldrun workspace vocabulary` | what the dashboard's editor completes as you type in a workspace (`--to`): agents, flows, skills, tools, secrets (names only), scripts, document types and linkable documents (`GET …/vocabulary`; `--json`) |
|
|
166
166
|
| `foldrun notify test` | send one test notification to whatever the workspace's `notify:` resolves to, and print what happened — the provider's own words when it failed ("domain not verified"). Exits 1 when it did not go. `--to <workspace>` |
|
package/docs/faq.md
CHANGED
|
@@ -18,7 +18,7 @@ Chat Completions API — once for the whole account in Settings → Model
|
|
|
18
18
|
block — and the platform bills you nothing for those tokens. On a hosted
|
|
19
19
|
platform every account brings its own API key — Claude login tokens are not
|
|
20
20
|
accepted — or, on foldrun's own platform, chooses **foldrun's models**:
|
|
21
|
-
Anthropic, OpenAI, Gemini or
|
|
21
|
+
Anthropic, OpenAI, Gemini, DeepSeek or Moonshot Kimi on foldrun's keys, billed in credits
|
|
22
22
|
at foldrun's price list. See [Providers](providers).
|
|
23
23
|
|
|
24
24
|
**Can agents reach the internet?** Yes — the public internet, as themselves,
|
package/docs/providers.md
CHANGED
|
@@ -32,7 +32,7 @@ Tokens on your own key are billed by your provider, not by the platform
|
|
|
32
32
|
## foldrun's models
|
|
33
33
|
|
|
34
34
|
On foldrun's own hosted platform an account can run on **foldrun's keys**
|
|
35
|
-
instead of its own: Anthropic, OpenAI, Google Gemini or
|
|
35
|
+
instead of its own: Anthropic, OpenAI, Google Gemini, DeepSeek or Moonshot Kimi, one at a
|
|
36
36
|
time for the whole account. No provider account is needed; the tokens are
|
|
37
37
|
billed in credits at **foldrun's price list**
|
|
38
38
|
([budgets and billing](budgets-and-billing.md#foldruns-models)).
|
|
@@ -51,6 +51,10 @@ billed in credits at **foldrun's price list**
|
|
|
51
51
|
`foldrun account model prices`. Anthropic's tiers are the usual Claude
|
|
52
52
|
models. A model id written out in full runs only if the price list names
|
|
53
53
|
it; anything not listed is refused before the call is made.
|
|
54
|
+
- **Where each provider processes the prompt** is its own: DeepSeek in
|
|
55
|
+
the People's Republic of China (its privacy policy), Moonshot in
|
|
56
|
+
Singapore, the others as their own terms say. Choose the provider
|
|
57
|
+
your data may go to.
|
|
54
58
|
- **What is refused**, before anything is sent: a model not on the price
|
|
55
59
|
list; the provider's own paid tools (web search, code execution run by
|
|
56
60
|
the provider), priority service tiers, audio, more than one completion per
|
package/package.json
CHANGED
package/src/commands.mjs
CHANGED
|
@@ -6007,9 +6007,9 @@ async function accountModelCmd(url, positional, flags) {
|
|
|
6007
6007
|
out(await put({ source: "own" }));
|
|
6008
6008
|
return 0;
|
|
6009
6009
|
}
|
|
6010
|
-
if (source !== "foldrun") throw new Error("`foldrun account model use foldrun --provider <anthropic|openai|gemini|
|
|
6010
|
+
if (source !== "foldrun") throw new Error("`foldrun account model use foldrun --provider <anthropic|openai|gemini|deepseek|moonshot>` or `foldrun account model use own`");
|
|
6011
6011
|
const supply = typeof flags.provider === "string" ? flags.provider : positional[2];
|
|
6012
|
-
if (!supply) throw new Error("which provider? `foldrun account model use foldrun --provider anthropic` (anthropic, openai, gemini or
|
|
6012
|
+
if (!supply) throw new Error("which provider? `foldrun account model use foldrun --provider anthropic` (anthropic, openai, gemini, deepseek or moonshot — `foldrun account model prices` lists what each costs)");
|
|
6013
6013
|
const r = await put({ source: "foldrun", supply });
|
|
6014
6014
|
out(r);
|
|
6015
6015
|
return runnable(r) ? 0 : 1;
|