@hienlh/ppm 0.23.6 → 0.23.7

package/src/services/system-services/systemd-collector.ts

@@ -0,0 +1,203 @@
+/**
+ * The Services page's backend: TWO `systemctl` spawns for a whole scope's list,
+ * one more for a unit's details, one `journalctl` for its log.
+ *
+ * Two traps, both found against a real host and both load-bearing:
+ *
+ *  - A unit name may begin with a dash. The root mount is literally `-.mount`,
+ *    so every call that takes unit names passes them after `--`, or systemctl
+ *    reads the name as an option bundle and the whole call fails.
+ *  - An action without `--no-ask-password` can BLOCK on a polkit prompt nobody
+ *    can answer, turning "stop this unit" into a wedged request until the
+ *    timeout. PPM is not root, so a system-scope action is expected to be
+ *    refused by systemd; it must be refused quickly and reported plainly.
+ */
+import type {
+  ServiceAction, ServiceActionResult, ServiceDetails, ServiceInfo, ServiceLogLine,
+  ServiceScope, ServicesSnapshot,
+} from "../../types/system-services.ts";
+import type { RunResult, Runner } from "../host-info/spawn-runner.ts";
+import { defaultRunner } from "../host-info/spawn-runner.ts";
+import { realLinuxFs } from "../system-metrics/linux-fs.ts";
+import {
+  keepUnit, parseJournalJson, parseListUnits, parseShowBlock, parseShowRecords,
+  SHOW_DETAIL_PROPERTIES, SHOW_PROPERTIES, toServiceInfo, type ListUnitsRow,
+} from "./systemd-parse.ts";
+import { checkServiceActionAllowed, serviceRefusals, type ServiceGuardContext } from "./service-guard.ts";
+
+export const SYSTEMCTL_TIMEOUT_MS = 10_000;
+/** An action may legitimately take a while; a stop waits for the unit to settle. */
+export const ACTION_TIMEOUT_MS = 20_000;
+export const MAX_LOG_LINES = 200;
+
+export const SCOPES: readonly ServiceScope[] = ["system", "user"];
+
+export function systemctlArgv(scope: ServiceScope, args: readonly string[]): string[] {
+  return scope === "user" ? ["systemctl", "--user", ...args] : ["systemctl", ...args];
+}
+
+/** `--unit=<name>` rather than `--unit <name>`: see the dash trap above. */
+export function journalctlArgv(scope: ServiceScope, unit: string, lines: number): string[] {
+  const argv = ["journalctl"];
+  if (scope === "user") argv.push("--user");
+  argv.push(
+    `--unit=${unit}`, "--boot", `--lines=${lines}`,
+    "--no-pager", "--output=json", "--output-fields=MESSAGE",
+  );
+  return argv;
+}
+
+export interface SystemdDeps {
+  run: Runner;
+  guard: ServiceGuardContext;
+}
+
+/** Attaches the refusals this unit carries, from the same function the action
+ *  route enforces — so a greyed-out button and a 403 cannot disagree. */
+export function withRefusals(info: ServiceInfo, guard: ServiceGuardContext): ServiceInfo {
+  const refused = serviceRefusals(info.unit, info.scope, guard);
+  return Object.keys(refused).length > 0 ? { ...info, refused } : info;
+}
+
+export function failureText(result: RunResult): string {
+  if (result.timedOut) return "timed out";
+  return result.stderr.trim() || result.stdout.trim() || `exited ${result.code}`;
+}
+
+export interface ScopeListing {
+  services: ServiceInfo[];
+  warnings: string[];
+  /** False when this manager did not answer at all (no systemd, no user bus). */
+  ok: boolean;
+}
+
+export async function listScope(scope: ServiceScope, deps: SystemdDeps): Promise<ScopeListing> {
+  const list = await deps.run(systemctlArgv(scope, [
+    "list-units", "--type=service,socket,mount", "--all", "--no-legend", "--plain", "--no-pager",
+  ]), SYSTEMCTL_TIMEOUT_MS);
+  if (list.timedOut || list.code !== 0) {
+    return { services: [], warnings: [`${scope} services unavailable: ${failureText(list)}`], ok: false };
+  }
+
+  const rows = parseListUnits(list.stdout).filter(keepUnit);
+  if (rows.length === 0) return { services: [], warnings: [], ok: true };
+
+  const show = await deps.run(systemctlArgv(scope, [
+    "show", `--property=${SHOW_PROPERTIES.join(",")}`, "--no-pager", "--", ...rows.map((r) => r.unit),
+  ]), SYSTEMCTL_TIMEOUT_MS);
+
+  const warnings: string[] = [];
+  let byId = new Map<string, Record<string, string>>();
+  if (show.timedOut || show.code !== 0) {
+    // The list still stands: LOAD/ACTIVE/SUB came from `list-units`. Only the
+    // unit-file state and the main pid are lost, so the page degrades rather
+    // than emptying.
+    warnings.push(`${scope} service details unavailable: ${failureText(show)}`);
+  } else {
+    byId = parseShowRecords(show.stdout);
+  }
+
+  const services = rows.map((row) => withRefusals(toServiceInfo(row, scope, byId.get(row.unit)), deps.guard));
+  return { services, warnings, ok: true };
+}
+
+export async function collectServices(deps: SystemdDeps): Promise<ServicesSnapshot> {
+  const listings = await Promise.all(SCOPES.map((scope) => listScope(scope, deps)));
+  return {
+    // Either manager answering is enough: a container commonly has the system
+    // one and no user session, and a headless server the other way round.
+    supported: listings.some((l) => l.ok),
+    services: listings.flatMap((l) => l.services),
+    warnings: listings.flatMap((l) => l.warnings),
+  };
+}
+
+export async function serviceLogs(
+  unit: string,
+  scope: ServiceScope,
+  deps: SystemdDeps,
+  lines: number = MAX_LOG_LINES,
+): Promise<ServiceLogLine[]> {
+  const result = await deps.run(journalctlArgv(scope, unit, lines), SYSTEMCTL_TIMEOUT_MS);
+  // Not gated on the exit code: journalctl exits non-zero for a unit with no
+  // entries this boot while still being perfectly healthy.
+  if (result.timedOut || !result.stdout.trim()) return [];
+  return parseJournalJson(result.stdout);
+}
+
+/** Null when the unit does not exist — the route turns that into a 404. */
+export async function serviceDetails(
+  unit: string,
+  scope: ServiceScope,
+  deps: SystemdDeps,
+): Promise<ServiceDetails | null> {
+  const show = await deps.run(systemctlArgv(scope, [
+    "show", `--property=${SHOW_DETAIL_PROPERTIES.join(",")}`, "--no-pager", "--", unit,
+  ]), SYSTEMCTL_TIMEOUT_MS);
+  if (show.timedOut || show.code !== 0) return null;
+
+  const record = parseShowBlock(show.stdout);
+  // `show` answers for a unit it has never heard of too, with LoadState=not-found
+  // and every other field blank. That is a 404, not a unit with no description.
+  if (!record.Id || record.LoadState === "not-found") return null;
+
+  const row: ListUnitsRow = {
+    unit: record.Id,
+    loadState: record.LoadState ?? "",
+    activeState: record.ActiveState ?? "",
+    subState: record.SubState ?? "",
+    description: record.Description ?? "",
+  };
+  const info = withRefusals(toServiceInfo(row, scope, record), deps.guard);
+  return {
+    ...info,
+    user: record.User || null,
+    group: record.Group || null,
+    fragmentPath: record.FragmentPath || null,
+    logs: await serviceLogs(record.Id, scope, deps),
+  };
+}
+
+/** Thrown when PPM's own guard refuses; the route maps it to 403, not 500. */
+export class ServiceActionRefused extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ServiceActionRefused";
+  }
+}
+
+export function actionFailureText(result: RunResult, scope: ServiceScope): string {
+  const text = failureText(result);
+  if (/interactive authentication required/i.test(text)) {
+    return scope === "system"
+      ? "systemd refused: PPM does not run as root, so system units cannot be changed from here"
+      : "systemd refused: this action needs an authentication PPM cannot provide";
+  }
+  return text;
+}
+
+export async function runServiceAction(
+  unit: string,
+  scope: ServiceScope,
+  action: ServiceAction,
+  deps: SystemdDeps,
+): Promise<ServiceActionResult> {
+  const verdict = checkServiceActionAllowed(unit, scope, action, deps.guard);
+  if (!verdict.allowed) throw new ServiceActionRefused(verdict.reason ?? "Refused");
+
+  const result = await deps.run(
+    systemctlArgv(scope, ["--no-ask-password", action, "--no-pager", "--", unit]),
+    ACTION_TIMEOUT_MS,
+  );
+  if (result.timedOut || result.code !== 0) throw new Error(actionFailureText(result, scope));
+  return { unit, scope, action };
+}
+
+/** PPM's own cgroup, which is what the guard derives its refusals from. */
+export function readSelfCgroup(): string | null {
+  return realLinuxFs.read("/proc/self/cgroup");
+}
+
+export function createSystemdServices(run: Runner = defaultRunner): SystemdDeps {
+  return { run, guard: { selfCgroup: readSelfCgroup() } };
+}

