tines 0.0.205 → 0.0.207

package/dist/index.js

@@ -5865,7 +5865,7 @@ function withList(cmd) {
     cmd.option(
       "--limit <n>",
       "maximum items to return (page size under --all-pages)",
-      (v) => Number.parseInt(v, 10)
+      parsePositiveInteger
     ).option("--cursor <cursor>", "resume from the next_cursor of a previous page").addOption(
       new Option(
         "--all-pages",
@@ -5874,6 +5874,15 @@ function withList(cmd) {
     )
   );
 }
+function parsePositiveInteger(value) {
+  if (!/^[1-9]\d*$/.test(value)) throw new Error("limit must be a positive integer");
+  const result = Number(value);
+  if (!Number.isSafeInteger(result)) throw new Error("limit must be a positive safe integer");
+  return result;
+}
+function isUsageIdentity(value, prefix) {
+  return value === "unknown" || new RegExp(`^${prefix}_[A-Za-z0-9]+$`).test(value);
+}
 function resolveUrlSetting(opts) {
   if (opts.url) return { value: opts.url, source: "flag" };
   if (process.env.TINES_API_URL) return { value: process.env.TINES_API_URL, source: "env" };
@@ -6271,7 +6280,7 @@ var CHANGE_LABEL = {
 function inspectableChanges(preview) {
   return preview.context.changes;
 }
-var effectiveness = (present, effective) => !present ? "not present" : effective ? "effective" : "overridden candidate";
+var effectiveness = (present2, effective) => !present2 ? "not present" : effective ? "effective" : "overridden candidate";
 function repoLine(change) {
   if (change.kind !== "repo") return null;
   const before = change.repo_before;
@@ -10961,6 +10970,52 @@ stop it first \u2014 \`tines runners pause ${settings.name}\`, wait for 0 active
   });
 }
 
+// src/usage-format.ts
+var present = (value) => value === null || value === void 0 || value === "" ? "unavailable" : String(value);
+var instant = (value) => {
+  if (typeof value !== "number") return present(value);
+  const parsed = new Date(value);
+  return Number.isFinite(parsed.getTime()) ? parsed.toISOString() : "unavailable";
+};
+function basisLine(basis, selection) {
+  if (!basis) return "historical calculated amount \xB7 basis unavailable";
+  const rates = basis.rates && typeof basis.rates === "object" ? basis.rates : {};
+  return [
+    `id ${present(basis.rate_id)}`,
+    `version ${present(basis.rate_version)}`,
+    `model ${present(basis.model)}`,
+    `plan ${present(basis.plan)}`,
+    `context ${present(basis.context_band)}`,
+    `source ${present(basis.source_url)}`,
+    `checked ${present(basis.source_checked_at)}`,
+    `effective ${present(basis.source_effective_at)}`,
+    `adopted ${instant(basis.rate_adopted_at)}`,
+    `valid to ${instant(basis.rate_valid_to)}`,
+    ...selection ? [`selected ${instant(selection.min)} \u2014 ${instant(selection.max)}`] : [`selected ${instant(basis.rate_selected_at)}`],
+    `rates input=${present(rates.input_tokens)} cache-read=${present(rates.cache_read_tokens)} cache-write=${present(rates.cache_write_tokens)} output=${present(rates.output_tokens)} per ${present(basis.unit_tokens)} tokens`
+  ].join(" \xB7 ");
+}
+function usageAggregateLines(label, aggregate) {
+  const nonzero = (record) => Object.entries(record).filter(([, count]) => typeof count === "number" && count > 0).map(([name2, count]) => `${name2}=${count}`).join(" \xB7 ") || "none";
+  return [
+    `${label} sources: provider ${aggregate.portions.provider.cost_usd_exact} (${aggregate.portions.provider.priced_run_count}) \xB7 calculated ${aggregate.portions.calculated.cost_usd_exact} (${aggregate.portions.calculated.priced_run_count}) \xB7 unknown ${aggregate.portions.unknown_source.cost_usd_exact} (${aggregate.portions.unknown_source.priced_run_count})`,
+    `${label} diagnostics: ${nonzero(aggregate.diagnostics)}`,
+    `${label} pricing reasons: ${nonzero(aggregate.pricing_reasons)}`,
+    ...aggregate.rate_portions.map(
+      (portion) => `${label} rate (${portion.cost_usd_exact}; ${portion.priced_run_count} runs): ${basisLine(portion.basis, { min: portion.rate_selected_at_min, max: portion.rate_selected_at_max })}`
+    )
+  ];
+}
+function usageEvidenceLines(id2, dimensions, accounting) {
+  const dims = ["project", "workflow", "state", "outcome", "runner", "tier"].map((name2) => `${name2}=${dimensions[name2].name} [${dimensions[name2].id ?? "unknown"}]`).join(" \xB7 ");
+  const diagnostics = Object.entries(accounting.diagnostics).filter(([, count]) => count > 0).map(([name2, count]) => `${name2}=${count}`).join(" \xB7 ");
+  return [
+    `Evidence ${id2}: ${dims}`,
+    `Accounting ${id2}: ${accounting.status} \xB7 source ${accounting.source ?? "unavailable"} \xB7 exact cost ${accounting.cost_exact ?? "unavailable"}${accounting.pricing_reason ? ` \xB7 reason ${accounting.pricing_reason}` : ""}${diagnostics ? ` \xB7 diagnostics ${diagnostics}` : ""}`,
+    ...accounting.source === "calculated" ? [`Rate ${id2}: ${basisLine(accounting.basis)}`] : []
+  ];
+}
+
 // src/commands/runners.ts
 function parseBoolean(value) {
   if (value === "true") return true;
@@ -11326,7 +11381,7 @@ function register8(program3) {
         "finalized",
         "pending"
       ])
-    ).option("--from <timestamp>", "inclusive period start").option("--to <timestamp>", "exclusive period cutoff").option("--project <name-or-id>", "project, including archived").option("--workflow <name-or-id>", "workflow").option("--state <id>", "starting state id").option("--tier <tier>", "model tier").addOption(
+    ).option("--from <timestamp>", "inclusive period start").option("--to <timestamp>", "exclusive period cutoff").option("--timezone <iana>", "period display timezone (with --timezone-source)").option("--timezone-source <source>", "supervisor_budget or utc_fallback").option("--project <name-or-id>", "project, including archived").option("--workflow <name-or-id>", "workflow").option("--state <id>", "starting state id").option("--tier <tier>", "model tier").addOption(
       new Option("--outcome <outcome>", "recorded outcome").choices([
         "advanced",
         "stalled",
@@ -11347,10 +11402,14 @@ function register8(program3) {
       die("--from and --to are required together");
     if ((evidence.from || evidence.to) && !evidence.population)
       die("period filters require --population");
+    if (evidence.timezone === void 0 !== (evidence.timezoneSource === void 0))
+      die("--timezone and --timezone-source are required together");
+    if (evidence.population && opts.limit !== void 0 && opts.limit > 100)
+      die("period evidence --limit must be at most 100");
     const issueId = opts.issue ? (await resolveIssue(api, opts.issue)).id : void 0;
-    const runnerId = opts.runner ? (await resolveRunner(api, opts.runner)).id : void 0;
-    const projectId = evidence.project ? (await resolveProject(api, evidence.project)).id : void 0;
-    const workflowId = evidence.workflow ? (await resolveWorkflow(api, evidence.workflow)).id : void 0;
+    const runnerId = opts.runner ? evidence.population && isUsageIdentity(opts.runner, "rnr") ? opts.runner : (await resolveRunner(api, opts.runner)).id : void 0;
+    const projectId = evidence.project ? evidence.population && isUsageIdentity(evidence.project, "prj") ? evidence.project : (await resolveProject(api, evidence.project)).id : void 0;
+    const workflowId = evidence.workflow ? evidence.population && isUsageIdentity(evidence.workflow, "wf") ? evidence.workflow : (await resolveWorkflow(api, evidence.workflow)).id : void 0;
     const res = await fetchList(
       opts,
       (page) => api.listRuns({
@@ -11366,6 +11425,8 @@ function register8(program3) {
         tier: evidence.tier,
         outcome: evidence.outcome,
         accounting_status: evidence.accountingStatus,
+        timezone: evidence.timezone,
+        timezone_source: evidence.timezoneSource,
         ...page
       })
     );
@@ -11390,6 +11451,16 @@ function register8(program3) {
         ["ID", "ISSUE", "RUNNER", "TIER", "STATUS", "DURATION", "COST", "CREATED"],
         ...items.map(runRow)
       ]);
+      if (evidence.population === "finalized") {
+        for (const run2 of items)
+          if (run2.usage_dimensions && run2.usage_accounting)
+            for (const line of usageEvidenceLines(
+              run2.id,
+              run2.usage_dimensions,
+              run2.usage_accounting
+            ))
+              console.log(line);
+      }
     });
   });
   withCommon(
@@ -12692,22 +12763,23 @@ function printReport(report) {
   console.log(
     `Pending at cutoff: ${report.pending.matching_count}${report.pending.unapplied_filters.length ? ` (before ${report.pending.unapplied_filters.join("/")} filters)` : ""}`
   );
-  if (report.groups.length === 0) return console.log("no finalized runs");
-  table([
-    ["GROUP", "SPEND", "COVERAGE", "FINAL", "PRICED", "MISSING", "MEDIAN", "P95", "MAX", "MEAN"],
-    ...report.groups.map(({ dimension, aggregate: a }) => [
-      dimension.name,
-      money(a.cost_usd),
-      a.coverage,
-      String(a.finalized_run_count),
-      String(a.priced_run_count),
-      String(a.unpriced_run_count + a.unreported_run_count),
-      money(a.distribution.median_cost_usd),
-      money(a.distribution.p95_cost_usd),
-      money(a.distribution.max_cost_usd),
-      money(a.distribution.mean_cost_usd)
-    ])
-  ]);
+  if (report.groups.length === 0) console.log("no finalized runs");
+  else
+    table([
+      ["GROUP", "SPEND", "COVERAGE", "FINAL", "PRICED", "MISSING", "MEDIAN", "P95", "MAX", "MEAN"],
+      ...report.groups.map(({ dimension, aggregate: a }) => [
+        dimension.name,
+        money(a.cost_usd),
+        a.coverage,
+        String(a.finalized_run_count),
+        String(a.priced_run_count),
+        String(a.unpriced_run_count + a.unreported_run_count),
+        money(a.distribution.median_cost_usd),
+        money(a.distribution.p95_cost_usd),
+        money(a.distribution.max_cost_usd),
+        money(a.distribution.mean_cost_usd)
+      ])
+    ]);
   console.log("Per-run cost \xB7 priced subset; p95 uses nearest rank.");
   if (report.groups.some((g) => g.aggregate.distribution.low_sample))
     console.log("Small samples (under 20): p95 equals maximum.");
@@ -12719,12 +12791,8 @@ function printReport(report) {
   console.log(
     `Matching sources: provider ${total.portions.provider.cost_usd_exact} \xB7 calculated ${total.portions.calculated.cost_usd_exact} \xB7 unknown ${total.portions.unknown_source.cost_usd_exact}`
   );
-  for (const portion of total.rate_portions) {
-    const basis = portion.basis;
-    console.log(
-      basis ? `Rate: ${basis.rate_id} v${basis.rate_version} \xB7 ${basis.model} \xB7 ${basis.source_url}` : `Rate: historical calculated amount \xB7 basis unavailable`
-    );
-  }
+  for (const line of usageAggregateLines("Scope", scope)) console.log(line);
+  for (const line of usageAggregateLines("Matching", total)) console.log(line);
 }
 function register12(program3) {
   withCommon(
@@ -12752,9 +12820,9 @@ function register12(program3) {
     if (opts.window && opts.from) throw new Error("--window cannot be combined with --from/--to");
     if (opts.state && !opts.workflow) throw new Error("--state requires --workflow");
     const api = client(opts);
-    const project = opts.project && opts.project !== "unknown" ? (await resolveProject(api, opts.project)).id : opts.project;
-    const workflow2 = opts.workflow && opts.workflow !== "unknown" ? (await resolveWorkflow(api, opts.workflow)).id : opts.workflow;
-    const runner = opts.runner && opts.runner !== "unknown" ? (await resolveRunner(api, opts.runner)).id : opts.runner;
+    const project = opts.project && !isUsageIdentity(opts.project, "prj") ? (await resolveProject(api, opts.project)).id : opts.project;
+    const workflow2 = opts.workflow && !isUsageIdentity(opts.workflow, "wf") ? (await resolveWorkflow(api, opts.workflow)).id : opts.workflow;
+    const runner = opts.runner && !isUsageIdentity(opts.runner, "rnr") ? (await resolveRunner(api, opts.runner)).id : opts.runner;
     const report = await api.getUsage({
       window: opts.window,
       from: opts.from,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tines",
-  "version": "0.0.205",
+  "version": "0.0.207",
   "description": "CLI for Tines, an orchestration layer for AI agents",
   "repository": {
     "type": "git",