foldrun 25.1.3 → 25.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/bin/foldrun.mjs +5 -2
- package/docs/api-usage.md +2 -3
- package/docs/api.md +6 -5
- package/docs/budgets-and-billing.md +72 -22
- package/docs/cli.md +3 -1
- package/package.json +2 -2
- package/src/commands.mjs +120 -3
package/bin/foldrun.mjs
CHANGED
|
@@ -206,6 +206,8 @@ const HELP = `foldrun — agents are just folders
|
|
|
206
206
|
foldrun usage what the account consumed, and what it was charged week by week (--days <n>, --json)
|
|
207
207
|
foldrun usage --limit <n> how many rows of by flow and by agent (the most charged; default 10, 0 hides them)
|
|
208
208
|
foldrun usage compute cores, GiB and disk its running steps may hold — the account, each workspace, each live run — what they hold now, and the steps waiting for room (--json)
|
|
209
|
+
foldrun usage meters what the period used, meter by meter: vCPU, RAM, step disk, storage, network with quantity, rate and credits, the plan fee, each step size, the two credit pots, and tokens by provider and model — your own key at 0 credits (--since <day>, --until <day>, --json)
|
|
210
|
+
foldrun usage rates what each meter costs this account, its plan and the plans on offer, and the price list for foldrun's models (--json)
|
|
209
211
|
foldrun usage budget spend against each cap — the account's and each workspace's budget:, what is spent in its window (today, this week, this month) and how close it is (--to <workspace> for one, --json)
|
|
210
212
|
foldrun schedule every flow that fires on a clock, its cron line and the next times (--to <workspace>)
|
|
211
213
|
foldrun schedule tick fire whatever is due now — Settings' "Run scheduler now"
|
|
@@ -224,7 +226,7 @@ const HELP = `foldrun — agents are just folders
|
|
|
224
226
|
foldrun billing details who invoices are made out to — also set --name "…" --abn … --address "line1, city, state, postcode, AU" --email …
|
|
225
227
|
foldrun billing details set --clear-address | --clear-email | --clear-abn drop one from the invoice details, the rest kept
|
|
226
228
|
foldrun billing portal a link to Stripe's billing portal (owner only)
|
|
227
|
-
foldrun billing plans the plans, which one the account is on and this cycle's credits — also plan <id>, plan cancel, plan resume (asks first)
|
|
229
|
+
foldrun billing plans the plans (credits, storage, compute at once), which one the account is on and this cycle's credits — also plan <id>, plan cancel, plan resume (asks first)
|
|
228
230
|
foldrun billing top-up <usd> Stripe's checkout page for adding credit (owner only; --no-browser prints it)
|
|
229
231
|
foldrun billing card Stripe's page for saving a card for auto top-up (owner only)
|
|
230
232
|
foldrun gallery the platform's built-in tools (web, docs, video) and skills (modern-website, motion-video), and whether you keep your own copy — also pull (a copy for offline runs), upgrade <name>, --json
|
|
@@ -346,11 +348,12 @@ Options
|
|
|
346
348
|
--follow logs: keep tailing a live run (with --url: on the platform)
|
|
347
349
|
--status <s> runs, stop, rerun: only these statuses, comma-separated (failed, completed, awaiting-approval…)
|
|
348
350
|
--since <span> runs, stop, rerun: only runs started within 24h, 7d, 90m, 2w, or today (the last 24h)
|
|
351
|
+
--since <day> usage meters: the period's first UTC day, YYYY-MM-DD (default the first of this month)
|
|
349
352
|
--since <span> audit: entries from 24h, 7d, 30d ago, or a date (default 7d); --until <date> ends the window
|
|
350
353
|
--action <a> audit: one action (apikey.created) or a family (apikey, secret, member, support)
|
|
351
354
|
--actor <who> audit: one person or key — an email, key:<label>, support:<email>
|
|
352
355
|
--since <days> observe, triggers: the window in days (observe default 7 as the account Observe page, observe --to 30 as a workspace's; triggers 7); observe takes --days too
|
|
353
|
-
--until <span|date> stop, rerun (bulk): only runs started before then — 2h ago, or a date
|
|
356
|
+
--until <span|date> stop, rerun (bulk): only runs started before then — 2h ago, or a date; usage meters: the period's last UTC day (YYYY-MM-DD)
|
|
354
357
|
--verdict <v> runs: only completed runs whose summary leads with it — good, bad, quiet, blocked (comma-separated)
|
|
355
358
|
--q <words> runs: the runs page's text search — every word, any order, across id, flow, workspace, status, verdict, summary and failure; assistant history: search the conversations
|
|
356
359
|
--flow <name> export: that flow and everything it runs; runs, stop, rerun: only that flow's runs; flow add: the other flow a subflow step runs; flow draft: the existing flow to redraft
|
package/docs/api-usage.md
CHANGED
|
@@ -96,13 +96,12 @@ room: one for **the key or person** making it, one for **the whole account**
|
|
|
96
96
|
(three times the first). Reads (`GET`, `HEAD`) and writes count separately,
|
|
97
97
|
per one-minute window. Health, status and version reads
|
|
98
98
|
(`/api/healthz`, `/api/status`, `/api/version`), signing out and ending a
|
|
99
|
-
support view are never counted or refused
|
|
99
|
+
support view are never counted or refused; neither is the public `GET /api/pricing`:
|
|
100
100
|
|
|
101
101
|
| Plan | Reads / key | Writes / key | Reads / account | Writes / account |
|
|
102
102
|
|---|---|---|---|---|
|
|
103
|
-
| none (
|
|
103
|
+
| Free, none (self-hosted) | 300 | 60 | 900 | 180 |
|
|
104
104
|
| Starter | 600 | 120 | 1,800 | 360 |
|
|
105
|
-
| Creator | 1,200 | 240 | 3,600 | 720 |
|
|
106
105
|
| Pro | 3,000 | 600 | 9,000 | 1,800 |
|
|
107
106
|
| Scale | 6,000 | 1,200 | 18,000 | 3,600 |
|
|
108
107
|
|
package/docs/api.md
CHANGED
|
@@ -18,7 +18,7 @@ proof instead of a key: a token or signature (`/s/<token>`, `/api/hooks`,
|
|
|
18
18
|
`/api/billing/partner/…` (a storefront's signature),
|
|
19
19
|
`/api/billing/confirm`), the sign-in and recovery steps (`/api/auth/signup`,
|
|
20
20
|
`login`, `forgot`, `reset`, `verify`, `mfa/verify`, `session`, `/api/cli/login`,
|
|
21
|
-
`/api/cli/login/<id>`, `/api/cli/authorize` GET, `/api/oauth/callback`), `/api/healthz`, `/api/status`, `/api/status/history`, `/api/signup`, `/api/version` and `/api/openapi.json` — and an AI app's OAuth sign-in to `/api/mcp`: `/api/mcp/oauth/register` (open, as the protocol needs) and `/api/mcp/oauth/token` (its code and PKCE verifier, or its refresh token, are the proof).
|
|
21
|
+
`/api/cli/login/<id>`, `/api/cli/authorize` GET, `/api/oauth/callback`), `/api/healthz`, `/api/status`, `/api/status/history`, `/api/signup`, `/api/pricing`, `/api/version` and `/api/openapi.json` — and an AI app's OAuth sign-in to `/api/mcp`: `/api/mcp/oauth/register` (open, as the protocol needs) and `/api/mcp/oauth/token` (its code and PKCE verifier, or its refresh token, are the proof).
|
|
22
22
|
|
|
23
23
|
```
|
|
24
24
|
Authorization: Bearer <api-key> # machines. Settings → API keys
|
|
@@ -399,12 +399,13 @@ Reads return which secrets exist, never their values.
|
|
|
399
399
|
| `/api/team/invites/<id>` | DELETE | revoke an invite: its link stops working at once. `{ ok, revoked, invite }` — `revoked: false` when it was already revoked or expired; `404` for an id that is not this account's; `409` for one already accepted (remove the member instead). `team:manage`, a key included; a scoped caller only inside its scope, and an admin invite only by the owner. Audited as `member.invite_revoked` |
|
|
400
400
|
| `/api/team/members/<id>` | PATCH, DELETE | change a member's role (`role`) and/or which workspaces they may open (`workspaces`: names, or null for all); remove them. A session, or the person's own `foldrun login` key (acting as at most admin). Removing someone revokes the keys and pending invites they made and any invite still pending to their address; a lower role or fewer workspaces revokes the keys and invites that reach beyond their new standing. `404` for an id that is not a member, whatever the body |
|
|
401
401
|
| `/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 |
|
|
402
|
-
| `/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; `runsWaiting` is `{ waiting, limit, source, slots? }` — the account's runs waiting for their turn (`null` for a caller scoped to some workspaces) and the most before a new run is refused (`null`: no limit), `source` `install` (`FOLDRUN_MAX_WAITING_RUNS`) or `derived` (20 × `slots`, the runs it may drive at once, at least 50) ([how many runs may wait](budgets-and-billing#how-many-runs-may-wait)); `compute.stepDefault`, when present, names the step figures that are the hosted default for an account whose plan sets none. 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)) |
|
|
402
|
+
| `/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; `runsWaiting` is `{ waiting, limit, source, slots? }` — the account's runs waiting for their turn (`null` for a caller scoped to some workspaces) and the most before a new run is refused (`null`: no limit), `source` `install` (`FOLDRUN_MAX_WAITING_RUNS`), `plan` (the account's plan sets it: Free 20, Starter 100, Pro 400, Scale 1,000, defaults the owners confirm) or `derived` (20 × `slots`, the runs it may drive at once, at least 50) ([how many runs may wait](budgets-and-billing#how-many-runs-may-wait)); `compute.stepDefault`, when present, names the step figures that are the hosted default for an account whose plan sets none. 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)) |
|
|
403
403
|
| `/api/usage/budget` | GET | spend against the caps, as the Spend limits page shows it (5 Nov 2026): `account` is the account's own `budget:` — `{ budget, label, spentUsd, window }`, `budget` being `{ usd, period }` or `null` for no limit, `label` `"$60/day"` or `null`, `spentUsd` what every workspace together has spent in the cap's window (the month's with no cap) and `window` `today`, `this week` or `this month`; `workspaces` is each workspace's the same way with its name as `workspace`, most spent first. A caller scoped to some workspaces sees those, and gets `account: null` with `accountHidden: true` — the account's figure is spend over every workspace. At the cap new runs are refused until the window turns ([four caps](budgets-and-billing#four-caps)) |
|
|
404
404
|
| `/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 |
|
|
405
405
|
| `/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 |
|
|
406
406
|
| `/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 |
|
|
407
|
-
| `/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` |
|
|
407
|
+
| `/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`. `?from=YYYY-MM-DD&to=YYYY-MM-DD` (UTC days; default the month so far; at most a year; anything else is a 400) bound four blocks, which answer every call (7 Nov 2026): `period` (`from`, `to`); `credits`, `{ pots: { planUsd, boughtUsd }, plan, boughtOldestExpiresAt, unit, usdPerCredit }` — the two credit pots (plan credits pay for compute, storage and network, never for tokens on foldrun's models; bought credits pay for anything) and the plan's terms with `status` and `resetsAt`; `tokens`, `{ totals: { calls, billedCredits, byokTokens }, byModel }`, one row per provider and model with `supply` (`foldrun`, `operator` or `own`), `calls`, `inputTokens`, `cacheReadTokens`, `cacheWriteTokens`, `outputTokens` and `billedCredits` — a model on the account's own key is listed at `0` with a `billedNote`; and `compute`, `{ meters, planFee, bySize }`, each meter (`vcpu`, `ram`, `disk`, `storage`, `network`, `search`, `browser`, `warm`) with `quantity`, `unit`, `rateCreditsPerUnit` and `credits` — `storage` also `includedGb`, `overGb` (only these are charged) and `basis`, and the three pod meters (the account's search and browser pods and its deploy-time runtime builds, charged for the vCPU and GiB they hold while they live and the bytes they move) `sessions`, `networkGb` and a `note`; `credits` on a pod meter and on `storage` is what the ledger charged over the period —, `planFee` the plan's fee as its own line, `bySize` the step sizes with their `creditsPerHour`; `billed` is what the ledger charged over the period (`totalCredits`, `waived`). They are consumption priced at today's rates, which can differ from `billed` after a price change. `credits`, `planFee` and `billed` are `null` to a caller scoped to some workspaces, whose `tokens` and `compute` cover those workspaces, and `null` where nothing is billed. The totals and `workspaces` above are over every retained run, whatever the period |
|
|
408
|
+
| `/api/usage/rates` | GET | the rates this account is charged now (7 Nov 2026): `rates`, `{ creditUsd, vcpuUsdPerHour, ramUsdPerGibHour, diskUsdPerGibMonth, storageUsdPerGbMonth, networkUsdPerGb, margin }` in dollars, `null` where nothing is billed; `plan`, the account's plan terms (`null` to a caller scoped to some workspaces); and `catalogue`, the same document as `/api/pricing`. The Usage page's Rates tab and `foldrun usage rates` |
|
|
408
409
|
| `/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` |
|
|
409
410
|
| `/api/observe?days=` | GET | the account Observe page's analysis, the same function the page renders from: `{ days, timezone, window: { from, to }, previous: { from, to, runs }, kpis, causes, desks, agents, tools, daily }`. `kpis` is the window against the one of the same length before it — `{ runs, finished, succeeded, rate, prevRate, failed, platformFailures, deskFailures, spendUsd, prevSpendUsd, medianSecs }` (`rate` is completed ÷ (completed + failed), `null` with none finished; money is what was charged); `causes` why runs went wrong, the platform's first — `{ kind (platform, verify, timeout, error, blocked, bad, stopped), key, label, platform, count, desks, sample, newest }`; `desks` every workspace worst first — `{ workspace, runs, rate, prevRate, deskFailures, platformFailures, spendUsd, medianSecs, worst: { what, count }, lastBad }`; `agents` the agents to watch (most failures, then retries, then charged; 10 at most) — `{ workspace, agent, steps, failed, retried, costUsd, chargedUsd, seconds }`; `tools` merged across workspaces — `{ name, calls, errors, workspaces, p95ms }`; `daily` one bucket per day in `timezone`, a week at least — `{ day, good, attention, failed, platform, other, spendUsd }`. A run it names (`newest`, `lastBad`) is `{ workspace, id, what, outcome, startedAt, finishedAt, failure }`. `days` 1–365, 7 unasked (the page's default). A key scoped to some workspaces sees theirs |
|
|
410
411
|
| `/api/insights?days=&workspace=` | GET | recurring problems found in the runs of the window (see [Runs](runs#insights)): `{ days, insights: [{ id, kind, workspace, agent, tool?, title, why, fix, credits, steps, evidence: [{ workspace, runId, step }] }] }`. `kind` is `cache` (an agent's big prompt mostly uncached), `big-result` (a tool result over 20k characters sent again on every later model call), `retry-loop` (a tool erroring three or more times in a step) or `timeout` (steps using 80% or more of their `timeout:`); `credits` is about what it cost in the window, null when it is not money. `days` 1–30, 7 unasked. A key scoped to some workspaces sees theirs |
|
|
@@ -468,8 +469,8 @@ person: a key names an account, never a who.
|
|
|
468
469
|
| `/api/billing/invoices` | GET | the Invoices tab as data (hosted only; 5 Nov 2026): `invoices` is the plan's tax invoices from Stripe, newest first — `{ id, number, description, createdAt, amount, currency, status, url, pdfUrl }`, `amount` in the invoice's currency and `url` Stripe's hosted page; `receipts` is every credit purchase on the ledger, newest first — `{ t, usd, label, receiptUrl }`, `receiptUrl` Stripe's hosted receipt or `null` for a credit not paid by card; `stripe` is false when Stripe is not configured or the account has no customer there (no invoices then). The whole account's payments, so refused (403) to a member or key scoped to some workspaces, as the statement is |
|
|
469
470
|
| `/api/billing/statement?month=&format=` | GET | one month of the ledger as a statement. JSON by default; `format=csv` downloads it with the month, the account and the spent and added totals in its header. `month` is `YYYY-MM`, default the current month. What the customer sees is the charge; the platform's provider cost is not on it. The whole account's money, so refused (403) to a member or key scoped to some workspaces, as the audit log is |
|
|
470
471
|
| `/api/billing/wallet` | GET, PUT | the balance summary (burn, runway, daily spend, month to date, the suggested top-up), the refill rule and the low-balance email — GET `{ enabled, stripe, summary, cardSaved, autoTopUp, email, dunning, tomanTopUp }`, PUT `autoTopUp`, `email`. `dunning.status` is `none`, `grace` (a plan invoice failed; runs go on until `graceUntil`) or `suspended` (new runs paused until it is paid), with `payUrl`, `amountDue` (minor units) and `currency`. `tomanTopUp` is `{ url }` — foldrun.ir's charge page with this account filled in — or null where foldrun.ir cannot sell now |
|
|
471
|
-
| `/api/billing/plans` | GET | the catalogue (four plans: fee, credits, per-credit price,
|
|
472
|
-
| `/api/billing/subscribe` | POST, DELETE | POST `plan` — starter,
|
|
472
|
+
| `/api/billing/plans` | GET | the catalogue (four plans — Free, Starter, Pro and Scale: fee, credits, per-credit price, storage, compute at once, workspaces, lane, and whether unused credits roll over), where this account stands (plan, status, this cycle's credits and what is left, when it resets), the balance in dollars and credits, and any overdraft the platform has allowed |
|
|
473
|
+
| `/api/billing/subscribe` | POST, DELETE | POST `plan` — starter, pro or scale (Free is granted, not bought). With no subscription yet, answers `url`: a Stripe Checkout in subscription mode; the return trip starts the first cycle. With a live one, changes it at Stripe at once, prorated (an upgrade is invoiced today and the bigger bundle lands with it; a downgrade comes back as credit on the next invoice), and answers `changed: true` — only once its prorated invoice is paid: when the payment needs the customer (a declined card, 3-D Secure) the change waits at Stripe as a pending update, nothing about the plan moves, and the answer is 402 `{ pending: true, payUrl }` — paying that invoice applies it; unpaid, Stripe drops it and voids the invoice after 23 hours. A plan set to stop and changed this way stays set to stop once paid — resuming it is the customer's own choice (`resume: true`); nothing resumes on its own. A plan set to stop at the period's end is still that live subscription: choosing a plan takes the stop off (and changes it if it is another plan) — never a second Checkout. With no subscription known here but one still billing at Stripe for the account's customer, 409: a second is not started. POST `resume: true` takes a pending cancellation off — nothing is charged and no cycle moves. DELETE ends the plan with the current cycle: the credits stand until then, and credits bought on top are kept |
|
|
473
474
|
| `/api/billing/stripe` | POST | Stripe's webhook — signature-verified, not for you. Every delivery is logged. Beside top-ups it turns plan cycles: one grant per (subscription, plan, period), whichever of the checkout, `invoice.paid` (either invoice shape) or `customer.subscription.updated` arrives first; `invoice.payment_failed` marks the plan past due and starts dunning (an email, a grace period, then new runs paused — see budgets-and-billing.md), `invoice.paid` and `invoice.voided` end it, `customer.subscription.deleted` ends the plan that subscription paid for — what is left of the bundle expires, the levers come off, money the customer added stays. `charge.refunded` debits a refunded top-up (never a plan fee), `charge.dispute.created` debits a chargeback and `charge.dispute.closed` returns it when won. Answers 500 — so Stripe redelivers — only when a lookup the event needs failed. The full event list is in budgets-and-billing.md |
|
|
474
475
|
| `/api/billing/partner/topups/rate` | GET | foldrun.ir only, HMAC-signed (see [Paying in Toman](budgets-and-billing#paying-in-toman-foldrunir)) — the Toman rate it sells at: `{ tomanPerUsd, setAt, min, max }`; `503` while no rate is set or it has gone stale |
|
|
475
476
|
| `/api/billing/partner/topups/quote` | POST | foldrun.ir only — `{ account, usd }` (account: a sign-in email or the account id) → `{ account: { label }, usd, toman, rial, tomanPerUsd, setAt }`. Nothing written; `label` is masked (`o•••r@a•••e.co · ac••`). `404` no such account, `400` an amount outside $5–$500 or over the gateway's 100,000,000 Toman |
|
|
@@ -25,7 +25,7 @@ mistake the editor names rather than a cap it quietly keeps.
|
|
|
25
25
|
When an agent's cap and the flow's both apply to one step, the tighter one
|
|
26
26
|
wins, and the step's error says which line set it: `budget: in the flow
|
|
27
27
|
file` or `budget: on the writer agent`.
|
|
28
|
-
| **runs at once** | `concurrency: 3` in the account's `AGENTS.md`, or Settings → Policies → Governance | the fourth run waits its turn in the queue — never refused, only later. Empty means the install's share (`FOLDRUN_ACCOUNT_CONCURRENCY`) or
|
|
28
|
+
| **runs at once** | `concurrency: 3` in the account's `AGENTS.md`, or Settings → Policies → Governance | the fourth run waits its turn in the queue — never refused, only later. Empty means the install's share (`FOLDRUN_ACCOUNT_CONCURRENCY`), or no cap. Your own number can lower that, never raise it. Plans are not sold on runs at once but on [compute at once](#compute-at-four-levels): paid by the second, it is the real limit. On foldrun's hosted platform a ceiling on runs driven together guards against a loop gone wrong; it is not something a plan sells |
|
|
29
29
|
| **the queue lane** | the plan's lane (`high` \| `normal` \| `low`); `priority: low` in the account's `AGENTS.md` lowers it, and `high` there counts only with a plan that gives it | when slots are short, accounts take turns, weighted by lane — high 3, normal 2, low 1: every account's first run goes before anyone's second, a fast lane takes three turns to a slow lane's one and never all of them, an account with runs going waits behind one with none, and a run that has waited ten minutes moves up a turn. A flow's own `priority:` orders runs within that. The cap above still holds |
|
|
30
30
|
| **compute at once** | the plan's cores, GiB and disk (below); `compute: { vcpu: 4, memory: 8Gi, disk: 40Gi }` in the account's `AGENTS.md`, or Settings → Policies → Governance, lowers it — and a workspace's and a flow's `compute:` narrow it further ([four levels](#compute-at-four-levels)) | what all the account's running steps may hold together — each step's cores, memory and disk, its `size:` class's or its own `resources:` ([agents](agents#resources--your-own-numbers)). A step that would pass it waits to start, like a full node — `room: waiting to start — 6 of this account's 8 GiB is held by its running steps…` — and starts in turn when one of the account's steps ends ([waiting for room](#waiting-for-room)). A step that **alone** is bigger than the pool, or than the plan's most for one step, fails at once with that message: no step finishing would make room. Without a plan, the install's `FOLDRUN_ACCOUNT_VCPU` / `FOLDRUN_ACCOUNT_MEMORY_GIB` / `FOLDRUN_ACCOUNT_DISK_GIB`, or no cap. Your own number can lower it, never raise it. `foldrun usage compute` shows the pool and what is held now. Enforced on the hosted platform and any k8s install; a self-hosted Docker install caps each step at its class but not the pool |
|
|
31
31
|
| **room to start** | the install's `FOLDRUN_RUN_MEMORY_GIB`, `FOLDRUN_RUN_DISK_GIB` and `FOLDRUN_ACCOUNT_PODS` | a step whose sandbox would not fit, or whose account already has its most sandboxes running, waits to start — `room: waiting to start — …` on its trail — instead of failing. The wait is not billed and has no time limit; the run page's start-up chip shows it as `room` ([waiting for room](#waiting-for-room)) |
|
|
@@ -139,10 +139,12 @@ or a `wait:` and waiting for a worker. A run asleep on its own `wait:` timer,
|
|
|
139
139
|
at an approval gate or waiting for an event does not count, nor does a run
|
|
140
140
|
that is running.
|
|
141
141
|
|
|
142
|
-
- **The limit.**
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
142
|
+
- **The limit.** On the hosted platform each plan sets its own number:
|
|
143
|
+
**Free 10, Starter 100, Pro 400, Scale 1,000**. Without a plan figure it is 20 for each run
|
|
144
|
+
the account may drive at once (its own `concurrency:`, or the install's),
|
|
145
|
+
and never fewer than 50. The refusal below names the number and where it
|
|
146
|
+
comes from. An install sets one number for every account with
|
|
147
|
+
`FOLDRUN_MAX_WAITING_RUNS` (`0`: no limit), which wins over the plan.
|
|
146
148
|
- **Past it, a new run is refused at once** — never lined up and dropped
|
|
147
149
|
later. A person or a key gets `409` with `code: "waiting_cap"`, `limit`
|
|
148
150
|
and `waiting`, and the sentence: *this account already has 50 runs
|
|
@@ -217,12 +219,19 @@ none — are **1¢ each**; the falling figure below is what a plan's bundle
|
|
|
217
219
|
works out to, and it is the reason to pick a bigger plan rather than buy
|
|
218
220
|
more credits.
|
|
219
221
|
|
|
220
|
-
| plan | a month | credits a month |
|
|
221
|
-
|
|
222
|
-
| **
|
|
223
|
-
| **
|
|
224
|
-
| **Pro** | $
|
|
225
|
-
| **Scale** | $
|
|
222
|
+
| plan | a month | credits a month | storage included | compute at once | one step, at most | workspaces | queue lane |
|
|
223
|
+
|---|---|---|---|---|---|---|---|
|
|
224
|
+
| **Free** | $0 | 300 | 2 GB | 2 vCPU · 4 GiB · 20 GiB disk | 2 vCPU · 4 GiB · 10 GiB disk | 2 | normal |
|
|
225
|
+
| **Starter** | $29 | 3,000 | 10 GB | 4 vCPU · 8 GiB · 40 GiB disk | 4 vCPU · 8 GiB · 20 GiB disk | 5 | normal |
|
|
226
|
+
| **Pro** | $99 | 11,000 | 100 GB | 16 vCPU · 32 GiB · 160 GiB disk | 8 vCPU · 16 GiB · 40 GiB disk | unlimited | fast |
|
|
227
|
+
| **Scale** | $499 | 60,000 | 1 TB | 64 vCPU · 128 GiB · 640 GiB disk | 8 vCPU · 16 GiB · 40 GiB disk | unlimited | fast |
|
|
228
|
+
|
|
229
|
+
Bigger than Scale: contact us for a custom plan.
|
|
230
|
+
|
|
231
|
+
Plans are sold on **compute at once**, not on runs at once: a run is one
|
|
232
|
+
flow execution, compute is paid by the second, and a step that does not fit
|
|
233
|
+
waits its turn. Free is a plan like the others, granted to every verified
|
|
234
|
+
account rather than bought.
|
|
226
235
|
|
|
227
236
|
**Compute at once** is what all of an account's running steps may hold
|
|
228
237
|
together, counted by the cores, memory and disk each step's sandbox is
|
|
@@ -232,8 +241,27 @@ single step the plan runs: `heavy` (4 vCPU · 8 GiB · 20 GiB disk) on every
|
|
|
232
241
|
plan, and up to 8 vCPU · 16 GiB · 40 GiB disk with `resources:` on Pro and
|
|
233
242
|
Scale.
|
|
234
243
|
|
|
235
|
-
**
|
|
236
|
-
|
|
244
|
+
**Two kinds of credit, kept apart.** One balance, two pots:
|
|
245
|
+
|
|
246
|
+
- **Plan credits** are the plan's monthly grant. They pay for compute,
|
|
247
|
+
storage and network, and **never for tokens on foldrun's models**.
|
|
248
|
+
- **Bought credits** (a top-up by card, or in Toman on foldrun.ir) pay for
|
|
249
|
+
anything, tokens on foldrun's models included.
|
|
250
|
+
|
|
251
|
+
Compute, storage and network draw on plan credits first, then bought
|
|
252
|
+
credits. Tokens on foldrun's models draw on bought credits only, so an
|
|
253
|
+
account that wants them buys credits. The Usage page and
|
|
254
|
+
`GET /api/usage` show the two pots separately.
|
|
255
|
+
|
|
256
|
+
**Free: 300 credits every month.** Free credits are plan credits, so they
|
|
257
|
+
never pay for tokens on foldrun's models. They **do not roll over**: what is
|
|
258
|
+
unused is lost at the end of the month (UTC), so an account cannot stockpile
|
|
259
|
+
them. The grant for a new month is made when the account has run something
|
|
260
|
+
since the last one, and an account gets it once a month however it is
|
|
261
|
+
opened or closed.
|
|
262
|
+
|
|
263
|
+
**How long a credit lasts.** On a paid plan, credits land when the invoice is
|
|
264
|
+
paid, and what is unused **rolls over** into the next cycle up to **twice** the
|
|
237
265
|
plan's monthly quota — so a balance of plan credits reaches at most three
|
|
238
266
|
times it: this cycle's, plus at most two carried. Anything above the cap
|
|
239
267
|
expires, and the statement line says how much rolled and how much did not.
|
|
@@ -247,11 +275,10 @@ Australian consumers can attract gift-card rules, which are three years.
|
|
|
247
275
|
|
|
248
276
|
Which credit a run spends is the order that favours the customer: the
|
|
249
277
|
plan's granted credits first, then bought credit oldest-first — so the
|
|
250
|
-
credit closest to expiring is always the credit being used.
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
anyway. Changing plan is charged at once, prorated by Stripe; the new plan
|
|
278
|
+
credit closest to expiring is always the credit being used. An account
|
|
279
|
+
without a paid plan is on Free: no card asked, credit bought on top costs
|
|
280
|
+
1¢ each. A paid plan is cheaper from the first month you would have spent
|
|
281
|
+
its fee anyway. Changing plan is charged at once, prorated by Stripe; the new plan
|
|
255
282
|
and its bundle land when that invoice is paid — a change whose payment
|
|
256
283
|
fails leaves you on the plan you had, with Stripe's page to pay it; paid
|
|
257
284
|
within 23 hours it goes through, otherwise Stripe drops it and voids the
|
|
@@ -290,7 +317,7 @@ partners whose compute is absorbed by arrangement.
|
|
|
290
317
|
|
|
291
318
|
## What a credit buys
|
|
292
319
|
|
|
293
|
-
|
|
320
|
+
Six meters, at the platform's rates. Every charge is recorded in **two
|
|
294
321
|
halves** — what the models cost and what the platform under them cost — and
|
|
295
322
|
the Usage page, the statement and its CSV all show them apart. They are
|
|
296
323
|
different questions: a customer on their own model key pays no model half
|
|
@@ -302,8 +329,23 @@ provider's own invoice.
|
|
|
302
329
|
| meter | what it counts |
|
|
303
330
|
|---|---|
|
|
304
331
|
| **tokens** | model usage at cost, times a margin. **Bring your own key and the margin does not apply** — a BYOK step is billed nothing for tokens. On foldrun's models, each call at foldrun's price list, times the margin ([below](#foldruns-models)) |
|
|
305
|
-
| **
|
|
306
|
-
| **
|
|
332
|
+
| **vCPU** | per second, the cores a step reserves while it runs |
|
|
333
|
+
| **RAM** | per second, the GiB a step reserves while it runs |
|
|
334
|
+
| **step disk** | per second, the GiB of disk the step may write; deleted when the step ends |
|
|
335
|
+
| **storage** | per GB-month, the files you keep between runs **over your plan's allowance**, accrued daily. Only the GB above what your plan includes are charged (Free 2 GB, Starter 10, Pro 100, Scale 1 TB). It counts your workspaces' files and your run history, as they are now; a GB is 2^30 bytes |
|
|
336
|
+
| **network** | per GB the sandbox moves, both directions |
|
|
337
|
+
| **search and browser pods** | an account's search engine and its browser run as pods of their own. Each is charged like a step: the vCPU and GiB it holds, for the seconds it lives (idle time included, until it is let go), at the same vCPU and RAM rates, plus the GB it moves at the network rate. A search pod holds 0.25 vCPU and 0.75 GiB and a browser pod 1 vCPU, 3 GiB and 4 GiB of disk by default; the platform's operator sets these sizes, so the size shown is the one in force. Each pod's requests equal its limits, so you are charged for exactly what is reserved for it, at the size the pod was made with. A pod session is not a run, so no minimum run charge applies |
|
|
338
|
+
| **warm builds** | when you deploy, your workspace's environments (the packages an agent declares) are built ahead of its first step, in a short pod. **You pay for it**, because it is the work the first step would otherwise have done in its own sandbox: a small sandbox's vCPU and RAM for the seconds it ran, and the GB it downloaded. It is bounded (one build at a time, ten minutes at most) and shown as its own line, so it is never hidden in another |
|
|
339
|
+
|
|
340
|
+
The rates are on the Usage page's **Rates** tab, in `foldrun usage rates`,
|
|
341
|
+
in `GET /api/usage/rates` and, for anyone, in the public
|
|
342
|
+
`GET /api/pricing`. They are the rates charging uses, read when you look.
|
|
343
|
+
A default step (2 vCPU, 2 GiB) costs about 16 credits an hour. The Usage
|
|
344
|
+
page's **Compute** tab shows each meter with its quantity, rate and credits,
|
|
345
|
+
the plan fee as its own line, and what each step size costs per hour;
|
|
346
|
+
`foldrun usage meters` prints the same. The search pods, browser pods and
|
|
347
|
+
warm builds each have a line with their pod-hours, sessions and the GB they
|
|
348
|
+
moved; storage shows the GB held now against what your plan includes.
|
|
307
349
|
|
|
308
350
|
There is deliberately **no per-step fee**. Steps are sandbox-seconds, so a
|
|
309
351
|
step fee would charge compute twice and punish a well-factored flow for
|
|
@@ -330,7 +372,15 @@ Settings → Models shows the list as you pay it, and so does
|
|
|
330
372
|
- **A daily cap** per account (UTC), in what you pay. Before each call the
|
|
331
373
|
gateway reserves its estimate against the cap, so twenty calls at once
|
|
332
374
|
cannot all pass it; one past it is refused until the next day.
|
|
333
|
-
- **
|
|
375
|
+
- **Bought credits pay for it, and only bought credits.** A call starts only
|
|
376
|
+
while the account has bought credit above zero; plan credits, a Free
|
|
377
|
+
grant included, are not spent on tokens.
|
|
378
|
+
- **A run that has started finishes.** A run already using foldrun's models
|
|
379
|
+
may go a little past zero bought credit to end (up to
|
|
380
|
+
`models.supply.finish_grace_usd`, $1 a run by default); a new run, or a new
|
|
381
|
+
call from an account not already in one, is refused at zero.
|
|
382
|
+
- **Your own key costs no credits.** The Usage page's Tokens tab lists those
|
|
383
|
+
calls at 0 credits so you can still see what was used.
|
|
334
384
|
|
|
335
385
|
## Prompt caching
|
|
336
386
|
|
package/docs/cli.md
CHANGED
|
@@ -182,12 +182,14 @@ claude.ai or Claude Code there, nor any MCP configuration on disk.
|
|
|
182
182
|
| `foldrun usage` | what the account consumed — runs, steps, tokens (with the share the prompt cache served), compute, storage, per workspace — and what it was charged over `--days <n>` (default 56) from the ledger, per workspace with the change against the period before. `--json` for both documents |
|
|
183
183
|
| `foldrun usage --limit <n>` | the Usage page's **by flow** and **by agent** tables in the text output: what each flow and each agent was charged over the window, its runs and the change against the period before, most charged first — the first `n` of each (default 10; `0` hides them). `--json` has them all, in `history.byFlow` and `history.byAgent` |
|
|
184
184
|
| `foldrun usage compute` | the cores, GiB and disk the account's running steps may hold together and in one step, at every level — the account, each workspace with a pool or anything held, each live run with its flow's pool — what each holds now, and the steps **waiting for room**, oldest first, each with its flow, agent, what it needs, how long it has waited, why and which level holds it (`GET /api/usage/compute`). A waiting step has no time limit and starts in turn. It also prints how many of the account's **runs wait for their turn** against its limit: while that many wait, a new run is refused at once (409, `waiting_cap`) rather than lined up, and the CLI says so where you started it. `--json` for the document. Set the levels with `foldrun account set compute …`, `foldrun workspace set compute … --to <ws>` and `foldrun flow compute <flow> …` |
|
|
185
|
+
| `foldrun usage meters` | what the period used, meter by meter (the Usage page's **Compute** and **Tokens** tabs; `GET /api/usage?from=&to=`): the two credit pots, plan credits and bought credits; vCPU, RAM, step disk, storage and network, each with its quantity, rate and credits (storage against the GB your plan includes); search pods, browser pods and warm builds, each with its pod-hours, sessions and the GB it moved; the plan fee as its own line; each step size with the credits an hour it costs; and tokens by provider and model, where a model on your own key shows `0 credits` because your provider bills you. `--since <day>` and `--until <day>` (UTC, `YYYY-MM-DD`) choose the period, default the month so far and at most a year; `--json` prints `period`, `credits`, `tokens`, `compute` and `billed`. A key limited to some workspaces sees those workspaces' usage and no credits, plan fee or ledger total |
|
|
186
|
+
| `foldrun usage rates` | what each meter costs this account now — vCPU per hour, RAM per GiB-hour, step disk, storage over the plan's allowance, network per GB — in dollars and credits, the account's plan, the plans on offer with their credits, storage and compute at once, what a default step costs an hour, and the price list for foldrun's models with the margin (the **Rates** tab; `GET /api/usage/rates`; `--json` prints it whole). Says so when nothing is billed |
|
|
185
187
|
| `foldrun usage budget` | the Spend limits page: the account's `budget:` and each workspace's, what is spent in its window (today, this week or this month, in the account's calendar) and how far into the cap that is — marked past the 80% warning, and at the cap with when new runs start again (`GET /api/usage/budget`). Most spent first; a workspace with no cap shows its month's spend. `--to <workspace>` for one, `--json` for the document. A key scoped to some workspaces sees those, not the account's figure. Set a cap with `foldrun account set budget …` or `foldrun workspace set budget 60/day --to <ws>` |
|
|
186
188
|
| `foldrun billing` | the account's balance, whether billing is on at all, what the platform is currently waiving, and the recent ledger entries with what each was for — a run names its workspace, flow and run id; an adjustment carries its own note. `--limit <n>` shows more. `statement [YYYY-MM]` is a month of the ledger (this month by default) — `--csv` for the file an accountant wants, to stdout or `--file <path>`. `wallet` is the burn, the runway and auto top-up; `wallet set auto-top-up --threshold <usd> --amount <usd>` turns it on (a refill of 5–500), `set auto-top-up off` turns it off, `set email <address>` is where receipts go. `details` is who invoices are made out to; `details set --name "…" --abn … --address "line1, city, state, postcode, AU" --email …` changes it, merged with what is there. `portal` prints a link to Stripe's billing portal. Changing the wallet, the details, and the portal are the account owner's; anyone else is told so |
|
|
187
189
|
| `foldrun billing invoices` | the Invoices tab: the plan's tax invoices from Stripe — number, date, amount and currency, status, what it was for, and Stripe's link to it — and every credit purchase with its receipt link, newest first (`GET /api/billing/invoices`). `--json` for the document. Any member or key with every workspace; one scoped to some is refused, as the statement is. An install without billing says it has none |
|
|
188
190
|
| `foldrun billing wallet clear email` | no address for receipts and low-balance warnings (`PUT /api/billing/wallet { email: null }`, as the wallet page's emptied field). `wallet set auto-top-up off` keeps the threshold and the refill for the next time it is turned on, as the page's switch does; `wallet` shows them beside off |
|
|
189
191
|
| `foldrun billing details set --clear-address` | drops the address from who invoices are made out to, the rest kept; `--clear-email` and `--clear-abn` the same for the email and the ABN (each refused beside its own `--address`/`--email`/`--abn`) |
|
|
190
|
-
| `foldrun billing plans` | the Plans page: every plan with its monthly fee, credits,
|
|
192
|
+
| `foldrun billing plans` | the Plans page: every plan with its monthly fee, credits, storage, compute at once and workspaces, which one the account is on and this cycle's credits left (`GET /api/billing/plans`). `billing plan <id>` chooses one — a first plan answers with Stripe's checkout page, a change on a live plan is prorated at Stripe at once (asks first; `--yes`); `plan cancel` stops it at the end of the cycle, `plan resume` undoes that until then (`POST`/`DELETE /api/billing/subscribe`) |
|
|
191
193
|
| `foldrun billing top-up <usd>` | the Payment page's top-up: Stripe's checkout page for that amount, opened in the browser (`--no-browser`, or no terminal, prints it). The credit lands when Stripe confirms the payment. `billing card` is the same for saving a card for auto top-up. Both need `billing:manage` |
|
|
192
194
|
| `foldrun gallery` | the tools (`web`, `docs`, `video`) and skills (`modern-website`, `motion-video`) the platform ships to every account, by shelf, and for each whether this account keeps its own copy and whether that copy still matches; `--json` for a script. `pull` lays the shelf down under `~/.foldrun/gallery/<host>/` for offline runs (`foldrun run` and `foldrun eval` refresh it themselves before each run); `upgrade <name>` replaces the account's copy of a tool or skill with the current gallery version, the old one a revision back. `foldrun check` knows the gallery's names, so a signed-out check warns rather than calling them missing |
|
|
193
195
|
| `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` |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "foldrun",
|
|
3
|
-
"version": "25.
|
|
3
|
+
"version": "25.2.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",
|
|
@@ -22,7 +22,7 @@
|
|
|
22
22
|
],
|
|
23
23
|
"scripts": {
|
|
24
24
|
"e2e": "FOLDRUN_E2E=1 FOLDRUN_DATA=$(mktemp -d /tmp/foldrun-e2e-XXXXXX) node --test --test-timeout=300000 tests/e2e.test.ts",
|
|
25
|
-
"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-team-me.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 tests/cli-usage-compute.test.ts tests/cli-fol105.test.ts tests/cli-key-renew.test.ts tests/cli-wait-failed.test.ts tests/cli-mcp.test.ts tests/cli-a2a.test.ts tests/cli-gateway.test.ts tests/cli-switches.test.ts tests/cli-parity-runs.test.ts tests/cli-parity-b.test.ts tests/cli-parity-clears.test.ts tests/cli-parity-c.test.ts tests/cli-runs-paging.test.ts tests/cli-budget-invoices.test.ts tests/cli-observe-analysis.test.ts tests/cli-failure-retention.test.ts tests/cli-snapshot.test.ts tests/cli-run-money.test.ts tests/cli-talk.test.ts tests/cli-text.test.ts",
|
|
25
|
+
"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-team-me.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 tests/cli-usage-compute.test.ts tests/cli-usage-meters.test.ts tests/cli-fol105.test.ts tests/cli-key-renew.test.ts tests/cli-wait-failed.test.ts tests/cli-mcp.test.ts tests/cli-a2a.test.ts tests/cli-gateway.test.ts tests/cli-switches.test.ts tests/cli-parity-runs.test.ts tests/cli-parity-b.test.ts tests/cli-parity-clears.test.ts tests/cli-parity-c.test.ts tests/cli-runs-paging.test.ts tests/cli-budget-invoices.test.ts tests/cli-observe-analysis.test.ts tests/cli-failure-retention.test.ts tests/cli-snapshot.test.ts tests/cli-run-money.test.ts tests/cli-talk.test.ts tests/cli-text.test.ts",
|
|
26
26
|
"release": "node scripts/release.mjs",
|
|
27
27
|
"typecheck": "tsc -p tsconfig.json",
|
|
28
28
|
"docs:sync": "node scripts/sync-docs.mjs",
|
package/src/commands.mjs
CHANGED
|
@@ -12614,6 +12614,121 @@ function computeText(p, none) {
|
|
|
12614
12614
|
return parts.length ? parts.join(" · ") : none;
|
|
12615
12615
|
}
|
|
12616
12616
|
|
|
12617
|
+
/** A credit figure: whole when large, two places when small. */
|
|
12618
|
+
const creditsText = (n) => {
|
|
12619
|
+
const v = Math.abs(Number(n)) >= 100 ? Math.round(Number(n)) : Math.round(Number(n) * 100) / 100;
|
|
12620
|
+
return v.toLocaleString("en-US");
|
|
12621
|
+
};
|
|
12622
|
+
|
|
12623
|
+
/** `--since <day>` and `--until <day>` are the API's `from` and `to` (`--to` already names a workspace here). */
|
|
12624
|
+
function usagePeriodQuery(flags) {
|
|
12625
|
+
const q = new URLSearchParams();
|
|
12626
|
+
for (const [flag, key] of [["since", "from"], ["until", "to"]]) {
|
|
12627
|
+
if (flags[flag] === undefined) continue;
|
|
12628
|
+
if (typeof flags[flag] !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(flags[flag])) throw new Error(`--${flag} is a UTC day, YYYY-MM-DD`);
|
|
12629
|
+
q.set(key, flags[flag]);
|
|
12630
|
+
}
|
|
12631
|
+
const s = q.toString();
|
|
12632
|
+
return s ? `?${s}` : "";
|
|
12633
|
+
}
|
|
12634
|
+
|
|
12635
|
+
/**
|
|
12636
|
+
* `foldrun usage meters [--since <day>] [--until <day>]` — what the period
|
|
12637
|
+
* used by meter: the two credit pots, compute and storage and network with
|
|
12638
|
+
* quantity, rate and credits, the plan fee, each step size, and tokens by
|
|
12639
|
+
* provider and model with your own key at 0 billed (the Usage page's
|
|
12640
|
+
* Compute and Tokens tabs; GET /api/usage?from&to).
|
|
12641
|
+
*/
|
|
12642
|
+
async function usageMetersCmd(flags) {
|
|
12643
|
+
const url = platformFor(flags, "usage meters");
|
|
12644
|
+
const u = await remoteCall(url, flags, `/api/usage${usagePeriodQuery(flags)}`);
|
|
12645
|
+
if (flags.json === true) {
|
|
12646
|
+
const { period, credits, tokens, compute, billed } = u;
|
|
12647
|
+
console.log(JSON.stringify({ period, credits, tokens, compute, billed }, null, 2));
|
|
12648
|
+
return 0;
|
|
12649
|
+
}
|
|
12650
|
+
const names = { vcpu: "vCPU", ram: "RAM", disk: "step disk", storage: "storage", network: "network", search: "search pods", browser: "browser pods", warm: "warm builds" };
|
|
12651
|
+
console.log(`\n ${c.bold("meters")} ${c.dim(`${u.period?.from} to ${u.period?.to}, at today's rates`)}`);
|
|
12652
|
+
const cr = u.credits;
|
|
12653
|
+
if (cr) {
|
|
12654
|
+
console.log(` ${c.dim("plan credits")} ${creditsText(cr.pots.planUsd / cr.usdPerCredit)} ${c.dim("bought credits")} ${creditsText(cr.pots.boughtUsd / cr.usdPerCredit)}${cr.plan ? ` ${c.dim(`on ${cr.plan.name}${cr.plan.resetsAt ? `, next ${String(cr.plan.resetsAt).slice(0, 10)}` : ""}`)}` : ""}`);
|
|
12655
|
+
}
|
|
12656
|
+
const meters = u.compute?.meters ?? [];
|
|
12657
|
+
console.log(`\n ${c.bold("compute, storage, network and pods")}`);
|
|
12658
|
+
for (const m of meters) {
|
|
12659
|
+
const q = m.quantity == null ? "—" : `${creditsText(m.quantity)} ${m.unit}`;
|
|
12660
|
+
const rate = m.rateCreditsPerUnit == null ? "" : `at ${creditsText(m.rateCreditsPerUnit)} credits per ${m.meter === "storage" ? "GB-month" : m.unit}`;
|
|
12661
|
+
const storageNote = m.meter === "storage" ? c.dim(m.includedGb !== undefined ? ` (${m.includedGb} GB included, ${m.overGb} over)` : "") : "";
|
|
12662
|
+
// The pods are charged for the vCPU and GiB they hold while they live
|
|
12663
|
+
// and the bytes they move; their sessions and GB moved read beside them.
|
|
12664
|
+
const podNote = m.sessions !== undefined ? c.dim(` (${m.sessions} ${m.sessions === 1 ? "session" : "sessions"}, ${creditsText(m.networkGb ?? 0)} GB moved)`) : "";
|
|
12665
|
+
const over = storageNote + podNote;
|
|
12666
|
+
console.log(` ${pad(names[m.meter] ?? m.meter, 26)} ${pad(q, 18)} ${pad(rate, 34)} ${c.bold(creditsText(m.credits))} credits${over}`);
|
|
12667
|
+
}
|
|
12668
|
+
const fee = u.compute?.planFee;
|
|
12669
|
+
if (fee) console.log(` ${pad("plan fee", 26)} ${c.dim(fee.label)} $${Number(fee.usd).toFixed(2)} for ${creditsText(fee.includedCredits)} credits`);
|
|
12670
|
+
const sizes = u.compute?.bySize ?? [];
|
|
12671
|
+
if (sizes.length) {
|
|
12672
|
+
console.log(`\n ${c.bold("by step size")}`);
|
|
12673
|
+
for (const z of sizes) console.log(` ${pad(z.size, 11)} ${pad(`${z.steps} steps`, 11)} ${pad(`${z.hours} h`, 9)} ${pad(`${z.vcpu} vCPU · ${z.memGiB} GiB · ${z.diskGiB} GiB disk`, 34)} ${z.creditsPerHour == null ? "" : `${creditsText(z.creditsPerHour)} credits an hour`}`);
|
|
12674
|
+
}
|
|
12675
|
+
const rows = u.tokens?.byModel ?? [];
|
|
12676
|
+
console.log(`\n ${c.bold("tokens")} ${c.dim("by provider and model; your own key is billed by your provider, 0 credits here")}`);
|
|
12677
|
+
if (!rows.length) console.log(` ${c.dim("no model calls in this period")}`);
|
|
12678
|
+
for (const r of rows) {
|
|
12679
|
+
const own = r.supply === "own";
|
|
12680
|
+
console.log(` ${pad(r.provider, 11)} ${pad(r.model, 28)} ${pad(`${r.calls} calls`, 10)} ${pad(`${creditsText(r.inputTokens)} in / ${creditsText(r.outputTokens)} out`, 24)} ${own ? c.dim("your key · 0 credits") : `${c.bold(creditsText(r.billedCredits))} credits`}`);
|
|
12681
|
+
}
|
|
12682
|
+
if (u.billed) console.log(`\n ${c.dim(`the ledger charged ${creditsText(u.billed.totalCredits)} credits over the period${u.billed.waived?.length ? ` · waived: ${u.billed.waived.join(", ")}` : ""}`)}`);
|
|
12683
|
+
console.log(`\n ${c.dim("--since <day> --until <day> choose the period · `foldrun usage rates` has the rates")}\n`);
|
|
12684
|
+
return 0;
|
|
12685
|
+
}
|
|
12686
|
+
|
|
12687
|
+
/**
|
|
12688
|
+
* `foldrun usage rates` — what each meter costs this account, its plan and
|
|
12689
|
+
* the plans on offer, and the price list for foldrun's models (the Usage
|
|
12690
|
+
* page's Rates tab; GET /api/usage/rates).
|
|
12691
|
+
*/
|
|
12692
|
+
async function usageRatesCmd(flags) {
|
|
12693
|
+
const url = platformFor(flags, "usage rates");
|
|
12694
|
+
const d = await remoteCall(url, flags, "/api/usage/rates");
|
|
12695
|
+
if (flags.json === true) {
|
|
12696
|
+
console.log(JSON.stringify(d, null, 2));
|
|
12697
|
+
return 0;
|
|
12698
|
+
}
|
|
12699
|
+
const r = d.rates;
|
|
12700
|
+
const cat = d.catalogue;
|
|
12701
|
+
if (!r && !cat) {
|
|
12702
|
+
console.log(`\n ${c.dim("nothing is billed on this platform, so there are no rates")}\n`);
|
|
12703
|
+
return 0;
|
|
12704
|
+
}
|
|
12705
|
+
const cu = r?.creditUsd ?? cat?.creditUsd ?? 0.01;
|
|
12706
|
+
const credits = (usdAmount) => creditsText(usdAmount / cu);
|
|
12707
|
+
console.log(`\n ${c.bold("rates")} ${c.dim(`one credit is $${cu}`)}`);
|
|
12708
|
+
if (r) {
|
|
12709
|
+
for (const [name, rate, per] of [["vCPU", r.vcpuUsdPerHour, "vCPU-hour"], ["RAM", r.ramUsdPerGibHour, "GiB-hour"], ["step disk", r.diskUsdPerGibMonth, "GiB-month"], ["storage over the plan", r.storageUsdPerGbMonth, "GB-month"], ["network", r.networkUsdPerGb, "GB, in and out"]]) {
|
|
12710
|
+
console.log(` ${pad(name, 22)} $${rate} per ${pad(per, 16)} ${c.dim(`${credits(rate)} credits`)}`);
|
|
12711
|
+
}
|
|
12712
|
+
console.log(` ${c.dim(`tokens on foldrun's models: the provider's price × ${r.margin}, from bought credits only`)}`);
|
|
12713
|
+
}
|
|
12714
|
+
if (d.plan) console.log(`\n ${c.bold("your plan")} ${d.plan.name}${d.plan.status ? c.dim(` (${d.plan.status})`) : ""} · ${creditsText(d.plan.creditsPerMonth)} credits a month · ${d.plan.storageGb} GB stored · ${d.plan.computeAtOnce.vcpu} vCPU · ${d.plan.computeAtOnce.memGiB} GiB at once${d.plan.rollover ? ` · unused credits roll over up to ${creditsText(d.plan.rolloverCapCredits)}` : " · unused credits are lost at month end"}`);
|
|
12715
|
+
if (cat) {
|
|
12716
|
+
console.log(`\n ${c.bold("plans")}`);
|
|
12717
|
+
for (const p of cat.plans ?? []) {
|
|
12718
|
+
console.log(` ${d.plan?.id === p.id ? c.green("●") : c.dim("○")} ${pad(p.name, 8)} ${pad(p.feeUsd ? `$${p.feeUsd}/mo` : "free", 9)} ${pad(`${creditsText(p.creditsPerMonth)} credits`, 16)} ${pad(`${p.storageGb} GB`, 8)} ${pad(`${p.computeAtOnce.vcpu} vCPU · ${p.computeAtOnce.memGiB} GiB`, 16)} ${p.lane === "fast" ? "fast lane" : ""}`);
|
|
12719
|
+
}
|
|
12720
|
+
if (cat.example) console.log(`\n ${c.dim(`a default step (${cat.example.vcpu} vCPU, ${cat.example.memGiB} GiB) costs about ${creditsText(cat.example.creditsPerHour)} credits an hour`)}`);
|
|
12721
|
+
const prices = cat.models?.prices ?? [];
|
|
12722
|
+
if (prices.length) {
|
|
12723
|
+
console.log(`\n ${c.bold("foldrun's models")} ${c.dim(`per million tokens, provider price × ${cat.models.margin}`)}`);
|
|
12724
|
+
for (const m of prices) console.log(` ${pad(m.provider, 11)} ${pad(m.model, 28)} in $${m.inputPerMTok} out $${m.outputPerMTok}${m.cacheReadPerMTok == null ? "" : ` cache read $${m.cacheReadPerMTok}`}`);
|
|
12725
|
+
}
|
|
12726
|
+
if (cat.models?.soon?.length) console.log(` ${c.dim(`coming: ${cat.models.soon.join(", ")}`)}`);
|
|
12727
|
+
}
|
|
12728
|
+
console.log();
|
|
12729
|
+
return 0;
|
|
12730
|
+
}
|
|
12731
|
+
|
|
12617
12732
|
/**
|
|
12618
12733
|
* `foldrun usage compute` — the cores and GiB the account's running steps
|
|
12619
12734
|
* may hold together and in one step, what they hold now, and the steps
|
|
@@ -14471,10 +14586,10 @@ async function billingPlansCmd(verb, sub, flags) {
|
|
|
14471
14586
|
if (verb === "plans") {
|
|
14472
14587
|
const p = await remoteCall(url, flags, "/api/billing/plans");
|
|
14473
14588
|
const cur = p.current;
|
|
14474
|
-
console.log(`\n ${c.bold("plans")} ${c.dim(`one credit is ${usd(p.creditUsd)}${cur?.plan ? ` · on ${cur.plan} (${cur.status})` : " ·
|
|
14589
|
+
console.log(`\n ${c.bold("plans")} ${c.dim(`one credit is ${usd(p.creditUsd)}${cur?.plan ? ` · on ${cur.plan} (${cur.status})` : " · Free: 300 credits a month, bought credits on top"}`)}`);
|
|
14475
14590
|
for (const x of p.plans ?? []) {
|
|
14476
14591
|
const mark = cur?.plan === x.id ? c.green("●") : c.dim("○");
|
|
14477
|
-
console.log(` ${mark} ${c.bold(pad(x.id, 8))} ${pad(`$${x.monthlyUsd}/mo`, 9)} ${pad(`${Number(x.credits).toLocaleString()} credits`, 16)} ${pad(`${x.
|
|
14592
|
+
console.log(` ${mark} ${c.bold(pad(x.id, 8))} ${pad(`$${x.monthlyUsd}/mo`, 9)} ${pad(`${Number(x.credits).toLocaleString()} credits`, 16)} ${pad(`${x.storageGb ?? "?"} GB`, 8)} ${pad(`${x.vcpu ?? "?"} vCPU · ${x.memGiB ?? "?"} GiB`, 16)} ${pad(x.workspaces == null ? "any workspaces" : `${x.workspaces} workspaces`, 15)} ${c.dim(x.pitch ?? "")}`);
|
|
14478
14593
|
}
|
|
14479
14594
|
if (cur?.plan) console.log(`\n ${c.dim(`this cycle: ${cur.cycleRemainingCredits ?? "?"} of ${cur.cycleCredits ?? "?"} credits left${cur.resetsAt ? `, resets ${String(cur.resetsAt).slice(0, 10)}` : ""}`)}`);
|
|
14480
14595
|
console.log(` ${c.dim(`balance ${usd(p.balanceUsd)}${p.cards ? "" : " · card payments are not configured on this install"}`)}`);
|
|
@@ -14482,7 +14597,7 @@ async function billingPlansCmd(verb, sub, flags) {
|
|
|
14482
14597
|
return 0;
|
|
14483
14598
|
}
|
|
14484
14599
|
if (verb === "plan") {
|
|
14485
|
-
if (!sub) throw new Error("`foldrun billing plan <starter|
|
|
14600
|
+
if (!sub) throw new Error("`foldrun billing plan <starter|pro|scale>`, `plan cancel` or `plan resume` — `billing plans` lists them");
|
|
14486
14601
|
if (sub === "cancel") {
|
|
14487
14602
|
if (!(await confirmed(flags, "billing plan cancel", "Cancel the plan at the end of this cycle? [y/N] "))) {
|
|
14488
14603
|
console.log(`\n ${c.dim("nothing changed")}\n`);
|
|
@@ -15874,6 +15989,8 @@ export async function run(command, positional, flags, workspace, layout) {
|
|
|
15874
15989
|
return observeCmd(flags, layout);
|
|
15875
15990
|
case "usage":
|
|
15876
15991
|
if (positional[0] === "compute") return usageComputeCmd(flags);
|
|
15992
|
+
if (positional[0] === "meters") return usageMetersCmd(flags);
|
|
15993
|
+
if (positional[0] === "rates") return usageRatesCmd(flags);
|
|
15877
15994
|
if (positional[0] === "budget") return usageBudgetCmd(flags);
|
|
15878
15995
|
return usageCmd(flags);
|
|
15879
15996
|
case "workspace":
|