package/src/services/system-services/systemd-parse.ts

@@ -0,0 +1,162 @@
+/**
+ * Pure parsers for systemd's text output - Mission Center's Services page, read
+ * through `systemctl` instead of D-Bus.
+ *
+ * MC talks to org.freedesktop.systemd1 over zbus. PPM has no D-Bus client in Bun,
+ * and shelling out is not the compromise it looks like: `list-units` plus ONE
+ * multi-unit `show` covers all 239 units on this host in 6 ms total, against MC's
+ * property read per unit. What is lost is change signalling, so the page polls
+ * (SERVICES_POLL_INTERVAL_MS) rather than subscribing.
+ *
+ * Mission Center also reads `list-unit-files` for the enabled flag. That call
+ * alone measured 322 ms here and `show` already answers UnitFileState for every
+ * unit that has one - the 26 units it leaves empty have no unit file at all, so
+ * the file list would not know them either. It is not made.
+ *
+ * Nothing here spawns anything; every function takes the captured stdout.
+ */
+import type { ServiceInfo, ServiceLogLine, ServiceScope } from "../../types/system-services.ts";
+
+/** Mission Center lists exactly these three unit types and ignores the rest. */
+export const LISTED_SUFFIXES: readonly string[] = [".service", ".socket", ".mount"];
+
+export function isListedUnit(name: string): boolean {
+  return LISTED_SUFFIXES.some((s) => name.endsWith(s));
+}
+
+export interface ListUnitsRow {
+  unit: string;
+  loadState: string;
+  activeState: string;
+  subState: string;
+  description: string;
+}
+
+/**
+ * `systemctl list-units --plain --no-legend` gives UNIT LOAD ACTIVE SUB DESCRIPTION.
+ *
+ * The `--plain` flag is supposed to drop the leading status bullet, but a failed
+ * unit is still marked in some versions, so it is stripped defensively - an
+ * unstripped bullet would shift every column by one and rename every unit.
+ */
+export function parseListUnits(stdout: string): ListUnitsRow[] {
+  const rows: ListUnitsRow[] = [];
+  for (const line of stdout.split("\n")) {
+    const cleaned = line.trim().replace(/^[●○×→*]\s+/, "");
+    if (!cleaned) continue;
+    const parts = cleaned.split(/\s+/);
+    if (parts.length < 4) continue;
+    const [unit, loadState, activeState, subState] = parts as [string, string, string, string];
+    rows.push({ unit, loadState, activeState, subState, description: parts.slice(4).join(" ") });
+  }
+  return rows;
+}
+
+/** One Key=Value block from `systemctl show`. A value may itself contain "=". */
+export function parseShowBlock(block: string): Record<string, string> {
+  const record: Record<string, string> = {};
+  for (const line of block.split("\n")) {
+    const eq = line.indexOf("=");
+    if (eq <= 0) continue;
+    record[line.slice(0, eq)] = line.slice(eq + 1);
+  }
+  return record;
+}
+
+/**
+ * A multi-unit `show` writes one block per unit separated by a blank line. Keyed
+ * by Id rather than by position: `show` answers under the unit's CANONICAL name,
+ * so asking about an alias comes back under a different one, and a positional
+ * read would attach every later unit's figures to the wrong row.
+ */
+export function parseShowRecords(stdout: string): Map<string, Record<string, string>> {
+  const byId = new Map<string, Record<string, string>>();
+  for (const block of stdout.split(/\n[ \t]*\n/)) {
+    const record = parseShowBlock(block);
+    if (record.Id) byId.set(record.Id, record);
+  }
+  return byId;
+}
+
+/** Properties one `show` call must ask for to fill a ServiceInfo. */
+export const SHOW_PROPERTIES: readonly string[] = [
+  "Id", "Description", "LoadState", "ActiveState", "SubState", "UnitFileState", "MainPID",
+];
+
+/** Everything a details pane adds on top of a list row. */
+export const SHOW_DETAIL_PROPERTIES: readonly string[] = [
+  ...SHOW_PROPERTIES, "User", "Group", "FragmentPath",
+];
+
+/**
+ * Mission Center's three booleans, derived exactly as it does: ActiveState
+ * "active" is running, "failed" is failed, and enabled is the unit-file state
+ * being the literal string "enabled" - static, indirect, alias, generated and
+ * masked all count as not enabled.
+ */
+export function toServiceInfo(
+  row: ListUnitsRow,
+  scope: ServiceScope,
+  show: Record<string, string> | undefined,
+): ServiceInfo {
+  const activeState = show?.ActiveState || row.activeState;
+  const subState = show?.SubState || row.subState;
+  // An empty UnitFileState means the unit has no unit file, which is null rather
+  // than a state of "".
+  const fileState = show?.UnitFileState ?? "";
+  const mainPid = Number(show?.MainPID ?? "0");
+  return {
+    unit: row.unit,
+    scope,
+    description: row.description || show?.Description || "",
+    activeState,
+    subState,
+    unitFileState: fileState || null,
+    running: activeState === "active",
+    failed: activeState === "failed",
+    enabled: fileState === "enabled",
+    mainPid: Number.isFinite(mainPid) && mainPid > 0 ? mainPid : null,
+  };
+}
+
+/** Drops what Mission Center drops: the wrong unit type, and a name systemd knows
+ *  with no file behind it. Masked units deliberately stay in the list. */
+export function keepUnit(row: ListUnitsRow): boolean {
+  return isListedUnit(row.unit) && row.loadState !== "not-found";
+}
+
+/**
+ * `journalctl -o json`, one JSON object per line.
+ *
+ * The short-iso form would be shorter to parse and is wrong: a multi-line message
+ * - a stack trace, a core dump report - prints as continuation lines with no
+ * timestamp, so each would become its own bogus entry. The JSON form keeps one
+ * record per entry whatever is in it.
+ */
+export function parseJournalJson(stdout: string): ServiceLogLine[] {
+  const lines: ServiceLogLine[] = [];
+  for (const raw of stdout.split("\n")) {
+    if (!raw.trim()) continue;
+    let record: Record<string, unknown>;
+    try {
+      record = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      continue;
+    }
+    const message = journalMessage(record.MESSAGE);
+    if (message === null) continue;
+    const micros = Number(record.__REALTIME_TIMESTAMP);
+    lines.push({ ts: Number.isFinite(micros) ? Math.round(micros / 1000) : 0, message });
+  }
+  return lines;
+}
+
+/** journald keeps a message that is not valid UTF-8 as an array of byte values. */
+export function journalMessage(value: unknown): string | null {
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) {
+    const bytes = value.filter((n): n is number => typeof n === "number" && n >= 0 && n <= 255);
+    return new TextDecoder().decode(Uint8Array.from(bytes));
+  }
+  return null;
+}

