@staix/agent-hub 0.12.2 → 0.12.4

package/src/hub/report.ts

@@ -4,6 +4,7 @@ export interface Report {
   from?: string;
   to?: string;
   peers: Record<string, { turns: number; busyMinutes: number; tokens: number }>;
+  usage: { peers: Record<string, UsageCoverage>; totals: UsageTotals; unknownPeers: string[]; completeCoverage: boolean; estimatedUsd?: number; measuredSpendUsd?: number };
   messages: { total: number; dropped: Record<string, number>; overflow: number; undeliverable: number; perTask: number };
   overlaps: { warnings: number; pairs: number };
   /** Files one agent changed after another owner's open task had changed them (issue #32). */
@@ -12,12 +13,82 @@ export interface Report {
   quota: { readings: number; hard: number };
 }
 
+export interface UsageCoverage {
+  records: number;
+  withUsage: number;
+  withoutUsage: number;
+  inputTokens: number;
+  inputRecords: number;
+  outputTokens: number;
+  outputRecords: number;
+  cacheReadTokens: number;
+  cacheReadRecords: number;
+  cacheWriteTokens: number;
+  cacheWriteRecords: number;
+  totalTokens: number;
+  totalRecords: number;
+}
+
+export type UsageTotals = Omit<UsageCoverage, "records" | "withUsage" | "withoutUsage">;
+
+const emptyUsage = (): UsageCoverage => ({ records: 0, withUsage: 0, withoutUsage: 0, inputTokens: 0, inputRecords: 0, outputTokens: 0, outputRecords: 0, cacheReadTokens: 0, cacheReadRecords: 0, cacheWriteTokens: 0, cacheWriteRecords: 0, totalTokens: 0, totalRecords: 0 });
+
+function recordUsage(coverage: UsageCoverage, e: Extract<StampedEvent, { type: "usage" }>): void {
+  coverage.records++;
+  const fields = [e.inputTokens, e.outputTokens, e.cacheReadTokens, e.cacheWriteTokens, e.totalTokens];
+  if (fields.some((n) => typeof n === "number" && Number.isSafeInteger(n) && n >= 0)) coverage.withUsage++;
+  else coverage.withoutUsage++;
+  const add = (field: keyof UsageTotals, n: number | undefined, countField: keyof UsageTotals) => {
+    if (typeof n === "number" && Number.isSafeInteger(n) && n >= 0) {
+      coverage[field] += n;
+      coverage[countField]++;
+    }
+  };
+  add("inputTokens", e.inputTokens, "inputRecords");
+  add("outputTokens", e.outputTokens, "outputRecords");
+  add("cacheReadTokens", e.cacheReadTokens, "cacheReadRecords");
+  add("cacheWriteTokens", e.cacheWriteTokens, "cacheWriteRecords");
+  add("totalTokens", e.totalTokens, "totalRecords");
+}
+
+function finalizeUsage(report: Report): void {
+  for (const id of Object.keys(report.peers)) {
+    if (!report.usage.peers[id]) {
+      report.usage.peers[id] = emptyUsage();
+      report.usage.unknownPeers.push(id);
+    }
+  }
+  for (const p of Object.values(report.usage.peers)) {
+    const out = report.usage.totals;
+    for (const field of ["inputTokens", "inputRecords", "outputTokens", "outputRecords", "cacheReadTokens", "cacheReadRecords", "cacheWriteTokens", "cacheWriteRecords", "totalTokens", "totalRecords"] as const) out[field] += p[field];
+    if (p.withoutUsage || p.inputRecords < p.withUsage || p.outputRecords < p.withUsage || p.cacheReadRecords < p.withUsage || p.cacheWriteRecords < p.withUsage || p.totalRecords < p.withUsage) report.usage.completeCoverage = false;
+  }
+  if (report.usage.unknownPeers.length) report.usage.completeCoverage = false;
+}
+
+function formatUsage(usage: Report["usage"]): string[] {
+  const lines: string[] = [];
+  for (const [id, u] of Object.entries(usage.peers).sort(([a], [b]) => a.localeCompare(b))) {
+    const coverage = `${u.withUsage}/${u.records} records with usage`;
+    const value = (name: string, count: number, records: number) => records ? `${name} ${count} (${records} known)` : `${name} unknown (0 known)`;
+    const known = [value("input", u.inputTokens, u.inputRecords), value("output", u.outputTokens, u.outputRecords), value("cache read", u.cacheReadTokens, u.cacheReadRecords), value("cache write", u.cacheWriteTokens, u.cacheWriteRecords), value("reported total", u.totalTokens, u.totalRecords)].join(", ");
+    const incomplete = u.withoutUsage || u.inputRecords < u.withUsage || u.outputRecords < u.withUsage || u.cacheReadRecords < u.withUsage || u.cacheWriteRecords < u.withUsage || u.totalRecords < u.withUsage;
+    lines.push(`usage ${id}: ${u.records ? coverage : "no usage records"}; ${known}; coverage ${incomplete ? "incomplete" : u.records ? "complete for recorded calls" : "unknown"}`);
+  }
+  const total = usage.totals.totalRecords ? `${usage.totals.totalTokens} reported tokens (${usage.totals.totalRecords} known records)` : "reported token total unknown (0 known records)";
+  const coverage = usage.completeCoverage ? "recorded-call coverage complete" : `incomplete or unknown peer coverage${usage.unknownPeers.length ? ` (${usage.unknownPeers.join(", ")})` : ""}`;
+  lines.push(`usage team totals: ${total}; ${coverage}; estimated price unknown; measured spend unknown`);
+  return lines;
+}
+
 /** The numbers `ahub report` prints, from `events.jsonl` alone (issue #40). */
 export function summarize(events: StampedEvent[]): Report {
-  const r: Report = { peers: {}, messages: { total: 0, dropped: {}, overflow: 0, undeliverable: 0, perTask: 0 }, overlaps: { warnings: 0, pairs: 0 }, conflicts: 0, tasks: {}, quota: { readings: 0, hard: 0 } };
+  const r: Report = { peers: {}, usage: { peers: {}, totals: { inputTokens: 0, inputRecords: 0, outputTokens: 0, outputRecords: 0, cacheReadTokens: 0, cacheReadRecords: 0, cacheWriteTokens: 0, cacheWriteRecords: 0, totalTokens: 0, totalRecords: 0 }, unknownPeers: [], completeCoverage: true }, messages: { total: 0, dropped: {}, overflow: 0, undeliverable: 0, perTask: 0 }, overlaps: { warnings: 0, pairs: 0 }, conflicts: 0, tasks: {}, quota: { readings: 0, hard: 0 } };
   const peer = (id: string) => (r.peers[id] ??= { turns: 0, busyMinutes: 0, tokens: 0 });
+  const usagePeer = (id: string) => (r.usage.peers[id] ??= emptyUsage());
   const pairs = new Set<string>();
   const taskMessages = new Map<string, number>();
+  const seenUsage = new Set<string>();
   for (const e of events) {
     r.from ??= e.at;
     r.to = e.at;
@@ -31,13 +102,26 @@ export function summarize(events: StampedEvent[]): Report {
       case "undeliverable":
         r.messages[e.type]++;
         break;
+      case "stale": // published, then dropped before delivery (issue #106)
+        r.messages.dropped.stale = (r.messages.dropped.stale ?? 0) + 1;
+        break;
       case "turn_end":
         peer(e.peer).turns++;
         peer(e.peer).busyMinutes += e.ms / 60_000;
         break;
+      case "state":
+        peer(e.peer);
+        break;
       case "tokens":
         peer(e.peer).tokens += e.n;
         break;
+      case "usage": {
+        const key = `${e.peer}\0${e.source}\0${e.id}`;
+        if (seenUsage.has(key)) break;
+        seenUsage.add(key);
+        recordUsage(usagePeer(e.peer), e);
+        break;
+      }
       case "task":
         r.tasks[e.event] = (r.tasks[e.event] ?? 0) + 1;
         break;
@@ -55,6 +139,8 @@ export function summarize(events: StampedEvent[]): Report {
     }
   }
   r.overlaps.pairs = pairs.size;
+  finalizeUsage(r);
+  // Pricing is intentionally absent: a token count is neither an estimated price nor provider-reported spend.
   r.messages.perTask = taskMessages.size ? Number(([...taskMessages.values()].reduce((a, b) => a + b, 0) / taskMessages.size).toFixed(1)) : 0;
   for (const p of Object.values(r.peers)) p.busyMinutes = Number(p.busyMinutes.toFixed(1));
   return r;
@@ -63,6 +149,7 @@ export function summarize(events: StampedEvent[]): Report {
 export function formatReport(r: Report): string[] {
   const lines = [`period: ${r.from ?? "-"} .. ${r.to ?? "-"}`];
   for (const [id, p] of Object.entries(r.peers).sort(([a], [b]) => a.localeCompare(b))) lines.push(`peer ${id}: ${p.turns} turn${p.turns === 1 ? "" : "s"}, ${p.busyMinutes} busy minutes, ${p.tokens ? `${p.tokens} tokens` : id === "pi" ? "tokens not reported" : "- tokens"}`);
+  if (Object.keys(r.usage.peers).length) lines.push(...formatUsage(r.usage));
   const dropped = Object.entries(r.messages.dropped).map(([k, n]) => `${n} ${k}`).join(", ");
   lines.push(`messages: ${r.messages.total} (dropped: ${dropped || "none"}; overflow ${r.messages.overflow}; undeliverable ${r.messages.undeliverable}); ${r.messages.perTask} per task that had any`);
   lines.push(`overlap warnings: ${r.overlaps.warnings}, task pairs: ${r.overlaps.pairs}; edit conflicts: ${r.conflicts}`);

package/src/hub/routing.ts

@@ -248,3 +248,88 @@ export function assign(
   if (owner === PI) trace.push(`pi decision: backend ${piBackend ?? "dgx"}${task.signals.includes("long_context") ? `, context limit ${piBackend === "mlx" ? routing.pi.mlx_max_context_tokens : routing.pi.dgx_max_context_tokens}` : ""}`);
   return { ...(owner ? { owner } : {}), ...(pii ? { reviewer: "user" } : reviewer ? { reviewer } : {}), ...(route ? { route } : {}), fixedModel, ...(piBackend ? { piBackend } : {}), trace };
 }
+
+/**
+ * One recorded task of a peer in a class, as stage proxies (issue #109): `orient` from being handed the task to its
+ * accept (queueing included), `work` from the accept to its done. Unknown stages stay undefined, never zero.
+ */
+export interface SplitObservation {
+  outcome: "approved" | "failed";
+  orient?: number;
+  work?: number;
+}
+
+/** Everything the shadow split prediction reads; `Tasks` builds it once and `route explain` shows the same. */
+export interface SplitInput {
+  /** The pair: the peer routing would pick for the task, and the owner of the open task it overlaps. */
+  peers: [PeerId, PeerId];
+  /** Each peer's observations in this class, from this hub run only: one version, one hook profile. */
+  observations: Record<PeerId, SplitObservation[]>;
+  /** Work units of the routed task and of the one it overlaps; undefined is unknown. */
+  units: [number | undefined, number | undefined];
+  /** Other open work each peer has: a busy owner does not start from orientation plus two whole units. */
+  backlog: Record<PeerId, number>;
+  available: Record<PeerId, boolean>;
+}
+
+export interface SplitPrediction {
+  verdict: "split" | "single" | "unknown";
+  trace: string[];
+  /** The peer that would finish both units soonest on its own. */
+  single?: PeerId;
+  /** Predicted seconds: both peers one unit each, in parallel (the later of the two), and the best peer alone. */
+  splitS?: number;
+  singleS?: number;
+}
+
+/** Observations a peer needs, and the share of failures a history may hold, before a prediction is made. */
+export const SPLIT_MIN = 5;
+const SPLIT_FAILURE_SHARE = 0.3;
+
+/**
+ * Shadow split prediction (issue #109): never changes assignment. For two similar units of overlapping work, a split
+ * (each peer one unit, in parallel) finishes when the later of `o + u` does; the best single peer takes `o + 2u`. With
+ * a faster and a slower peer that is `o_s + u_s < o_f + 2u_f`. It is a model assumption (equal units, measured
+ * orientation, free coordination), not a bound, so anything that breaks it makes the prediction unknown: unequal or
+ * unknown units, a busy or unavailable peer, too few or failure-heavy records, or work times too spread out to call
+ * comparable. A difference under a tenth of the single time is inconclusive.
+ */
+export function predictSplit(input: SplitInput): SplitPrediction {
+  const trace: string[] = ["shadow split prediction (it never changes assignment):"];
+  const unknown = (why: string): SplitPrediction => ({ verdict: "unknown", trace: [...trace, `  unknown: ${why}`] });
+  const [a, b] = input.peers;
+  if (a === b) return unknown("the routed task and the one it overlaps have the same owner");
+  const [ua, ub] = input.units;
+  if (ua === undefined || ub === undefined || ua !== ub) return unknown(`work units ${ua ?? "?"} and ${ub ?? "?"}: the rule needs two equal, known units`);
+  for (const p of [a, b]) {
+    if (!input.available[p]) return unknown(`${p} is not available`);
+    if ((input.backlog[p] ?? 0) > 0) return unknown(`${p} has ${input.backlog[p]} other open task(s): it would not start from orientation plus two units`);
+  }
+  const median = (xs: number[]) => {
+    const v = [...xs].sort((x, y) => x - y);
+    return v.length % 2 ? v[(v.length - 1) / 2]! : (v[v.length / 2 - 1]! + v[v.length / 2]!) / 2;
+  };
+  const stats: Record<PeerId, { o: number; u: number }> = {};
+  for (const p of [a, b]) {
+    const all = input.observations[p] ?? [];
+    const failed = all.filter((o) => o.outcome !== "approved").length;
+    const ok = all.filter((o): o is Required<SplitObservation> => o.outcome === "approved" && o.orient !== undefined && o.work !== undefined);
+    if (ok.length < SPLIT_MIN) return unknown(`${p} has ${ok.length} measured task(s) in this hub run; ${SPLIT_MIN} are needed`);
+    if (failed / all.length > SPLIT_FAILURE_SHARE) return unknown(`${failed} of ${all.length} of ${p}'s recorded tasks failed: its successes alone would understate its time`);
+    const works = ok.map((o) => o.work).sort((x, y) => x - y);
+    const u = median(works);
+    const iqr = works[Math.floor((works.length * 3) / 4)]! - works[Math.floor(works.length / 4)]!;
+    if (u <= 0 || iqr / u > 1) return unknown(`${p}'s work times spread too widely (IQR ${Math.round(iqr / 1000)} s against a median of ${Math.round(u / 1000)} s) to call its tasks comparable units`);
+    stats[p] = { o: median(ok.map((o) => o.orient)), u };
+    trace.push(`  ${p}: orientation ${Math.round(stats[p]!.o / 1000)} s, one unit ${Math.round(u / 1000)} s (median of ${ok.length})`);
+  }
+  const single = stats[a]!.o + 2 * stats[a]!.u <= stats[b]!.o + 2 * stats[b]!.u ? a : b;
+  const s = (ms: number) => Math.round(ms / 1000);
+  const splitS = s(Math.max(stats[a]!.o + stats[a]!.u, stats[b]!.o + stats[b]!.u));
+  const singleS = s(stats[single]!.o + 2 * stats[single]!.u);
+  trace.push(`  split: ${splitS} s (${a} ${s(stats[a]!.o + stats[a]!.u)} s, ${b} ${s(stats[b]!.o + stats[b]!.u)} s for one unit each); ${single} alone: ${singleS} s for two`);
+  if (Math.abs(splitS - singleS) < singleS / 10) return { ...unknown("the difference is under a tenth of the single time: inconclusive"), single, splitS, singleS };
+  const verdict = splitS < singleS ? "split" : "single";
+  trace.push(verdict === "split" ? "  a split would finish sooner" : `  ${single} alone would finish sooner`);
+  return { verdict, trace, single, splitS, singleS };
+}