@yunazgr/pi-companion 0.2.4 → 0.2.6

package/README.md

@@ -13,7 +13,7 @@ The UI is a static SvelteKit application. There is no Node runtime in production
   <img src="docs/mobile.webp" alt="Session detail on a phone" width="28%" />
 </p>
 
-Screenshots use demo sessions, not private conversation data. See the [session menu](docs/session-menu.webp), [desktop session rows](docs/session-list-desktop.webp) and [mobile session list](docs/session-list.webp), plus [attachment previews](docs/attachments.webp), [file-grouped changes](docs/changes.webp) and [connection recovery](docs/connection-error.webp).
+Screenshots use demo sessions, not private conversation data, and are regenerated with `node tools/screenshots.mjs` (see [Running locally from source](#running-locally-from-source)). See the [session menu](docs/session-menu.webp), [desktop session rows](docs/session-list-desktop.webp) and [mobile session list](docs/session-list.webp), plus [attachment previews](docs/attachments.webp), [file-grouped changes](docs/changes.webp) and [connection recovery](docs/connection-error.webp).
 
 ## Install
 
@@ -115,6 +115,7 @@ Optional environment variables (none are required):
 | PI_COMPANION_AUTOSTART=0 | never launch a daemon, only connect |
 | PI_COMPANION_PUBLIC_URL | daemon-side: public URL embedded in pairing QR codes |
 | PI_COMPANION_ALLOWED_ORIGINS | daemon-side: extra comma-separated browser origins accepted besides the loopback addresses and the public URL |
+| PI_COMPANION_ADMIN_ADDR, PI_COMPANION_DEVICE_ADDR | daemon-side: loopback listen addresses (default `127.0.0.1:43721` / `127.0.0.1:43722`), for running a second daemon next to the usual one, e.g. for screenshots. The extension still looks for 43721 unless `PI_COMPANION_URL` points elsewhere |
 
 Local admin:
 
@@ -148,6 +149,16 @@ Pi's `companion_ask_user` tool asks one to four questions at once. Each question
 
 Dialogs from other extensions (`ctx.ui.select`, `ctx.ui.confirm`, `ctx.ui.input`) are relayed to the same sheet while the terminal dialog stays open: whichever side answers first wins and the other closes. Question tools that draw their own `ctx.ui.custom` picker are relayed through a small adapter: pi-jar's `jar_ask` is supported, and a companion answer completes its terminal picker. Other `ctx.ui.custom` components and `ctx.ui.editor` stay terminal-only because they cannot be answered from outside. Pending questions are part of the session snapshot, so a browser that connects later still sees them.
 
+## Notifications, camera and catching up
+
+Settings → **Notifications and camera** (on every device, not just the console) asks the browser for both permissions from a tap, as browsers require, and shows whether each is allowed, blocked or unavailable. Overview also offers a one-time "Turn on notifications" banner.
+
+With notifications on, the device gets a system notification (through the service worker, so it works for installed apps and Android) when Pi asks a question, finishes a turn or a session ends. Tapping it opens that session. Nothing is sent while you are already looking at that session. iPhone and iPad only allow web notifications from an app added to the Home Screen. The camera is used only for the pairing QR scanner. Camera access requires HTTPS or localhost; plain HTTP LAN/phone links cannot prompt. After upgrading, restart the daemon and reload the app to refresh cached camera policies. Settings distinguishes browser denial, page/proxy policy blocks and transient camera errors, with retry or manual-code pairing guidance.
+
+Activity no longer lives only in the open tab. The daemon keeps a bounded, in-memory log of each session's recent feed (streamed text is merged, up to 800 entries) at `GET /api/sessions/{id}/activity` on both surfaces (paired devices: shared sessions only). The UI rebuilds the feed from it when a session opens and after every reconnect or resync, so a phone that slept, dropped its connection or was closed catches up without sending a new message. Prompts, steers and answers from any device are added to that log too. The log is cleared when the daemon restarts or the session is archived.
+
+Attaching files uses plain HTTP, so it keeps working while the live socket is reconnecting (common right after a phone's file picker closes); only a deliberate disconnect or revoked access blocks it.
+
 ## Pairing and devices
 
 Pairing is daemon-wide rather than session-specific. Everything lives on the **Devices** page of the local console (port 43721):
@@ -167,11 +178,37 @@ Paired devices (name, browser user agent, pairing and last-seen times, credentia
 
 A phone pairs once with the daemon. Individual Pi sessions still opt in using /companion.
 
-Network loss and daemon restarts reconnect automatically with bounded backoff. Heartbeats detect silent connections, and returning to the foreground or restoring network access retries immediately. Pairing credentials and unsent drafts survive outages; session snapshots, pending questions, and previously loaded upload lists refresh on reconnect. Missed activity is not replayed, and prompts/answers are never automatically resent. A deliberate **Disconnect** waits for the device’s explicit retry; **Revoke** removes access and requires pairing again.
+Network loss and daemon restarts reconnect automatically with bounded backoff. Heartbeats detect silent connections, and returning to the foreground or restoring network access retries immediately. Pairing credentials and unsent drafts survive outages; session snapshots, pending questions, and previously loaded upload lists refresh on reconnect. Recent activity is replayed from the daemon’s bounded log, but prompts/answers are never automatically resent. A deliberate **Disconnect** waits for the device’s explicit retry; **Revoke** removes access and requires pairing again.
+
+## Session metadata and usage
+
+Shared session title, model, effort and working directory refresh on Pi events and once per second while sharing, including while idle. Session detail shows context-window usage and estimated session cost. Native Pi context and recorded usage costs take precedence; independent extension reports fill unavailable fields. Missing usage is shown as unavailable, not zero.
+
+**Settings → Usage** is available on the console and paired devices. It displays the latest snapshot per provider: weekly usage, 5-hour usage when reported, reset times, source and snapshot age. Quota snapshots are not added across sessions or accounts. These are extension-reported limits, not billing totals or locally inferred quotas; providers without a quota report remain unavailable.
+
+Extensions can publish a provider-neutral event without importing Companion:
+
+```ts
+pi.events.emit("companion:telemetry", {
+  source: "my-usage-extension", // distinguish independent producers
+  // sessionId: ctx.sessionManager.getSessionId(), // optional session guard
+  context: { tokens: 24000, window: 200000, percent: 12 },
+  cost: { amount: 0.25, currency: "USD" },
+  providers: [{
+    provider: "openai-codex", updatedAt: new Date().toISOString(),
+    weekly: { usedPercent: 35, resetsAt: "2026-10-12T00:00:00Z" },
+    fiveHour: { usedPercent: 20 } // omit windows the provider doesn't supply
+  }]
+});
+```
+
+Publish complete snapshots per provider; session context and cost may be supplied independently by different extensions. Companion also accepts `usage:update`, `session:usage` and `provider:usage` with this shape. On opt-in and every 30 seconds it emits `companion:telemetry:request` with the Pi `sessionId` and `companionSessionId`, allowing adapters to respond with their cached snapshots. It never reads provider credentials or calls quota APIs itself. Extensions with private, non-exported quota data need an adapter to publish this contract.
+
+As a legacy fallback, `ctx.ui.setStatus` reports with explicit `ctx 12%` / `context 12%` and `cost: $0.25` (or cost/usage/footer keys containing `$0.25`) are recognized. Quota status lines must identify `provider=…` and label `7d`/`weekly` and `5h`/`5-hour` percentages (`used`, `left`, or `remaining`). Unlabelled percentages mean used. Status rendering is preserved. Invalid reports are ignored; extension context/cost expires after five minutes without a fresh reading. Context estimates are also invalidated on model changes, compaction and tree navigation; quota snapshots retain their original timestamps and visibly age.
 
 ## Settings
 
-The **Settings** page (local console only) covers:
+The **Settings → General** page provides appearance and device permissions on every device; daemon configuration is local-console-only:
 
 | Setting | Default | Notes |
 |---|---|---|
@@ -248,9 +285,10 @@ A single-page SvelteKit app, embedded in the daemon binary:
 | Page | Who sees it | What it is for |
 |---|---|---|
 | Overview | everyone | Dot-field hero, live counts, sessions that need your answer, a labeled live-session table, and a spaced onboarding/help panel with Claymorphism actions |
-| Sessions | everyone | Searchable, filterable full-width session rows (Working / Waiting / Ended), with short titles, workspace/model metadata, View details and safe Archive actions. Paired devices only see shared sessions |
+| Sessions | everyone | Searchable, filterable full-width session rows (Working / Waiting / Ended); the whole row opens the session, the status badge sits top-right, and ended sessions offer a safe Archive action. Paired devices only see shared sessions |
 | Session detail | everyone | Activity-first transcript with Markdown, highlighted code, Mermaid diagrams, collapsible tool output/thinking and question sheets. Compact header and navigation leave more space for the shell. The expanding composer includes Auto/Plan selection, attachment previews and a full-width labeled Send/Steer action; Plan uses the existing `/plan` command, not an agent permission setting. The top-right session menu opens Shared files, Changes and Archive session. The session header shows a status dot; clicking its title reveals status and session metadata. Changes are grouped by file with clear separators and a filename filter |
-| Devices, Settings | local console only | Pairing, connection status, disconnect and revoke; daemon settings with a save bar that appears only for unsaved edits |
+| Devices | local console only | Pairing, connection status, disconnect and revoke |
+| Settings | everyone | Theme, notification and camera permissions; on the console also daemon settings with a save bar that appears only for unsaved edits |
 | Help, Privacy, Terms | everyone | Setup stepper, commands, tools, troubleshooting; data handling; terms of use. Help is opened from the Overview |
 
 The Live indicator in the header and sidebar opens the connection sheet (status, version and, on this computer, the console and device addresses and data folders).
@@ -268,7 +306,7 @@ Design notes:
 - installable PWA: scoped manifest with explicit 192×192 and 512×512 PNG icons plus a maskable icon, standalone display mode, Apple home-screen metadata, and a service worker that caches only the public shell and static assets; API/session traffic and uploads are never cached
 - mobile: bottom tab bar, safe-area insets, 44px touch targets, 16px inputs (no iOS zoom), Enter inserts a newline on touch keyboards
 - accessibility: skip link, visible focus rings, labeled controls and table metadata, accessible session menus, live regions for the feed and questions, reduced-motion support
-- the dot field is Raksara's component, loaded when the browser is idle, paused when hidden, and static under reduced motion
+- the dot field is Raksara's component, loaded when the browser is idle, paused when hidden, and static under reduced motion. It opens on the Pi Companion mark, then morphs through a computer, a phone and a terminal
 - dropping a file anywhere outside the Shared files drop zone is ignored. Without this, the browser tries to open the file itself (Firefox reports this as "may not load or link to file:///")
 
 ### Caching and updates
@@ -314,7 +352,7 @@ Clone the repository, then:
 
 `npm run serve` builds the embedded Svelte UI and starts the Rust daemon in the foreground. It prints:
 
-      Pi Companion v0.2.2
+      Pi Companion v0.2.6
 
       Console          http://127.0.0.1:43721
       Paired devices   http://127.0.0.1:43722
@@ -347,6 +385,13 @@ which proxies /api and /ws to the daemon on 43721.
 
 If you start Pi from the checkout without running `npm run serve`, running `/companion` can still auto-start a local daemon build if one exists under `server/target/debug` or `server/target/release`. For predictable UI work, prefer `npm run serve` in one terminal and `pi -e ./src/index.ts` in another.
 
+To regenerate the README screenshots from demo sessions (your running daemon is left alone; the demo daemon uses ports 43731/43732 and a throwaway data folder):
+
+    npm run ui:build && cargo build --release --manifest-path server/Cargo.toml
+    node tools/screenshots.mjs
+
+It needs Playwright and `cwebp`. Set `PLAYWRIGHT=/path/to/node_modules/playwright/index.mjs` if Playwright isn't installed in this repo, and `CHROME=/path/to/chrome` to use an existing browser.
+
 To test the same behavior as a published install, stop any development daemon first and install the package normally:
 
     pi install npm:@yunazgr/pi-companion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunazgr/pi-companion",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Local-first remote control for Pi sessions: live activity feed, steering, git diff, file drop and phone pairing from a single Rust daemon.",
   "keywords": [
     "pi-package",

package/src/bridge.ts

@@ -5,6 +5,7 @@ import WebSocket from "ws";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { relayDialogs, ToolDialogRelay, type AskChannel, type AskInput } from "./ask.js";
 import { ensureDaemon } from "./daemon.js";
+import { TelemetryRelay } from "./telemetry.js";
 import type { AskAnswers, AskRequest, BridgeMessage, ServerMessage, SessionSnapshot, TempFile } from "./protocol.js";
 
 const execFileAsync = promisify(execFile);
@@ -17,6 +18,10 @@ export class CompanionBridge implements AskChannel {
   private ctx?: ExtensionContext;
   private reconnect?: NodeJS.Timeout;
   private heartbeat?: NodeJS.Timeout;
+  private metadataTimer?: NodeJS.Timeout;
+  private telemetryRequestedAt = 0;
+  private restoreStatus?: () => void;
+  private telemetry = new TelemetryRelay();
   private closed = false;
   private activated = false;
   private restoreDialogs?: () => void;
@@ -44,22 +49,55 @@ export class CompanionBridge implements AskChannel {
   setContext(ctx: ExtensionContext) {
     this.ctx = ctx;
     if (this.activated && this.snapshot.remoteEnabled && ctx.hasUI && !this.restoreDialogs) this.restoreDialogs = relayDialogs(ctx.ui, this, this.toolDialogs);
-    const name = this.pi.getSessionName() ?? this.snapshot.name;
-    this.snapshot = {
-      ...this.snapshot,
-      name,
-      cwd: ctx.cwd,
-      shortTitle: name?.trim() || ctx.cwd.split(/[\\/]/).filter(Boolean).pop() || "Pi",
-      mainModel: ctx.model?.id,
-      effort: ctx.thinkingLevel,
-      status: ctx.isIdle() ? "idle" : "active"
-    };
+    this.refreshMetadata();
   }
 
   setName(name?: string) {
-    this.snapshot.name = name;
+    this.snapshot.name = name ?? null;
     this.snapshot.shortTitle = name?.trim() || this.snapshot.cwd.split(/[\\/]/).filter(Boolean).pop() || "Pi";
-    this.send({ type: "session.update", session: { name, shortTitle: this.snapshot.shortTitle } });
+    this.send({ type: "session.update", session: { name: name ?? null, shortTitle: this.snapshot.shortTitle } });
+  }
+
+  /** Context getters remain live while idle; send only changed metadata, including explicit clears. */
+  refreshMetadata() {
+    const ctx = this.ctx;
+    if (!ctx || this.closed) return;
+    const cwd = ctx.cwd || ctx.sessionManager?.getCwd?.() || process.cwd();
+    const name = this.pi.getSessionName() ?? null;
+    if ((this.snapshot.mainModel ?? null) !== (ctx.model?.id ?? null)) this.telemetry.invalidateContext();
+    const next = {
+      name, cwd,
+      shortTitle: name?.trim() || cwd.split(/[\\/]/).filter(Boolean).pop() || "Pi",
+      mainModel: ctx.model?.id ?? null,
+      effort: ctx.thinkingLevel ?? this.pi.getThinkingLevel?.() ?? null,
+      telemetry: this.telemetry.snapshot(ctx)
+    };
+    const patch: Partial<SessionSnapshot> = {};
+    for (const key of Object.keys(next) as Array<keyof typeof next>) {
+      if (JSON.stringify(this.snapshot[key]) !== JSON.stringify(next[key])) Object.assign(patch, { [key]: next[key] });
+    }
+    Object.assign(this.snapshot, patch);
+    if (Object.keys(patch).length) this.send({ type: "session.update", session: patch });
+    if (this.activated && this.snapshot.remoteEnabled && Date.now() - this.telemetryRequestedAt >= 30_000) this.requestTelemetry();
+  }
+
+  invalidateContext() {
+    this.telemetry.invalidateContext();
+  }
+
+  ingestTelemetry(value: unknown, source: string) {
+    if (!this.isActivated() || !this.snapshot.remoteEnabled) return;
+    const id = value && typeof value === "object" ? (value as { sessionId?: unknown }).sessionId : undefined;
+    if (id !== undefined && id !== this.sessionId && id !== this.ctx?.sessionManager?.getSessionId?.()) return;
+    this.telemetry.ingest(value, source);
+    this.refreshMetadata();
+  }
+
+  private requestTelemetry() {
+    this.telemetryRequestedAt = Date.now();
+    try {
+      this.pi.events?.emit("companion:telemetry:request", { sessionId: this.ctx?.sessionManager?.getSessionId?.(), companionSessionId: this.sessionId });
+    } catch { /* A failing third-party responder must never interrupt sharing. */ }
   }
 
   setRemoteEnabled(remoteEnabled: boolean) {
@@ -73,6 +111,10 @@ export class CompanionBridge implements AskChannel {
     // End only Companion sharing: Pi itself and its local history keep running.
     this.restoreDialogs?.();
     this.restoreDialogs = undefined;
+    this.restoreStatus?.();
+    this.restoreStatus = undefined;
+    if (this.metadataTimer) clearInterval(this.metadataTimer);
+    this.metadataTimer = undefined;
     for (const entry of [...this.asks.values()]) entry.settle(null);
     for (const pending of this.pendingDeletes.values()) {
       clearTimeout(pending.timer);
@@ -99,6 +141,23 @@ export class CompanionBridge implements AskChannel {
   activate() {
     this.activated = true;
     if (this.snapshot.remoteEnabled && this.ctx?.hasUI && !this.restoreDialogs) this.restoreDialogs = relayDialogs(this.ctx.ui, this, this.toolDialogs);
+    if (!this.snapshot.remoteEnabled) return;
+    const ui = this.ctx?.ui;
+    if (ui && typeof ui.setStatus === "function" && !this.restoreStatus) {
+      const original = ui.setStatus;
+      const relay = this.telemetry;
+      const wrapped: typeof original = function(key, value) {
+        original.call(ui, key, value);
+        relay.status(key, value);
+      };
+      ui.setStatus = wrapped;
+      this.restoreStatus = () => { if (ui.setStatus === wrapped) ui.setStatus = original; };
+    }
+    if (!this.metadataTimer) {
+      this.metadataTimer = setInterval(() => this.refreshMetadata(), 1000);
+      this.metadataTimer.unref();
+    }
+    this.refreshMetadata();
   }
 
   isActivated() {
@@ -170,6 +229,10 @@ export class CompanionBridge implements AskChannel {
     this.closed = true;
     this.restoreDialogs?.();
     this.restoreDialogs = undefined;
+    this.restoreStatus?.();
+    this.restoreStatus = undefined;
+    if (this.metadataTimer) clearInterval(this.metadataTimer);
+    this.metadataTimer = undefined;
     for (const entry of [...this.asks.values()]) entry.settle(null);
     if (this.reconnect) clearTimeout(this.reconnect);
     if (this.heartbeat) clearTimeout(this.heartbeat);

package/src/index.ts

@@ -71,6 +71,11 @@ export default function companionExtension(pi: ExtensionAPI) {
   let bridge = new CompanionBridge(pi);
   let sharingGeneration = 0;
 
+  // Any extension can publish the neutral contract. No dependency on a particular footer/provider.
+  for (const channel of ["companion:telemetry", "usage:update", "session:usage", "provider:usage"]) {
+    pi.events?.on(channel, value => bridge.ingestTelemetry(value, channel));
+  }
+
   pi.on("session_start", (_event, ctx) => {
     // Switching or starting a Pi session must not inherit the previous opt-in.
     sharingGeneration += 1;
@@ -84,6 +89,7 @@ export default function companionExtension(pi: ExtensionAPI) {
     bridge.setName(event.name);
   });
   pi.on("model_select", (_event, ctx) => {
+    bridge.invalidateContext();
     bridge.setContext(ctx);
   });
   pi.on("thinking_level_select", (_event, ctx) => {
@@ -99,6 +105,15 @@ export default function companionExtension(pi: ExtensionAPI) {
     bridge.updateStatus("idle");
     bridge.emit("agent.end", { messages: Array.isArray((event as { messages?: unknown[] }).messages) ? (event as { messages: unknown[] }).messages.length : 0 });
   });
+  pi.on("message_end", (_event, ctx) => bridge.setContext(ctx));
+  pi.on("session_compact", (_event, ctx) => {
+    bridge.invalidateContext();
+    bridge.setContext(ctx);
+  });
+  pi.on("session_tree", (_event, ctx) => {
+    bridge.invalidateContext();
+    bridge.setContext(ctx);
+  });
   // Forward compact deltas instead of the full partial message on every token.
   pi.on("message_update", event => {
     const update = event.assistantMessageEvent;

package/src/protocol.ts

@@ -36,15 +36,30 @@ export type AskRequest = {
 /** Answers keyed by question id; each value lists chosen option labels and/or custom text. */
 export type AskAnswers = Record<string, string[]>;
 
+export type UsageWindow = { usedPercent: number; resetsAt?: string };
+export type ProviderUsage = {
+  provider: string;
+  source?: string;
+  updatedAt: string;
+  weekly?: UsageWindow;
+  fiveHour?: UsageWindow;
+};
+export type SessionTelemetry = {
+  context?: { tokens?: number; window?: number; percent?: number; source?: string };
+  cost?: { amount: number; currency?: string; source?: string };
+  providers?: ProviderUsage[];
+};
+
 export type SessionSnapshot = {
   id: string;
-  name?: string;
+  name?: string | null;
   cwd: string;
   pid: number;
   shortTitle: string;
   status: "active" | "idle" | "stopped";
-  mainModel?: string;
-  effort?: string;
+  mainModel?: string | null;
+  effort?: string | null;
+  telemetry?: SessionTelemetry;
   remoteEnabled: boolean;
   connectedAt: string;
   /** Questions waiting for an answer. Kept in the snapshot so late-joining browsers see them. */

package/src/telemetry.ts

@@ -0,0 +1,145 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ProviderUsage, SessionTelemetry, UsageWindow } from "./protocol.js";
+
+const record = (value: unknown): Record<string, unknown> | undefined =>
+  value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+const number = (value: unknown): number | undefined => typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+const text = (value: unknown): string | undefined => typeof value === "string" && value.trim() ? value.slice(0, 160) : undefined;
+function timestamp(value: unknown): string | undefined {
+  const millis = typeof value === "number" ? (value < 1e12 ? value * 1000 : value) : typeof value === "string" ? Date.parse(value) : NaN;
+  return Number.isFinite(millis) && Math.abs(millis) <= 8.64e15 ? new Date(millis).toISOString() : undefined;
+}
+function usageWindow(value: unknown): UsageWindow | undefined {
+  const raw = record(value);
+  if (!raw) return;
+  const remaining = number(raw.remainingPercent);
+  const usedPercent = number(raw.usedPercent ?? raw.used_percent) ?? (remaining !== undefined && remaining <= 100 ? 100 - remaining : undefined);
+  if (usedPercent === undefined || usedPercent > 100) return;
+  return { usedPercent, resetsAt: timestamp(raw.resetsAt ?? raw.resetAt ?? raw.reset_at) };
+}
+
+/** Allowlisted, provider-neutral input; never relay arbitrary extension data or credentials. */
+export function normalizeTelemetry(value: unknown, source = "extension", now = Date.now()): SessionTelemetry {
+  const raw = record(value);
+  if (!raw) return {};
+  const result: SessionTelemetry = {};
+  const context = record(raw.context ?? raw.contextUsage);
+  if (context) {
+    const tokens = number(context.tokens);
+    const window = number(context.window ?? context.contextWindow);
+    const percent = number(context.percent) ?? (tokens !== undefined && window ? tokens / window * 100 : undefined);
+    if (tokens !== undefined || percent !== undefined) result.context = { tokens, window, percent, source };
+  }
+  const cost = record(raw.cost);
+  const amount = number(cost?.amount ?? cost?.total ?? raw.cost);
+  if (amount !== undefined) result.cost = { amount, currency: text(cost?.currency) ?? "USD", source };
+  const providers = Array.isArray(raw.providers) ? raw.providers.slice(0, 100) : raw.provider ? [raw] : [];
+  const normalized: ProviderUsage[] = [];
+  for (const item of providers) {
+    const provider = record(item);
+    const name = text(provider?.provider);
+    if (!provider || !name) continue;
+    const weekly = usageWindow(provider.weekly ?? provider.sevenDay ?? provider.seven_day);
+    const fiveHour = usageWindow(provider.fiveHour ?? provider.five_hour);
+    if (!weekly && !fiveHour) continue;
+    normalized.push({ provider: name, source, updatedAt: timestamp(provider.updatedAt) ?? new Date(now).toISOString(), weekly, fiveHour });
+  }
+  if (normalized.length) result.providers = normalized;
+  return result;
+}
+
+/** Independent sources may supply different fields; one broken/missing adapter cannot erase another. */
+export class TelemetryRelay {
+  private sources = new Map<string, { telemetry: SessionTelemetry; contextAt?: number; costAt?: number }>();
+
+  ingest(value: unknown, fallbackSource = "extension", now = Date.now()) {
+    const raw = record(value);
+    const source = text(raw?.source) ?? fallbackSource;
+    const telemetry = normalizeTelemetry(raw?.telemetry ?? value, source, now);
+    if (!Object.keys(telemetry).length) return;
+    const previousEntry = this.sources.get(source);
+    const previous = previousEntry?.telemetry;
+    const providers = new Map(previous?.providers?.map(provider => [provider.provider, provider]));
+    for (const provider of telemetry.providers ?? []) {
+      const old = providers.get(provider.provider);
+      // A delayed adapter response must not roll a newer provider snapshot backward.
+      if (!old || Date.parse(provider.updatedAt) >= Date.parse(old.updatedAt)) providers.set(provider.provider, provider);
+    }
+    this.sources.delete(source);
+    this.sources.set(source, {
+      telemetry: { ...previous, ...telemetry, providers: [...providers.values()] },
+      contextAt: telemetry.context ? now : previousEntry?.contextAt,
+      costAt: telemetry.cost ? now : previousEntry?.costAt
+    });
+    if (this.sources.size > 100) this.sources.delete(this.sources.keys().next().value!);
+  }
+
+  /** Token estimates from the old projection/model are not valid after compaction or a switch. */
+  invalidateContext() {
+    for (const entry of this.sources.values()) {
+      delete entry.telemetry.context;
+      delete entry.contextAt;
+    }
+  }
+
+  /** Legacy status producers need no Companion dependency. Explicit labels avoid ambiguous numbers. */
+  status(key: string, value: string | undefined) {
+    if (!value) { this.sources.delete("status:" + key); return; }
+    const plain = value.replace(/\x1b\[[0-9;]*m/g, "");
+    const telemetry: Record<string, unknown> = { source: "status:" + key };
+    const context = plain.match(/(?:context|ctx)\s*[:=]?\s*([\d.]+)%/i);
+    const labelledCost = plain.match(/cost\s*[:=]?\s*\$([\d.]+)/i);
+    const cost = labelledCost ?? (/cost|usage|token|footer|context/i.test(key) ? plain.match(/\$([\d.]+)/) : null);
+    if (context) telemetry.context = { percent: Number(context[1]) };
+    if (cost) telemetry.cost = { amount: Number(cost[1]) };
+    const weekly = plain.match(/(?:weekly|7d|7-day)\s*[:=]?\s*([\d.]+)%\s*(left|remaining|used)?/i);
+    const fiveHour = plain.match(/(?:5h|5-hour)\s*[:=]?\s*([\d.]+)%\s*(left|remaining|used)?/i);
+    const window = (match: RegExpMatchArray | null) => match ? { usedPercent: /left|remaining/i.test(match[2] ?? "") ? 100 - Number(match[1]) : Number(match[1]) } : undefined;
+    const provider = plain.match(/provider\s*[:=]\s*([\w.-]+)/i)?.[1];
+    if (provider && (weekly || fiveHour)) telemetry.providers = [{ provider, weekly: window(weekly), fiveHour: window(fiveHour) }];
+    this.ingest(telemetry);
+  }
+
+  snapshot(ctx: ExtensionContext | undefined, now = Date.now()): SessionTelemetry {
+    const result: SessionTelemetry = {};
+    const providers = new Map<string, ProviderUsage>();
+    let latestContext = -Infinity;
+    let latestCost = -Infinity;
+    for (const { telemetry, contextAt, costAt } of this.sources.values()) {
+      if (telemetry.context && contextAt !== undefined && now - contextAt <= 300_000 && contextAt >= latestContext) {
+        result.context = telemetry.context;
+        latestContext = contextAt;
+      }
+      if (telemetry.cost && costAt !== undefined && now - costAt <= 300_000 && costAt >= latestCost) {
+        result.cost = telemetry.cost;
+        latestCost = costAt;
+      }
+      for (const provider of telemetry.providers ?? []) {
+        const old = providers.get(provider.provider);
+        if (!old || Date.parse(provider.updatedAt) >= Date.parse(old.updatedAt)) providers.set(provider.provider, provider);
+      }
+    }
+    if (providers.size) result.providers = [...providers.values()];
+    try {
+      const native = ctx?.getContextUsage?.();
+      if (native) {
+        // Native unknown after compaction is authoritative: do not resurrect stale extension tokens.
+        result.context = { tokens: number(native.tokens), window: number(native.contextWindow), percent: number(native.percent), source: "native" };
+      }
+    } catch { /* Older runtimes/other extensions may not implement this getter. */ }
+    try {
+      const entries = ctx?.sessionManager?.getEntries?.() ?? [];
+      let total = 0;
+      let known = false;
+      for (const entry of entries) {
+        const raw = record(entry);
+        const message = record(raw?.message);
+        const usage = record(raw?.type === "message" ? message?.usage : ["usage", "compaction", "branch_summary"].includes(String(raw?.type)) ? raw?.usage : undefined);
+        const cost = number(record(usage?.cost)?.total);
+        if (cost !== undefined) { known = true; total += cost; }
+      }
+      if (known && Number.isFinite(total)) result.cost = { amount: total, currency: "USD", source: "native" };
+    } catch { /* Preserve extension estimate when native usage is unavailable. */ }
+    return result;
+  }
+}