scaledthought 0.1.0 → 0.2.2

package/README.md

@@ -10,8 +10,9 @@ Agents: the full setup protocol is at <https://scaledthought.com/llms.txt>.
 npx -y scaledthought@latest init --region us   # or: --region ca (data stays in Canada)
 ```
 
-`init` creates a free account (no card), writes `ST_API_KEY` and `ST_BASE_URL` to `./.env` (mode 0600),
-adds `.env` to `.gitignore`, and prints the account, the models live in your region and `next_steps`.
+`init` creates an account, writes `ST_API_KEY` and `ST_BASE_URL` to `./.env` (mode 0600), adds `.env` to
+`.gitignore`, and prints the account, its credit balance (`balance_usd`, `needs_credits`), the models live in your
+region, `next_command` and `next_steps`.
 Running it again is safe. If a key already exists it returns `"already_initialized": true` and the
 account status instead of creating a second account.
 
@@ -25,6 +26,19 @@ ad platform). `account` and `account ad-measurement` print `ad_measurement` (tru
 account could be sent: a `us` account that signed up with an ad click and hasn't opted out; always false in `ca`) and
 `ad_measurement_opt_out` (the stored preference). Neither flag is a secret.
 
+Inference is prepaid, and a new account has no credits: until your human pays, completions return
+`402 insufficient_credits`. So the first thing after `init` is a top-up your human approves:
+
+```bash
+npx -y scaledthought@latest billing topup --amount-usd 5  # prints approval_url and topup_id
+# show your human the approval_url, exactly as printed; they pay by card
+npx -y scaledthought@latest billing wait                  # returns once they've paid; on topup_pending run it again
+```
+
+`billing wait` returns within about 90 seconds (`--timeout-s` to change it), under Claude Code's default 2-minute
+shell timeout. Prefer it to `billing topup --wait`: an agent's shell tool usually shows a command's output only when it
+ends, so the link would reach the human only after the payment it is waiting for.
+
 ```bash
 npx -y scaledthought@latest models --live                 # models serving in your region now
 npx -y scaledthought@latest chat -m auto "Reply with OK"  # one real completion
@@ -33,7 +47,7 @@ npx -y scaledthought@latest account                       # plan, region, spend
 npx -y scaledthought@latest account ad-measurement off    # opt out of ad measurement
 ```
 
-Other commands: `keys list|create|rotate|revoke|revoke-self` (`keys create --expires-in 30d --scopes inference --child`, `keys rotate <id> --grace 24h`), `usage`, `billing status|topup|auto-reload|transactions`, `batches …`,
+Other commands: `keys list|create|rotate|revoke|revoke-self` (`keys create --expires-in 30d --scopes inference --child`, `keys rotate <id> --grace 24h`), `usage`, `billing status|topup|wait|auto-reload|transactions`, `batches …`,
 `fine-tune …`, `benchmarks <id>`, `status` (with your account's notices when a key is set), `doctor` (setup check),
 `webhooks add <url> [--events …]|list|remove <id>` (signed callbacks), `transcribe <file>` (speech to text, `--translate` for English,
 `--format srt|vtt|text|verbose_json`) and `speak -o out.mp3 "text"` (text to speech, streamed to the file; US
@@ -46,4 +60,4 @@ Use the key from any OpenAI SDK: `base_url = $ST_BASE_URL`, `api_key = $ST_API_K
 - The key's prefix (`st_us_…` / `st_ca_…`) picks the region's hosts. Requests never cross regions.
 - Errors look like `{"error":{"code":"…","message":"…","hint":"…"}}`. Exit code 2 means bad usage, 1 anything else.
 
-Free tier: $1/day of inference across the account, 60 requests/min per key, up to 5 keys, no card.
+Before the first credit purchase an account has lower limits: 60 requests/min per key and up to 5 keys.

package/dist/index.js

