@yunazgr/pi-companion 0.2.5 → 0.2.6

package/README.md

@@ -153,7 +153,7 @@ Dialogs from other extensions (`ctx.ui.select`, `ctx.ui.confirm`, `ctx.ui.input`
 
 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.
+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.
 
@@ -178,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 |
 |---|---|---|
@@ -326,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.5
+      Pi Companion v0.2.6
 
       Console          http://127.0.0.1:43721
       Paired devices   http://127.0.0.1:43722

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yunazgr/pi-companion",
-  "version": "0.2.5",
+  "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;
+  }
+}