talon-agent 3.14.0 → 3.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "3.14.0",
+  "version": "3.15.0",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "Dylan Neve",
   "license": "MIT",

package/src/frontend/shared/status-context.ts

@@ -1,5 +1,166 @@
 import type { CacheMetricsSupport } from "../../core/types.js";
 
+// ── /context breakdown ────────────────────────────────────────────────────────
+
+/**
+ * Rough token estimate — ~4 chars/token, the house heuristic used everywhere
+ * (soul/projector, cache-telemetry). No real tokenizer is wired, so every
+ * measured figure in the breakdown below is an estimate at this fidelity.
+ */
+export function estimateContextTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+export type ContextSegmentKey = "system" | "tools" | "conversation";
+
+interface ContextSegment {
+  key: ContextSegmentKey;
+  label: string;
+  tokens: number;
+  /** Share of the window (0–100) when the window is known, else share of used. */
+  pct: number;
+}
+
+export interface ContextBreakdown {
+  /** True once there is anything to show (a system prompt or a reported fill). */
+  known: boolean;
+  /** True when the window size is known — only then can free space be shown. */
+  windowKnown: boolean;
+  used: number;
+  max: number;
+  usedPct: number;
+  free: number;
+  freePct: number;
+  /** Fixed → variable order: System, Tools, Conversation. */
+  segments: ContextSegment[];
+  warn: boolean;
+}
+
+function posInt(n: number | undefined): number {
+  return typeof n === "number" && Number.isFinite(n) && n > 0
+    ? Math.round(n)
+    : 0;
+}
+
+function round1(n: number): number {
+  return Math.round(n * 10) / 10;
+}
+
+/**
+ * Decompose the context window into System / Tools / Conversation + free.
+ *
+ * The honesty this has to preserve: the backend reports exactly one
+ * authoritative number, `contextTokens` (the real last-turn fill). Nothing
+ * reports a per-category split, so:
+ *
+ *   - **System** is measured from the actual (frozen) system prompt — accurate,
+ *     and the part a user can act on.
+ *   - **Conversation** is estimated from stored history. It can overshoot what
+ *     is really in-window after compaction; when it does, it is clamped to fit.
+ *   - **Tools** is the residual: `used − system − conversation`. Tool schemas
+ *     (invisible to us — they live inside the SDK) dominate it, but it also
+ *     absorbs message-formatting overhead and estimation slack. Labelled as the
+ *     remainder, not claimed as exact.
+ *
+ * When the backend reports no fill, tools cannot be derived, so only the two
+ * measured/estimated parts are shown and the window's free space (if known) is
+ * whatever is left of it.
+ */
+export function buildContextBreakdown(input: {
+  contextTokens?: number;
+  contextWindow?: number;
+  systemTokens: number;
+  conversationTokens: number;
+}): ContextBreakdown {
+  const max = posInt(input.contextWindow);
+  const system = Math.max(0, Math.round(input.systemTokens));
+  let conversation = Math.max(0, Math.round(input.conversationTokens));
+  const fill = posInt(input.contextTokens);
+
+  const segments: ContextSegment[] = [];
+  let used: number;
+
+  if (fill > 0) {
+    used = fill;
+    // System is sent in full every turn; if our estimate exceeds the real fill
+    // that is estimation slack, not reality — clamp so parts never exceed used.
+    const sys = Math.min(system, used);
+    let tools = used - sys - conversation;
+    if (tools < 0) {
+      // Conversation overshot the real fill (compaction dropped in-window
+      // messages) — give the remainder back to conversation, zero the residual.
+      conversation = Math.max(0, used - sys);
+      tools = 0;
+    }
+    segments.push({ key: "system", label: "System", tokens: sys, pct: 0 });
+    segments.push({ key: "tools", label: "Tools", tokens: tools, pct: 0 });
+    segments.push({
+      key: "conversation",
+      label: "Conversation",
+      tokens: conversation,
+      pct: 0,
+    });
+  } else {
+    // No authoritative fill — show what we can measure; tools isn't derivable.
+    used = system + conversation;
+    segments.push({ key: "system", label: "System", tokens: system, pct: 0 });
+    segments.push({
+      key: "conversation",
+      label: "Conversation",
+      tokens: conversation,
+      pct: 0,
+    });
+  }
+
+  const windowKnown = max > 0;
+  const free = windowKnown ? Math.max(0, max - used) : 0;
+  const denom = windowKnown ? max : used;
+  for (const s of segments) {
+    s.pct = denom > 0 ? round1((s.tokens / denom) * 100) : 0;
+  }
+
+  return {
+    known: used > 0,
+    windowKnown,
+    used,
+    max,
+    usedPct: windowKnown ? Math.min(100, round1((used / max) * 100)) : 0,
+    free,
+    freePct: windowKnown ? round1((free / max) * 100) : 0,
+    segments,
+    warn: windowKnown && used / max >= 0.8,
+  };
+}
+
+/**
+ * Distribute `width` integer cells across `weights` proportionally, by the
+ * largest-remainder method — the cells sum to exactly `width` and no positive
+ * weight is systematically rounded to nothing before its peers. Zero weights
+ * get zero cells. Used to lay out the segmented bar so its coloured runs sum to
+ * the bar width regardless of rounding.
+ */
+export function apportionCells(
+  weights: readonly number[],
+  width: number,
+): number[] {
+  const total = weights.reduce((a, b) => a + b, 0);
+  if (total <= 0 || width <= 0) return weights.map(() => 0);
+  const exact = weights.map((w) => (Math.max(0, w) / total) * width);
+  const cells = exact.map((x) => Math.floor(x));
+  let remaining = width - cells.reduce((a, b) => a + b, 0);
+  const byRemainder = exact
+    .map((x, i) => ({ i, frac: x - Math.floor(x) }))
+    .sort((a, b) => b.frac - a.frac);
+  for (const { i } of byRemainder) {
+    if (remaining <= 0) break;
+    if (weights[i]! > 0) {
+      cells[i]!++;
+      remaining--;
+    }
+  }
+  return cells;
+}
+
 export interface ContextDisplay {
   known: boolean;
   used: number;

package/src/frontend/terminal/commands.ts

@@ -18,7 +18,13 @@ import {
 import {
   buildCacheDisplay,
   buildContextDisplay,
+  buildContextBreakdown,
+  estimateContextTokens,
+  apportionCells,
+  type ContextBreakdown,
+  type ContextSegmentKey,
 } from "../shared/status-context.js";
+import { getRecentHistory } from "../../storage/history.js";
 import {
   formatDuration,
   formatTokenCount,
@@ -113,6 +119,63 @@ export function clearCommands(): void {
   nameIndex.clear();
 }
 
+// ── /context rendering ───────────────────────────────────────────────────────
+
+/** Each used segment gets its own colour; free is a dim hatch. */
+const CONTEXT_SEGMENT_COLOR: Record<ContextSegmentKey, (s: string) => string> =
+  {
+    system: pc.blue,
+    tools: pc.yellow,
+    conversation: pc.cyan,
+  };
+
+const CONTEXT_BAR_WIDTH = 42;
+
+/**
+ * The segmented bar: one coloured run per segment (proportional to the window),
+ * then the free space as a dim `░` hatch. Cell counts come from
+ * `apportionCells`, so the runs always sum to exactly the bar width.
+ */
+function renderContextBar(bd: ContextBreakdown): string {
+  const weights = bd.segments.map((s) => s.tokens);
+  if (bd.windowKnown) weights.push(bd.free);
+  const cells = apportionCells(weights, CONTEXT_BAR_WIDTH);
+  let bar = "";
+  bd.segments.forEach((s, i) => {
+    bar += CONTEXT_SEGMENT_COLOR[s.key]("█".repeat(cells[i] ?? 0));
+  });
+  if (bd.windowKnown) {
+    bar += pc.dim("░".repeat(cells[bd.segments.length] ?? 0));
+  }
+  return bar;
+}
+
+/** One aligned legend row per segment (and Free), colour-matched to the bar. */
+function renderContextLegend(bd: ContextBreakdown): string[] {
+  const rows = bd.segments.map((s) => ({
+    dot: CONTEXT_SEGMENT_COLOR[s.key]("●"),
+    label: s.label,
+    tokens: s.tokens,
+    pct: s.pct,
+  }));
+  if (bd.windowKnown) {
+    rows.push({
+      dot: pc.dim("░"),
+      label: "Free",
+      tokens: bd.free,
+      pct: bd.freePct,
+    });
+  }
+  const labelW = Math.max(...rows.map((r) => r.label.length));
+  const tokW = Math.max(...rows.map((r) => formatTokenCount(r.tokens).length));
+  return rows.map((r) => {
+    const label = r.label.padEnd(labelW);
+    const tok = formatTokenCount(r.tokens).padStart(tokW);
+    const pct = `${r.pct}%`.padStart(6);
+    return `${r.dot} ${label}  ${pc.dim(tok)}  ${pc.dim(pct)}`;
+  });
+}
+
 // ── Built-in commands ────────────────────────────────────────────────────────
 
 export function registerBuiltinCommands(): void {
@@ -393,6 +456,95 @@ export function registerBuiltinCommands(): void {
     },
   });
 
+  registerCommand({
+    name: "context",
+    aliases: ["ctx"],
+    description: "Context-window usage, broken down",
+    async handler(_args, ctx) {
+      const chatId = ctx.chatId();
+      const u = getSessionInfo(chatId).usage;
+      const be = ctx.backend;
+      const activeModel = getChatSettings(chatId).model ?? ctx.config.model;
+
+      // Window + a friendly model name, enriched from the backend like /status.
+      let contextWindow = u.contextWindow;
+      let modelName = resolveModelName(activeModel);
+      if (be?.models?.getRawModelInfo) {
+        const mi = await be.models
+          .getRawModelInfo(activeModel)
+          .catch(() => undefined);
+        if (mi) {
+          if (mi.contextWindow) contextWindow ||= mi.contextWindow;
+          if (mi.displayName) modelName = mi.displayName;
+        }
+      }
+
+      // System = the actual frozen prompt the model is running with. Measure
+      // it directly rather than rebuilding, so the number matches what was
+      // really sent (the prompt is frozen per session by design).
+      const parts = ctx.config.systemPromptParts;
+      const systemText = parts
+        ? [parts.staticText, parts.dynamicText].filter(Boolean).join("\n")
+        : (ctx.config.systemPrompt ?? "");
+      const systemTokens = estimateContextTokens(systemText);
+
+      // Conversation = stored history for this chat. An estimate: the model's
+      // real in-window history may be smaller after compaction, which the
+      // breakdown clamps against the authoritative fill.
+      const history = getRecentHistory(chatId, 2000);
+      const conversationTokens = estimateContextTokens(
+        history.map((m) => m.text ?? "").join("\n"),
+      );
+
+      const bd = buildContextBreakdown({
+        contextTokens: u.contextTokens,
+        contextWindow,
+        systemTokens,
+        conversationTokens,
+      });
+
+      ctx.renderer.writeln();
+      if (!bd.known) {
+        ctx.renderer.writeln(
+          `  ${pc.bold("Context")}  ${pc.dim("no usage yet — send a message first")}`,
+        );
+        ctx.reprompt();
+        return;
+      }
+
+      const windowStr = bd.windowKnown
+        ? `${formatTokenCount(bd.max)} window`
+        : pc.dim("window unknown");
+      ctx.renderer.writeln(
+        `  ${pc.bold("Context")}  ${modelName}  ·  ${windowStr}`,
+      );
+
+      const usedStr = bd.windowKnown
+        ? `${formatTokenCount(bd.used)} / ${formatTokenCount(bd.max)}  ·  ${bd.usedPct}% used`
+        : `${formatTokenCount(bd.used)} used`;
+      ctx.renderer.writeln(
+        `  ${bd.warn ? pc.yellow(usedStr) : pc.dim(usedStr)}${bd.warn ? pc.yellow("  · nearing limit") : ""}`,
+      );
+      ctx.renderer.writeln();
+      ctx.renderer.writeln(`  ${renderContextBar(bd)}`);
+      ctx.renderer.writeln();
+      for (const line of renderContextLegend(bd)) {
+        ctx.renderer.writeln(`  ${line}`);
+      }
+      // Explain only what's on screen: Tools is derivable (and shown) only
+      // when the backend reported a real fill.
+      const hasTools = bd.segments.some((s) => s.key === "tools");
+      ctx.renderer.writeln(
+        `  ${pc.dim(
+          hasTools
+            ? "System measured; Conversation estimated; Tools is the remainder."
+            : "System measured; Conversation estimated from stored history.",
+        )}`,
+      );
+      ctx.reprompt();
+    },
+  });
+
   registerCommand({
     name: "reset",
     description: "Start a fresh session",