metergraph-cli 0.2.1 → 0.2.3

package/src/read-output.js

@@ -1,11 +1,38 @@
 import { authMessage } from "./output.js";
+import { PLAIN, fields, headline, paragraph, render, steps, toneFor } from "./style.js";
 
 // Fixed text for read command reasons and notices. Reasons shared with sign
 // in and doctor fall back to their wording. Nothing here contains a value from
 // a server response other than validated metadata printed by readText.
 
 const READ_MESSAGES = {
-  not_signed_in: 'This project is not signed in. Run "metergraph login --runtime local" first.',
+  not_signed_in:
+    'This project is not signed in and no Metadata key was given. Run "metergraph login --runtime local" first, ' +
+    "or, where browser sign in cannot finish, give the CLI a coding-agent key with Metadata access in " +
+    "METERGRAPH_AGENT_TOKEN.",
+  agent_key_rejected:
+    "The service refused the Metadata key: it is unknown, expired or revoked. Nothing was read.",
+  agent_key_insufficient_scope:
+    "The key is valid but lacks Metadata access to this workspace, for example because it is an ingest key. " +
+    "No broader access was requested. Nothing was read.",
+  agent_token_malformed:
+    "METERGRAPH_AGENT_TOKEN does not hold exactly one key with no label, spaces or extra lines. Its value is not " +
+    "shown. Nothing was sent.",
+  agent_token_missing: "No Metadata key was found. Nothing was sent.",
+  metergraph_url_invalid:
+    "METERGRAPH_URL is not a bare https origin, or an http origin on localhost. Its value is not shown. Nothing was sent.",
+  bound_to_other_origin:
+    "This project is bound to a different origin than --url or METERGRAPH_URL names. Nothing was sent.",
+  bound_to_other_workspace: "This project is bound to a different workspace than --workspace names. Nothing was sent.",
+  agent_key_origin_unconfirmed:
+    "This project's binding names a non-hosted origin, and a key is never sent to an origin taken only from a " +
+    "project file. Set METERGRAPH_URL or pass --url with the same origin to confirm it. Nothing was sent.",
+  scope_mismatch:
+    "The credential is not limited to exactly the Metadata scope, so it was not used. The CLI never uses broader access.",
+  content_access_granted:
+    "The credential would allow content, replay or provider access, so it was not used. The CLI never uses broader access.",
+  platform_credential_handoff:
+    "--agent-token-file cannot be checked for privacy on this platform. Use METERGRAPH_AGENT_TOKEN instead.",
   capability_unavailable:
     "The service does not offer this read to the project's Metadata grant. No data was read and no broader access was requested.",
   exceeds_service_bounds:
@@ -19,9 +46,29 @@ const READ_MESSAGES = {
   contract_version_unsupported: "The service answered with an agent access contract version this CLI does not support.",
   content_in_metadata_response:
     "The service's Metadata response contained a field that could carry captured content or a credential. Nothing from it was printed.",
-  filter_mismatch: "The service reported different trace filters than the ones requested. Nothing from it was printed.",
+  filter_mismatch: "The service reported different filters than the ones requested. Nothing from it was printed.",
   filter_not_applied:
     "The service returned traces that do not match the requested filter. Nothing from it was printed.",
+  metadata_filter_unsupported:
+    "The service did not confirm the metadata filter, so the CLI cannot show that it applied. " +
+    "The service may predate metadata filters. Nothing from it was printed.",
+  metadata_filter_mismatch:
+    "The service reported different metadata filters than the ones requested. Nothing from it was printed.",
+  group_by_mismatch:
+    "The service did not group by the requested dimensions or metadata key. The service may predate that grouping. " +
+    "Nothing from it was printed.",
+  coverage_not_reported:
+    "The service's grouped usage response carries no coverage evidence, so its groups cannot be checked. " +
+    "Nothing from it was printed.",
+  window_mismatch:
+    "The service read a different UTC window than the one requested. Nothing from it was printed.",
+  usage_aggregates_unavailable:
+    "This deployment does not offer grouped usage (by provider, model, route or UTC day) to the project's " +
+    "Metadata grant. Nothing was read.",
+  temporarily_unavailable:
+    "The service stopped this read at its time budget and returned nothing partial. Nothing was retried.",
+  response_too_large:
+    "The response is larger than the read's size budget, so nothing from it was printed.",
   read_response_invalid: "The service's response is not usable JSON. Nothing from it was printed.",
   usage_response_invalid: "The service's usage response does not match the contract. Nothing from it was printed.",
   routes_response_invalid: "The service's routes response does not match the contract. Nothing from it was printed.",
@@ -38,16 +85,33 @@ const READ_MESSAGES = {
     "The service's Metadata response contained a credential this CLI holds for the project. Nothing from it was printed.",
 };
 
+const AGENT_TOKEN_FILE_MESSAGE =
+  "The --agent-token-file file is not usable. It must be an existing regular file owned by this user with mode " +
+  "0600 and one link, in a directory only this user can write, holding exactly one key. Its path and content are " +
+  "not shown. Nothing was sent.";
+
 export function readMessage(outcome, reason) {
+  if (typeof reason === "string" && reason.startsWith("agent_token_file_")) return AGENT_TOKEN_FILE_MESSAGE;
   return READ_MESSAGES[reason] ?? authMessage(outcome, reason);
 }
 
 const NOTICES = {
+  workspace_not_pinned:
+    "No workspace was pinned, so the key's own workspace was verified and used. Pass --workspace, or bind the " +
+    "project, so that a key for another workspace fails instead.",
+  agent_key_not_used:
+    "METERGRAPH_AGENT_TOKEN is set, but this project's saved sign in was used. Pass --agent-token-file to use a key instead.",
   application_traffic_not_verified:
     "Application traffic is not verified. A signed in project, existing data or a configured SDK alone does not prove it.",
   evidence_incomplete: "The service marked this evidence as incomplete.",
   rows_truncated: "The service returned fewer rows than exist. Totals cover the returned rows only.",
   more_pages: "More traces exist. Pass --cursor with next_cursor to read the next page.",
+  metadata_groups_truncated:
+    "More metadata values exist than --limit. Calls in the window still counts every call.",
+  metadata_key_mostly_missing:
+    "Most of this window's calls or cost have no value for the grouped key, so the rows with a value explain less than half of it.",
+  metadata_values_missing:
+    "Some calls have no usable value for the grouped key (missing, not a string or too long). They are shown as (no value) and totalled as not attributed to any value.",
   routes_truncated_locally:
     "The service returned more routes than --limit. Only the first rows are shown; the routes endpoint has no server limit or window.",
   route_details_omitted: "Route descriptions, constraints and evaluation contract bodies are not printed.",
@@ -55,17 +119,136 @@ const NOTICES = {
   unsafe_text_omitted: "Some names contained control or formatting characters and are shown as null.",
   unrecognized_capabilities_ignored: "Capabilities this CLI does not recognize are not shown.",
   privacy_class_details_omitted: "Privacy class descriptions are not printed.",
+  coverage_partial:
+    "The service reports this read does not cover the whole question. See coverage.reasons before treating any total as complete.",
+  coverage_unknown:
+    "The service could not establish whether this read is complete, so it is not treated as complete.",
+  coverage_not_reported:
+    "This service does not report coverage details. Completeness rests on its evidence and truncation flags alone.",
+  pricing_lower_bound:
+    "Some calls have missing, partial or unknown pricing, so cost is a lower bound.",
+  mixed_provider_traces:
+    "Some traces used more than one provider or model. A trace cost is the whole-trace total and cannot be split by provider; use usage for per-route cost.",
+  unpriced_traces: "Some traces have no priced call, so their cost is unknown (shown as -), not zero.",
+  groups_truncated:
+    "More groups matched than --limit. Only the highest-cost groups are listed; the all-calls totals still cover every matching call.",
+  ranking_partial:
+    "The service returns the highest-cost groups first, so this ranking covers only the listed groups, not every group.",
+  current_day_partial:
+    "The window ends now, part way through the current UTC day, so that day is partial.",
+  partial_day_comparison:
+    "A partial current UTC day is compared with a whole prior period. The totals are not like for like.",
+  comparison_incomplete:
+    "One of the compared windows is incomplete, so a change may be missing groups. A group absent from a cut window is unknown, not zero.",
+  environment_restricted_key:
+    "The grant is restricted to some environments, so totals cover only those environments.",
   trace_links_unavailable:
     "The service does not provide workspace-bound trace links yet, so no link is shown.",
 };
 
+// Coverage, window and pricing lines shared by usage and traces. Only
+// validated fields and fixed tokens are printed.
+function coverageLines(lines, report) {
+  // Service warning codes, once, on one line. Their messages are never printed.
+  const codes = [...new Set((report.warnings ?? []).map((entry) => entry.code))];
+  if (codes.length > 0) lines.push(`Service warnings: ${codes.join(", ")}`);
+  const coverage = report.coverage;
+  if (coverage) {
+    const requested = coverage.requested_window;
+    const effective = coverage.effective_window;
+    if (requested && effective && (requested.since !== effective.since || requested.until !== effective.until)) {
+      lines.push(
+        `Window read: ${effective.since} to ${effective.until} ` +
+          `(requested ${requested.since} to ${requested.until})`,
+      );
+    }
+    const matched = coverage.rows.matched === null ? "" : ` of ${coverage.rows.matched}`;
+    // Pricing reasons are shown on the Pricing line instead.
+    const reasons = coverage.reasons.filter((reason) => !reason.startsWith("pricing_"));
+    lines.push(
+      `Coverage: ${coverage.completeness}` +
+        (reasons.length > 0 ? ` (${reasons.join(", ")})` : "") +
+        `; ${coverage.rows.returned}${matched} ${coverage.rows.shape === "page" ? "rows on this page" : "rows returned"}` +
+        `; as of ${coverage.as_of}`,
+    );
+  } else {
+    lines.push("Coverage: not reported by this service");
+  }
+  const pricing = report.pricing;
+  if (pricing) {
+    lines.push(
+      pricing.cost === "exact"
+        ? `Pricing: exact (${pricing.priced_calls} priced calls, ${pricing.zero_cost_calls} priced at zero)`
+        : `Pricing: lower bound (${pricing.unpriced_calls} unpriced, ${pricing.partial_calls} partially priced, ` +
+            `${pricing.unknown_calls} unknown, ${pricing.priced_calls} priced of which ${pricing.zero_cost_calls} at zero)`,
+    );
+  }
+}
+
+// Notices for human output, without lines that repeat what the report
+// already printed. JSON output keeps every notice token.
+// - A Coverage line with completeness and reasons supersedes the generic
+//   incomplete-evidence and truncation notices.
+// - A Pricing line supersedes the lower-bound notice.
+// - The "mostly missing" warning supersedes the plain missing-values notice.
+// - Service warning codes are printed once on the "Service warnings" line,
+//   so the "messages omitted" note adds nothing in text.
+// - Grouped usage prints the partial UTC day in its Window line, the spend
+//   without a key value in its metadata lines, and the comparison's window
+//   lengths, prior coverage and completeness in its comparison lines.
+// A metadata grouping where no call has a value: every call is unattributed.
+function noCallHasTheKey(report) {
+  const groups = report?.metadata_groups;
+  if (!groups || !report.totals) return false;
+  return report.totals.calls > 0 && groups.listed_with_value.calls === 0 &&
+    groups.unlisted.other_values.calls === 0 && groups.unattributed.calls === report.totals.calls;
+}
+
+function textNotices(tokens, report) {
+  const shown = new Set(tokens);
+  const coverage = report?.coverage ?? null;
+  if (coverage && coverage.completeness !== "complete") {
+    for (const token of ["evidence_incomplete", "rows_truncated", "groups_truncated"]) shown.delete(token);
+  }
+  if (report?.pricing) shown.delete("pricing_lower_bound");
+  if (report?.source === "usage_aggregates") {
+    shown.delete("current_day_partial");
+    if (report.metadata_groups) shown.delete("metadata_values_missing");
+    if (report.comparison) {
+      for (const token of ["partial_day_comparison", "comparison_incomplete"]) shown.delete(token);
+      // Only the prior notices the comparison lines state (coverage, pricing,
+      // completeness, truncation); any other prior notice is still shown.
+      for (const token of [
+        "prior_coverage_partial", "prior_coverage_unknown", "prior_coverage_not_reported",
+        "prior_pricing_lower_bound", "prior_evidence_incomplete", "prior_groups_truncated",
+        "prior_warning_messages_omitted",
+      ]) shown.delete(token);
+    }
+  }
+  if (shown.has("metadata_key_mostly_missing")) shown.delete("metadata_values_missing");
+  // The grouped body states outright when no call has the key.
+  if (noCallHasTheKey(report)) {
+    shown.delete("metadata_key_mostly_missing");
+    shown.delete("metadata_values_missing");
+  }
+  shown.delete("warning_messages_omitted");
+  return tokens.filter((token) => shown.has(token));
+}
+
 export function noticeText(token) {
+  if (token.startsWith("prior_")) {
+    const text = NOTICES[token.slice("prior_".length)];
+    return text === undefined ? null : `Prior window: ${text}`;
+  }
   return NOTICES[token] ?? null;
 }
 
 const yesNo = (value) => (value === true ? "yes" : value === false ? "no" : "not checked");
 const show = (value) => (value === null || value === undefined ? "-" : String(value));
-const usd = (value) => (value === null ? "-" : `$${value.toFixed(4)}`);
+// Four decimals, or the service's eight for a non-zero amount below $0.0001,
+// so a small cost never prints as zero.
+const usd = (value) =>
+  value === null ? "-" : `$${value !== 0 && Math.abs(value) < 0.0001 ? value.toFixed(8) : value.toFixed(4)}`;
 
 function table(header, rows) {
   const widths = header.map((title, column) =>
@@ -75,51 +258,100 @@ function table(header, rows) {
   return [line(header), ...rows.map(line)];
 }
 
-export function readText(result, message) {
+const READ_TITLES = {
+  status: "Project status",
+  context: "Workspace context",
+  capabilities: "Agent capabilities",
+  usage: "Usage",
+  routes: "Routes",
+  traces: "Traces",
+};
+
+export function readText(result, message, style = PLAIN) {
   const data = result.data;
-  const lines = [`Metergraph ${result.command} (Metadata only)`];
-  if (data.origin !== null) lines.push(`Origin: ${data.origin}`);
+  const title = `${READ_TITLES[result.command] ?? result.command}${result.ok ? "" : " could not be read"}`;
+  const lines = [
+    `${headline(style, result.ok ? "info" : toneFor(result.outcome), title, result.outcome)}  ${style.dim("Metadata only")}`,
+    "",
+  ];
+  const rows = [["Origin", data.origin]];
   if (result.command === "status") {
-    statusLines(data, lines);
+    statusRows(data, rows);
+    lines.push(...fields(style, rows));
   } else {
-    if (data.workspace !== null) lines.push(`Workspace: ${data.workspace.id}`);
-    if (result.ok) resultLines(result.command, data.result, lines);
+    rows.push(["Workspace", data.workspace?.id ?? null]);
+    if (result.ok) {
+      const body = [];
+      resultLines(result.command, data.result, body);
+      // "Label: value" lines before the first blank line join the field block.
+      let split = 0;
+      while (split < body.length && body[split] !== "" && /^[A-Z][^:]{0,40}: /.test(body[split])) {
+        const at = body[split].indexOf(": ");
+        rows.push([body[split].slice(0, at), body[split].slice(at + 2)]);
+        split += 1;
+      }
+      lines.push(...fields(style, rows), "");
+      for (const line of body.slice(split)) {
+        lines.push(/^[A-Z_]+( +[A-Z_]+)*$/.test(line.trim()) && line === line.toUpperCase() && line.trim() !== ""
+          ? `  ${style.dim(line)}` : line === "" ? "" : `  ${line}`);
+      }
+    } else {
+      lines.push(...fields(style, rows));
+    }
+  }
+  const notices = textNotices(data.notices, result.ok ? data.result : null).map(noticeText).filter(Boolean);
+  if (notices.length > 0) {
+    lines.push("");
+    for (const text of notices) {
+      const [first, ...rest] = paragraph(style, text, "    ");
+      lines.push(`  ${style.yellow("!")} ${first.trimStart()}`, ...rest);
+    }
   }
-  const notices = data.notices.map(noticeText).filter(Boolean);
-  if (notices.length > 0) lines.push("", ...notices.map((text) => `Note: ${text}`));
   if (!result.ok) {
-    lines.push("", `Result: ${result.outcome} (exit ${result.exit_code})`, message);
+    lines.push("", ...paragraph(style, message));
     if (data.retry_after_seconds !== null && data.retry_after_seconds !== undefined) {
-      lines.push(`Retry after: ${data.retry_after_seconds} seconds`);
+      lines.push(...fields(style, [["Retry after", `${data.retry_after_seconds} seconds`]]));
     }
   }
-  if (data.next_action?.message) lines.push(`Next: ${data.next_action.message}`);
-  return `${lines.join("\n")}\n`;
+  if (data.next_action?.message) {
+    const next = data.next_action;
+    const handoff = next.kind === "use_agent_key";
+    const keysUrl = handoff
+      ? next.person_steps.find((step) => step.action === "create_metadata_key")?.url ?? null
+      : next.url ?? null;
+    lines.push("", ...steps(style, [
+      ["", next.message],
+      ["Keys page", keysUrl],
+      ["Connection guide", handoff ? next.url : null],
+    ]));
+  }
+  return render(lines);
 }
 
-function statusLines(data, lines) {
-  lines.push(
-    `Configured: ${data.configured ? "yes (.metergraph/project.json)" : "no"}`,
-    `Reachable: ${yesNo(data.reachable)}`,
-    `Authenticated: ${data.authenticated ? "yes, verified by the service" : "no"}`,
-    `Workspace: bound ${show(data.workspace.intended)}, verified ${show(data.workspace.actual)}`,
-    `Deployment profile: bound ${show(data.deployment_profile)}, reported by the service: ${
+function statusRows(data, rows) {
+  rows.push(
+    ["Configured", data.configured ? "yes" : "no"],
+    ["Credential", { oauth_grant: "saved sign in", agent_key: "Metadata key" }[data.credential] ?? "none"],
+    ["Reachable", yesNo(data.reachable)],
+    ["Authenticated", data.authenticated ? "yes, verified by the service" : "no"],
+    ["Workspace", `bound ${show(data.workspace.intended)}, verified ${show(data.workspace.actual)}`],
+    ["Deployment profile", `bound ${show(data.deployment_profile)}, reported by the service: ${
       data.deployment_profile_verified === true
         ? "same"
         : data.deployment_profile_verified === false
           ? "different"
           : "not checked"
-    }`,
-    `Scopes: ${data.scopes.length > 0 ? data.scopes.join(" ") : "none"}`,
+    }`],
+    ["Scopes", data.scopes.length > 0 ? data.scopes.join(" ") : "none"],
   );
   if (data.capabilities !== null) {
     const flag = (name) => yesNo(data.capabilities[name]);
-    lines.push(
-      `Metadata reads: usage ${flag("usage")}, routes ${flag("routes")}, traces ${flag("trace_metadata")}`,
-      "Content, evidence and replay: not available to this grant",
+    rows.push(
+      ["Metadata reads", `usage ${flag("usage")}, routes ${flag("routes")}, traces ${flag("trace_metadata")}`],
+      ["Content and replay", "not available to this grant"],
     );
   }
-  lines.push(`Application traffic verified: no`);
+  rows.push(["Application traffic verified", "no"]);
 }
 
 function resultLines(command, report, lines) {
@@ -149,8 +381,17 @@ function resultLines(command, report, lines) {
     );
     return;
   }
+  if (command === "usage" && report.source === "usage_aggregates") {
+    aggregateUsageLines(report, lines);
+    return;
+  }
   if (command === "usage") {
-    lines.push(`Window: last ${report.window.days} days (${report.window.since} to ${report.window.until})`, "");
+    lines.push(
+      `Window: rolling ${report.window.hours} h ending now, ${report.window.since} to ${report.window.until} UTC ` +
+        "(not aligned to UTC days: the first and last dates are partial; --today, --since or --group-by use UTC days)",
+    );
+    if (report.filters.metadata.count > 0) lines.push(metadataFilterLine(report.filters.metadata));
+    lines.push("");
     if (report.empty) {
       lines.push("No usage rows in this window.");
     } else {
@@ -173,6 +414,14 @@ function resultLines(command, report, lines) {
           `${totals.input_tokens} input and ${totals.output_tokens} output tokens.`,
       );
     }
+    if (report.population_totals) {
+      const all = report.population_totals;
+      lines.push(
+        `All matching calls in the window: ${all.calls} calls, ${all.error_calls} errors, ${usd(all.cost_usd)}, ` +
+          `${all.input_tokens} input and ${all.output_tokens} output tokens.`,
+      );
+    }
+    coverageLines(lines, report);
     lines.push(`Evidence: ${report.complete ? "complete" : "incomplete"}`);
     return;
   }
@@ -194,7 +443,9 @@ function resultLines(command, report, lines) {
     return;
   }
   if (command === "traces") {
-    lines.push(`Window: last ${report.window.days} days`, "");
+    lines.push(`Window: last ${report.window.days} days`);
+    if (report.filters.metadata.count > 0) lines.push(metadataFilterLine(report.filters.metadata));
+    lines.push("");
     if (report.empty) {
       lines.push("No traces on this page.");
     } else {
@@ -211,6 +462,174 @@ function resultLines(command, report, lines) {
     }
     lines.push("", `Page: ${report.page.rows} traces, limit ${report.page.limit}`);
     if (report.next_cursor !== null) lines.push(`Next page: --cursor ${report.next_cursor}`);
+    coverageLines(lines, report);
+    const mixed = report.traces.filter((trace) => trace.mixed_providers).length;
+    const matching = report.attribution?.cost_basis === "matching_calls";
+    lines.push(
+      (matching ? "Costs: matching calls only (a filter selected calls, not whole traces)" : "Costs: whole-trace totals") +
+        (mixed > 0 ? `; ${mixed} trace${mixed === 1 ? "" : "s"} used several providers, not split by provider` : ""),
+    );
+    lines.push(`Evidence: ${report.complete ? "complete" : "incomplete"}`);
     lines.push("Trace links: not available from the service yet");
   }
 }
+
+// Filter values are not printed back; only the keys they applied to.
+function metadataFilterLine(filters) {
+  return `Metadata filter: exact match on ${filters.keys.join(", ")}`;
+}
+
+const DIMENSION_TITLES = { provider: "PROVIDER", model: "MODEL", route: "ROUTE", day: "DAY_UTC" };
+const titleOf = (dimension) => DIMENSION_TITLES[dimension] ?? "METADATA_VALUE";
+// One group's cell for a dimension. The metadata group without a value is
+// named, not shown as an empty string.
+const cellOf = (item, dimension) => {
+  if (dimension === "day") return `${item.day}${item.partial_day ? " (partial)" : ""}`;
+  if (dimension.startsWith("metadata.")) return item.has_value ? show(item.metadata_value) : "(no value)";
+  return show(item[dimension]);
+};
+// A change in dollars: four decimals, or the service's eight when smaller, so
+// a non-zero change never prints as zero.
+const usdChange = (value) => `$${value !== 0 && value < 0.0001 ? value.toFixed(8) : value.toFixed(4)}`;
+const signed = (value, format) => (value === null ? "-" : `${value > 0 ? "+" : value < 0 ? "-" : ""}${format(Math.abs(value))}`);
+const percent = (value) => (value === null ? "-" : `${value > 0 ? "+" : ""}${value}%`);
+
+function windowLine(window) {
+  const kind = window.preset === "utc_days"
+    ? window.days === 1
+      ? "today so far"
+      : `the current UTC day so far and the ${window.days - 1} whole UTC days before it`
+    : "explicit window";
+  const partial = window.partial_days.length > 0 ? `; partial UTC day ${window.partial_days.join(", ")}` : "";
+  return `${window.since} to ${window.until} UTC, ${window.hours} h (${kind}${partial})`;
+}
+
+// Grouped usage: one row per group in the chosen order, then all-calls
+// totals, coverage, pricing, attribution and the latency definitions.
+function aggregateUsageLines(report, lines) {
+  const filters = Object.entries(report.filters)
+    .filter(([key, count]) => key !== "metadata" && count > 0)
+    .map(([key, count]) => `${key} (${count} value${count === 1 ? "" : "s"})`);
+  lines.push(`Window: ${windowLine(report.window)}`, `Grouped by: ${report.group_by.join(", ")}`);
+  const metadataDimension = report.group_by.find((dimension) => dimension.startsWith("metadata."));
+  if (metadataDimension) {
+    lines.push(`Metadata key: ${metadataDimension.slice("metadata.".length)} (a route is not a prompt; one route can carry several values)`);
+  }
+  if (filters.length > 0) lines.push(`Filters: exact match on ${filters.join(", ")}`);
+  if (report.filters.metadata.count > 0) lines.push(metadataFilterLine(report.filters.metadata));
+  lines.push(
+    `Ranked by: ${report.sort.meaning}${report.sort.complete ? "" : " (listed groups only)"}`,
+    "",
+  );
+  if (report.empty) {
+    lines.push("No calls match this window and these filters.");
+  } else {
+    const rows = report.items.map((item) => [
+      String(item.rank),
+      ...report.group_by.map((dimension) => cellOf(item, dimension)),
+      usd(item.cost_usd),
+      String(item.calls),
+      usd(item.cost_per_call_usd),
+      String(item.error_calls),
+      show(item.latency.avg_ms),
+      show(item.latency.p95_ms),
+    ]);
+    lines.push(...table(
+      ["#", ...report.group_by.map(titleOf), "COST", "CALLS", "COST/CALL", "ERRORS",
+        "AVG_MS", "P95_MS_EST"],
+      rows,
+    ));
+  }
+  const all = report.totals;
+  lines.push(
+    "",
+    `Groups: ${report.rows} listed of ${report.matched_groups ?? "an unreported number of"} matched.`,
+    `All matching calls: ${all.calls} calls, ${all.error_calls} errors, ${usd(all.cost_usd)}, ` +
+      `${usd(all.cost_per_call_usd)} per call, ${all.input_tokens} input and ${all.output_tokens} output tokens.`,
+  );
+  if (noCallHasTheKey(report)) {
+    lines.push(
+      `No call in this window has a value for ${report.metadata_groups.key}. ` +
+        "Check the key's spelling and that the SDK sets it.",
+    );
+  }
+  if (report.metadata_groups) {
+    const groups = report.metadata_groups;
+    const { other_values: other, missing_key: missing, ineligible_value: ineligible } = groups.unlisted;
+    lines.push(
+      `Attributed to a ${groups.key} value: ${groups.listed_with_value.calls} listed calls ` +
+        `(${usd(groups.listed_with_value.cost_usd)}); ${other.groups} more values past --limit: ` +
+        `${other.calls} calls (${usd(other.cost_usd)}).`,
+      `Not attributed to any ${groups.key} value: ${groups.unattributed.calls} calls ` +
+        `(${usd(groups.unattributed.cost_usd)}): without the key ${missing.calls} (${usd(missing.cost_usd)}), ` +
+        `non-string or oversize value ${ineligible.calls} (${usd(ineligible.cost_usd)}).`,
+    );
+  }
+  coverageLines(lines, report);
+  if (report.attribution) {
+    lines.push(
+      `Attribution: per ${report.attribution.level}; ` +
+        (report.attribution.per_provider_exact
+          ? "a trace that used several providers adds each call's cost to that call's provider"
+          : "cost is not split exactly by provider"),
+    );
+  }
+  lines.push(
+    "Latency: AVG_MS is the mean over calls that reported latency; P95_MS_EST is estimated from a fixed latency " +
+      "histogram, not an exact percentile.",
+    `Evidence: ${report.complete ? "complete" : "incomplete"}`,
+  );
+  if (report.comparison) comparisonLines(report, lines);
+}
+
+function comparisonLines(report, lines) {
+  const comparison = report.comparison;
+  const { totals } = comparison;
+  lines.push(
+    "",
+    `Compared with ${comparison.mode === "previous" ? "the whole previous period" : "the previous period to the same elapsed time"}: ` +
+      windowLine(comparison.prior.window),
+    `Total cost: ${usd(totals.current.cost_usd)} now, ${usd(totals.prior.cost_usd)} before, ` +
+      (totals.cost_change_known
+        ? `${signed(totals.cost_change.delta, usdChange)} (${percent(totals.cost_change.percent)})`
+        : "change unknown (a window's coverage is incomplete or its cost is a lower bound)"),
+    `Calls: ${totals.current.calls} now, ${totals.prior.calls} before, ` +
+      (totals.calls_change_known === false
+        ? "change unknown (a window's coverage is incomplete)"
+        : `${signed(totals.calls_change.delta, String)} (${percent(totals.calls_change.percent)})`),
+  );
+  if (comparison.partial_day_compared_with_full) {
+    lines.push(
+      `Not like for like: ${comparison.hours.current} h now against ${comparison.hours.prior} h before.`,
+    );
+  }
+  if (comparison.items.length > 0) {
+    const rows = comparison.items.map((item) => [
+      ...report.group_by.map((dimension) => (dimension === "day" ? show(item.day) : cellOf(item, dimension))),
+      item.current === null ? "unknown" : usd(item.current.cost_usd),
+      item.prior === null ? "unknown" : usd(item.prior.cost_usd),
+      signed(item.cost_change.delta, usdChange),
+      percent(item.cost_change.percent),
+      item.current === null ? "unknown" : String(item.current.calls),
+      item.prior === null ? "unknown" : String(item.prior.calls),
+    ]);
+    lines.push(
+      "",
+      ...table(
+        [...report.group_by.map(titleOf), "COST", "PRIOR_COST", "CHANGE", "CHANGE_%",
+          "CALLS", "PRIOR_CALLS"],
+        rows,
+      ),
+    );
+  }
+  const prior = comparison.prior;
+  const priorCodes = [...new Set((prior.warnings ?? []).map((entry) => entry.code))];
+  lines.push(
+    "",
+    ...(priorCodes.length > 0 ? [`Prior service warnings: ${priorCodes.join(", ")}`] : []),
+    `Prior coverage: ${prior.coverage?.completeness ?? "not reported"}` +
+      (prior.coverage && prior.coverage.reasons.length > 0 ? ` (${prior.coverage.reasons.join(", ")})` : "") +
+      `; pricing ${prior.pricing?.cost === "exact" ? "exact" : prior.pricing ? "lower bound" : "not reported"}`,
+    `Comparison: ${comparison.complete ? "complete" : "incomplete"}`,
+  );
+}