Python
// 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;
}