Skip to content
Python
16.7 KB
Raw Blame
// Observability Phase 3 ("learn across runs"): the pure helpers the Usage tab, the turn
// footer, the coworker page, TeamView and the Scheduled view share. Kept out of the
// components so the rules can be tested on their own (technical-design.md §7 to §12).
// Tokens only: nothing here ever turns a count into money.

/** One day as the viewer sees it: `[label, start, end)` in epoch ms (TD3-2). */
export type DayBoundary = [string, number, number];
export type Period = "today" | "7d" | "30d";

const pad = (n: number) => String(n).padStart(2, "0");
const isoLocal = (d: Date) => `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;

/** The viewer's local days of a period, oldest first, built from local midnights, so a DST
 * day is simply 23 or 25 hours long. "Today" is one day; 7 and 30 days end today. */
export function localDays(period: Period, now: Date = new Date()): DayBoundary[] {
  const n = period === "today" ? 1 : period === "7d" ? 7 : 30;
  const out: DayBoundary[] = [];
  for (let i = n - 1; i >= 0; i--) {
    const a = new Date(now.getFullYear(), now.getMonth(), now.getDate() - i);
    const b = new Date(now.getFullYear(), now.getMonth(), now.getDate() - i + 1);
    out.push([isoLocal(a), a.getTime(), b.getTime()]);
  }
  return out;
}

/** The same number of local days just before `days` (for "vs last period"). */
export function previousDays(days: DayBoundary[]): DayBoundary[] {
  if (!days.length) return [];
  const first = new Date(days[0][1]);
  const n = days.length;
  const out: DayBoundary[] = [];
  for (let i = n; i >= 1; i--) {
    const a = new Date(first.getFullYear(), first.getMonth(), first.getDate() - i);
    const b = new Date(first.getFullYear(), first.getMonth(), first.getDate() - i + 1);
    out.push([isoLocal(a), a.getTime(), b.getTime()]);
  }
  return out;
}

/** "vs last period" only when the ledger reaches back over the whole earlier period (TD3-7,
 * V3-11): never a "▲ 100%" from a period that was not kept. */
export function comparable(keptFrom: number | null | undefined, prevStart: number): boolean {
  return keptFrom != null && keptFrom <= prevStart;
}

export function changePct(now: number, before: number): number | null {
  if (!before) return null;
  return Math.round(((now - before) / before) * 100);
}

// -- tokens per day, by purpose (§7.2, M3-R4) --------------------------------------------------
export const SERIES = ["main", "summary", "auto_approver", "title", "other"] as const;
export type Series = (typeof SERIES)[number];

/** The chart's five series: main work and helpers together, summaries, the auto-approver,
 * session titles, and everything else, so a day's series add up to that day's total. */
export function seriesOf(purpose: string | null | undefined): Series {
  switch (purpose) {
    case "main":
    case "helper":
      return "main";
    case "summary":
      return "summary";
    case "auto_approver":
      return "auto_approver";
    case "title":
      return "title";
    default:
      return "other";
  }
}

export interface RollupGroup {
  key: Record<string, any>;
  total: number;
  input_fresh: number;
  cache_read: number;
  cache_write: number;
  output: number;
  calls: number;
  unreported: number;
  failed: number;
  over_limit?: number;
  turns: number;
  checked: number;
  with_warn: number;
  automation_turns?: number;
  approvals?: number;
  median_active_ms?: number | null;
}

/** `day,purpose` groups -> per day, per series, plus each series' total for the legend. */
export function purposeByDay(days: DayBoundary[], groups: RollupGroup[]) {
  const byDay = new Map<string, Record<Series, number>>();
  for (const [label] of days) byDay.set(label, { main: 0, summary: 0, auto_approver: 0, title: 0, other: 0 });
  const legend: Record<Series, number> = { main: 0, summary: 0, auto_approver: 0, title: 0, other: 0 };
  for (const g of groups) {
    const row = byDay.get(String(g.key.day));
    if (!row) continue;
    const s = seriesOf(g.key.purpose);
    row[s] += g.total;
    legend[s] += g.total;
  }
  const rows = days.map(([label]) => ({ label, values: byDay.get(label)!, total: SERIES.reduce((n, s) => n + byDay.get(label)![s], 0) }));
  return { rows, legend, max: Math.max(1, ...rows.map((r) => r.total)) };
}

/** T3-7: the same days without main work, on their own scale, so summaries, the
 * auto-approver and titles get a readable size (main work is often 95% or more). Null when
 * the period has none of them. */
export function overheadByDay(chart: ReturnType<typeof purposeByDay>) {
  const series = SERIES.filter((s) => s !== "main");
  const rows = chart.rows.map((r) => ({ ...r, values: { ...r.values, main: 0 }, total: r.total - r.values.main }));
  const max = Math.max(0, ...rows.map((r) => r.total));
  return max > 0 ? { rows, max, series } : null;
}

// -- the Auto-approve strip (§7.3, M3-R5) -----------------------------------------------------
/** Under 10 checks a part is a count ("allowed 1"), from 10 a share ("allowed 72%"): "allowed
 * 100%" of one check says nothing. */
export function approverPart(n: number, checks: number): { share: boolean; value: number } {
  if (checks >= 10) return { share: true, value: Math.round((n / checks) * 100) };
  return { share: false, value: n };
}

// -- the turn footer (§8.2, M3-R6, M3-R7) -------------------------------------------------------
export interface TurnFooter {
  turn_id: string;
  seq: number | null;
  status: string;
  first_message_id?: string | null;
  last_message_id?: string | null;
  started_at?: number;
  duration_ms: number | null;
  active_ms?: number | null;
  total: number;
  at_least: boolean;
  warn: number | null;
  auto_approved: number;
  asked: number;
  live_checks?: number;
  wake?: { reason?: string; batched?: number | null } | null;
  feedback?: TurnFeedback | null;
}

export interface TurnFeedback {
  turn_id: string;
  session_id: string;
  rating: "up" | "down";
  reasons: string[];
  rated_at: number;
  changed_at: number | null;
  content?: { note: string | null };
}

export interface FeedbackWhere {
  local: boolean;
  export: string | null;
  managed: boolean;
  by?: string | null;
  with_note: boolean;
}

export type FooterPart =
  | { kind: "time"; ms: number }
  | { kind: "tokens"; total: number; at_least: boolean }
  | { kind: "issues"; n: number }
  | { kind: "auto_approved"; n: number }
  | { kind: "asked"; n: number };

/** The footer's parts, each only when it says something: no "0 issues", no "0 asked you". */
export function footerParts(f: TurnFooter): FooterPart[] {
  const out: FooterPart[] = [];
  if (f.duration_ms != null) out.push({ kind: "time", ms: f.duration_ms });
  out.push({ kind: "tokens", total: f.total, at_least: f.at_least });
  if (f.warn) out.push({ kind: "issues", n: f.warn });
  if (f.auto_approved) out.push({ kind: "auto_approved", n: f.auto_approved });
  if (f.asked) out.push({ kind: "asked", n: f.asked });
  return out;
}

/** The turn an answer belongs to: the turn whose last message is the answer (`mid`); else by
 * the answer's time (unix seconds), the first turn not yet over a second before it, as the
 * Steps link picks it; else the answer's position among the answers. */
export function turnForAnswer(footers: TurnFooter[], ts: number | undefined, answerIndex: number, mid?: string): TurnFooter | null {
  if (!footers.length) return null;
  if (mid) {
    const byMid = footers.find((f) => f.last_message_id === mid);
    if (byMid) return byMid;
  }
  if (ts != null && footers.every((f) => f.started_at != null)) {
    const at = ts * 1000 - 1000;
    const f = footers.find((x) => x.duration_ms == null || (x.started_at as number) + x.duration_ms >= at);
    return f ?? footers[footers.length - 1];
  }
  return footers[Math.min(answerIndex, footers.length - 1)] ?? null;
}

export const REASONS = ["wrong_answer", "too_slow", "did_unasked", "did_not_finish", "other"] as const;

/** The rating card's last line: where the rating went (§8.3). */
export function whereKey(w: FeedbackWhere | null | undefined, future = false): { key: string; withNote: boolean } {
  // T3-8: before Send or Skip nothing is saved yet, so the open card says where it *will* go.
  const pre = future ? "p3.fb.will_" : "p3.fb.where_";
  if (!w || !w.export) return { key: pre + "local", withNote: false };
  if (w.managed) return { key: pre + "company", withNote: !future && !!w.with_note };
  return { key: pre + (w.export === "langfuse" ? "langfuse" : "otlp"), withNote: !future && !!w.with_note };
}

// -- wake reasons (OB-17) ----------------------------------------------------------------------
/** The i18n key of a wake reason; a review wake that the 2 s window gathered is a "review batch". */
export function wakeKey(wake: { reason?: string; batched?: number | null } | null | undefined): string | null {
  const r = wake?.reason;
  if (!r) return null;
  if (r === "review" && wake?.batched) return "p3.wake.review_batch";
  return `p3.wake.${r}`;
}

export function cacheShare(cacheRead: number, input: number): number | null {
  return input > 0 ? Math.round((cacheRead / input) * 100) : null;
}

// -- coverage (OB-16) -----------------------------------------------------------------------------
export const AREA_WORD: Record<string, string> = { code: "code", secrets: "secret", deps: "dependency", iac: "infrastructure" };

// -- run health (OB-18) -----------------------------------------------------------------------------
export type Health = "ok" | "failed" | "skipped" | "did_not_finish" | "unknown";
export function healthTone(h: string | undefined): "ok" | "err" | "muted" {
  if (h === "ok") return "ok";
  if (h === "failed" || h === "did_not_finish") return "err";
  return "muted";
}

/** Compact time-of-day for "as of 14:02". */
export function hhmm(ms: number): string {
  const d = new Date(ms);
  return `${pad(d.getHours())}:${pad(d.getMinutes())}`;
}

/** "21 Oct" */
export function shortDate(ms: number): string {
  return new Date(ms).toLocaleDateString(undefined, { day: "2-digit", month: "short" });
}

/** T3-15: when a coworker version was in use, as a person says it: "Nov 2" for one day,
 * "Nov 3 – today", "Nov 3 or earlier – today" when the ledger keeps nothing older. */
export function inUseSpan(
  first: number | null, last: number | null, beforeKept: boolean,
  t: (k: string, o?: any) => string, now = new Date(),
): string {
  if (first == null || last == null) return "—";
  const day = (ms: number) => {
    const d = new Date(ms);
    return d.toDateString() === now.toDateString()
      ? t("p3.doing.today")
      : d.toLocaleDateString(undefined, { month: "short", day: "numeric" });
  };
  const from = beforeKept ? t("p3.doing.or_earlier", { date: day(first) }) : day(first);
  const sameDay = new Date(first).toDateString() === new Date(last).toDateString();
  return sameDay && !beforeKept ? from : `${from} – ${day(last)}`;
}

// -- moving between turns in the Trace panel (T3-14) ------------------------------------------
/** A turn's part of the conversation the GUI already holds: what you asked, its answer, and
 * the tools and files its steps touched. Nothing here is fetched or sent anywhere. */
export interface TurnText {
  user: string;
  answer: string;
  tools: string[];
  files: string[];
}

type ConvItem = { kind: string; text?: string; mid?: string; name?: string; args?: any };

const FILE_KEYS = ["path", "file", "file_path", "filename", "paths", "files", "target", "dest", "source"];

function filesOf(args: any): string[] {
  if (!args || typeof args !== "object") return [];
  const out: string[] = [];
  for (const k of FILE_KEYS) {
    const v = args[k];
    if (typeof v === "string" && v) out.push(v);
    else if (Array.isArray(v)) for (const x of v) if (typeof x === "string" && x) out.push(x);
  }
  return out;
}

/** Splits the conversation at each turn's answer: a turn's part runs from just after the
 * previous turn's last message to its own (`last_message_id`, the answer's `mid`). A turn with
 * no answer yet (running, or cut off) gets what is left at the end when it is the last one. */
export function turnTexts(
  turns: { turn_id: string; first_message_id?: string | null; last_message_id?: string | null }[],
  items: ConvItem[],
): Map<string, TurnText> {
  const at = new Map<string, number>();
  items.forEach((it, i) => {
    if (it.mid) at.set(it.mid, i);
  });
  const out = new Map<string, TurnText>();
  const fill = (tid: string, from: number, to: number) => {
    const part: TurnText = { user: "", answer: "", tools: [], files: [] };
    for (const it of items.slice(from, to)) {
      if (it.kind === "user" && it.text) part.user += (part.user ? "\n" : "") + it.text;
      else if (it.kind === "assistant" && it.text) part.answer += (part.answer ? "\n" : "") + it.text;
      else if ((it.kind === "tool" || it.kind === "approval") && it.name) {
        part.tools.push(it.name);
        part.files.push(...filesOf(it.args));
      }
    }
    out.set(tid, part);
  };
  // UX-060: a turn knows the message that started it (`first_message_id`); when every turn
  // does, its part runs from there to the next turn's start. Splitting at answers (below)
  // mislabelled turns a minute apart, so it is only the fallback for older recordings.
  const starts = turns.map((tn) => (tn.first_message_id != null ? at.get(tn.first_message_id) : undefined));
  if (turns.length > 0 && starts.every((s) => s != null)) {
    turns.forEach((tn, k) => {
      const from = starts[k] as number;
      const to = k + 1 < turns.length ? (starts[k + 1] as number) : items.length;
      fill(tn.turn_id, from, Math.max(from, to));
    });
    return out;
  }
  let start = 0;
  turns.forEach((tn, k) => {
    const end = tn.last_message_id != null ? at.get(tn.last_message_id) : undefined;
    if (end != null && end >= start) {
      fill(tn.turn_id, start, end + 1);
      start = end + 1;
    } else if (k === turns.length - 1) {
      fill(tn.turn_id, start, items.length);
    }
  });
  return out;
}

export function formatDuration(ms: number | null | undefined): string {
  if (ms == null || !Number.isFinite(ms)) return "—";
  if (ms > 0 && ms < 100) return "<0.1s";
  if (ms < 10_000) return `${(ms / 1000).toFixed(1)}s`;
  if (ms < 60_000) return `${Math.round(ms / 1000)}s`;
  const m = Math.floor(ms / 60_000);
  const s = Math.round((ms % 60_000) / 1000);
  return s ? `${m}m ${s}s` : `${m}m`;
}

// -- the trace index (UX-060) -------------------------------------------------------------------
/** One row per message of yours, joined to the turn it started by the turn's
 * `first_message_id`. Rows come from the transcript alone, so a message whose turn was never
 * recorded still has one (greyed, no trace); the last one shows "Working…" while a turn runs. */
export interface TraceRow {
  n: number;
  mid?: string;
  words: string;
  turnId: string | null;
  durationMs: number | null;
  issues: number;
  working: boolean;
}

export function traceRows(
  items: { kind: string; text?: string; mid?: string }[],
  turns: { turn_id: string; first_message_id?: string | null; duration_ms: number | null; status?: string; issues?: number }[],
  running = false,
): TraceRow[] {
  const byFirst = new Map<string, (typeof turns)[number]>();
  for (const tn of turns) if (tn.first_message_id) byFirst.set(tn.first_message_id, tn);
  const users = items.filter((it) => it.kind === "user");
  // A message sent in this window has no id until the session is reopened; those pair
  // with the turns no id claimed, in order — one message, one turn.
  const claimed = new Set(users.map((it) => it.mid).filter((m): m is string => !!m && byFirst.has(m)));
  const spare = turns.filter((tn) => tn.first_message_id && !claimed.has(tn.first_message_id));
  return users.map((it, i) => {
    const tn = it.mid && byFirst.has(it.mid) ? byFirst.get(it.mid) : it.mid ? undefined : spare.shift();
    const last = i === users.length - 1;
    const working = tn ? tn.duration_ms == null && (tn.status === "running" || (last && running)) : last && running;
    return {
      n: i + 1,
      mid: it.mid,
      words: firstWords(it.text || "", 60),
      turnId: tn?.turn_id ?? null,
      durationMs: tn?.duration_ms ?? null,
      issues: tn?.issues ?? 0,
      working,
    };
  });
}

/** Whether a turn matches the list's search: its number, what you asked, the answer, tool
 * names, file names and its issues' titles, ignoring case. */
export function turnMatches(n: number, text: TurnText | undefined, issueTitles: string[], query: string): boolean {
  const q = query.trim().toLowerCase();
  if (!q) return true;
  if (/^\d+$/.test(q)) return String(n) === q;
  const hay = [text?.user, text?.answer, ...(text?.tools || []), ...(text?.files || []), ...issueTitles]
    .filter(Boolean).join("\n").toLowerCase();
  return hay.includes(q);
}

/** The first words of a message, on one line. */
export function firstWords(text: string, max = 70): string {
  const one = text.replace(/\s+/g, " ").trim();
  return one.length > max ? one.slice(0, max - 1).trimEnd() + "…" : one;
}