tines 0.0.208 → 0.0.210

package/README.md

@@ -45,6 +45,8 @@ 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 supervisor stats --window 7d --project Tines
 ```
 
 Issues are addressed as `<project>/<number>`; schedules as `<project>/<name>`; workflow

package/dist/index.js

@@ -3482,6 +3482,7 @@ function parsePrSpec(spec) {
   return repoUrl2 ? { repo_url: repoUrl2, number: Number.parseInt(url[2], 10) } : null;
 }
 var MODEL_TIERS = ["smartest", "balanced", "cheapest"];
+var RUN_END_OUTCOMES = ["advanced", "stalled", "interrupted"];
 var RUNNER_ONLINE_WINDOW_MS = 2 * 60 * 1e3;
 var DEFAULT_RESUME_WINDOW_HOURS = 48;
 var DEFAULT_RESUME_MAX_TURNS = 25;
@@ -3575,6 +3576,11 @@ function utilizationLabel(quota, activeRuns, stateName = (id2) => id2) {
     ([stateId, { name: name2, n }]) => `${name2} ${n}/${quota.overrides[stateId] ?? quota.default_limit}`
   ).join(" \xB7 ");
 }
+var RUN_OUTCOME_BUCKETS = [
+  ...RUN_END_OUTCOMES,
+  "failed",
+  "unrecorded"
+];
 var LIBRARY_MAX_BYTES = 5 * 1024 * 1024;
 
 // ../shared/src/events.ts
@@ -4153,6 +4159,9 @@ function createApiClient(options) {
       `/api/v1/runs${query(filters)}`
     ),
     getUsage: (filters = {}) => get(`/api/v1/usage${query(filters)}`),
+    getIssueUsage: (issue) => get(`/api/v1/usage${query({ mode: "issue", issue })}`),
+    getUsageScope: (scope) => get(`/api/v1/usage${query({ scope })}`),
+    getUsageEvidence: (filters) => get(`/api/v1/usage/evidence${query(filters)}`),
     getRun: (id2) => get(`/api/v1/runs/${id2}`),
     /**
      * The run's complete log (not the 256 KB tail `getRun` returns) as a
@@ -4180,7 +4189,9 @@ function createApiClient(options) {
     getPreferences: () => get("/api/v1/preferences"),
     updatePreferences: (body) => request("PATCH", "/api/v1/preferences", body),
     getSupervisorSettings: () => get("/api/v1/supervisor/settings"),
-    getSupervisorQueue: () => get("/api/v1/supervisor/queue"),
+    getSupervisorQueue: (q = {}) => get(`/api/v1/supervisor/queue${query(q)}`),
+    getSupervisorStats: (q = {}) => get(`/api/v1/supervisor/stats${query(q)}`),
+    getSupervisorSentBack: (q) => get(`/api/v1/supervisor/stats/sent-back${query(q)}`),
     updateSupervisorSettings: (body) => request("PUT", "/api/v1/supervisor/settings", body),
     // API keys (create/revoke require a browser session, not a key)
     listApiKeys: (filters = {}) => get(`/api/v1/api-keys${query(filters)}`),
@@ -4423,6 +4434,38 @@ async function listAll(fetchPage, opts = {}) {
 // ../shared/src/routing.ts
 var INHERIT_RUNNER_ID = "*";
 
+// ../shared/src/stats-format.ts
+var MIN = 6e4;
+var HOUR = 60 * MIN;
+var DAY = 24 * HOUR;
+function durationLabel(ms) {
+  if (ms === null || ms === void 0) return "\u2014";
+  if (ms < MIN) return `${Math.round(ms / 1e3)} s`;
+  if (ms < HOUR) return `${Math.round(ms / MIN)} min`;
+  if (ms < DAY) return `${(ms / HOUR).toFixed(1)} h`;
+  return `${(ms / DAY).toFixed(1)} d`;
+}
+function shareLabel(share) {
+  if (share === null || share === void 0) return "\u2014";
+  return `${Math.round(share * 100)}%`;
+}
+function deltaLabel(delta, kind) {
+  if (delta === null || delta === void 0) return "";
+  if (delta === 0) return "=";
+  const arrow = delta > 0 ? "\u25B2" : "\u25BC";
+  const size = Math.abs(delta);
+  switch (kind) {
+    case "ms":
+      return `${arrow} ${durationLabel(size)}`;
+    case "share":
+      return `${arrow} ${Math.round(size * 100)} pp`;
+    case "ratio":
+      return `${arrow} ${size.toFixed(1)}`;
+    default:
+      return `${arrow} ${size}`;
+  }
+}
+
 // ../shared/src/issue-transfer.ts
 var compare = (a, b) => a < b ? -1 : a > b ? 1 : 0;
 function conflictsByKey(context2) {
@@ -8168,27 +8211,33 @@ function registerTime(program3) {
 function registerEvents(program3) {
   const events = program3.command("events").description("Read the activity log");
   withList(
-    events.command("list").description("List activity events, newest first").option("-i, --issue <ref>", "filter to one issue (<project>/<number>)").option("-p, --project <name>", "filter by project name or id").option("-t, --type <type>", "filter by event type (e.g. issue.transitioned)")
-  ).action(async (opts) => {
-    const api = client(opts);
-    const issueId = opts.issue ? (await resolveIssue(api, opts.issue)).id : void 0;
-    const res = await fetchList(
-      opts,
-      (page) => api.listEvents({
-        issue: issueId,
-        project: opts.project,
-        type: opts.type,
-        ...page
-      })
-    );
-    printList(res, opts, (items) => {
-      if (items.length === 0) return console.log("no events");
-      table([
-        ["WHEN", "ACTOR", "EVENT"],
-        ...items.map((ev) => [timestamp(ev.created_at), displayActor(ev), eventSummary(ev)])
-      ]);
-    });
-  });
+    events.command("list").description("List activity events, newest first").option("-i, --issue <ref>", "filter to one issue (<project>/<number>)").option("-p, --project <name>", "filter by project name or id").option("-t, --type <type>", "filter by event type (e.g. issue.transitioned)").option("--since <time>", "inclusive lower bound (ISO 8601 or epoch ms)").option("--until <time>", "exclusive upper bound (ISO 8601 or epoch ms)").option("--state <workflow/state>", "events referencing a workflow state")
+  ).action(
+    async (opts) => {
+      const api = client(opts);
+      const issueId = opts.issue ? (await resolveIssue(api, opts.issue)).id : void 0;
+      const stateId = opts.state ? (await resolveStateFlag(api, opts.state)).state.id : void 0;
+      const res = await fetchList(
+        opts,
+        (page) => api.listEvents({
+          issue: issueId,
+          project: opts.project,
+          type: opts.type,
+          since: opts.since,
+          until: opts.until,
+          state: stateId,
+          ...page
+        })
+      );
+      printList(res, opts, (items) => {
+        if (items.length === 0) return console.log("no events");
+        table([
+          ["WHEN", "ACTOR", "EVENT"],
+          ...items.map((ev) => [timestamp(ev.created_at), displayActor(ev), eventSummary(ev)])
+        ]);
+      });
+    }
+  );
 }
 
 // src/commands/projects.ts
@@ -11009,9 +11058,11 @@ function usageAggregateLines(label, aggregate) {
 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 ");
+  const tokens = ["input_tokens", "output_tokens", "cache_read_tokens", "cache_write_tokens"].map((name2) => `${name2}=${present(accounting.tokens[name2])}`).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}` : ""}`,
+    `Tokens ${id2}: ${tokens} \xB7 invalid_tokens=${accounting.invalid_tokens.length ? accounting.invalid_tokens.join(",") : "none"}`,
     ...accounting.source === "calculated" ? [`Rate ${id2}: ${basisLine(accounting.basis)}`] : []
   ];
 }
@@ -11829,10 +11880,26 @@ function queueFix(block) {
       return null;
   }
 }
+function outcomeLabel(stats) {
+  const o = stats.current.runs.outcomes;
+  const parts = [`adv ${o.advanced}`, `stalled ${o.stalled}`, `failed ${o.failed}`];
+  if (o.interrupted > 0) parts.push(`intr ${o.interrupted}`);
+  if (o.unrecorded > 0) parts.push(`unrecorded ${o.unrecorded}`);
+  if (stats.current.runs.active > 0) parts.push(`active ${stats.current.runs.active}`);
+  return parts.join(" \xB7 ");
+}
+function statsLevers() {
+  return [
+    "levers:",
+    "  queue wait  tines supervisor quota roster --state <wf>/<state>=<n>",
+    "  runs        tines runs list --state <wf>/<state>",
+    "  sent back   tines context show <wf>/<state> instructions"
+  ];
+}
 function register10(program3) {
   const supervisor = program3.command("supervisor").description("The automation kill switch, quota policy, and attempt limit");
   withCommon(
-    supervisor.command("status").description("One-screen overview: kill switch, quota, utilization, runners")
+    supervisor.command("status").description("One-screen overview: kill switch, quota, utilization, runners").option("--project <name-or-id>", "filter waiting work to one project")
   ).action(async (opts) => {
     const api = client(opts);
     const [settings, runnersRes, workflows, activeRunItems, queue] = await Promise.all([
@@ -11840,7 +11907,7 @@ function register10(program3) {
       api.listRunners(),
       api.listWorkflows(),
       listAll((page) => api.listRuns({ active: true, ...page })),
-      api.getSupervisorQueue()
+      api.getSupervisorQueue({ project: opts.project })
     ]);
     if (opts.json) {
       return printJson({
@@ -11897,6 +11964,71 @@ function register10(program3) {
       );
     }
   });
+  withCommon(
+    supervisor.command("stats").description("Per-stage flow this week: queue wait, work time, runs per visit, sent back").option("--window <window>", "Rolling window, e.g. 24h or 7d", "7d").option("--project <ref>", "Narrow to one project (id or name)").option("--sent-back <workflow/state>", "Show the issues behind one sent-back figure")
+  ).action(async (opts) => {
+    const api = client(opts);
+    const project = opts.project ? await resolveProject(api, opts.project) : null;
+    if (opts.sentBack) {
+      const { state } = await resolveStateFlag(api, opts.sentBack);
+      const detail = await api.getSupervisorSentBack({
+        state: state.id,
+        window: opts.window,
+        project: project?.id ?? void 0
+      });
+      if (opts.json) return printJson(detail);
+      console.log(`sent back from ${detail.state.workflow_name}/${detail.state.name}`);
+      if (detail.prompt)
+        console.log(`prompt: ${detail.prompt.name} (current v${detail.prompt.current_version})`);
+      if (detail.items.length === 0) return console.log("no issues sent back");
+      for (const item of detail.items) {
+        console.log(
+          `${item.issue.project_name}/${item.issue.number} \u2192 ${item.to_state_name} \xB7 prompt ${item.prompt_version ? `v${item.prompt_version}` : "unknown"} \xB7 ${item.actor.user_name}`
+        );
+        console.log(`  ${item.comment?.excerpt.split("\n")[0] ?? "no comment"}`);
+      }
+      return;
+    }
+    const report = await api.getSupervisorStats({
+      window: opts.window,
+      project: project?.id ?? void 0
+    });
+    if (opts.json) return printJson(report);
+    if (report.states.length === 0) {
+      console.log("No agent stage saw work in the last window.");
+      return;
+    }
+    const windowLabel = opts.window ?? "7d";
+    console.log(
+      `this week (${windowLabel}${report.project ? `, project ${report.project.name}` : ""})${report.previous ? ` \u2014 vs the ${windowLabel} before` : ""}`
+    );
+    table([
+      ["  stage", "visits", "queue p50", "p90", "work p50", "runs/visit", "ended", "sent back"],
+      ...report.states.map((s) => [
+        `  ${s.workflow_name}/${s.state_name}`,
+        `${s.current.visits}\xB7${s.current.exits} ${deltaLabel(s.delta.visits, "count")}`.trim(),
+        `${durationLabel(s.current.queue_wait?.p50 ?? null)} ${deltaLabel(s.delta.queue_wait_p50, "ms")}`.trim(),
+        durationLabel(s.current.queue_wait?.p90 ?? null),
+        `${durationLabel(s.current.work?.p50 ?? null)} ${deltaLabel(s.delta.work_p50, "ms")}`.trim(),
+        s.current.runs.per_visit === null ? "\u2014" : `${s.current.runs.per_visit.toFixed(1)} ${deltaLabel(s.delta.runs_per_visit, "ratio")}`.trim(),
+        outcomeLabel(s),
+        `${s.current.sent_back.count} of ${s.current.exits} (${shareLabel(s.current.sent_back.share)}) \xB7 agents ${s.current.sent_back.agent} ${deltaLabel(s.delta.sent_back_share, "share")}`.trim()
+      ])
+    ]);
+    if (report.markers.length > 0) {
+      console.log("changes:");
+      for (const marker of report.markers) {
+        console.log(`  ${marker.label}`);
+        for (const effect of marker.effects) {
+          const state = report.states.find((row) => row.state_id === effect.state_id);
+          console.log(
+            `    ${state?.state_name ?? effect.state_id}: since ${effect.after?.exits ?? 0} exits, ${shareLabel(effect.after?.sent_back_share)} sent back, queue ${durationLabel(effect.after?.queue_wait_p50)} \xB7 before ${effect.before?.exits ?? 0} exits, ${shareLabel(effect.before?.sent_back_share)} sent back, queue ${durationLabel(effect.before?.queue_wait_p50)}`
+          );
+        }
+      }
+    }
+    for (const line of statsLevers()) console.log(line);
+  });
   withCommon(
     supervisor.command("enable").description("Resume automation (the kill switch on)")
   ).action(async (opts) => {
@@ -12740,6 +12872,62 @@ function normalizeUrl(value) {
 }
 
 // src/commands/usage.ts
+function printEvidence(page) {
+  console.log(
+    `Usage evidence \xB7 ${page.kind} \xB7 ${page.population} \xB7 ${page.total_count} total \xB7 ${page.sort} ${page.direction}`
+  );
+  if (page.kind === "issues")
+    table([
+      ["ISSUE", "SPEND", "COVERAGE", "RUNS"],
+      ...page.items.map((item) => [
+        item.issue_ref ? `${item.issue_ref.project_name}/${item.issue_ref.number} ${item.issue_ref.title}` : item.issue_id ? `Unavailable issue (${item.issue_id})` : "Unknown issue",
+        money(item.aggregate.cost_usd),
+        item.aggregate.coverage,
+        String(item.attempt_count)
+      ])
+    ]);
+  else
+    table([
+      ["RUN", "ISSUE", "SPEND", "AT"],
+      ...page.items.map((item) => {
+        const run2 = item;
+        return [
+          run2.id,
+          run2.issue_id,
+          page.population === "pending" ? "Pending" : money(run2.usage_accounting?.cost ?? null),
+          new Date(run2.ended_at ?? run2.created_at).toISOString()
+        ];
+      })
+    ]);
+  if (page.kind === "runs" && page.population === "finalized")
+    for (const item of page.items) {
+      if ("id" in item && "usage_accounting" in item && item.usage_dimensions)
+        for (const line of usageEvidenceLines(
+          item.id,
+          item.usage_dimensions,
+          item.usage_accounting
+        ))
+          console.log(line);
+    }
+  console.log(
+    `Matching total: ${money(page.matching_total.cost_usd)} \xB7 ${page.attempt_count} attempts \xB7 ${page.pending_count} pending`
+  );
+  if (page.next_cursor) console.log(`Next cursor: ${page.next_cursor}`);
+}
+function printIssueReport(report) {
+  const { issue } = report;
+  console.log(
+    `Usage \xB7 ${issue.issue_ref ? `${issue.issue_ref.project_name}/${issue.issue_ref.number}` : issue.issue_id} \xB7 Lifetime through now`
+  );
+  console.log(`as of ${new Date(report.cutoff).toISOString()} \xB7 direct retained attempts`);
+  if (issue.attempt_count === 0) console.log("No agent runs");
+  else {
+    console.log(
+      `${money(issue.aggregate.cost_usd)} \xB7 ${issue.aggregate.coverage} \xB7 ${issue.aggregate.finalized_run_count} finalized \xB7 ${issue.pending_count} pending at cutoff`
+    );
+    for (const line of usageAggregateLines("Lifetime", issue.aggregate)) console.log(line);
+  }
+}
 var money = (value) => usageCostLabel(value);
 function printReport(report) {
   console.log(`Usage \xB7 ${report.filters.project ?? "All projects"} \xB7 ${report.by}`);
@@ -12798,7 +12986,12 @@ 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(
+    ).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([
+        "finalized",
+        "pending"
+      ])
+    ).addOption(new Option("--sort <sort>", "evidence sort").choices(["cost", "time"])).addOption(new Option("--direction <direction>", "sort direction").choices(["asc", "desc"])).option("--cursor <token>", "evidence page cursor").option("--limit <count>", "evidence page size (1-100)").option("--all-pages", "fetch every evidence page").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",
@@ -12814,7 +13007,100 @@ function register12(program3) {
     ).addOption(
       new Option("--by <dimension>", "group dimension").choices(["project", "workflow", "state", "outcome", "runner", "tier"]).default("workflow")
     )
-  ).action(async (opts) => {
+  ).action(async (opts, command) => {
+    const evidenceOnly = [
+      opts.member,
+      opts.population,
+      opts.sort,
+      opts.direction,
+      opts.cursor,
+      opts.limit,
+      opts.allPages
+    ];
+    if (evidenceOnly.some((value) => value !== void 0) && !opts.evidence)
+      throw new Error(
+        "--member/--population/--sort/--direction/--cursor/--limit/--all-pages require --evidence"
+      );
+    if (opts.evidence && !opts.scope) throw new Error("--evidence requires --scope");
+    if (opts.scope) {
+      const reportFlags = [
+        opts.issue,
+        opts.window,
+        opts.from,
+        opts.to,
+        opts.project,
+        opts.workflow,
+        opts.state,
+        opts.runner,
+        opts.tier,
+        opts.outcome,
+        opts.accountingStatus
+      ];
+      if (command.getOptionValueSource("by") === "cli") reportFlags.push(opts.by);
+      if (reportFlags.some((value) => value !== void 0))
+        throw new Error("--scope cannot be combined with report options");
+      const api2 = client(opts);
+      if (!opts.evidence) {
+        const report2 = await api2.getUsageScope(opts.scope);
+        if (opts.json) return printJson(report2);
+        if (report2.mode === "issue") printIssueReport(report2);
+        else printReport(report2);
+        return;
+      }
+      let cursor = opts.cursor;
+      const seenCursors = /* @__PURE__ */ new Set();
+      const seenIds = /* @__PURE__ */ new Set();
+      let combined = null;
+      do {
+        if (cursor && seenCursors.has(cursor))
+          throw new Error("Evidence pagination repeated a cursor");
+        if (cursor) seenCursors.add(cursor);
+        const page = await api2.getUsageEvidence({
+          scope: opts.scope,
+          kind: opts.evidence,
+          population: opts.population,
+          member: opts.member,
+          sort: opts.sort,
+          direction: opts.direction,
+          limit: opts.limit ? Number(opts.limit) : void 0,
+          cursor
+        });
+        for (const item of page.items) {
+          const id2 = "id" in item ? item.id : item.issue_id ?? "unknown";
+          if (seenIds.has(id2)) throw new Error(`Evidence pagination repeated ${id2}`);
+          seenIds.add(id2);
+        }
+        combined = combined ? { ...page, items: [...combined.items, ...page.items], previous_cursor: null } : page;
+        cursor = page.next_cursor ?? void 0;
+      } while (opts.allPages && cursor);
+      if (!combined) throw new Error("Evidence response was empty");
+      if (opts.json) return printJson(combined);
+      printEvidence(combined);
+      return;
+    }
+    if (opts.issue) {
+      const contradictions = [
+        opts.window,
+        opts.from,
+        opts.to,
+        opts.project,
+        opts.workflow,
+        opts.state,
+        opts.runner,
+        opts.tier,
+        opts.outcome,
+        opts.accountingStatus
+      ];
+      if (command.getOptionValueSource("by") === "cli") contradictions.push(opts.by);
+      if (contradictions.some((value) => value !== void 0))
+        throw new Error("--issue cannot be combined with period or filter options");
+      const api2 = client(opts);
+      const issueId = isUsageIdentity(opts.issue, "iss") ? opts.issue : (await resolveIssue(api2, opts.issue)).id;
+      const report2 = await api2.getIssueUsage(issueId);
+      if (opts.json) return printJson(report2);
+      printIssueReport(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.208",
+  "version": "0.0.210",
   "description": "CLI for Tines, an orchestration layer for AI agents",
   "repository": {
     "type": "git",