package/src/shared/prompt-cache-idle.ts

@@ -0,0 +1,197 @@
+/**
+ * Whether a session has sat idle long enough that its prompt cache is gone.
+ *
+ * The cost of a turn is dominated by the replayed transcript, and that replay is cheap only
+ * while the prefix behind it is still cached (see `turn-usage.ts`). The cache is the one
+ * part of that with a clock on it: it lapses on its own, silently, some time after the last
+ * turn — so the first message of the next morning costs several times what the last message
+ * of the night before did, for no reason visible in the conversation.
+ *
+ * `TurnCostWarning` reports that after the fact, on the turn that paid. This says it
+ * *before*, while the user can still decide whether to carry on in this chat or start a
+ * cheaper one. Pure and shared so the threshold is the same one the warning already uses.
+ */
+
+import { PREFIX_WARN_TOKENS } from "./turn-usage.ts";
+
+/**
+ * What the server knows about a session's cache.
+ *
+ * `ttlMs` alone is the state of a session that has not completed a turn yet — it is a
+ * property of the install, not of the conversation, and sending it early is what lets a
+ * long-lived tab arm this notice from its own turns without waiting for a reconnect.
+ */
+export interface PromptCacheState {
+  /** This install's cache lifetime: an hour on a subscription, five minutes on an API key. */
+  ttlMs: number;
+  /** When the last turn completed — the moment the cache was last written. */
+  lastTurnEndedAt?: number;
+  /**
+   * Cached prefix *billed* on the last turn — a running session total, not a transcript size.
+   *
+   * The SDK sums `modelUsage` across a streaming session, so a long chat reports tens of
+   * millions against a context window of one. It is a usable floor for "has this session
+   * cached anything worth losing" and nothing more; never show it as a number.
+   */
+  billedPrefixTokens?: number;
+  /**
+   * Context the last turn actually held — the figure that may be displayed.
+   *
+   * Measured from one API call's own `usage` rather than summed (see
+   * `TurnUsage.contextTokens`). Absent for a turn recorded before PPM measured this, so the
+   * notice has to read correctly without it.
+   */
+  contextTokens?: number;
+  /**
+   * When this session was compacted, if it has been since its last cache write.
+   *
+   * A compaction replaces the conversation with a summary, so the cached prefix no longer
+   * matches anything that will be sent — the cache is gone regardless of how recently it was
+   * written. Cleared again by the first API call after the boundary, which caches the new
+   * prefix; it therefore only survives a compaction that nothing followed, which is exactly
+   * the `/compact` the user is about to type into.
+   */
+  compactedAt?: number;
+}
+
+/** Why a session's cache is gone. */
+export type ColdReason = "expired" | "compacted";
+
+export interface IdleCacheNotice {
+  /** How long since the last turn, or since the compaction, for the wording. */
+  idleMs: number;
+  reason: ColdReason;
+  /**
+   * Transcript that the next message re-sends, when PPM measured it.
+   *
+   * Never set for a compaction: what will be re-cached then is the summary the compaction
+   * produced, which no API call has reported a size for yet. Claude Code hardcodes the same
+   * `undefined` for that branch.
+   */
+  contextTokens?: number;
+}
+
+/**
+ * The notice to show, or null for nothing worth saying.
+ *
+ * Silent in three cases, all of them deliberate. Before the TTL, because the cache really is
+ * still warm and a countdown to a cost that has not happened is just noise. Below
+ * `PREFIX_WARN_TOKENS`, because a session that has never billed even that much has nothing
+ * worth warning about — the same floor the after-the-fact warning uses, so the two cannot
+ * disagree about what is worth mentioning. And with no state at all, because "PPM has not
+ * measured this" and "this session has nothing cached" must not be reported as the same thing.
+ */
+export function idleCacheNotice(
+  state: PromptCacheState | null | undefined,
+  now: number,
+): IdleCacheNotice | null {
+  const status = promptCacheStatus(state, now);
+  if (status.kind !== "cold") return null;
+  return {
+    idleMs: status.idleMs,
+    reason: status.reason,
+    ...(status.contextTokens != null && { contextTokens: status.contextTokens }),
+  };
+}
+
+/**
+ * The cache's clock, for a countdown that is on screen the whole time.
+ *
+ * Same three gates as the notice, deliberately: a chip that turns red at the hour while no
+ * banner appears — or the reverse — asks the user to reconcile two readings of one fact.
+ * `unknown` means PPM has not measured this session, which must render as nothing rather
+ * than as a full or empty timer.
+ */
+export type PromptCacheStatus =
+  | { kind: "unknown" }
+  | { kind: "warm"; remainingMs: number }
+  | { kind: "cold"; reason: ColdReason; idleMs: number; contextTokens?: number };
+
+export function promptCacheStatus(
+  state: PromptCacheState | null | undefined,
+  now: number,
+): PromptCacheStatus {
+  if (!state) return { kind: "unknown" };
+
+  // Before every other question, including whether anything has been measured at all. A
+  // compaction does not make the cache *stale*, it makes it inapplicable — the prefix it
+  // holds is not the conversation any more — so a turn that finished ten seconds ago is
+  // still cold. Ordered exactly as Claude Code orders it, and it also settles the floor
+  // below: a session large enough to have been compacted is never a trivial one.
+  if (state.compactedAt != null) {
+    return { kind: "cold", reason: "compacted", idleMs: Math.max(0, now - state.compactedAt) };
+  }
+
+  // No completed turn means nothing has been cached, so there is nothing to lose yet.
+  if (state.lastTurnEndedAt == null || state.billedPrefixTokens == null) return { kind: "unknown" };
+  if (state.billedPrefixTokens < PREFIX_WARN_TOKENS) return { kind: "unknown" };
+
+  const idleMs = now - state.lastTurnEndedAt;
+  // A clock that disagrees between server and browser can make this negative; a turn that
+  // just finished is the warmest case there is, so it reads as "not idle" either way.
+  if (idleMs < state.ttlMs) {
+    // Clamped, so a skewed clock shows a full window rather than one longer than the TTL.
+    return { kind: "warm", remainingMs: Math.min(state.ttlMs, state.ttlMs - idleMs) };
+  }
+
+  return {
+    kind: "cold",
+    reason: "expired",
+    idleMs,
+    ...(state.contextTokens != null && { contextTokens: state.contextTokens }),
+  };
+}
+
+const MINUTE_MS = 60_000;
+const HOUR_MS = 60 * MINUTE_MS;
+const DAY_MS = 24 * HOUR_MS;
+
+/**
+ * How long the session has been idle, at the coarsest unit that still says something.
+ *
+ * Minutes are dropped past a day: "2d 7h 13m" is three figures to answer "is this stale",
+ * which is the only question being asked.
+ */
+export function formatIdleDuration(ms: number): string {
+  if (ms >= DAY_MS) {
+    const days = Math.floor(ms / DAY_MS);
+    const hours = Math.floor((ms % DAY_MS) / HOUR_MS);
+    return hours > 0 ? `${days}d ${hours}h` : `${days}d`;
+  }
+  if (ms >= HOUR_MS) {
+    const hours = Math.floor(ms / HOUR_MS);
+    const minutes = Math.floor((ms % HOUR_MS) / MINUTE_MS);
+    return minutes > 0 ? `${hours}h ${minutes}m` : `${hours}h`;
+  }
+  return `${Math.max(1, Math.floor(ms / MINUTE_MS))}m`;
+}
+
+/**
+ * Time left on the cache, for the composer's countdown chip.
+ *
+ * Rounded **up**, so a fresh turn reads the install's whole window (`60m`, not `59m`) and the
+ * last partial minute reads `1m` rather than `0m` — a zero here would say expired while the
+ * cache is still warm, which is the one reading the chip must never give.
+ *
+ * Minutes throughout, with no hours branch: the longest window PPM has is the subscription's
+ * hour, so the only thing an hours branch could ever render is the full window as `1h` — one
+ * more unit for the eye to parse, in the single case the chip is least interesting.
+ */
+export function formatCacheCountdown(ms: number): string {
+  return `${Math.max(1, Math.ceil(ms / MINUTE_MS))}m`;
+}
+
+/**
+ * A measured context size, at the precision the decision needs.
+ *
+ * Whole thousands: the user is deciding whether to carry on in this chat or start a fresh
+ * one, and no part of that turns on the difference between 58.7k and 59k.
+ */
+export function formatContextTokens(tokens: number): string {
+  if (tokens >= 1_000_000) {
+    const millions = tokens / 1_000_000;
+    return `${millions >= 10 ? Math.round(millions) : millions.toFixed(1)}M`;
+  }
+  if (tokens >= 1_000) return `${Math.round(tokens / 1_000)}k`;
+  return `${tokens}`;
+}

