onebrowser 0.3.0 → 0.5.0

package/README.md

@@ -15,13 +15,15 @@ const page = await session.newPage(); // Playwright; or any CDP client on sessio
 await page.goto('https://example.com');
 await session.close();
 
-await browsers.quota('steel'); // { remaining, unit: 'USD', renewsAt: null }
-await browsers.syncUsage(); // fetches the providers' records of ended sessions into the ledger
+await browsers.readQuota('steel'); // { remaining, unbilled, unit: 'USD', renewsAt: null }
+browsers.quota('steel'); // the same now, from that reading: sessions opened since count at once
+browsers.maxSessionCost('steel'); // what a session with the default options costs at most, in USD
+await browsers.syncUsage(); // stores the providers' records of ended sessions in the ledger
 browsers.usage({ since: Date.parse('2026-11-01') }); // [{ day, provider, client, sessions, minutes, … }]
 await browsers.close();
 ```
 
-**What it does not do**: choose a provider, cap the sessions held at once, spread sessions over providers, or stop using a provider whose quota runs low. Those are policy, and belong to the program using it. onebrowser opens the session it is asked for, and tells the program what it needs to decide: the quota, and `QuotaError` when a provider refuses a session for the account's quota.
+Choosing a provider, capping sessions and stopping before a quota runs out are the program's policy. onebrowser opens the sessions it is asked for and gives the program what it needs to decide: what the quota has left, what a session costs at most, and `QuotaError` when a provider refuses a session for the account's quota.
 
 Built in: [Steel](https://steel.dev), [TinyFish](https://tinyfish.ai), [Hyperbrowser](https://hyperbrowser.ai), [Lightpanda](https://lightpanda.io), [Kernel](https://www.kernel.sh), [Anchor Browser](https://anchorbrowser.io) and [Firecrawl](https://www.firecrawl.dev); a program can add its own (see [Adding a provider](#adding-a-provider)). Node 22.13 or later.
 
@@ -33,24 +35,26 @@ Built in: [Steel](https://steel.dev), [TinyFish](https://tinyfish.ai), [Hyperbro
 |---|---|
 | `client` | The program using it, recorded with each session; required |
 | `ledgerPath` | SQLite file of the ledger (default below; `':memory:'` for tests). Opened when first needed |
-| `providers` | Settings per provider name, on top of its adapter's `defaults`: `apiKey`, and the adapter's own settings (API base URLs, plan facts such as `monthlyHours`) |
+| `providers` | Settings per provider name, on top of its adapter's `defaults`: `apiKey`, `price`, `billingDelayMs`, `minIdleTimeoutSec` (see [Quota](#quota)) and the adapter's own (API base URLs, plan facts such as `monthlyHours`) |
 | `adapters` | Further adapters by provider name, or replacements of built-in ones |
 
 | Method | |
 |---|---|
 | `providers` | Names of the providers it can open sessions with |
 | `checkReady(provider)` | Throws when the provider is unknown or has no API key |
-| `openSession({ provider, proxyCountry, idleTimeoutSec, maxDurationMs })` | A new session, recorded in the ledger once the provider has created it. Throws `QuotaError` when the provider refuses it for the account's quota |
-| `quota(provider)` | `{ remaining, unit, renewsAt }` in the provider's own unit; `renewsAt` (ms) when it renews by itself, `null` when only a top-up renews it. Throws when it cannot be read |
-| `syncUsage()` | Stores the providers' records (duration, proxy traffic) of the ended sessions that have none yet: `{ reported, failed: [{ provider, error }] }`. Sessions of a provider it has no adapter for (another program's own) are left to the programs that have one |
+| `openSession({ provider, proxyCountry, idleTimeoutSec, maxDurationMs })` | A new session, in the ledger from when the provider has created it. Throws `QuotaError` when the provider refuses it for the account's quota |
+| `readQuota(provider, { maxAgeMs })` | Reads the provider's quota, unless a reading in progress or started at most `maxAgeMs` ago (default 0) can be used, a failed one too; then answers as `quota()` |
+| `quota(provider)` | What is left now, from the last reading: `{ remaining, unbilled, unit, renewsAt }` (see [Quota](#quota)). Throws until the provider has been read, and while its last reading failed |
+| `maxSessionCost(provider, options)` | What a session with these options costs at most, in the unit of the provider's quota |
+| `syncUsage()` | Stores the providers' records (duration, proxy traffic) of ended sessions: `{ reported, failed: [{ provider, error }] }` |
 | `usage({ since })` | Sessions opened since `since` (ms) per UTC day, provider and client: `sessions`, `minutes` (the provider's record, else the open-to-close timing), `untimed`, `unsynced`, `proxyBytes` |
 | `close()` | Closes the sessions still open and the ledger |
 
-A session (`openSession`) has `id`, `provider`, `egress`, `cdpUrl` (it may carry the API key: never log it), `openedAt`, `closedAt`, and:
+A session has `id`, `provider`, `egress`, `cdpUrl` (it may carry the API key: never log it), `openedAt` (when it was asked for), `closedAt` (when its provider released it), and:
 
-- `connect()`: Playwright's `Browser` over its CDP connection, made once. A keep-alive command every 15 s keeps the provider's idle timeout from ending a session that is in use.
-- `newPage()`: always a new page in the default context: the page a remote browser starts with is not always one that can be navigated.
-- `close()`: disconnects and releases it; only the first call does. The ledger records it closed in any case. Throws when the provider could not release it: the provider then ends it by itself.
+- `connect()`: Playwright's `Browser` over its CDP connection, made once. A keep-alive command every 15 s keeps the provider's idle timeout from ending a session in use.
+- `newPage()`: a new page in the default context: the page a remote browser starts with cannot always be navigated.
+- `close()`: disconnects and releases it; every call answers as the first. Throws when the provider could not release it: the provider ends it by itself, and the ledger counts it as lasting as long as it can.
 
 A session and a `OneBrowser` are async-disposable: `await using session = await browsers.openSession({ provider: 'steel' })` closes the session at the end of its block (Node 24 or later; on Node 22 call `close()`).
 
@@ -59,7 +63,7 @@ A session and a `OneBrowser` are async-disposable: `await using session = await
 | Option | Default | Meaning |
 |---|---|---|
 | `proxyCountry` | `null` | A country code: the provider's proxy in that country. `null`: its default egress |
-| `idleTimeoutSec` | 60 | A session whose client is gone (its process was killed) ends this long after at the latest. At least 30 (twice the keep-alive interval) |
+| `idleTimeoutSec` | 60 | A session whose client is gone (its process was killed) ends this long after at the latest, or after the provider's `minIdleTimeoutSec` if longer. At least 30 (twice the keep-alive interval) |
 | `maxDurationMs` | 15 min | The session ends this long after it was opened at the latest: this process closes it then, and the provider's own limit is set to it where its API takes one |
 
 `sessionOptions(options)` returns them with the defaults filled in and throws when one is unknown or out of range, so that a program can check its configuration before it opens any session.
@@ -78,15 +82,21 @@ How each provider meets them:
 
 ### Quota
 
