@marcosgilf/pi-session 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcos Gil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# pi-session
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Show context percentage/window in Pi's default footer and detailed token, cache, cost, and context usage in a modal.
+
+## Install
+
+```sh
+pi install npm:@marcosgilf/pi-session
+```
+
+- When installed alone, the default footer shows session context use.
+- `/session-usage` opens detailed session information.
+- Command+Shift+S (`super+shift+s`) opens the same modal.
+- In modal: `c` copies full summary; Ctrl/Cmd+C copies selected text; click outside closes.
+- Install `@marcosgilf/pi-footer` to place session context before skill statuses and Copilot usage beside the model. It loads this extension as a dependency; do not install both packages separately.
+
+Pi extensions run with Pi's operating-system permissions. Review package source before installing.

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@marcosgilf/pi-session",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Session token, cost, cache, and context usage for Pi.",
+  "type": "module",
+  "license": "MIT",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "session",
+    "usage",
+    "tokens"
+  ],
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./core": "./src/core.ts",
+    "./events": "./src/events.ts"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "dependencies": {
+    "@marcosgilf/pi-modal": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  }
+}

package/src/core.ts

@@ -0,0 +1,124 @@
+type Usage = {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  cost?: { total?: number };
+};
+
+type UsageEntry = {
+  type?: string;
+  provider?: string;
+  usage?: Usage;
+  message?: { role?: string; provider?: string; usage?: Usage };
+};
+
+export type SessionUsage = {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+  latestCacheHitRate?: number;
+};
+
+export type ContextUsageStyle = "error" | "warning" | "text" | "dim";
+
+export function formatTokens(tokens: number): string {
+  if (tokens < 1_000) return tokens.toString();
+  if (tokens < 10_000) return `${(tokens / 1_000).toFixed(1)}k`;
+  if (tokens < 1_000_000) return `${Math.round(tokens / 1_000)}k`;
+  if (tokens < 10_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`;
+  return `${Math.round(tokens / 1_000_000)}M`;
+}
+
+export function getContextUsageStyle(percent: number | null): ContextUsageStyle {
+  return percent === null ? "dim" : percent > 90 ? "error" : percent > 70 ? "warning" : "text";
+}
+
+export function formatContextUsageIndicator(
+  percent: number | null,
+  contextWindow: number,
+): {
+  text: string;
+  style: ContextUsageStyle;
+} {
+  const label = percent === null ? "?" : `${percent.toFixed(1)}%`;
+  return { text: `${label}/${formatTokens(contextWindow)}`, style: getContextUsageStyle(percent) };
+}
+
+export function formatSessionUsageSummary(
+  stats: SessionUsage,
+  context?: { percent: number | null; contextWindow: number },
+  options: { subscription?: boolean; autoCompaction?: boolean } = {},
+): string[] {
+  const tokens = [
+    stats.input > 0 ? `↑${formatTokens(stats.input)}` : undefined,
+    stats.output > 0 ? `↓${formatTokens(stats.output)}` : undefined,
+    stats.cacheRead > 0 ? `R${formatTokens(stats.cacheRead)}` : undefined,
+    stats.cacheWrite > 0 ? `W${formatTokens(stats.cacheWrite)}` : undefined,
+    (stats.cacheRead > 0 || stats.cacheWrite > 0) && stats.latestCacheHitRate !== undefined
+      ? `CH${stats.latestCacheHitRate.toFixed(1)}%`
+      : undefined,
+  ]
+    .filter((part): part is string => part !== undefined)
+    .join(" ");
+  const lines = ["Session usage", tokens || "No token usage in this session"];
+  if (stats.cost > 0 || options.subscription) {
+    lines.push(`$${stats.cost.toFixed(3)}${options.subscription ? " (sub)" : ""}`);
+  }
+  const auto = options.autoCompaction === false ? "" : " (auto)";
+  lines.push(
+    context
+      ? `${context.percent === null ? "?" : `${context.percent.toFixed(1)}%`}/${formatTokens(context.contextWindow)}${auto}`
+      : `Context unavailable${auto}`,
+  );
+  return lines;
+}
+
+export function summarizeSession(entries: readonly unknown[], provider?: string): SessionUsage {
+  const total = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+  let latestCacheHitRate: number | undefined;
+  let sawAssistantUsage = false;
+  const add = (usage?: Usage) => {
+    if (!usage) return;
+    for (const key of ["input", "output", "cacheRead", "cacheWrite"] as const) {
+      const value = usage[key];
+      if (typeof value === "number" && Number.isFinite(value) && value > 0) total[key] += value;
+    }
+    const cost = usage.cost?.total;
+    if (typeof cost === "number" && Number.isFinite(cost) && cost > 0) total.cost += cost;
+  };
+
+  for (const rawEntry of entries) {
+    if (!rawEntry || typeof rawEntry !== "object") continue;
+    const entry = rawEntry as UsageEntry;
+    if (
+      entry.type === "message" &&
+      entry.message?.role === "assistant" &&
+      (!provider || entry.message.provider === provider)
+    ) {
+      const usage = entry.message.usage;
+      add(usage);
+      if (usage) {
+        sawAssistantUsage = true;
+        const promptTokens = (usage.input ?? 0) + (usage.cacheRead ?? 0) + (usage.cacheWrite ?? 0);
+        latestCacheHitRate = promptTokens > 0 ? ((usage.cacheRead ?? 0) / promptTokens) * 100 : undefined;
+      }
+    } else if (
+      entry.type === "message" &&
+      entry.message?.role === "toolResult" &&
+      (!provider || entry.message.provider === provider)
+    ) {
+      add(entry.message.usage);
+    } else if (entry.type === "usage" && (!provider || entry.provider === provider)) {
+      add(entry.usage);
+    } else if (!provider && (entry.type === "compaction" || entry.type === "branch_summary")) {
+      add(entry.usage);
+    }
+  }
+  return {
+    ...total,
+    ...(sawAssistantUsage ? { latestCacheHitRate } : {}),
+  };
+}

package/src/events.ts

@@ -0,0 +1,2 @@
+export const SESSION_USAGE_STATUS_KEY = "pi-session";
+export const OPEN_SESSION_USAGE_EVENT = "pi-footer:open-session-usage";

package/src/index.ts

@@ -0,0 +1,86 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type ModalContent, type ModalRow, showModal } from "@marcosgilf/pi-modal";
+import { formatContextUsageIndicator, formatSessionUsageSummary, summarizeSession } from "./core.ts";
+import { OPEN_SESSION_USAGE_EVENT, SESSION_USAGE_STATUS_KEY } from "./events.ts";
+
+function buildSessionUsageModal(ctx: ExtensionContext, autoCompaction: boolean): ModalContent {
+  const stats = summarizeSession(ctx.sessionManager.getEntries());
+  const model = ctx.model;
+  const subscription =
+    model !== undefined &&
+    ctx.modelRegistry.getProvider(model.provider)?.auth.oauth?.isSubscription === true &&
+    ctx.modelRegistry.isUsingOAuth(model);
+  const summary = formatSessionUsageSummary(stats, ctx.getContextUsage(), { subscription, autoCompaction });
+  const rows: ModalRow[] = [
+    { text: summary[0], style: "accent" },
+    { text: "" },
+    ...summary.slice(1, -1).map((text) => ({ text })),
+    { text: "" },
+    { text: summary[summary.length - 1] },
+  ];
+  return { rows, clipboardText: summary.join("\n") };
+}
+
+function updateSessionStatus(ctx: ExtensionContext): void {
+  if (ctx.mode !== "tui") return;
+  const context = ctx.getContextUsage();
+  const contextWindow = context?.contextWindow ?? ctx.model?.contextWindow;
+  const status = contextWindow ? formatContextUsageIndicator(context?.percent ?? null, contextWindow).text : undefined;
+  ctx.ui.setStatus(SESSION_USAGE_STATUS_KEY, status);
+}
+
+async function showSessionUsage(ctx: ExtensionContext, autoCompaction: boolean): Promise<void> {
+  const unavailableMessage = "/session-usage requires Pi TUI mode.";
+  if (ctx.mode !== "tui") {
+    ctx.ui.notify(unavailableMessage, "warning");
+    return;
+  }
+  const build = () => buildSessionUsageModal(ctx, autoCompaction);
+  await showModal(ctx, build(), { refresh: async () => build() }, unavailableMessage);
+}
+
+export default function (pi: ExtensionAPI): void {
+  let currentContext: ExtensionContext | undefined;
+
+  const autoCompactionEnabled = () => pi.getSettings().compaction?.enabled ?? true;
+
+  pi.events.on(OPEN_SESSION_USAGE_EVENT, () => {
+    if (currentContext) void showSessionUsage(currentContext, autoCompactionEnabled());
+  });
+
+  pi.on("session_start", (_event, ctx) => {
+    currentContext = ctx;
+    updateSessionStatus(ctx);
+  });
+  pi.on("agent_end", (_event, ctx) => {
+    currentContext = ctx;
+    updateSessionStatus(ctx);
+  });
+  pi.on("turn_end", (_event, ctx) => {
+    currentContext = ctx;
+    updateSessionStatus(ctx);
+  });
+  pi.on("model_select", (_event, ctx) => {
+    currentContext = ctx;
+    updateSessionStatus(ctx);
+  });
+  pi.on("session_tree", (_event, ctx) => {
+    currentContext = ctx;
+    updateSessionStatus(ctx);
+  });
+  pi.on("session_compact", (_event, ctx) => updateSessionStatus(ctx));
+  pi.on("session_shutdown", (_event, ctx) => {
+    if (ctx.mode === "tui") ctx.ui.setStatus(SESSION_USAGE_STATUS_KEY, undefined);
+    currentContext = undefined;
+  });
+
+  pi.registerCommand("session-usage", {
+    description: "Show session token, cost, and context usage",
+    handler: (_args, ctx) => showSessionUsage(ctx, autoCompactionEnabled()),
+  });
+
+  pi.registerShortcut("super+shift+s", {
+    description: "Show session token, cost, and context usage",
+    handler: (ctx) => showSessionUsage(ctx, autoCompactionEnabled()),
+  });
+}