package/src/shared/turn-usage.ts

@@ -46,6 +46,36 @@ export interface TurnUsage {
    */
   accountId?: string;
   accountLabel?: string;
+  /**
+   * Live context held at the end of the turn — what the next message actually replays.
+   *
+   * Not derivable from anything else on this type. Every other field here is summed out of
+   * the result's `modelUsage`, which the SDK accumulates across a streaming session and
+   * across subagents: one measured session reported 55.9M prefix tokens against a 200k
+   * window, and per-turn deltas fare no better (one turn's delta was 4.2M — twenty-one
+   * windows — because twenty subagents each replayed their own prefix into the same sum).
+   *
+   * This comes instead from the `usage` on the turn's last top-level assistant message,
+   * which is one API call's own input side and so is a real context size. Absent when no
+   * such message carried usage; never substitute a summed figure for it.
+   */
+  contextTokens?: number;
+  /**
+   * Cache window the API reported for this turn, when it reported one.
+   *
+   * Outranks the provider's credential-shaped guess wherever both exist — see
+   * `messageCacheTtl`. Absent on a turn that only read the cache, and on every turn recorded
+   * before PPM read this field.
+   */
+  cacheTtlMs?: number;
+  /**
+   * When a compaction invalidated this session's cache, if one did and nothing re-cached after.
+   *
+   * Not a timestamp of "the last compaction" — the provider clears it on the next API call,
+   * so an auto-compact mid-turn never reaches here. What survives is a compaction the turn
+   * ended on, which is the case where the user's next message pays to rebuild the prefix.
+   */
+  compactedAt?: number;
 }
 
 /** Total prefix replayed to the API this turn, cached or not. */