-| Provider | Quota, unit | Read from |
-|---|---|---|
-| `steel` | balance, USD | `GET /v1/credits/balance`, the endpoint of Steel's dashboard (not in its API docs) |
-| `tinyfish` | wallet, USD | [`GET /v1/wallet`](https://docs.tinyfish.ai/wallet); a session refused with 402 throws `QuotaError` |
-| `hyperbrowser` | credits | `GET /api/team/credit-info`, the endpoint of Hyperbrowser's SDK (not in its API docs) |
-| `lightpanda` | browser hours of the calendar month (`monthlyHours`, default: the free plan's) | the ledger's record of its sessions: its console shows the month's usage, but its token cannot read it. So the reading is whole while the account is used only through ledgers of this machine |
-| `kernel` | browser hours of the calendar month (`monthlyHours`, default: what the free plan's credits pay for) | the uptime of the account's sessions this month, from `GET /browsers`; a session refused with 403 (spending cap) throws `QuotaError` |
-| `anchor` | credits | `GET /v1/billing`; a session refused with 402 throws `QuotaError` |
-| `firecrawl` | credits; the plan's credits renew at the end of each billing period | [`GET /v2/team/credit-usage`](https://docs.firecrawl.dev/api-reference/endpoint/credit-usage); a session refused with 402 throws `QuotaError` |
+`quota()` is the last reading less `unbilled`: what the ledger's sessions that the reading does not show cost at the provider's `price`. A reading shows the sessions that ended `billingDelayMs` before it; the others are open ones, counted as lasting as long as they can (`maxDurationMs`, then `idleTimeoutSec`, at least the provider's `minIdleTimeoutSec`), and those ended since, counted as long as they lasted. So each session counts once from when its provider has created it, whichever program on the machine opened it, and a program can check before each session that the account pays for it (`maxSessionCost`). A provider that bills a session while it runs has part of it counted twice, on the safe side. Not counted: sessions opened through another machine's ledger, until the provider bills them, and proxy traffic billed by the GB.
+
+`price` is in the quota's unit: `perHour`, `perSession` (default 0), the session time billed in whole `stepSec`, rounded up (default 1), and at least `minSec` (default 0). Where a provider does not document its rounding, the adapter takes the minute. `renewsAt` (ms) is when the quota renews by itself; `null` when only a top-up renews it. `price` and `billingDelayMs` are settings: a program on another plan sets its own.
+
+| Provider | Quota, unit | Read from | `price` | `billingDelayMs` |
+|---|---|---|---|---|
+| `steel` | balance, USD | `GET /v1/credits/balance`, the endpoint of Steel's dashboard (not in its API docs) | $0.10 an hour (Launch plan), by the minute | 5 min |
+| `tinyfish` | wallet, USD | [`GET /v1/wallet`](https://docs.tinyfish.ai/wallet); a session refused with 402 throws `QuotaError` | $0.002 a minute, by the minute | 5 min |
+| `hyperbrowser` | credits | `GET /api/team/credit-info`, the endpoint of Hyperbrowser's SDK (not in its API docs) | 100 an hour, by the minute | 5 min |
+| `lightpanda` | browser hours of the calendar month (`monthlyHours`, default: the free plan's) | the ledger's record of its sessions that have ended: its console shows the month's usage, but its token cannot read it. So the reading is whole while the account is used only through ledgers of this machine | 1 per browser hour, by the second | 0 |
+| `kernel` | browser hours of the calendar month (`monthlyHours`, default: what the free plan's credits pay for), counted from the first of the month, 00:00 UTC | the uptime of the account's sessions this month, from `GET /browsers` (Kernel has no API for what its credits leave); a session refused with 403 (spending cap) throws `QuotaError` | 1 per browser hour, by the second | 5 min |
+| `anchor` | credits | `GET /v1/billing`; a session refused with 402 throws `QuotaError` | 0.01 a session and 0.15 an hour, by the minute: above what its sessions' records bill (its docs: 0.05 an hour) | 5 min |
+| `firecrawl` | credits; the plan's credits renew at the end of each billing period | [`GET /v2/team/credit-usage`](https://docs.firecrawl.dev/api-reference/endpoint/credit-usage); a session refused with 402 throws `QuotaError` | 2 a minute, in 30 s steps, at least a minute | 5 min |
+
+Every provider read from its API showed a session's cost within about a minute of its end (2026-11); `billingDelayMs` leaves room for more.
 
 ### API keys
 
@@ -94,30 +104,30 @@ How each provider meets them:
 
 ### The ledger
 
-One SQLite file per machine by default: `$ONEBROWSER_DB`, else `onebrowser/sessions.db` in `$XDG_DATA_HOME` (default `~/.local/share`). Every program that uses onebrowser on the machine shares it, each under its own `client`, so the record of a provider account's sessions is whole whichever program opened them; several processes may write to it at once. Each session is recorded when its provider has created it (it is billed from then on, also when connecting fails afterwards), closed when released, and completed with the provider's own record by `syncUsage()` once it has ended.
+One SQLite file per machine by default: `$ONEBROWSER_DB`, else `onebrowser/sessions.db` in `$XDG_DATA_HOME` (default `~/.local/share`), shared by every program on the machine under its own `client`. A session is recorded when its provider has created it (it is billed from then on), with when it ends at the latest; closed when its provider has released it; and completed with the provider's own record by `syncUsage()`. A ledger made by an earlier onebrowser is brought up to date when opened; one made by a later onebrowser is refused.
 
 ## Command line
 
 The provider accounts and the ledger belong to the machine rather than to one program, so the `onebrowser` command reads them without a program of your own. It opens no sessions.
 
 ```sh
-npx onebrowser quota                 # what each provider account with an API key has left
+npx onebrowser quota                 # what each provider account with an API key has left, once its sessions not billed yet are paid for
 npx onebrowser quota steel kernel    # only these; one without an API key is a failed reading
 npx onebrowser usage --days 7        # the ledger's sessions per UTC day, provider and client, today included
 npx onebrowser usage --json --env-file .env
 ```
 
-`usage` first fetches the providers' records of the sessions that have ended, as `syncUsage()` does. With `--json`, `quota` prints an array of what `quota()` returns, with the provider: `{ provider, remaining, unit, renewsAt }`, or `{ provider, error }` for a failed reading; `usage` prints `{ ledger, since, sessions, failed }`, where `sessions` is what `usage()` returns and `failed` what `syncUsage()` could not fetch. API keys are read as by the library, from the environment (`--env-file PATH` loads a file into it first). Exit status: 0 done, 1 a reading failed, 2 the command line is wrong.
+`usage` first fetches the providers' records of the sessions that have ended, as `syncUsage()` does. With `--json`, `quota` prints an array of what `readQuota()` returns, with the provider: `{ provider, remaining, unbilled, unit, renewsAt }`, or `{ provider, error }` for a failed reading; `usage` prints `{ ledger, since, sessions, failed }`, where `sessions` is what `usage()` returns and `failed` what `syncUsage()` could not fetch. API keys are read as by the library, from the environment (`--env-file PATH` loads a file into it first). Exit status: 0 done, 1 a reading failed, 2 the command line is wrong.
 
 ## Adding a provider
 
 Write `src/providers/<name>.js` and register it in `ADAPTERS` (`src/providers/index.js`, where the contract is):
 
-- `defaults`: its settings (API base URLs, plan facts).
+- `defaults`: `price`, `billingDelayMs`, `minIdleTimeoutSec` if the provider takes no idle timeout as short as asked (see [Quota](#quota)), and its own settings (API base URLs, plan facts).
 - `createSession(settings, apiKey, { proxyCountry, idleTimeoutSec, maxDurationMs }) → { id, cdpUrl, egress }`: maps the session options onto the provider's parameters; throws `QuotaError` when the provider refuses the session for the account's quota.
 - `releaseSession(settings, apiKey, session)`.
 - `sessionUsage(settings, apiKey, [{ id, openedAt, closedAt }]) → [{ id, durationMs, proxyBytes }]`: the record of those sessions that have ended: the provider's own, or the ledger's timing for a provider whose records its API key cannot read.
-- `quota(settings, apiKey, history) → { remaining, unit, renewsAt? }`: `history.sessionMsSince(ms)` is the ledger's record of the provider's sessions, for a provider that cannot report its own usage.
+- `quota(settings, apiKey, history) → { remaining, unit, renewsAt? }`: for a provider that cannot report its usage, `history.endedSessionMsSince(ms)` is the session time of the ledger's sessions that the reading shows.
 
 Requests go through `src/providers/http.js`: every status other than 2xx is an `HttpError` (with `status`), so an adapter handles only the statuses that mean something of their own, such as a quota refusal.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "onebrowser",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "One interface to remote browser providers: sessions by provider name, a usage ledger, account quotas",
   "keywords": ["browser", "remote-browser", "cdp", "playwright", "steel", "hyperbrowser", "lightpanda", "kernel", "tinyfish", "anchorbrowser", "firecrawl"],
   "license": "MIT",

package/src/cli.js

@@ -6,6 +6,8 @@ const DAY_MS = 864e5;
 
 const day = (ms) => new Date(ms).toISOString().slice(0, 10);
 
+const round = (x) => Number(x.toFixed(2));
+
 /** The command line is wrong: exit status 2 */
 class CommandLineError extends Error {}
 
@@ -28,11 +30,11 @@ const COMMANDS = {
       if (unknown.length) throw new CommandLineError(`unknown provider ${unknown.join(', ')} (expected ${browsers.providers.join(', ')})`);
       const asked = names.length ? names : browsers.providers.filter((p) => isReady(browsers, p));
       if (!asked.length) throw new Error(`no provider has an API key: set ${browsers.providers.map(apiKeyEnv).join(', ')}`);
-      const quotas = await Promise.all(asked.map((provider) => browsers.quota(provider).then((q) => ({ provider, ...q }), (e) => ({ provider, error: e.message }))));
+      const quotas = await Promise.all(asked.map((provider) => browsers.readQuota(provider).then((q) => ({ provider, ...q }), (e) => ({ provider, error: e.message }))));
       if (json) out.write(`${JSON.stringify(quotas, null, 2)}\n`);
       else {
         for (const q of quotas) {
-          const text = q.error ? `unknown (${q.error})` : `${Number(q.remaining.toFixed(2))} ${q.unit} left${q.renewsAt ? `, renews ${day(q.renewsAt)}` : ''}`;
+          const text = q.error ? `unknown (${q.error})` : `${round(q.remaining)} ${q.unit} left${q.unbilled ? ` (after ${round(q.unbilled)} not billed yet)` : ''}${q.renewsAt ? `, renews ${day(q.renewsAt)}` : ''}`;
           out.write(`${q.provider.padEnd(14)} ${text}\n`);
         }
       }
@@ -66,7 +68,8 @@ const COMMANDS = {
 const help = (providers) => `onebrowser: the quotas of remote browser provider accounts, and the sessions in this machine's ledger
 
 Usage:
-  onebrowser quota [PROVIDER...]   what each provider account has left; default: every provider with an API key
+  onebrowser quota [PROVIDER...]   what each provider account has left, less what the sessions in the ledger
+                                   that it has not billed yet cost; default: every provider with an API key
   onebrowser usage [--days N]      sessions per UTC day, provider and client in the last N UTC days, today
                                    included (default 30), after fetching the providers' records of ended sessions
 

package/src/cost.js

@@ -0,0 +1,22 @@
+/**
+ * A provider's price (its `price` setting), in the unit its quota is read in:
+ *   perHour     for the session time
+ *   perSession  for each session, however short (default 0)
+ *   stepSec     the session time is billed in whole steps of this, rounded up (default 1)
+ *   minSec      and at least this much of it (default 0)
+ * It bounds what sessions cost, so where a provider does not document its rounding the adapter takes the minute.
+ */
+
+/** The price with its defaults filled in; throws when it is not one */
+export function fullPrice(price) {
+  const { perHour, perSession = 0, stepSec = 1, minSec = 0, ...unknown } = price ?? {};
+  const fine = [perHour, perSession, minSec].every((x) => Number.isFinite(x) && x >= 0) && Number.isFinite(stepSec) && stepSec > 0;
+  if (!fine || Object.keys(unknown).length) throw new Error(`price must be { perHour, perSession, stepSec, minSec } of numbers ≥ 0 (stepSec > 0), not ${JSON.stringify(price)}`);
+  return { perHour, perSession, stepSec, minSec };
+}
+
+/** What a session that lasts durationMs costs at `price` (fullPrice) */
+export function sessionCost({ perHour, perSession, stepSec, minSec }, durationMs) {
+  const billedSec = Math.max(minSec, Math.ceil(durationMs / 1000 / stepSec) * stepSec);
+  return perSession + (perHour * billedSec) / 3600;
+}

package/src/index.js

@@ -1,7 +1,8 @@
+import { sessionCost } from './cost.js';
 import { readApiKey } from './credentials.js';
 import { QuotaError } from './errors.js';
 import { defaultLedgerPath, Ledger } from './ledger.js';
-import { ADAPTERS, checkAdapter } from './providers/index.js';
+import { ADAPTERS, checkAdapter, fullSettings } from './providers/index.js';
 import { KEEP_ALIVE_MS, Session } from './session.js';
 
 export { apiKeyEnv } from './credentials.js';
@@ -9,18 +10,18 @@ export { QuotaError };
 
 /** Session options when openSession() is not given them */
 const SESSION_DEFAULTS = {
-  proxyCountry: null, // null: the provider's default egress
-  idleTimeoutSec: 60, // a session whose client is gone (its process was killed) ends this long after at the latest
+  proxyCountry: null,
+  idleTimeoutSec: 60,
   maxDurationMs: 15 * 60_000,
 };
 
 /**
- * The session options of openSession() with the defaults filled in (SESSION_DEFAULTS); throws when one is unknown
- * or out of range, so that a program can check its configuration before it opens any session:
+ * The session options of openSession() with the defaults filled in; throws when one is unknown or out of range,
+ * so that a program can check its configuration before it opens any session:
  *   proxyCountry     country code: the provider's proxy there; null: its default egress
- *   idleTimeoutSec   a session whose client is gone ends this long after at the latest; at least twice the
- *                    keep-alive interval (session.js)
- *   maxDurationMs    the session ends this long after it was opened at the latest
+ *   idleTimeoutSec   a session whose client is gone ends this long after at the latest, or after the provider's
+ *                    minIdleTimeoutSec if longer (≥ 2 × KEEP_ALIVE_MS)
+ *   maxDurationMs    a session ends this long after it was opened at the latest
  */
 export function sessionOptions(options = {}) {
   const unknown = Object.keys(options).filter((k) => !Object.hasOwn(SESSION_DEFAULTS, k));
@@ -33,26 +34,24 @@ export function sessionOptions(options = {}) {
   return o;
 }
 
+/** How long a session lasts at most, whatever becomes of its process: closed at maxDurationMs, else ended by its provider once idle */
+const sessionMsAtMost = (o, settings) => o.maxDurationMs + Math.max(o.idleTimeoutSec, settings.minIdleTimeoutSec) * 1000;
+
 /**
- * Remote browsers from several providers behind one interface: a session is asked for by provider name, the way
- * an LLM request names its model. Every session is recorded in a ledger (ledger.js), which the usage of each
- * provider account and, for providers that cannot report it themselves, its quota are read from.
- *
- * Which provider to use, how many sessions to hold and when to stop using one are the caller's decisions:
- * OneBrowser opens the sessions it is asked for.
+ * Remote browsers from several providers behind one interface: a session is asked for by provider name. Every
+ * session is recorded in a ledger (ledger.js) shared by the programs on the machine, so that each provider
+ * account's usage, and what its quota has left at any moment, are known. Which provider to use, and when to
+ * stop using one, are the caller's decisions.
  *
- * new OneBrowser({ client, ledgerPath, providers, adapters })
- *   client       the program using it, recorded with each session (several programs may share one ledger)
- *   ledgerPath   SQLite file of the ledger (default: defaultLedgerPath() in ledger.js; ':memory:' for tests),
- *                opened when first needed
- *   providers    settings per provider name: apiKey (else from the environment, see credentials.js), and the
- *                adapter's own settings on top of its defaults (providers/<name>.js)
- *   adapters     further adapters by provider name, or replacements of built-in ones (providers/index.js)
+ * client: the program using it, recorded with each session; ledgerPath: the ledger's SQLite file, opened when
+ * first needed; providers: settings per provider name on top of its adapter's defaults (providers/index.js),
+ * apiKey among them (else credentials.js); adapters: further or replacement adapters by provider name.
  */
 export class OneBrowser {
-  #providers = new Map(); // name → { adapter, settings: its defaults with the given ones on top, apiKey: the one given }
+  #providers = new Map(); // name → { adapter, settings, apiKey }
   #ledger = null;
   #open = new Set();
+  #readings = new Map(); // provider → { latest, done }: its latest quota reading, and the latest one done
 
   constructor({ client, ledgerPath = defaultLedgerPath(), providers = {}, adapters = {} }) {
     if (!client?.trim()) throw new Error('onebrowser: client must name the program using it');
@@ -60,14 +59,13 @@ export class OneBrowser {
     this.ledgerPath = ledgerPath;
     for (const [name, adapter] of Object.entries({ ...ADAPTERS, ...adapters })) {
       checkAdapter(name, adapter);
-      const { apiKey, ...settings } = providers[name] ?? {};
-      this.#providers.set(name, { adapter, settings: { ...adapter.defaults, ...settings }, apiKey });
+      const { apiKey, ...given } = providers[name] ?? {};
+      this.#providers.set(name, { adapter, settings: fullSettings(name, { ...adapter.defaults, ...given }), apiKey });
     }
     const unknown = Object.keys(providers).filter((name) => !this.#providers.has(name));
     if (unknown.length) throw new Error(`onebrowser: no adapter for provider ${unknown.join(', ')}`);
   }
 
-  /** Names of the providers it can open sessions with */
   get providers() {
     return [...this.#providers.keys()];
   }
@@ -76,10 +74,14 @@ export class OneBrowser {
     return (this.#ledger ??= new Ledger(this.ledgerPath));
   }
 
-  /** The adapter, settings and API key of `provider`; throws when it is unknown or has no API key */
-  #ready(provider) {
+  #known(provider) {
     const p = this.#providers.get(provider);
     if (!p) throw new Error(`unknown provider ${provider} (expected ${this.providers.join(', ')})`);
+    return p;
+  }
+
+  #ready(provider) {
+    const p = this.#known(provider);
     return { ...p, apiKey: readApiKey(provider, p.apiKey) };
   }
 
@@ -89,13 +91,13 @@ export class OneBrowser {
   }
 
   /**
-   * A new session with `provider`, recorded in the ledger once the provider has created it; options: see
-   * sessionOptions(). Throws when the provider does not create one; QuotaError when it refuses for the account's
-   * quota.
+   * A new session with `provider` (options: sessionOptions()), in the ledger from when its provider has created
+   * it. Throws when the provider creates none; QuotaError when it refuses for the account's quota.
    */
   async openSession({ provider, ...options }) {
     const { adapter, settings, apiKey } = this.#ready(provider);
     const o = sessionOptions(options);
+    const openedAt = Date.now();
     let remote;
     try {
       remote = await adapter.createSession(settings, apiKey, o);
@@ -103,40 +105,91 @@ export class OneBrowser {
       if (e instanceof QuotaError) throw e;
       throw new Error(`failed to create a ${provider} session: ${e.message}`);
     }
-    const session = new Session({
-      provider, remote, maxDurationMs: o.maxDurationMs,
-      release: async (s) => {
-        this.#open.delete(s);
-        this.#store.closed(s);
-        await adapter.releaseSession(settings, apiKey, s);
-      },
-    });
+    const session = new Session({ provider, remote, openedAt, maxDurationMs: o.maxDurationMs, release: (s) => this.#release(adapter, settings, apiKey, s) });
     try {
-      this.#store.opened({ provider, id: session.id, client: this.client, openedAt: session.openedAt });
+      this.#store.opened({ provider, id: session.id, client: this.client, openedAt, endsBy: openedAt + sessionMsAtMost(o, settings) });
     } catch (e) {
-      await session.close().catch(() => {}); // a session the ledger has no record of is not handed out
+      await session.close().catch(() => {}); // a session the ledger does not know is not handed out
       throw e;
     }
     this.#open.add(session);
     return session;
   }
 
+  /** Releases `session` at its provider and records it closed: when it was released, so its whole billed time counts */
+  async #release(adapter, settings, apiKey, session) {
+    try {
+      await adapter.releaseSession(settings, apiKey, session);
+      const closedAt = Date.now();
+      this.#store.closed({ provider: session.provider, id: session.id, closedAt });
+      return closedAt;
+    } finally {
+      this.#open.delete(session);
+    }
+  }
+
   /**
-   * What is left of the account's quota with `provider`: { remaining, unit, renewsAt } in the provider's own
-   * unit; renewsAt (ms) when it renews by itself, null when only a top-up renews it. Throws when it cannot be read.
+   * Reads the account's quota with `provider` from the provider, unless a reading in progress or started at most
+   * maxAgeMs ago can be used (a failed one throws again); then answers as quota().
    */
-  async quota(provider) {
+  async readQuota(provider, { maxAgeMs = 0 } = {}) {
+    const reading = this.#reading(provider, maxAgeMs);
+    await reading.settled;
+    if (reading.error) throw reading.error;
+    return this.quota(provider);
+  }
+
+  /**
+   * What is left of the account's quota now, in the provider's unit: { remaining, unbilled, unit, renewsAt }. The
+   * last reading shows the sessions that ended billingDelayMs before it; `unbilled` is what the ledger's others
+   * cost at the provider's price, open ones as if they lasted as long as they can, and remaining the reading less
+   * that. renewsAt (ms): when the quota renews by itself; null: only a top-up renews it. Throws until the
+   * provider has been read, and while its last reading failed.
+   */
+  quota(provider) {
+    const { settings } = this.#known(provider);
+    const reading = this.#readings.get(provider)?.done;
+    if (!reading) throw new Error(`the quota of ${provider} has not been read yet (readQuota)`);
+    if (reading.error) throw reading.error;
+    const unbilled = this.#store.openSince(provider, reading.billedBefore).reduce((cost, s) => cost + sessionCost(settings.price, s.durationMs), 0);
+    const { remaining, unit, renewsAt = null } = reading.value;
+    return { remaining: remaining - unbilled, unbilled, unit, renewsAt };
+  }
+
+  /** The latest reading of the provider's quota if it is in progress or at most maxAgeMs old, else a new one */
+  #reading(provider, maxAgeMs) {
+    const readings = this.#readings.get(provider) ?? { latest: null, done: null };
+    this.#readings.set(provider, readings);
+    const { latest } = readings;
+    const inProgress = latest && latest !== readings.done;
+    if (inProgress || (latest && Date.now() - latest.startedAt <= maxAgeMs)) return latest;
     const { adapter, settings, apiKey } = this.#ready(provider);
-    const q = await adapter.quota(settings, apiKey, this.#store.history(provider));
-    if (!(Number.isFinite(q?.remaining) && typeof q.unit === 'string')) throw new Error(`${provider} answered no quota: ${JSON.stringify(q)}`);
-    return { remaining: q.remaining, unit: q.unit, renewsAt: q.renewsAt ?? null };
+    const startedAt = Date.now();
+    const reading = { startedAt, billedBefore: startedAt - settings.billingDelayMs, value: null, error: null };
+    readings.latest = reading;
+    reading.settled = (async () => {
+      try {
+        const q = await adapter.quota(settings, apiKey, this.#store.history(provider, reading.billedBefore));
+        if (!(Number.isFinite(q?.remaining) && typeof q.unit === 'string')) throw new Error(`${provider} answered no quota: ${JSON.stringify(q)}`);
+        reading.value = q;
+      } catch (e) {
+        reading.error = e;
+      }
+      readings.done = reading;
+    })();
+    return reading;
+  }
+
+  /** What a session with these options costs at most, in the unit of the provider's quota */
+  maxSessionCost(provider, options) {
+    const { settings } = this.#known(provider);
+    return sessionCost(settings.price, sessionMsAtMost(sessionOptions(options), settings));
   }
 
   /**
-   * Stores each provider's record (duration, proxy traffic) of the sessions in the ledger that have ended and have
-   * none yet; sessions still running wait for a later call. A provider that cannot be reached, or has no API key,
-   * is left for a later call too. Sessions of a provider it has no adapter for (another program's own) are left
-   * to the programs that have one. Returns { reported: sessions completed, failed: [{ provider, error }] }.
+   * Stores the providers' records (duration, proxy traffic) of the ledger's ended sessions that have none yet:
+   * { reported, failed: [{ provider, error }] }. What cannot be fetched now, and the sessions of providers it has
+   * no adapter for, are left for a later call.
    */
   async syncUsage() {
     const store = this.#store;
@@ -157,10 +210,8 @@ export class OneBrowser {
 
   /**
    * Sessions opened since `since` (ms), per UTC day, provider and client:
-   * [{ day, provider, client, sessions, minutes, untimed, unsynced, proxyBytes }]. Minutes are the provider's
-   * record where syncUsage has stored it, otherwise the open-to-close timing of the process that opened the
-   * session; untimed: sessions with neither (their process ended before closing them and the provider has not
-   * reported them yet); unsynced: sessions without the provider's record.
+   * [{ day, provider, client, sessions, minutes, untimed, unsynced, proxyBytes }]. minutes: the provider's record
+   * (syncUsage), else the open-to-close timing; untimed: sessions with neither; unsynced: those without the record.
    */
   usage({ since }) {
     return this.#store.usage(since);
@@ -173,7 +224,6 @@ export class OneBrowser {
     this.#ledger = null;
   }
 
-  /** close(), for `await using browsers = new OneBrowser(…)` */
   [Symbol.asyncDispose]() {
     return this.close();
   }

package/src/ledger.js

@@ -14,41 +14,85 @@ export function defaultLedgerPath() {
   return path.join(data, 'onebrowser', 'sessions.db');
 }
 
-/**
- * sessions   every remote browser session: recorded when its provider has created it (it is billed from then on,
- *            even if connecting fails), closed when released, and completed with the provider's own record
- *            (duration, proxy traffic) once the session has ended and syncUsage has fetched it
- */
+/** Every remote browser session, from when its provider has created it: it is billed from then on, even if connecting fails */
 const SCHEMA = `
-CREATE TABLE IF NOT EXISTS sessions (
+CREATE TABLE sessions (
   provider      TEXT NOT NULL,
   id            TEXT NOT NULL,            -- the session id its provider gave it
   client        TEXT NOT NULL,            -- the program that opened it (OneBrowser's client)
-  opened_at     TEXT NOT NULL,            -- when the provider created it
-  closed_at     TEXT,                     -- when it was released; empty if its process ended first
+  opened_at     TEXT NOT NULL,            -- when it was asked for; its provider created it right after
+  ends_by       TEXT NOT NULL,            -- when it has ended at the latest, whatever becomes of its process
+  closed_at     TEXT,                     -- when its provider released it; empty until then, and if it never was
   duration_ms   INTEGER,                  -- the provider's record, once the session has ended
   proxy_bytes   INTEGER,                  -- proxy traffic in the provider's record
   synced_at     TEXT,                     -- when the provider's record was stored; empty = not yet
   PRIMARY KEY (provider, id)
 );
-CREATE INDEX IF NOT EXISTS idx_sessions_opened ON sessions(provider, opened_at);
+CREATE INDEX idx_sessions_opened ON sessions(provider, opened_at);
 `;
 
-/** Duration of a session: the provider's record, else the open-to-close timing of the process that opened it */
-const SESSION_MS = 'COALESCE(duration_ms, CAST((julianday(closed_at) - julianday(opened_at)) * 86400000 AS INTEGER))';
+/**
+ * The version of SCHEMA (PRAGMA user_version), and the step to it from each earlier one: a ledger outlives the
+ * onebrowser that made it. onebrowser 0.1–0.3 made version 1 and left user_version 0.
+ */
+const VERSION = 2;
+const UPGRADES = {
+  // 1 → 2: ends_by, as if the sessions of 1 had the default session options (15 min, then 60 s idle). Each step
+  // makes its version as that version was, whatever SCHEMA has become since.
+  1: `ALTER TABLE sessions RENAME TO sessions_1;
+      DROP INDEX idx_sessions_opened;
+      CREATE TABLE sessions (
+        provider TEXT NOT NULL, id TEXT NOT NULL, client TEXT NOT NULL, opened_at TEXT NOT NULL, ends_by TEXT NOT NULL,
+        closed_at TEXT, duration_ms INTEGER, proxy_bytes INTEGER, synced_at TEXT, PRIMARY KEY (provider, id)
+      );
+      CREATE INDEX idx_sessions_opened ON sessions(provider, opened_at);
+      INSERT INTO sessions (provider, id, client, opened_at, ends_by, closed_at, duration_ms, proxy_bytes, synced_at)
+        SELECT provider, id, client, opened_at, strftime('%Y-%m-%dT%H:%M:%fZ', opened_at, '+16 minutes'), closed_at, duration_ms, proxy_bytes, synced_at
+        FROM sessions_1;
+      DROP TABLE sessions_1;`,
+};
+
+/** ms from one ISO time to another */
+const msBetween = (from, to) => `CAST(ROUND((julianday(${to}) - julianday(${from})) * 86400000) AS INTEGER)`;
+
+/** How long a session lasted: the provider's record, else the open-to-close timing of the process that opened it */
+const SESSION_MS = `COALESCE(duration_ms, ${msBetween('opened_at', 'closed_at')})`;
+
+/** How long a session lasts at most: as SESSION_MS, or until it ends at the latest while it has no timing */
+const SESSION_MS_AT_MOST = `COALESCE(${SESSION_MS}, ${msBetween('opened_at', 'ends_by')})`;
+
+/** When a session has ended or ends at the latest */
+const ENDED_AT = 'COALESCE(closed_at, ends_by)';
 
 const iso = (ms) => new Date(ms).toISOString();
 const int = (x) => (x === null || x === undefined || !Number.isFinite(Number(x)) ? null : Math.trunc(Number(x)));
 
 export class Ledger {
+  #file;
   #db;
   #stmts = new Map();
 
   constructor(file) {
     if (file !== ':memory:') fs.mkdirSync(path.dirname(file), { recursive: true });
+    this.#file = file;
     this.#db = new DatabaseSync(file);
     this.#db.exec('PRAGMA journal_mode=WAL; PRAGMA busy_timeout=5000;'); // several processes share it
-    this.#db.exec(SCHEMA);
+    this.#migrate();
+  }
+
+  /** Makes the ledger, or brings an earlier one up to date, in one transaction: another process may be opening it too */
+  #migrate() {
+    const version = () => this.#db.prepare('PRAGMA user_version').get().user_version;
+    if (version() === VERSION) return;
+    this.tx(() => {
+      if (!this.#db.prepare("SELECT 1 FROM sqlite_schema WHERE type = 'table' AND name = 'sessions'").get()) this.#db.exec(SCHEMA);
+      else {
+        const from = version() || 1;
+        if (from > VERSION) throw new Error(`onebrowser: the ledger ${this.#file} was made by a later onebrowser (schema ${from}; this one knows ${VERSION})`);
+        for (let v = from; v < VERSION; v++) this.#db.exec(UPGRADES[v]);
+      }
+      this.#db.exec(`PRAGMA user_version = ${VERSION}`);
+    });
   }
 
   #q(sql) {
@@ -57,23 +101,29 @@ export class Ledger {
     return s;
   }
 
-  opened({ provider, id, client, openedAt }) {
-    this.#q('INSERT INTO sessions (provider, id, client, opened_at) VALUES (?,?,?,?)').run(provider, id, client, iso(openedAt));
+  opened({ provider, id, client, openedAt, endsBy }) {
+    this.#q('INSERT INTO sessions (provider, id, client, opened_at, ends_by) VALUES (?,?,?,?,?)').run(provider, id, client, iso(openedAt), iso(endsBy));
   }
 
   closed({ provider, id, closedAt }) {
     this.#q('UPDATE sessions SET closed_at=? WHERE provider=? AND id=? AND closed_at IS NULL').run(iso(closedAt), provider, id);
   }
 
-  /** The record of one provider's sessions, as a provider adapter reads it for its quota (providers/index.js) */
-  history(provider) {
+  /** The provider's sessions that a quota reading shows, those that ended before `billedBefore` (ms); openSince() has the rest */
+  history(provider, billedBefore) {
     return {
-      /** Session time (ms) of the sessions opened since `since` (ms) that have a duration */
-      sessionMsSince: (since) => this.#q(`SELECT COALESCE(SUM(${SESSION_MS}), 0) ms FROM sessions WHERE provider=? AND opened_at >= ?`).get(provider, iso(since)).ms,
+      /** Their session time (ms) since `since` (ms), each as long as it can have lasted while it has no timing */
+      endedSessionMsSince: (since) =>
+        this.#q(`SELECT COALESCE(SUM(${SESSION_MS_AT_MOST}), 0) ms FROM sessions WHERE provider=? AND opened_at >= ? AND ${ENDED_AT} < ?`).get(provider, iso(since), iso(billedBefore)).ms,
     };
   }
 
-  /** Sessions with one of `providers` whose provider's record has not been stored yet: [{ provider, id, openedAt, closedAt }] (ISO times) */
+  /** The provider's sessions open at any time since `at` (ms): [{ durationMs }], as long as they can last while untimed */
+  openSince(provider, at) {
+    return this.#q(`SELECT ${SESSION_MS_AT_MOST} durationMs FROM sessions WHERE provider=? AND ${ENDED_AT} >= ?`).all(provider, iso(at));
+  }
+
+  /** Sessions of `providers` without their provider's record yet: [{ provider, id, openedAt, closedAt }] (ISO times) */
   awaitingUsage(providers) {
     return this.#q(
       'SELECT provider, id, opened_at openedAt, closed_at closedAt FROM sessions WHERE synced_at IS NULL AND provider IN (SELECT value FROM json_each(?)) ORDER BY opened_at',
@@ -84,8 +134,9 @@ export class Ledger {
     this.#q('UPDATE sessions SET duration_ms=?, proxy_bytes=?, synced_at=? WHERE provider=? AND id=?').run(int(durationMs), int(proxyBytes), iso(Date.now()), provider, id);
   }
 
+  /** Runs fn in a transaction that takes the write lock at once: another process may be writing too */
   tx(fn) {
-    this.#db.exec('BEGIN');
+    this.#db.exec('BEGIN IMMEDIATE');
     try {
       const r = fn();
       this.#db.exec('COMMIT');

package/src/providers/anchor.js

@@ -12,6 +12,11 @@ import { json } from './http.js';
  */
 export const defaults = {
   apiBase: 'https://api.anchorbrowser.io/v1',
+  // credits ($1 each): $0.01 a browser and, by its docs, $0.05 an hour by the minute; the sessions' own records
+  // (credits_used) bill more, about $0.06 an hour and a step of $0.003 in the second minute, which this covers
+  price: { perSession: 0.01, perHour: 0.15, stepSec: 60 },
+  billingDelayMs: 5 * 60_000, // seen within 10 s
+  minIdleTimeoutSec: 60, // idle_timeout is in whole minutes, at least 1
 };
 
 const headers = (apiKey) => ({ 'anchor-api-key': apiKey });

package/src/providers/firecrawl.js

@@ -13,6 +13,8 @@ import { json } from './http.js';
  */
 export const defaults = {
   apiBase: 'https://api.firecrawl.dev/v2',
+  price: { perHour: 120, stepSec: 30, minSec: 60 }, // credits: 2 a minute, in whole credits rounded up, at least 1 minute
+  billingDelayMs: 5 * 60_000, // seen within 10 s
 };
 
 const TTL_SEC = { min: 30, max: 3600 }; // what Firecrawl takes for ttl; activityTtl has the same maximum

package/src/providers/hyperbrowser.js

@@ -9,6 +9,8 @@ import { json } from './http.js';
  */
 export const defaults = {
   apiBase: 'https://api.hyperbrowser.ai/api',
+  price: { perHour: 100, stepSec: 60 }, // credits; its rounding is not documented
+  billingDelayMs: 5 * 60_000, // billed while the session runs, seen within 10 s of its end
 };
 
 const headers = (apiKey) => ({ 'x-api-key': apiKey });

package/src/providers/index.js

@@ -1,3 +1,4 @@
+import { fullPrice } from '../cost.js';
 import * as anchor from './anchor.js';
 import * as firecrawl from './firecrawl.js';
 import * as hyperbrowser from './hyperbrowser.js';
@@ -7,26 +8,22 @@ import * as steel from './steel.js';
 import * as tinyfish from './tinyfish.js';
 
 /**
- * Provider adapters, by provider name: the only provider-specific code. Each exports:
- *   defaults                 its settings (API base URLs, plan facts such as monthlyHours); OneBrowser's
- *                            `providers` option overrides them per provider. The API key is not among them:
- *                            each function gets it as its own argument
- *   createSession(settings, apiKey, options) → { id, cdpUrl, egress }
- *       options: { proxyCountry, idleTimeoutSec, maxDurationMs } (OneBrowser.openSession), mapped onto the
- *       provider's own parameters. Throws on failure; QuotaError (errors.js) when the provider refuses the
- *       session because the account's quota is used up
- *   releaseSession(settings, apiKey, session)   ends the session; throws on failure
+ * Provider adapters by name: the only provider-specific code. Each exports:
+ *   defaults   its settings, which OneBrowser's `providers` option overrides:
+ *     price               what its sessions cost, in the unit of its quota (cost.js)
+ *     billingDelayMs      how long after a session has ended its quota reading shows it, at the latest
+ *     minIdleTimeoutSec   the shortest idle timeout it takes (default 0)
+ *     and its own         API base URLs, plan facts such as monthlyHours
+ *   createSession(settings, apiKey, { proxyCountry, idleTimeoutSec, maxDurationMs }) → { id, cdpUrl, egress }
+ *       throws QuotaError (errors.js) when the provider refuses the session for the account's quota
+ *   releaseSession(settings, apiKey, session)
  *   sessionUsage(settings, apiKey, [{ id, openedAt, closedAt }]) → [{ id, durationMs, proxyBytes }]
- *       the record of those sessions that have ended: the provider's own, or, for a provider whose records the
- *       API key cannot read, the ledger's timing (closedAt is empty for a session no process closed); throws on
- *       failure
+ *       the provider's record of those that have ended, or the ledger's timing where its API key cannot read one
  *   quota(settings, apiKey, history) → { remaining, unit, renewsAt? }
- *       what is left of the account's quota, in the provider's own unit (USD, credits, hours, …), and when it
- *       renews if it does by itself (ms); history: the ledger's record of the provider's sessions
- *       (Ledger.history). Throws when it cannot be read
- *
- * Their requests go through http.js, which turns every status other than 2xx into an HttpError: an adapter
- * handles only the statuses that mean something of their own.
+ *       what the account has left in the provider's unit, and when it renews by itself (ms); history: the
+ *       ledger's sessions that the reading shows (Ledger.history), for a provider that cannot count its usage
+ * Every function throws when it fails. Requests go through http.js, which throws HttpError for a status other
+ * than 2xx.
  */
 export const ADAPTERS = { tinyfish, steel, hyperbrowser, lightpanda, kernel, anchor, firecrawl };
 
@@ -37,3 +34,16 @@ export function checkAdapter(name, adapter) {
   const missing = CONTRACT.filter((f) => typeof adapter?.[f] !== 'function');
   if (missing.length) throw new Error(`provider ${name}: its adapter lacks ${missing.join(', ')}`);
 }
+
+/** An adapter's settings with the defaults of those every adapter has; throws when one of them is missing or wrong */
+export function fullSettings(name, { price, billingDelayMs, minIdleTimeoutSec = 0, ...own }) {
+  const atLeast0 = (x) => Number.isFinite(x) && x >= 0;
+  try {
+    const full = fullPrice(price);
+    if (!atLeast0(billingDelayMs)) throw new Error(`billingDelayMs must be a number ≥ 0, not ${billingDelayMs}`);
+    if (!atLeast0(minIdleTimeoutSec)) throw new Error(`minIdleTimeoutSec must be a number ≥ 0, not ${minIdleTimeoutSec}`);
+    return { ...own, price: full, billingDelayMs, minIdleTimeoutSec };
+  } catch (e) {
+    throw new Error(`provider ${name}: ${e.message}`);
+  }
+}

package/src/providers/kernel.js

@@ -14,6 +14,8 @@ import { utcMonth } from './month.js';
 export const defaults = {
   apiBase: 'https://api.onkernel.com',
   monthlyHours: 80, // headless browser hours a month that the free plan's credits pay for, rounded down
+  price: { perHour: 1 }, // the quota is in headless browser hours, billed by the second
+  billingDelayMs: 5 * 60_000, // seen within 10 s
 };
 
 const headers = (apiKey) => ({ Authorization: `Bearer ${apiKey}` });
@@ -42,8 +44,8 @@ export async function releaseSession(settings, apiKey, session) {
 /**
  * Browser hours left of the month's monthlyHours, after the uptime of every session of the account this month:
  * Kernel's own records, which include sessions opened by any program. The sessions are listed newest first, so
- * the listing stops at a page that holds none of this month. The hours are assumed to renew with each calendar
- * month (UTC).
+ * the listing stops at a page that holds none of this month. Kernel counts usage from the first of each month,
+ * 00:00 UTC (https://www.kernel.sh/docs/info/spending-caps), and has no API that reads what its credits leave.
  */
 export async function quota(settings, apiKey) {
   const month = utcMonth();

package/src/providers/lightpanda.js

@@ -13,6 +13,8 @@ const MAX_CONNECTION_MS = 15 * 60_000;
 export const defaults = {
   connectBase: 'wss://euwest.cloud.lightpanda.io/ws',
   monthlyHours: 10, // browser hours a month on the free plan
+  price: { perHour: 1 }, // the quota is in browser hours, billed by the second
+  billingDelayMs: 0, // the quota is the ledger's record
 };
 
 export async function createSession(settings, apiKey, { proxyCountry }) {
@@ -30,13 +32,13 @@ export async function releaseSession() {}
 
 /**
  * Browser hours left of the month's monthlyHours. Lightpanda's console shows the month's usage, but the token
- * cannot read it: the month's usage is the ledger's record of the sessions (history), which is all of it while
- * the account is used through ledgers of this machine only. The hours are assumed to renew with each calendar
- * month (UTC).
+ * cannot read it: the month's usage is the ledger's record of the sessions that have ended (history), which is
+ * all of it while the account is used through ledgers of this machine only. The hours are assumed to renew with
+ * each calendar month (UTC).
  */
 export async function quota(settings, apiKey, history) {
   const month = utcMonth();
-  const usedHours = history.sessionMsSince(month.start) / 3_600_000;
+  const usedHours = history.endedSessionMsSince(month.start) / 3_600_000;
   return { remaining: settings.monthlyHours - usedHours, unit: 'hours', renewsAt: month.next };
 }
 

package/src/providers/steel.js

@@ -8,6 +8,8 @@ import { json } from './http.js';
 export const defaults = {
   apiBase: 'https://api.steel.dev/v1',
   connectBase: 'wss://connect.steel.dev',
+  price: { perHour: 0.1, stepSec: 60 }, // USD on the Launch plan, by the minute rounded up
+  billingDelayMs: 5 * 60_000, // seen within 11 s
 };
 
 const headers = (apiKey) => ({ 'steel-api-key': apiKey });

package/src/providers/tinyfish.js

@@ -10,6 +10,8 @@ import { json } from './http.js';
 export const defaults = {
   apiBase: 'https://api.browser.tinyfish.ai',
   walletUrl: 'https://agent.tinyfish.ai/v1/wallet',
+  price: { perHour: 0.12, stepSec: 60 }, // USD: $0.002 a minute, proxy included; its rounding is not documented
+  billingDelayMs: 5 * 60_000, // seen within 64 s
 };
 
 const headers = (apiKey) => ({ 'X-API-Key': apiKey });

package/src/session.js

@@ -1,45 +1,39 @@
-/**
- * A CDP command this often while connected keeps a provider's idle timeout from ending a session that is in use
- * (also while a page waits long for an answer). OneBrowser requires idleTimeoutSec to be at least twice as long.
- */
+/** A CDP command this often keeps a provider's idle timeout from ending a session in use; idleTimeoutSec must be at least twice as long */
 export const KEEP_ALIVE_MS = 15_000;
 
 /** Playwright errors carry a multi-line call log; the first line says what failed */
 const firstLine = (e) => String(e.message).split('\n')[0];
 
 /**
- * One remote browser session, as OneBrowser.openSession() opened it: created by its provider and recorded in the
- * ledger. Use it over CDP: through cdpUrl with any CDP client, or through connect() / newPage() with Playwright.
- * It ends at the latest maxDurationMs after it was opened: this process closes it then (a client using it sees
- * its connection drop). close() releases it; one never closed (its process was killed) is ended by its provider
- * idleTimeoutSec after its client left.
- *
- *   id, provider, egress     the provider's session id, its name, and the egress the session uses
- *   cdpUrl                   CDP WebSocket URL (it may carry the API key: never log it)
- *   openedAt, closedAt       ms; closedAt is null while open
+ * A remote browser session (OneBrowser.openSession), used over CDP: cdpUrl with any client (it may carry the API
+ * key: never log it), or connect() / newPage() with Playwright. This process closes it maxDurationMs after it was
+ * opened; one whose process died is ended by its provider idleTimeoutSec (at least its minIdleTimeoutSec) after
+ * its client left.
+ * openedAt: when it was asked for; closedAt: when its provider released it, null until then.
  */
 export class Session {
   #release;
-  #browser = null; // the connection in progress or made: a promise of Playwright's Browser
+  #closing = null;
+  #browser = null; // a promise of Playwright's Browser
   #keepAlive = null;
   #deadline;
 
-  /** release(session): records the session closed and releases it at its provider (OneBrowser) */
-  constructor({ provider, remote, maxDurationMs, release }) {
+  /** release(session) → closedAt: releases it at its provider and records it closed (OneBrowser) */
+  constructor({ provider, remote, openedAt, maxDurationMs, release }) {
     this.provider = provider;
     this.id = remote.id;
     this.egress = remote.egress;
     this.cdpUrl = remote.cdpUrl;
-    this.openedAt = Date.now();
+    this.openedAt = openedAt;
     this.closedAt = null;
     this.#release = release;
-    this.#deadline = setTimeout(() => this.close().catch(() => {}), maxDurationMs); // a release that fails here leaves the session to the provider's idle timeout
+    this.#deadline = setTimeout(() => this.close().catch(() => {}), openedAt + maxDurationMs - Date.now());
     this.#deadline.unref();
   }
 
-  /** Playwright's Browser over this session's CDP connection, made once; the keep-alive runs while it is connected */
+  /** Playwright's Browser over this session's CDP connection, made once; a keep-alive runs while it is connected */
   connect() {
-    if (this.closedAt) return Promise.reject(new Error(`${this.provider} session ${this.id} is closed`));
+    if (this.#closing) return Promise.reject(new Error(`${this.provider} session ${this.id} is closed`));
     this.#browser ??= this.#connect();
     return this.#browser;
   }
@@ -54,7 +48,7 @@ export class Session {
     }
     try {
       const cdp = await browser.newBrowserCDPSession();
-      if (this.closedAt) throw new Error(`${this.provider} session ${this.id} is closed`); // closed while connecting
+      if (this.#closing) throw new Error(`${this.provider} session ${this.id} is closed`);
       this.#keepAlive = setInterval(() => cdp.send('Browser.getVersion').catch(() => {}), KEEP_ALIVE_MS);
       this.#keepAlive.unref();
     } catch (e) {
@@ -64,10 +58,7 @@ export class Session {
     return browser;
   }
 
-  /**
-   * A new page in the browser's default context. Always a new one: the page a remote browser starts with is not
-   * always one that can be navigated.
-   */
+  /** A new page in the default context: the page a remote browser starts with cannot always be navigated */
   async newPage() {
     const browser = await this.connect();
     const context = browser.contexts()[0] ?? (await browser.newContext());
@@ -75,22 +66,20 @@ export class Session {
   }
 
   /**
-   * Disconnects and releases the session at its provider; only the first call does. The ledger records it closed
-   * in any case. Throws when the provider could not release it: the provider then ends it by itself,
-   * idleTimeoutSec after the disconnect.
+   * Disconnects and releases the session; every call answers as the first. Throws when its provider could not
+   * release it: the ledger then counts it as lasting as long as it can, as its provider ends it by itself.
    */
-  async close() {
-    if (this.closedAt) return;
-    this.closedAt = Date.now();
+  close() {
+    return (this.#closing ??= this.#close());
+  }
+
+  async #close() {
     clearTimeout(this.#deadline);
     clearInterval(this.#keepAlive);
-    const browser = this.#browser;
-    this.#browser = null;
-    await browser?.then((b) => b.close()).catch(() => {});
-    await this.#release(this);
+    await this.#browser?.then((b) => b.close()).catch(() => {});
+    this.closedAt = await this.#release(this);
   }
 
-  /** close(): `await using session = await browsers.openSession(…)` releases it at the end of the block */
   [Symbol.asyncDispose]() {
     return this.close();
   }