tines 0.0.211 → 0.0.213

package/README.md

@@ -46,12 +46,18 @@ tines issues comment <project>/<number> - <<'EOF'    # body from stdin; @file al
 EOF
 tines events list --issue <project>/<number>
 tines events list --since 2026-09-01T00:00:00Z --until 2026-09-08T00:00:00Z --state Engineering/Review
+tines events list --project Tines --all-pages --max-items 20000 --json
 tines supervisor stats --window 7d --project Tines
 ```
 
 Issues are addressed as `<project>/<number>`; schedules as `<project>/<name>`; workflow
 states as `<workflow>/<state>`. Every `list` command returns one page — add `--all-pages`
-for the whole list — and every command takes `--json` for machine-readable output.
+for the whole list — and every command takes `--json` for machine-readable output. Complete
+list walks have a default 10,000-item safety ceiling. Use `--max-items <n>` with
+`--all-pages` to choose a different positive finite bound; exceeding it fails without
+printing a partial result. `--limit` remains the per-request page size. A larger bound keeps
+more output in memory and makes more requests, so increase it deliberately or narrow the
+list's filters.
 `tines <noun> --help` lists the rest: `workflows`, `context`, `journal`, `schedules`,
 `runners`, `runs`, `routing`, `supervisor`.
 

package/dist/index.js

@@ -4160,6 +4160,7 @@ function createApiClient(options) {
     ),
     getUsage: (filters = {}) => get(`/api/v1/usage${query(filters)}`),
     getIssueUsage: (issue) => get(`/api/v1/usage${query({ mode: "issue", issue })}`),
+    getCohortUsage: (filters) => get(`/api/v1/usage${query({ mode: "cohort", ...filters })}`),
     getUsageScope: (scope) => get(`/api/v1/usage${query({ scope })}`),
     getUsageEvidence: (filters) => get(`/api/v1/usage/evidence${query(filters)}`),
     getRun: (id2) => get(`/api/v1/runs/${id2}`),
@@ -5904,23 +5905,39 @@ function withCommon(cmd) {
   ).option("--api-key <key>", "API key (or set TINES_API_KEY, or run `tines login`)").option("--json", "output the raw JSON response");
 }
 function withList(cmd) {
-  return withCommon(
-    cmd.option(
-      "--limit <n>",
-      "maximum items to return (page size under --all-pages)",
-      parsePositiveInteger
-    ).option("--cursor <cursor>", "resume from the next_cursor of a previous page").addOption(
-      new Option(
-        "--all-pages",
-        "fetch every page, not just the first (slower on large lists)"
-      ).conflicts("cursor")
-    )
-  );
+  const listCommand = cmd.option(
+    "--limit <n>",
+    "maximum items to return (page size under --all-pages)",
+    parsePositiveInteger
+  ).option("--cursor <cursor>", "resume from the next_cursor of a previous page").addOption(
+    new Option(
+      "--all-pages",
+      "fetch every page, not just the first (default safety ceiling: 10000 items)"
+    ).conflicts("cursor")
+  ).option(
+    "--max-items <n>",
+    "safety ceiling for --all-pages (default 10000; exceeding it errors)",
+    parseMaxItems
+  ).hook("preAction", (_thisCommand, actionCommand) => {
+    const opts = actionCommand.opts();
+    if (opts.maxItems !== void 0 && !opts.allPages) {
+      actionCommand.error("--max-items requires --all-pages");
+    }
+  });
+  return withCommon(listCommand);
 }
 function parsePositiveInteger(value) {
-  if (!/^[1-9]\d*$/.test(value)) throw new Error("limit must be a positive integer");
+  return parsePositiveIntegerOption(value, "limit");
+}
+function parseMaxItems(value) {
+  return parsePositiveIntegerOption(value, "max-items");
+}
+function parsePositiveIntegerOption(value, optionName) {
+  if (!/^[1-9]\d*$/.test(value)) throw new Error(`${optionName} must be a positive integer`);
   const result = Number(value);
-  if (!Number.isSafeInteger(result)) throw new Error("limit must be a positive safe integer");
+  if (!Number.isSafeInteger(result)) {
+    throw new Error(`${optionName} must be a positive safe integer`);
+  }
   return result;
 }
 function isUsageIdentity(value, prefix) {
@@ -5999,7 +6016,10 @@ more results: rerun with --all-pages, or resume with --cursor ${res.next_cursor}
 }
 async function fetchList(opts, fetchPage) {
   if (opts.allPages) {
-    return { items: await listAll(fetchPage, { pageSize: opts.limit }), next_cursor: null };
+    return {
+      items: await listAll(fetchPage, { pageSize: opts.limit, maxItems: opts.maxItems }),
+      next_cursor: null
+    };
   }
   const res = await fetchPage({ limit: opts.limit, cursor: opts.cursor });
   if (res.next_cursor && opts.json && !opts.cursor) {
@@ -12872,6 +12892,7 @@ function normalizeUrl(value) {
 }
 
 // src/commands/usage.ts
+var collect3 = (value, previous = []) => [...previous, value];
 function printEvidence(page) {
   console.log(
     `Usage evidence \xB7 ${page.kind} \xB7 ${page.population} \xB7 ${page.total_count} total \xB7 ${page.sort} ${page.direction}`
@@ -12886,6 +12907,17 @@ function printEvidence(page) {
         String(item.attempt_count)
       ])
     ]);
+  else if (page.kind === "entries")
+    table([
+      ["EVENT", "ISSUE", "STATE", "AT", "EVIDENCE"],
+      ...page.items.map((item) => [
+        item.event_id,
+        item.issue_id ?? "Unavailable issue",
+        item.state_name ?? item.state_id ?? "Unclassifiable",
+        new Date(item.created_at).toISOString(),
+        item.chosen ? "Chosen completion" : item.reopening_relevant ? "Reopening witness" : item.qualifies ? "Qualifying entry" : item.unavailable_reason ?? "Excluded"
+      ])
+    ]);
   else
     table([
       ["RUN", "ISSUE", "SPEND", "AT"],
@@ -12912,6 +12944,18 @@ function printEvidence(page) {
   console.log(
     `Matching total: ${money(page.matching_total.cost_usd)} \xB7 ${page.attempt_count} attempts \xB7 ${page.pending_count} pending`
   );
+  if (page.counters && page.history && page.from !== void 0 && page.to !== void 0 && page.observed_through !== void 0) {
+    console.log(
+      `Cohort selection: ${page.counters.distinct_issue_count} completed \xB7 ${page.counters.attempt_count} attempts \xB7 ${page.counters.pending_count} pending`
+    );
+    console.log(
+      `Entries [${new Date(page.from).toISOString()}, ${new Date(page.to).toISOString()}) \xB7 history ${page.history.status} \xB7 observed through ${new Date(page.observed_through).toISOString()}`
+    );
+    if (page.parent_counters)
+      console.log(
+        `Parent cohort: ${page.parent_counters.distinct_issue_count} completed \xB7 ${money(page.parent_matching_total?.cost_usd ?? null)}`
+      );
+  }
   if (page.next_cursor) console.log(`Next cursor: ${page.next_cursor}`);
 }
 function printIssueReport(report) {
@@ -12928,6 +12972,35 @@ function printIssueReport(report) {
     for (const line of usageAggregateLines("Lifetime", issue.aggregate)) console.log(line);
   }
 }
+function printCohortReport(report) {
+  console.log(`Completed issues \xB7 ${report.workflow.name}`);
+  console.log(
+    `${new Date(report.from).toISOString()} \u2014 ${new Date(report.to).toISOString()} \xB7 costs through exclusive cutoff`
+  );
+  console.log(
+    `Terminal states: ${report.selected_states.map((state) => state.name).join(", ") || "None available"}`
+  );
+  console.log("Completed-issue costs are not additive to period spend.");
+  console.log(
+    `${report.counters.distinct_issue_count} issues \xB7 ${report.counters.attempt_count}/${report.counters.distinct_issue_count} attempts/all issues \xB7 ${money(report.counters.known_cost_per_issue.value_usd)} known USD/all issues`
+  );
+  console.log(
+    `${report.counters.priced_run_coverage.numerator}/${report.counters.priced_run_coverage.denominator} priced finalized runs \xB7 ${report.counters.fully_priced_issue_count}/${report.counters.distinct_issue_count} fully priced issues \xB7 ${report.counters.pending_count} pending \xB7 ${report.counters.zero_run_issue_count} no-run`
+  );
+  console.log(
+    `${report.counters.reopened_issue_count} reopened \xB7 ${report.counters.reopening_history_unavailable_issue_count} reopening unknown \xB7 observed through ${new Date(report.observed_through).toISOString()}`
+  );
+  console.log(
+    `History: ${report.history.status} \xB7 ${report.history.qualifying_fact_count} qualifying entries`
+  );
+  for (const state of report.terminal_states)
+    console.log(
+      `${state.state.name}: ${state.counters.distinct_issue_count} completed \xB7 ${money(state.aggregate.cost_usd)} known`
+    );
+  if (report.counters.distinct_issue_count === 0)
+    console.log("No completed issues in available history");
+  if (report.scope) console.log(`Scope: ${report.scope}`);
+}
 var money = (value) => usageCostLabel(value);
 function printReport(report) {
   console.log(`Usage \xB7 ${report.filters.project ?? "All projects"} \xB7 ${report.by}`);
@@ -12986,8 +13059,15 @@ 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("--issue <ref>", "direct issue lifetime through now").option("--scope <token>", "replay a frozen usage scope").addOption(new Option("--evidence <kind>", "list evidence").choices(["issues", "runs"])).option("--member <issue-id>", "narrow run evidence to one contributing issue").addOption(
-      new Option("--population <population>", "finalized or pending").choices([
+    ).option("--from <bound>", "custom inclusive start (date or offset timestamp)").option("--to <bound>", "custom exclusive end (date or offset timestamp)").option("--issue <ref>", "direct issue lifetime through now").option("--cohort", "report issues completed in the selected workflow and window").option(
+      "--done-state <id>",
+      "terminal state id (repeatable; defaults to all done states)",
+      collect3
+    ).option("--scope <token>", "replay a frozen usage scope").addOption(
+      new Option("--evidence <kind>", "list evidence").choices(["issues", "runs", "entries"])
+    ).option("--member <issue-id>", "narrow run evidence to one contributing issue").addOption(
+      new Option("--population <population>", "all, finalized, or pending").choices([
+        "all",
         "finalized",
         "pending"
       ])
@@ -13025,6 +13105,8 @@ function register12(program3) {
     if (opts.scope) {
       const reportFlags = [
         opts.issue,
+        opts.cohort,
+        opts.doneState,
         opts.window,
         opts.from,
         opts.to,
@@ -13044,6 +13126,7 @@ function register12(program3) {
         const report2 = await api2.getUsageScope(opts.scope);
         if (opts.json) return printJson(report2);
         if (report2.mode === "issue") printIssueReport(report2);
+        else if (report2.mode === "cohort") printCohortReport(report2);
         else printReport(report2);
         return;
       }
@@ -13066,7 +13149,7 @@ function register12(program3) {
           cursor
         });
         for (const item of page.items) {
-          const id2 = "id" in item ? item.id : item.issue_id ?? "unknown";
+          const id2 = "event_id" in item ? item.event_id : "id" in item ? item.id : item.issue_id ?? "unknown";
           if (seenIds.has(id2)) throw new Error(`Evidence pagination repeated ${id2}`);
           seenIds.add(id2);
         }
@@ -13080,6 +13163,8 @@ function register12(program3) {
     }
     if (opts.issue) {
       const contradictions = [
+        opts.cohort,
+        opts.doneState,
         opts.window,
         opts.from,
         opts.to,
@@ -13101,6 +13186,37 @@ function register12(program3) {
       printIssueReport(report2);
       return;
     }
+    if (opts.doneState?.length && !opts.cohort) throw new Error("--done-state requires --cohort");
+    if (opts.cohort) {
+      if (!opts.workflow) throw new Error("--cohort requires --workflow");
+      if ([
+        opts.issue,
+        opts.scope,
+        opts.state,
+        opts.runner,
+        opts.tier,
+        opts.outcome,
+        opts.accountingStatus
+      ].some((value) => value !== void 0) || command.getOptionValueSource("by") === "cli")
+        throw new Error("--cohort cannot be combined with issue, scope, grouping, or run filters");
+      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");
+      const api2 = client(opts);
+      const project2 = opts.project && !isUsageIdentity(opts.project, "prj") ? (await resolveProject(api2, opts.project)).id : opts.project;
+      const workflow3 = !isUsageIdentity(opts.workflow, "wf") ? (await resolveWorkflow(api2, opts.workflow)).id : opts.workflow;
+      const report2 = await api2.getCohortUsage({
+        workflow: workflow3,
+        project: project2,
+        window: opts.window,
+        from: opts.from,
+        to: opts.to,
+        done_state: opts.doneState
+      });
+      if (opts.json) return printJson(report2);
+      printCohortReport(report2);
+      return;
+    }
     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");

package/package.json

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