@@ -553,8 +553,8 @@ import { join } from "node:path";
 // package.json
 var package_default = {
   name: "scaledthought",
-  version: "0.1.0",
-  description: "Headless open-model inference, run by your agent. Free to start. US or Canada.",
+  version: "0.2.2",
+  description: "Headless open-model inference, run by your agent. Prepaid, pay per token. US or Canada.",
   license: "MIT",
   keywords: [
     "llm",
@@ -631,6 +631,7 @@ function readDotEnv(cwd) {
   }
   return out;
 }
+var CREDITS_HINT = "This account has no credits for this request (inference is prepaid). Run `npx -y scaledthought@latest billing topup --amount-usd 5` (creating it charges nothing) and give your human its message_for_human. If it printed opened_in_browser: true, run `npx -y scaledthought@latest billing wait` in the same turn (again on topup_pending, up to 15 minutes): it returns as soon as they pay. Otherwise end your turn with the message and run billing wait once they're back. Then retry. Don't retry before that or create another account.";
 var HINTS = {
   no_key: "Run `npx -y scaledthought@latest init --region us|ca` in this directory, or set ST_API_KEY.",
   bad_key: "ST_API_KEY must look like st_{us|ca}_{live|test}_<40 chars>. Re-run init in a directory without one.",
@@ -641,17 +642,16 @@ var HINTS = {
   expiry_exceeds_parent: "A key can't outlive the key that creates it. Pass a shorter `--expires-in`.",
   budget_exceeds_parent: "A sub-agent key's daily budget can't exceed what its parent has left today. Pass a smaller `--budget-usd`.",
   budget_exceeded: "This key's daily budget is spent. It resets at 00:00 UTC, or raise it with MCP budget_manage (accounts with credits).",
-  insufficient_credits: "The free $1/day is used up and there aren't enough prepaid credits. Run `billing topup --amount-usd 5` and send your human the approval_url, or wait for 00:00 UTC.",
-  free_tier_unavailable: "No free allowance right now (the first 30 days are over, or the region's free usage is used up until 00:00 UTC). Run `billing topup --amount-usd 20` and send your human the approval_url.",
-  credits_required_for_batches: "Batches are paid from prepaid credits, not the free allowance. Run `billing topup --amount-usd 5` and send your human the approval_url, then retry.",
-  credits_required_for_fine_tuning: "Fine-tuning is paid from prepaid credits, not the free allowance. Run `billing topup --amount-usd 5` and send your human the approval_url, then retry.",
+  insufficient_credits: CREDITS_HINT,
+  credits_required_for_batches: `Batches are paid from prepaid credits. ${CREDITS_HINT}`,
+  credits_required_for_fine_tuning: `Fine-tuning is paid from prepaid credits. ${CREDITS_HINT}`,
   approval_required: "This change needs your human's approval. Send them the approval_url from `billing topup`; disabling or lowering auto-reload needs none.",
   daily_cap_exceeded: "An operator-set daily cap on this account is reached. It resets at 00:00 UTC. Tell your human.",
-  free_tier_limit: "Free accounts can't go above the free tier. Run `billing topup --amount-usd 5` for prepaid credits to lift limits.",
-  free_tier_key_limit: "Free accounts have at most 5 active keys. Revoke one with `keys revoke <id>`, or buy credits with `billing topup`.",
+  free_tier_limit: "Accounts that haven't bought credits have lower limits. The first credit purchase lifts them: run `billing topup --amount-usd 5` and show your human the approval_url.",
+  free_tier_key_limit: "Accounts that haven't bought credits have at most 5 active keys. Revoke one with `keys revoke <id>`, or buy credits with `billing topup`.",
   too_many_pending_topups: "Two approval links are still unpaid. Ask your human to use one (see `billing status` pending_topups), or wait for them to expire.",
   daily_topup_limit: "Top-ups are limited to $2,000 per account per rolling 24 hours (open links and auto-reloads included). Use a smaller amount (see available_usd) or wait.",
-  billing_upgrade_removed: "Run `billing topup --amount-usd 5` and send your human the approval_url.",
+  billing_upgrade_removed: "Run `billing topup --amount-usd 5` and show your human the approval_url.",
   gone: "This endpoint was removed. For credits use `billing topup --amount-usd 5`.",
   fine_tuning_requires_self_hosted: "This base model can't be fine-tuned in your region (it isn't served on our own GPUs). Choose another base model.",
   rate_limit_exceeded: "Wait the number of seconds in retry_after, then retry.",
@@ -756,6 +756,8 @@ async function responseError(res) {
   const retry = res.headers.get("retry-after");
   if (retry)
     extra.retry_after = Number(retry);
+  if (!hint && res.status === 402 && !HINTS[code])
+    hint = CREDITS_HINT;
   return new CliError(code, data.error?.message ?? (res.statusText || `HTTP ${res.status}`), hint, extra);
 }
 async function api(ctx, method, path, opts = {}) {
@@ -902,6 +904,7 @@ async function speak(ctx, o) {
 }
 
 // src/commands.ts
+import { spawn } from "node:child_process";
 import { chmodSync, existsSync as existsSync2, readFileSync as readFileSync3, writeFileSync } from "node:fs";
 import { join as join3, resolve as resolve2 } from "node:path";
 
@@ -8961,6 +8964,8 @@ var EXPERIMENT_METRICS = [
   "signups",
   "activation_rate",
   "paid_rate",
+  "topup_request_rate",
+  "topup_completion_rate",
   "cost_per_activated",
   "cost_per_payer",
   "onboarding_success_rate",
@@ -9220,7 +9225,7 @@ var GrowthResults = object({
   decisions: array(GrowthDecision)
 });
 // ../../packages/schemas/src/legal.ts
-var TERMS_VERSION = "2026-10-02";
+var TERMS_VERSION = "2026-10-10";
 var LEGAL_SITE = "https://scaledthought.com";
 var LEGAL_PATHS = {
   index: "/legal",
@@ -9238,23 +9243,29 @@ var REFUND_POLICY_URL = `${LEGAL_SITE}${LEGAL_PATHS.creditsAndRefunds}`;
 var TERMS_NOTICE = `By creating this account you accept the ScaledThought Terms of Service (${TERMS_URL}) and Privacy Policy ` + `(${PRIVACY_URL}) on behalf of the person or organisation you act for, who is the customer.`;
 
 // src/commands.ts
-var FREE_TIER = {
-  usd_per_day: 1,
-  allowance_days: 30,
-  requests_per_min: 60,
-  max_keys: 5,
-  card_required: false
-};
 var NPX = "npx -y scaledthought@latest";
-function nextSteps(model) {
+var FIRST_TOPUP_USD = 5;
+var TOPUP_COMMAND = `${NPX} billing topup --amount-usd ${FIRST_TOPUP_USD}`;
+var WAIT_COMMAND = `${NPX} billing wait`;
+var WAIT_PATIENCE_MIN = 15;
+var CREDIT_STEPS = [
+  `Inference is prepaid and this account has no credits yet: completions return 402 insufficient_credits until your human pays. Do these first, in order:`,
+  `1. Run: ${TOPUP_COMMAND}. It opens the checkout page in your human's browser and prints approval_url, topup_id and message_for_human. Creating it charges nothing: don't ask first.`,
+  `2. If opened_in_browser is true, the checkout page (where your human accepts the Terms and pays $${FIRST_TOPUP_USD} by card) is already in front of them: tell them so with message_for_human and, in the same turn, run: ${WAIT_COMMAND}. It returns status "paid" with the new balance as soon as they pay; on topup_pending run it again, for up to ${WAIT_PATIENCE_MIN} minutes in all. Don't wait for them to say they've paid.`,
+  `3. If opened_in_browser is false (or it's still unpaid after ${WAIT_PATIENCE_MIN} minutes), end your turn with message_for_human: it holds the approval_url exactly as printed. When they're back, run ${WAIT_COMMAND}. Either way, don't retry the call and don't create another account.`,
+  "4. Then make the call below."
+];
+function nextSteps(model, needsCredits) {
   return [
+    ...needsCredits ? CREDIT_STEPS : [],
     model ? `Verify with one real completion: ${NPX} chat -m ${model} "Reply with OK" (or POST $ST_BASE_URL/chat/completions with that model)` : `No chat model is live in this region right now. Check again with: ${NPX} models --live`,
     `Or let the router pick: ${NPX} chat -m auto "Reply with OK"`,
     "Use it from code: any OpenAI SDK with base_url=$ST_BASE_URL and api_key=$ST_API_KEY (both are in .env)",
     `Optional, connect MCP: ${NPX} mcp`,
-    `Past the free $${FREE_TIER.usd_per_day}/day (for the first ${FREE_TIER.allowance_days} days): ${NPX} billing topup --amount-usd 5 returns an approval_url for your human to buy prepaid credits`
+    ...needsCredits ? [] : [`More credits when needed: ${TOPUP_COMMAND} returns an approval_url for your human (inference is prepaid)`]
   ];
 }
+var balanceOf = (b) => b && typeof b.balance_usd === "number" ? b.balance_usd : null;
 function termsOf(acct = {}) {
   return {
     url: acct.terms_url ?? TERMS_URL,
@@ -9263,10 +9274,18 @@ function termsOf(acct = {}) {
     notice: acct.terms_notice ?? TERMS_NOTICE
   };
 }
-async function liveSummary(ctx, region) {
+async function liveSummary(ctx, region, balanceUsd) {
   const live = await listModels(ctx, { live: true, region });
   const suggested = live.find((m) => m.category !== "embedding" && m.modality === "chat")?.id ?? null;
-  return { newest_models: live.slice(0, 5), suggested_model: suggested, next_steps: nextSteps(suggested) };
+  const needsCredits = (balanceUsd ?? 0) <= 0;
+  return {
+    balance_usd: balanceUsd ?? 0,
+    needs_credits: needsCredits,
+    next_command: needsCredits ? TOPUP_COMMAND : `${NPX} chat -m ${suggested ?? "auto"} "Reply with OK"`,
+    newest_models: live.slice(0, 5),
+    suggested_model: suggested,
+    next_steps: nextSteps(suggested, needsCredits)
+  };
 }
 function signupAttribution(region, opts) {
   const warnings = [];
@@ -9302,13 +9321,13 @@ async function init(ctx, opts) {
       throw new CliError("region_mismatch", `A ${region} key already exists (${where}) but --region ${opts.region} was requested. Nothing was created.`, `Accounts are pinned to one region. Use the existing ${region} account, or run init in a directory with no ST_API_KEY (and no ST_API_KEY in the environment) to create a separate ${opts.region} account.`, { existing_region: region, requested_region: opts.region });
     const status = await account(ctx);
     const ignored = [opts.source !== undefined && "--source", opts.adClick !== undefined && "--ad-click"].filter(Boolean);
+    const shown = withoutFreeFields(status);
     return {
       already_initialized: true,
-      ...status,
+      ...shown,
       key_saved_to: where,
-      free_tier: FREE_TIER,
       terms: termsOf(),
-      ...await liveSummary(ctx, region),
+      ...await liveSummary(ctx, region, balanceOf(status)),
       ...ignored.length ? { warnings: [`${ignored.join(" and ")} apply only to a new account and were not sent.`] } : {}
     };
   }
@@ -9328,17 +9347,16 @@ async function init(ctx, opts) {
   writeEnv(ctx.cwd, { ST_API_KEY: acct.api_key, ST_BASE_URL: acct.base_url });
   ensureGitignored(ctx.cwd);
   const keyed = { ...ctx, env: { ...ctx.env, ST_API_KEY: acct.api_key } };
+  const billing = await api(keyed, "GET", "/v1/billing").catch(() => null);
   return {
     already_initialized: false,
     account_id: acct.account_id,
     region: acct.region,
-    plan: "free",
     base_url: acct.base_url,
     key_saved_to: ".env (ST_API_KEY, ST_BASE_URL)",
-    free_tier: FREE_TIER,
     terms: termsOf(acct),
     ...attribution.source ? { source: acct.source ?? attribution.source } : {},
-    ...await liveSummary(keyed, acct.region),
+    ...await liveSummary(keyed, acct.region, balanceOf(billing)),
     ...attribution.warnings.length ? { warnings: attribution.warnings } : {}
   };
 }
@@ -9409,9 +9427,20 @@ function unitPrices(p) {
   };
 }
 var showModel = (ctx, id, region) => api(ctx, "GET", `/v1/models/${encodeURIComponent(id)}`, { auth: false, region: publicRegion(ctx, region) });
+function withoutFreeFields(o) {
+  const out = {};
+  for (const [k, v] of Object.entries(o)) {
+    if (/^free_/.test(k))
+      continue;
+    if (k === "topup" && typeof v === "string" && /free/i.test(v))
+      continue;
+    out[k] = v;
+  }
+  return out;
+}
 async function account(ctx) {
-  const a = await api(ctx, "GET", "/v1/account");
-  const fields = ["balance_usd", "free_remaining_today_usd", "auto_reload"];
+  const a = withoutFreeFields(await api(ctx, "GET", "/v1/account"));
+  const fields = ["balance_usd", "auto_reload"];
   if (fields.every((f) => (f in a)))
     return a;
   const b = await api(ctx, "GET", "/v1/billing").catch(() => null);
@@ -9512,7 +9541,7 @@ async function chat(ctx, o) {
     usage: usageOut
   };
 }
-var billingStatus = (ctx) => api(ctx, "GET", "/v1/billing");
+var billingStatus = async (ctx) => withoutFreeFields(await api(ctx, "GET", "/v1/billing"));
 var TOPUP_LIMITS = { min_usd: 5, max_usd: 2000, daily_max_usd: 2000, auto_reload_monthly_max_usd: 1e4 };
 function checkTopupLimits(amountUsd, autoReload) {
   const { min_usd, max_usd, daily_max_usd, auto_reload_monthly_max_usd } = TOPUP_LIMITS;
@@ -9529,20 +9558,94 @@ function checkTopupLimits(amountUsd, autoReload) {
     range("auto-reload-monthly-max", autoReload.monthly_limit_usd, autoReload.amount_usd, auto_reload_monthly_max_usd);
 }
 var TOPUP_DONE = new Set(["paid", "expired", "failed", "canceled"]);
-function topupNextSteps(amountUsd, autoReload) {
+function topupNextSteps(topupId, amountUsd, opened, autoReload) {
+  const wait = `${WAIT_COMMAND}${topupId ? ` ${topupId}` : ""}`;
   return [
-    `Send approval_url to your human. They pay $${amountUsd} by card; credits are added once the payment is confirmed.`,
+    opened ? `The checkout page is already open in your human's browser: don't open it again. Tell them with message_for_human (it holds the approval_url in case it didn't open), then in the same turn run: ${wait}. It returns status "paid" with the balance as soon as they pay; on topup_pending run it again, for up to ${WAIT_PATIENCE_MIN} minutes in all. Don't wait for them to say they've paid. If it's still unpaid after that, end your turn with message_for_human.` : `Give your human message_for_human now and end your turn there: it holds the approval_url exactly as printed (a one-time payment link; don't shorten or reformat it). Don't run billing wait (or anything else that waits) before they have the link: they may not see your messages until your turn ends.`,
+    `On that page they accept the Terms and the Credits & Refunds policy and pay $${amountUsd} by card; credits are added once the payment is confirmed. Nothing is charged without their approval.`,
     ...autoReload ? [
       `Approving also saves the card for auto-reload: $${autoReload.amount_usd} whenever the balance drops below $${autoReload.threshold_usd}${autoReload.monthly_limit_usd ? `, at most $${autoReload.monthly_limit_usd} a month` : ""}.`
     ] : [],
-    `Check with: ${NPX} billing status (balance_usd, pending_topups). Nothing is charged without the human's approval.`
+    ...opened ? [] : [
+      `When they say they've paid: ${wait} (returns status "paid" with the balance, at once if already paid; topup_pending means not yet: tell them, don't make a new link).`
+    ],
+    "Once paid, retry the call that returned 402. Don't create another top-up while this one is pending: the link stays valid until expires_at."
   ];
 }
+function openInBrowser(url) {
+  if (!/^https:\/\//.test(url))
+    return Promise.resolve(false);
+  const [bin, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", '""', url.replace(/&/g, "^&")]] : ["xdg-open", [url]];
+  return new Promise((done) => {
+    try {
+      const child = spawn(bin, args, { detached: true, stdio: "ignore", windowsHide: true });
+      child.once("error", () => done(false));
+      child.once("spawn", () => {
+        child.unref();
+        done(true);
+      });
+    } catch {
+      done(false);
+    }
+  });
+}
 async function billingTopup(ctx, o) {
   const created = await api(ctx, "POST", "/v1/billing/topup", {
     body: { amount_usd: o.amountUsd, ...o.autoReload ? { auto_reload: o.autoReload } : {} }
   });
-  return { status: "pending", ...created, next_steps: topupNextSteps(o.amountUsd, o.autoReload) };
+  const noOpen = o.noOpen || ctx.env.ST_NO_BROWSER === "1";
+  const opened = !noOpen && !!created.approval_url && await (o.open ?? openInBrowser)(created.approval_url);
+  return {
+    status: "pending",
+    ...created,
+    opened_in_browser: opened,
+    message_for_human: messageForHuman(created.approval_url, o.amountUsd, o.autoReload, opened),
+    next_steps: topupNextSteps(created.topup_id, o.amountUsd, opened, o.autoReload)
+  };
+}
+function messageForHuman(approvalUrl, amountUsd, autoReload, opened = false) {
+  if (!approvalUrl)
+    return null;
+  const reload = autoReload ? ` It also turns on auto-reload: $${autoReload.amount_usd} whenever the balance drops below $${autoReload.threshold_usd}${autoReload.monthly_limit_usd ? `, at most $${autoReload.monthly_limit_usd} a month` : ""}.` : "";
+  if (opened)
+    return `To finish the setup, I've opened the ScaledThought checkout page in your browser to buy $${amountUsd} of prepaid credits (USD). If it didn't open, use this link:
+
+${approvalUrl}
+
+On that page you accept the Terms of Service and the Credits & Refunds policy and pay by card. Nothing is charged until you approve.${reload} I'm watching for the payment and will carry on as soon as it goes through.`;
+  return `To finish the setup, please buy $${amountUsd} of prepaid ScaledThought credits (USD) here:
+
+${approvalUrl}
+
+On that page you accept the Terms of Service and the Credits & Refunds policy and pay by card. Nothing is charged until you approve.${reload} Tell me when it's done and I'll continue.`;
+}
+var WAIT_DEFAULT_S = 90;
+async function billingWait(ctx, o = {}) {
+  let id = o.topupId;
+  if (id !== undefined && !/^top_[0-9A-Za-z]+$/.test(id))
+    throw new CliError("bad_argument", `"${id}" is not a top-up id (top_...).`, "Use topup_id from `billing topup`.");
+  if (!id) {
+    const b = await api(ctx, "GET", "/v1/billing");
+    const pending = (b.pending_topups ?? []).filter((t) => t.status === "pending" && t.approval_url);
+    id = pending[0]?.topup_id;
+    if (!id) {
+      const paid = (b.recent_transactions ?? []).find((t) => t.topup_id)?.topup_id ?? null;
+      if ((b.balance_usd ?? 0) > 0)
+        return { status: "paid", topup_id: paid, billing: withoutFreeFields(b) };
+      throw new CliError("no_pending_topup", "There is no top-up waiting for payment and the balance is $0.", `Run \`${TOPUP_COMMAND}\` and show your human the approval_url, then run \`${WAIT_COMMAND}\`.`);
+    }
+  }
+  const deadline = Date.now() + (o.timeoutS ?? WAIT_DEFAULT_S) * 1000;
+  for (;; ) {
+    const t = await api(ctx, "GET", `/v1/billing/topups/${encodeURIComponent(id)}`);
+    if (t.status === "paid")
+      return { status: "paid", topup_id: id, billing: await billingStatus(ctx) };
+    if (TOPUP_DONE.has(t.status ?? ""))
+      throw new CliError(`topup_${t.status}`, t.status === "expired" ? `Top-up ${id} expired before it was paid.` : `Top-up ${id} was not paid (${t.status}${t.failure_code ? `: ${t.failure_code}` : ""}).`, `Run \`${TOPUP_COMMAND}\` again and show your human the new approval_url.`, { topup_id: id });
+    if (Date.now() >= deadline)
+      throw new CliError("topup_pending", `Top-up ${id} isn't paid yet.`, `Not paid yet. If the checkout page is open in your human's browser (billing topup printed opened_in_browser: true), run \`${WAIT_COMMAND} ${id}\` again right away, for up to ${WAIT_PATIENCE_MIN} minutes in all. If they don't have the approval_url (below), or it's still unpaid after that, end your turn and give it to them, then run it again when they're back. Don't create a new top-up.`, { topup_id: id, approval_url: t.approval_url ?? null });
+    await new Promise((r) => setTimeout(r, o.pollMs ?? 3000));
+  }
 }
 async function billingTopupAndWait(ctx, o) {
   const created = await billingTopup(ctx, o);
@@ -9734,13 +9837,10 @@ async function doctor(ctx) {
       next: err.hint ?? "Fix the error above, then run doctor again."
     };
   }
-  checks.push({ check: "account", ok: a.status === "active", detail: `${a.account_id} (${a.plan}, ${a.status})` });
-  const credit = (a.balance_usd ?? 0) > 0 || (a.free_remaining_today_usd ?? 0) > 0;
-  checks.push({
-    check: "credit",
-    ok: credit,
-    detail: `balance $${a.balance_usd ?? 0}, free left today $${a.free_remaining_today_usd ?? 0}`
-  });
+  const purchased = a.plan === "paid" ? "credits bought" : "no credit purchase yet";
+  checks.push({ check: "account", ok: a.status === "active", detail: `${a.account_id} (${purchased}, ${a.status})` });
+  const credit = (a.balance_usd ?? 0) > 0;
+  checks.push({ check: "credit", ok: credit, detail: `balance $${a.balance_usd ?? 0}` });
   const notices = a.notices ?? [];
   return {
     ok: checks.every((c) => c.ok) && notices.length === 0,
@@ -9750,10 +9850,10 @@ async function doctor(ctx) {
     checks,
     notices,
     notice_text: a.notice_text ?? [],
-    next: notices.length ? "Tell your human about each notice (notice_text)." : credit ? null : "No credit: run `npx scaledthought billing topup --amount-usd 20` and send your human the approval_url."
+    next: notices.length ? "Tell your human about each notice (notice_text)." : credit ? null : `No credits: run \`${TOPUP_COMMAND}\`, show your human the approval_url, then run \`${WAIT_COMMAND}\`.`
   };
 }
-var WEBHOOK_EVENTS = ["balance.low", "free_allowance.ending", "key.expiring", "budget.exhausted"];
+var WEBHOOK_EVENTS = ["balance.low", "key.expiring", "budget.exhausted"];
 async function webhooksAdd(ctx, o) {
   if (!/^https:\/\//i.test(o.url))
     throw new CliError("bad_argument", "The webhook URL must be https://.", "Pass a public https endpoint.");
@@ -10108,7 +10208,7 @@ function num(flag, v) {
 var init2 = defineCommand({
   meta: {
     name: "init",
-    description: "Create a free account (no card), save ST_API_KEY and ST_BASE_URL to ./.env, list live models. Idempotent. " + "Creating an account accepts the Terms of Service (scaledthought.com/legal/terms) for the human you act for."
+    description: "Create an account, save ST_API_KEY and ST_BASE_URL to ./.env, list live models and the next steps (a new account has no credits: top up first). Idempotent. " + "Creating an account accepts the Terms of Service (scaledthought.com/legal/terms) for the human you act for."
   },
   args: {
     ...jsonFlag,
@@ -10163,7 +10263,7 @@ var models = defineCommand({
 });
 var ACCOUNT_SUBCOMMANDS = new Set(["delete", "ad-measurement"]);
 var account2 = defineCommand({
-  meta: { name: "account", description: "Region, spend, credit balance and free allowance left today" },
+  meta: { name: "account", description: "Region, spend, credit balance and auto-reload" },
   args: jsonFlag,
   run: ({ args, rawArgs }) => {
     if (rawArgs.some((a) => ACCOUNT_SUBCOMMANDS.has(a)))
@@ -10419,7 +10519,7 @@ var billing = defineCommand({
     status: defineCommand({
       meta: {
         name: "status",
-        description: "Balance, free allowance left today, auto-reload, pending top-ups, recent transactions"
+        description: "Credit balance, auto-reload, pending top-ups (with their approval links), recent transactions"
       },
       args: jsonFlag,
       run: ({ args }) => run(() => billingStatus(makeCtx()), args)
@@ -10427,7 +10527,7 @@ var billing = defineCommand({
     topup: defineCommand({
       meta: {
         name: "topup",
-        description: "Buy prepaid credits: returns an approval_url for your human. Optional auto-reload"
+        description: "Buy prepaid credits: opens the checkout page in your human's browser (approval_url); then run `billing wait`, which returns once they pay. Optional auto-reload"
       },
       args: {
         ...jsonFlag,
@@ -10442,13 +10542,42 @@ var billing = defineCommand({
           type: "string",
           description: "Most auto-reload may charge per calendar month (USD, default 5x the amount)"
         },
-        wait: { type: "boolean", description: "Poll until the human pays or the link expires or fails" }
+        open: {
+          type: "boolean",
+          default: true,
+          description: "Open the checkout page in the browser (--no-open only prints approval_url)"
+        },
+        wait: {
+          type: "boolean",
+          description: "Poll until the human pays or the link expires or fails. Only if your human sees your terminal live: an agent's shell tool shows the link only after the command ends. Prefer `billing wait`"
+        }
       },
       run: async ({ args }) => {
         const amountUsd = num("amount-usd", args["amount-usd"]);
         const autoReload = autoReloadArgs(args);
         checkTopupLimits(amountUsd, autoReload);
-        await run(() => args.wait ? billingTopupAndWait(makeCtx(), { amountUsd, autoReload, onPending: (t) => out(t, args) }) : billingTopup(makeCtx(), { amountUsd, autoReload }), args);
+        const noOpen = args.open === false;
+        await run(() => args.wait ? billingTopupAndWait(makeCtx(), { amountUsd, autoReload, noOpen, onPending: (t) => out(t, args) }) : billingTopup(makeCtx(), { amountUsd, autoReload, noOpen }), args);
+      }
+    }),
+    wait: defineCommand({
+      meta: {
+        name: "wait",
+        description: "Wait until your human pays a top-up you showed them (default: the newest pending one). Returns status paid; exits topup_pending after --timeout-s (run it again)"
+      },
+      args: {
+        ...jsonFlag,
+        topup_id: { type: "positional", required: false, description: "topup_id from `billing topup` (optional)" },
+        "timeout-s": {
+          type: "string",
+          description: `Seconds to wait before exiting with topup_pending (default ${WAIT_DEFAULT_S}, at most 600)`
+        }
+      },
+      run: async ({ args }) => {
+        const t = args["timeout-s"] === undefined ? undefined : num("timeout-s", args["timeout-s"]);
+        if (t !== undefined && t > 600)
+          throw new CliError("bad_argument", `--timeout-s must be at most 600, got ${t}.`, "Run wait again instead.");
+        await run(() => billingWait(makeCtx(), { topupId: args.topup_id || undefined, timeoutS: t }), args);
       }
     }),
     "auto-reload": defineCommand({
@@ -10644,7 +10773,7 @@ var doctor2 = defineCommand({
 var webhooks = defineCommand({
   meta: {
     name: "webhooks",
-    description: "Signed HTTPS callbacks: balance.low, free_allowance.ending, key.expiring, budget.exhausted"
+    description: "Signed HTTPS callbacks: balance.low, key.expiring, budget.exhausted"
   },
   subCommands: {
     add: defineCommand({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "scaledthought",
-  "version": "0.1.0",
-  "description": "Headless open-model inference, run by your agent. Free to start. US or Canada.",
+  "version": "0.2.2",
+  "description": "Headless open-model inference, run by your agent. Prepaid, pay per token. US or Canada.",
   "license": "MIT",
   "keywords": [
     "llm",