@@ -66,7 +96,7 @@ export function uncachedPrefixTokens(u: TurnUsage): number {
  */
 export function buildTurnUsage(
   modelUsage: Record<string, ModelUsageLike> | undefined,
-  opts: { coldReason?: string; accountId?: string; accountLabel?: string } = {},
+  opts: { coldReason?: string; accountId?: string; accountLabel?: string; contextTokens?: number; cacheTtlMs?: number; compactedAt?: number } = {},
 ): TurnUsage | undefined {
   if (!modelUsage) return undefined;
   const entries = Object.entries(modelUsage);
@@ -113,9 +143,63 @@ export function buildTurnUsage(
     ...(opts.coldReason && { coldReason: opts.coldReason }),
     ...(opts.accountId && { accountId: opts.accountId }),
     ...(opts.accountLabel && { accountLabel: opts.accountLabel }),
+    ...(opts.contextTokens != null && { contextTokens: opts.contextTokens }),
+    ...(opts.cacheTtlMs != null && { cacheTtlMs: opts.cacheTtlMs }),
+    ...(opts.compactedAt != null && { compactedAt: opts.compactedAt }),
   };
 }
 
+/**
+ * Context size carried by one assistant message's `usage`, or undefined if it carried none.
+ *
+ * The input side of a single API call: what the model was actually given, whether it arrived
+ * fresh or out of the cache. Output tokens are excluded — they are not in the context the
+ * *next* call replays until they have been written back as a message, and counting them here
+ * would inflate every turn by its own answer.
+ */
+export function messageContextTokens(usage: unknown): number | undefined {
+  if (!usage || typeof usage !== "object") return undefined;
+  const u = usage as Record<string, unknown>;
+  const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+  const total = num(u.input_tokens) + num(u.cache_read_input_tokens) + num(u.cache_creation_input_tokens);
+  // Zero is not a context, it is a frame that carried no input side — a usage object with
+  // only output tokens, say. Returning it would render as "re-sends about 0 tokens" on a
+  // full session. Matches Claude Code's own reader, which likewise sums all three fields
+  // without requiring any one of them and rejects a zero total.
+  return total > 0 ? total : undefined;
+}
+
+/** Which prompt-cache window the API wrote this turn's prefix into. */
+export type PromptCacheTtl = "1h" | "5m";
+
+/**
+ * The cache lifetime the API itself reports, or undefined when it reported none.
+ *
+ * PPM otherwise *infers* this from the credential — an `sk-ant-oat` token means a
+ * subscription and therefore an hour, anything else five minutes — which is a guess about
+ * billing made from the shape of a string. It is wrong for a proxy, for a custom `base_url`,
+ * and for a subscription past its usage limits, and being wrong is not cosmetic: the
+ * countdown and the idle banner both measure against this, so a session whose cache really
+ * lives an hour is declared cold at minute five.
+ *
+ * `usage.cache_creation` answers it outright. Mirrors Claude Code's own reader, including
+ * the order: a prefix written into both windows is reported as the longer one, because that
+ * is the one still standing. Returns the discriminant rather than milliseconds so this stays
+ * free of the server's constants — `shared/` is imported by the browser bundle.
+ */
+export function messageCacheTtl(usage: unknown): PromptCacheTtl | undefined {
+  if (!usage || typeof usage !== "object") return undefined;
+  const cc = (usage as { cache_creation?: unknown }).cache_creation;
+  if (!cc || typeof cc !== "object") return undefined;
+  const c = cc as Record<string, unknown>;
+  const num = (v: unknown): number => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+  if (num(c.ephemeral_1h_input_tokens) > 0) return "1h";
+  if (num(c.ephemeral_5m_input_tokens) > 0) return "5m";
+  // A turn that only *read* the cache writes nothing, so it names no window. That is silence,
+  // not five minutes: answering the short one here would expire a warm hour-long cache.
+  return undefined;
+}
+
 /**
  * A prefix smaller than this is cheap however it is billed, so a poor hit rate on it is not
  * worth interrupting the user over. Short sessions legitimately start cold.