@solgridai/cli 0.2.0-beta.0 → 0.2.0-beta.1

package/README.md

@@ -13,6 +13,19 @@ npm install -g @solgridai/cli
 solgrid --version
 ```
 
+### 测试版
+
+新版本正式发布前，会先以测试版（例如 `0.2.0-beta.0`）发布到 npm 的 `beta` 标签，用于提前试用新功能。直接执行 `npm install -g @solgridai/cli` 不会装到测试版。
+
+```bash
+npm install -g @solgridai/cli@beta           # 安装最新的测试版
+npm install -g @solgridai/cli@0.2.0-beta.0   # 或指定版本
+solgrid --version
+npm install -g @solgridai/cli                # 装回正式版
+```
+
+测试版的新功能可能依赖还没上线到生产环境的接口。这时请按发布说明，用 `SOLGRID_API_BASE_URL` 指向对应的环境，并使用该环境的 API Key（见[配置](#配置)）。
+
 ## 快速开始
 
 ```bash

package/dist/index.js

@@ -2075,7 +2075,7 @@ function useColor() {
 // node_modules/commander/index.js
 var program = new Command;
 // src/build-info.ts
-var buildInfo = { packageName: "@solgridai/cli", version: "0.2.0-beta.0" };
+var buildInfo = { packageName: "@solgridai/cli", version: "0.2.0-beta.1" };
 
 // src/core/errors.ts
 class CliError extends Error {
@@ -2104,6 +2104,7 @@ class CliError extends Error {
 class ApiError extends CliError {
   status;
   key;
+  keyDetail;
   routeMissing;
   apiKeySentTo;
   signedUrl;
@@ -2112,6 +2113,7 @@ class ApiError extends CliError {
     this.name = "ApiError";
     this.status = options.status;
     this.key = options.key;
+    this.keyDetail = options.keyDetail;
     this.routeMissing = options.routeMissing === true;
     this.apiKeySentTo = options.apiKeySentTo;
     this.signedUrl = options.signedUrl === true;
@@ -2120,6 +2122,7 @@ class ApiError extends CliError {
     return new ApiError(this.code, this.message, {
       ...this.status !== undefined ? { status: this.status } : {},
       ...this.key ? { key: this.key } : {},
+      ...this.keyDetail ? { keyDetail: this.keyDetail } : {},
       routeMissing: this.routeMissing,
       ...this.apiKeySentTo ? { apiKeySentTo: this.apiKeySentTo } : {},
       signedUrl: this.signedUrl,
@@ -2541,6 +2544,41 @@ function formatAmount(amount) {
   const sign = negative ? "-" : "";
   return amount.currency === "USD" ? `${sign}$${number}` : `${sign}${number} ${amount.currency}`;
 }
+function plainDecimal(value) {
+  if (!Number.isFinite(value))
+    return;
+  const text = String(value);
+  const match = /^(-?)(\d+)(?:\.(\d+))?e([+-]\d+)$/.exec(text);
+  if (!match)
+    return text;
+  const [, sign = "", whole = "", fraction = "", exponent = "0"] = match;
+  const digits = whole + fraction;
+  const point = whole.length + Number(exponent);
+  if (point <= 0)
+    return `${sign}0.${"0".repeat(-point)}${digits}`;
+  if (point >= digits.length)
+    return `${sign}${digits}${"0".repeat(point - digits.length)}`;
+  return `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
+}
+function ceilToSixDecimals(value) {
+  const decimal = typeof value === "number" ? plainDecimal(value) : value.trim();
+  if (decimal === undefined || !/^\d+(\.\d+)?$/.test(decimal))
+    return;
+  const [whole = "0", fraction = ""] = decimal.split(".");
+  let micros = BigInt(whole + fraction.slice(0, 6).padEnd(6, "0"));
+  if (/[1-9]/.test(fraction.slice(6)))
+    micros += 1n;
+  const text = micros.toString().padStart(7, "0");
+  return `${text.slice(0, -6)}.${text.slice(-6)}`;
+}
+function formatUnitPrice(amount) {
+  if (!amount || typeof amount.value !== "number" && typeof amount.value !== "string")
+    return "-";
+  const decimal = ceilToSixDecimals(amount.value);
+  if (decimal === undefined)
+    return formatAmount(amount);
+  return amount.currency === "USD" ? `$${decimal}` : `${decimal} ${amount.currency}`;
+}
 
 // src/core/api/client.ts
 var DEFAULT_TIMEOUT_MS = 30000;
@@ -2664,6 +2702,7 @@ function envelopeError(response, envelope, text, url, auth) {
   const status = bodyCode ?? (response.ok ? 400 : response.status);
   const serverMessage = typeof envelope?.message === "string" && envelope.message ? envelope.message : undefined;
   const key = errorKeyOf(envelope);
+  const keyDetail = keyDetailOf(envelope);
   const details = [
     ...validationDetails(envelope?.errorData, key),
     ...frameworkErrorDetails(envelope?.errors)
@@ -2673,6 +2712,7 @@ function envelopeError(response, envelope, text, url, auth) {
   return new ApiError(errorCodeForStatus(status), message, {
     status,
     ...key ? { key } : {},
+    ...keyDetail ? { keyDetail } : {},
     ...auth,
     ...serverJsonHint ? { hint: serverJsonHint } : {},
     details
@@ -2688,10 +2728,20 @@ function hasSerializerErrors(errors) {
   const value = errors?.serializerErrors;
   return Array.isArray(value) ? value.length > 0 : typeof value === "string" && value.length > 0;
 }
+function keyItemOf(envelope) {
+  const items = Array.isArray(envelope?.errorData) ? envelope.errorData : [];
+  return items.find((entry) => entry && typeof entry === "object" && !entry.propertyName && typeof entry.errorCode === "string" && ERROR_KEY.test(entry.errorCode));
+}
+function keyDetailOf(envelope) {
+  const item = keyItemOf(envelope);
+  if (!item)
+    return;
+  const { errorCode: _code, errorMessage: _message, propertyName: _property, ...rest } = item;
+  return Object.keys(rest).length > 0 ? rest : undefined;
+}
 var ERROR_KEY = /^[a-z][a-z0-9]*(?:_[a-z0-9]+)+$/;
 function errorKeyOf(envelope) {
-  const items = Array.isArray(envelope?.errorData) ? envelope.errorData : [];
-  const item = items.find((entry) => entry && !entry.propertyName && typeof entry.errorCode === "string" && ERROR_KEY.test(entry.errorCode));
+  const item = keyItemOf(envelope);
   if (item?.errorCode)
     return item.errorCode;
   const message = envelope?.message;
@@ -2849,7 +2899,44 @@ function presentApiError(error) {
 `) || undefined;
   return { message: base.message, hint };
 }
+function isAmount(value) {
+  const amount = value;
+  return typeof amount === "object" && amount !== null && (typeof amount.value === "string" || typeof amount.value === "number");
+}
+var RAISE_BUDGET = `Raise or disable the daily budget at ${CONSOLE_URLS.budgets}`;
+function explainDailyBudget(detail) {
+  const { reason, spent, held, requestedReservation, dailyLimit, remaining } = detail ?? {};
+  const amounts = [spent, held, requestedReservation, dailyLimit, remaining];
+  if (!amounts.every(isAmount))
+    return;
+  const [spentText, heldText, needText, limitText, leftText] = amounts.map((amount) => formatAmount(amount));
+  switch (reason) {
+    case "daily_spend_limit_reached":
+      return {
+        message: `Today's spending (${spentText}) has reached the daily budget of ${limitText}.`,
+        hint: `${RAISE_BUDGET}, or try again tomorrow (the budget resets at 00:00 UTC).`
+      };
+    case "requested_reservation_exceeds_remaining_budget":
+      return {
+        message: `This run requires a reservation of ${needText}, more than the ${leftText} left of today's ${limitText} budget (${spentText} spent).`,
+        hint: RAISE_BUDGET
+      };
+    case "reservation_exceeds_remaining_budget":
+      return {
+        message: `Runs still in progress hold ${heldText} of today's ${limitText} budget, leaving ${leftText}; this run requires a reservation of ${needText}.`,
+        hint: `Wait for those runs to finish (what they do not use is released), then retry with the same idempotency key, or submit runs one at a time.
+${RAISE_BUDGET}`
+      };
+    default:
+      return;
+  }
+}
 function explain(error) {
+  if (error.key === "daily_budget_exceeded") {
+    const budget = explainDailyBudget(error.keyDetail);
+    if (budget)
+      return budget;
+  }
   const known = error.key ? KEY_PRESENTATIONS[error.key] : undefined;
   if (known)
     return known;
@@ -2977,6 +3064,7 @@ function createOutput(ctx, json) {
             message,
             ...cliError instanceof ApiError && cliError.status !== undefined ? { status: cliError.status } : {},
             ...cliError instanceof ApiError && cliError.key ? { key: cliError.key } : {},
+            ...cliError instanceof ApiError && cliError.keyDetail ? { detail: cliError.keyDetail } : {},
             ...cliError.details.length > 0 ? { details: cliError.details } : {},
             ...hint ? { hint } : {}
           },
@@ -4988,8 +5076,8 @@ function withUnit(amount, unit) {
   return unit ? `${amount} ${unit}` : amount;
 }
 function describeLeaf(leaf) {
-  const text = withUnit(formatAmount(leaf.amount), unitText(leaf));
-  return leaf.flatFee ? `${text} + ${formatAmount(leaf.flatFee)} flat` : text;
+  const text = withUnit(formatUnitPrice(leaf.amount), unitText(leaf));
+  return leaf.flatFee ? `${text} + ${formatUnitPrice(leaf.flatFee)} flat` : text;
 }
 var METER_UNITS = {
   Calls: ["call", "calls"],
@@ -5013,8 +5101,7 @@ function meterText(meter, size = 1) {
   return size === 1 ? `per ${one}` : `per ${countText(size)} ${many}`;
 }
 function rateAmount(rate) {
-  const micros = Math.ceil(Number((rate.unitPriceUsd * 1e6).toPrecision(12)));
-  return formatAmount({ value: (micros / 1e6).toFixed(6), currency: "USD" });
+  return formatUnitPrice({ value: rate.unitPriceUsd, currency: "USD" });
 }
 function describeRate(rate) {
   return `${rateAmount(rate)} ${meterText(rate.meter, rate.unitSize)}`;
@@ -5034,7 +5121,7 @@ function hasConditions(rate) {
 function summarizeRates(price, rates) {
   const only = rates.length === 1 ? rates[0] : undefined;
   if (only) {
-    const amount = price.amount ? formatAmount(price.amount) : rateAmount(only);
+    const amount = price.amount ? formatUnitPrice(price.amount) : rateAmount(only);
     const text = `${amount} ${meterText(only.meter, only.unitSize)}`;
     return hasConditions(only) ? `${text} (${conditionsText(only)})` : text;
   }
@@ -5069,20 +5156,20 @@ function summarizePrice(price, fallback) {
   switch (price.type) {
     case "PER_UNIT_MATRIX": {
       const first = price.variants?.[0]?.price;
-      text = `from ${withUnit(formatAmount(price.amount), first ? unitText(first) : "")}`;
+      text = `from ${withUnit(formatUnitPrice(price.amount), first ? unitText(first) : "")}`;
       break;
     }
     case "TIERED":
       text = price.default ? describeLeaf(price.default) : "varies";
       break;
     case "BY_PERIOD":
-      text = withUnit(formatAmount(price.amount), price.period ? periodText(price.period) : "");
+      text = withUnit(formatUnitPrice(price.amount), price.period ? periodText(price.period) : "");
       break;
     default:
-      text = withUnit(formatAmount(price.amount), unitText(price));
+      text = withUnit(formatUnitPrice(price.amount), unitText(price));
   }
   if (price.flatFee)
-    text += ` + ${formatAmount(price.flatFee)} flat`;
+    text += ` + ${formatUnitPrice(price.flatFee)} flat`;
   if (price.type === "TIERED" && price.tiers?.length)
     text += " + add-ons";
   return text;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solgridai/cli",
-  "version": "0.2.0-beta.0",
+  "version": "0.2.0-beta.1",
   "description": "Command-line client for Solgrid: discover, inspect and run tools from your terminal or agent.",
   "license": "MIT",
   "repository": {

package/skills/solgrid-cli/SKILL.md

@@ -172,9 +172,18 @@ with the same key, or look the run up first.
   | `error.key` | Meaning |
   |---|---|
   | `wallet_balance_insufficient` | Balance too low; the user can top up on the console's Wallet page |
-  | `daily_budget_exceeded` | Daily budget reached; adjustable on the console's Budgets page |
+  | `daily_budget_exceeded` | Daily budget reached; adjustable on the console's Budgets page (but see below) |
   | `per_call_limit_exceeded` | The run costs more than the per-call limit; adjustable on the console's Budgets page |
 
+- The daily budget counts today's spending plus what runs still in progress
+  hold. If `daily_budget_exceeded` comes with
+  `error.detail.reason: "reservation_exceeds_remaining_budget"`, those holds
+  are the cause: wait for the user's runs in progress to finish, then retry
+  with the **same** idempotency key (a refused run was never started), or
+  submit runs one at a time. `error.detail` also has `spent`, `held`,
+  `requestedReservation`, `dailyLimit` and `remaining`.
+- The budget is checked when a run starts; a run's final cost can exceed what
+  it held, so a day's spending can end slightly over the budget.
 - Never top up the wallet or change budgets on the user's behalf.
 
 ## Using local files as input