tines 0.0.186 → 0.0.187

package/dist/index.js

@@ -4139,7 +4139,10 @@ function createApiClient(options) {
     appendRunLog: (runId, body) => request("POST", `/api/v1/runs/${runId}/logs`, body),
     finishRun: (runId, body) => request("POST", `/api/v1/runs/${runId}/finish`, body),
     // Agent runs
-    listRuns: (filters = {}) => get(`/api/v1/runs${query(filters)}`),
+    listRuns: (filters = {}) => get(
+      `/api/v1/runs${query(filters)}`
+    ),
+    getUsage: (filters = {}) => get(`/api/v1/usage${query(filters)}`),
     getRun: (id2) => get(`/api/v1/runs/${id2}`),
     /**
      * The run's complete log (not the 256 KB tail `getRun` returns) as a
@@ -4540,6 +4543,20 @@ var schedule = shape({
 // ../shared/src/library/choices.ts
 var PACKAGE_CHOICES_MAX_BYTES = 512 * 1024;
 
+// ../shared/src/usage.ts
+function usageCostLabel(cost, finalized = 1) {
+  if (finalized === 0) return "No runs";
+  if (cost === null) return "Unknown";
+  if (cost === 0) return "$0";
+  if (cost < 0.01) return "<$0.01";
+  return cost.toLocaleString("en-US", {
+    style: "currency",
+    currency: "USD",
+    minimumFractionDigits: 2,
+    maximumFractionDigits: 2
+  });
+}
+
 // src/format.ts
 function timestamp(ms) {
   return new Date(ms).toISOString().replace("T", " ").slice(0, 19);
@@ -9641,22 +9658,71 @@ function register8(program3) {
   });
   const runsCmd = program3.command("runs").description("Agent runs: attempts at issues by runners");
   withList(
-    runsCmd.command("list").description("List runs, newest first").option("-i, --issue <ref>", "filter to one issue (<project>/<number>)").option("-r, --runner <name>", "filter by runner name").option("--active", "only runs holding a claim (assigned/launching/running)")
+    runsCmd.command("list").description("List runs, newest first").option("-i, --issue <ref>", "filter to one issue (<project>/<number>)").option("-r, --runner <name>", "filter by runner name").option("--active", "only runs holding a claim (assigned/launching/running)").addOption(
+      new Option("--population <mode>", "period evidence population").choices([
+        "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(
+      new Option("--outcome <outcome>", "recorded outcome").choices([
+        "advanced",
+        "stalled",
+        "interrupted",
+        "unknown"
+      ])
+    ).addOption(
+      new Option("--accounting-status <status>", "usage accounting status").choices([
+        "priced",
+        "unpriced",
+        "unreported"
+      ])
+    )
   ).action(async (opts) => {
     const api = client(opts);
+    const evidence = opts;
+    if (evidence.from === void 0 !== (evidence.to === void 0))
+      die("--from and --to are required together");
+    if ((evidence.from || evidence.to) && !evidence.population)
+      die("period filters require --population");
     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 res = await fetchList(
       opts,
       (page) => api.listRuns({
         issue: issueId,
         runner: runnerId,
         active: opts.active ? true : void 0,
+        population: evidence.population,
+        from: evidence.from,
+        to: evidence.to,
+        project: projectId,
+        workflow: workflowId,
+        state: evidence.state,
+        tier: evidence.tier,
+        outcome: evidence.outcome,
+        accounting_status: evidence.accountingStatus,
         ...page
       })
     );
     printList(res, opts, (items) => {
       if (items.length === 0) return console.log(opts.active ? "no active runs" : "no runs");
+      if (evidence.population === "pending") {
+        table([
+          ["ID", "ISSUE", "RUNNER", "TIER", "STATUS", "COST", "CREATED"],
+          ...items.map((run) => [
+            run.id,
+            run.issue_ref ? `${run.issue_ref.project_name}/${run.issue_ref.number}` : run.issue_id,
+            run.runner_name,
+            run.tier,
+            "Pending at cutoff",
+            "\u2014",
+            timestamp(run.created_at)
+          ])
+        ]);
+        return;
+      }
       table([
         ["ID", "ISSUE", "RUNNER", "TIER", "STATUS", "DURATION", "COST", "CREATED"],
         ...items.map(runRow)
@@ -10442,6 +10508,111 @@ see \`tines workflows create --help\` for the expected shape`
   });
 }
 
+// src/commands/usage.ts
+var money = (value) => usageCostLabel(value);
+function printReport(report) {
+  console.log(`Usage \xB7 ${report.filters.project ?? "All projects"} \xB7 ${report.by}`);
+  console.log(
+    `${new Date(report.from).toISOString()} \u2014 ${new Date(report.to).toISOString()} \xB7 ${report.timezone} (${report.timezone_source.replace("_", " ")})`
+  );
+  console.log(
+    `generated ${new Date(report.generated_at).toISOString()} \xB7 ${report.accounting_basis}`
+  );
+  const scope = report.scope_total;
+  console.log(
+    `Scope total: ${money(scope.cost_usd)} \xB7 ${scope.coverage} \xB7 ${scope.finalized_run_count} finalized \xB7 ${scope.priced_run_count} priced \xB7 ${scope.unpriced_run_count + scope.unreported_run_count} without price`
+  );
+  if (JSON.stringify(report.filters) !== JSON.stringify({ ...report.filters.project ? { project: report.filters.project } : {} })) {
+    const matching = report.matching_total;
+    console.log(
+      `Matching subtotal: ${money(matching.cost_usd)} \xB7 ${matching.coverage} \xB7 ${matching.finalized_run_count} finalized`
+    );
+  }
+  const total = report.matching_total;
+  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)
+    ])
+  ]);
+  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.");
+  console.log(
+    `Matching tokens: ${Object.entries(total.tokens).map(
+      ([name2, t]) => `${name2} ${t.value ?? "unknown"} (${t.reported_runs}/${total.finalized_run_count} runs)`
+    ).join(" \xB7 ")}`
+  );
+  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`
+    );
+  }
+}
+function register12(program3) {
+  withCommon(
+    program3.command("usage").description("Compare finalized run spend for a period").addOption(
+      new Option("--window <window>", "today, 7d, or 30d").choices(["today", "7d", "30d"])
+    ).option("--from <bound>", "custom inclusive start (date or offset timestamp)").option("--to <bound>", "custom exclusive end (date or offset timestamp)").option("--project <name-or-id>", "project scope (including archived), or unknown").option("--workflow <name-or-id>", "workflow filter, or unknown").option("--state <id>", "starting state id (requires --workflow)").option("--runner <name-or-id>", "runner filter, or unknown").option("--tier <tier>", "tier filter").addOption(
+      new Option("--outcome <outcome>", "recorded outcome").choices([
+        "advanced",
+        "stalled",
+        "interrupted",
+        "unknown"
+      ])
+    ).addOption(
+      new Option("--accounting-status <status>", "price coverage").choices([
+        "priced",
+        "unpriced",
+        "unreported"
+      ])
+    ).addOption(
+      new Option("--by <dimension>", "group dimension").choices(["project", "workflow", "state", "outcome", "runner", "tier"]).default("workflow")
+    )
+  ).action(async (opts) => {
+    if (opts.from === void 0 !== (opts.to === void 0))
+      throw new Error("--from and --to are required together");
+    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 workflow = 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 report = await api.getUsage({
+      window: opts.window,
+      from: opts.from,
+      to: opts.to,
+      project,
+      workflow,
+      state: opts.state,
+      runner,
+      tier: opts.tier,
+      outcome: opts.outcome,
+      accounting_status: opts.accountingStatus,
+      by: opts.by
+    });
+    if (opts.json) return printJson(report);
+    printReport(report);
+  });
+}
+
 // src/program.ts
 var program2 = new Command();
 program2.name("tines").description("CLI for Tines").version(cliVersion()).enablePositionalOptions();
@@ -10457,6 +10628,7 @@ register9(program2);
 register8(program2);
 register7(program2);
 register10(program2);
+register12(program2);
 registerEvents(program2);
 
 // src/index.ts

package/package.json

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