Token tracking (#58)

* feat: session token tracking with /tokens command and exit summary

Track cumulative input/output/cache tokens, request count, and turn
count across the session. Display via:

- /tokens command — show session totals at any time
- Exit summary — printed at all exit points (interactive, --prompt, SIGINT)
- Per-turn inline display unchanged (📊 line)

New state fields: totalInputTokens, totalOutputTokens,
totalCacheReadTokens, totalRequests, totalTurns

Accumulation happens in the assistant.usage event handler.
Turn count incremented on each onUserPromptSubmitted.

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

* feat: teach LLM to build reusable modules proactively

Add guidance to system message encouraging the LLM to use
register_module when it identifies missing capabilities rather
than just describing gaps. Modules persist across sessions.

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

* fix: update sourceHash on register_module to prevent hash mismatch warnings

When register_module saves a user module, it now writes the sourceHash
to the .json metadata. Previously only loadModuleAsync set this field,
so re-registering a module with updated code would leave a stale hash
that the validator flagged as a mismatch warning.

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

* fix: address PR #58 review feedback

1. event-handler.ts: guard against undefined token values before accumulating
2. llm-output.ts: format large token numbers with toLocaleString, fix alignment
3. index.ts: use guard function for exit summary (no tokens = no summary)
4. state.ts: add doc comment clarifying totalRequests tracks premium requests
5. module-store.ts: use computeTruncatedHash instead of manual slice

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

---------

Signed-off-by: Simon Davies <simongdavies@users.noreply.github.com>

Author: simongdavies

package-lock.json

@@ -51,6 +51,13 @@ const COMMANDS: readonly CommandEntry[] = Object.freeze([
       "Enables verbose SDK event logging (same as HYPERAGENT_DEBUG=1).\n" +
       "Shows every event the agent receives from the Copilot SDK.",
   },
+  {
+    completion: "/tokens",
+    help: "Show session token usage summary",
+    detail:
+      "Displays cumulative input/output/cache tokens, request count,\n" +
+      "and turn count for the current session. Also shown on exit.",
+  },
   {
     completion: "/reasoning conversation ",
     help: "Set conversation reasoning effort (low|medium|high|xhigh)",

src/agent/commands.ts

@@ -429,6 +429,14 @@ export function registerEventHandler(
           cost?: number;
           duration?: number;
         };
+
+        // Accumulate session totals. Count one request per usage event;
+        // usageData.cost is premium request count, not a reliable API-call counter.
+        state.totalInputTokens += usageData.inputTokens ?? 0;
+        state.totalOutputTokens += usageData.outputTokens ?? 0;
+        state.totalCacheReadTokens += usageData.cacheReadTokens ?? 0;
+        state.totalRequests += 1;
+
         // Ensure stats appear on a new line — streamed
         // message_delta writes don't end with \n.
         if (state.streamedContent) {

src/agent/event-handler.ts

@@ -116,6 +116,7 @@ import {
   renderReasoningTransition,
   printUsageStats,
   printExtendedReasoningNotice,
+  formatTokenSummary,
 } from "./llm-output.js";
 
 // ── Session Timing ───────────────────────────────────────────────────
@@ -145,6 +146,19 @@ function formatSessionDuration(): string {
   return seconds > 0 ? `${minutes}m ${seconds}s` : `${minutes}m`;
 }
 
+/**
+ * Print session token summary to console.
+ * Called at all exit points (interactive, --prompt, SIGINT).
+ */
+function printExitTokenSummary(): void {
+  if (state.totalInputTokens === 0 && state.totalOutputTokens === 0) return;
+  const lines = formatTokenSummary(state);
+  console.log(); // blank line before summary
+  for (const line of lines) {
+    console.log(`  ${line}`);
+  }
+}
+
 // ── Paths ────────────────────────────────────────────────────────────
 
 const __agentFilename = fileURLToPath(import.meta.url);
@@ -4482,6 +4496,9 @@ function buildSessionConfig() {
       // Guidance is stored in state.lastGuidance and re-injected on
       // every turn so it survives compaction.
       onUserPromptSubmitted: async (input: { prompt: string }) => {
+        // Track turn count
+        state.totalTurns++;
+
         // Capture prompt and reset per-prompt tracking flags
         state.currentUserPrompt = input.prompt;
         state.hasCalledListModules = false;
@@ -5172,6 +5189,7 @@ async function main(): Promise<void> {
           await processMessage(session, "continue");
         }
       }
+      printExitTokenSummary();
       console.log(`\n✅ Prompt completed. (${formatSessionDuration()})\n`);
       cleanupCtrlR?.();
       rl.close();
@@ -5206,6 +5224,7 @@ async function main(): Promise<void> {
       // Exit — either bare 'exit' or '/exit'
       const lower = trimmed.toLowerCase();
       if (lower === "exit" || lower === "/exit") {
+        printExitTokenSummary();
         console.log(`\n👋 Goodbye! (session: ${formatSessionDuration()})\n`);
         break;
       }
@@ -5412,6 +5431,7 @@ const SHUTDOWN_TIMEOUT_MS = 5_000;
 
 // Graceful shutdown — clean up on SIGINT (Ctrl+C)
 process.on("SIGINT", async () => {
+  printExitTokenSummary();
   console.log(`\n\n👋 Goodbye! (session: ${formatSessionDuration()})\n`);
 
   // Stop transcript synchronously — async won't complete before exit

src/agent/index.ts

@@ -60,6 +60,33 @@ export function printUsageStats(stats: string, indent: string): void {
   console.log(`${indent}${C.dim("📊 " + stats)}`);
 }
 
+/**
+ * Format a session token summary for /tokens command or exit display.
+ * Returns an array of lines (without leading newline).
+ */
+export function formatTokenSummary(state: {
+  totalInputTokens: number;
+  totalOutputTokens: number;
+  totalCacheReadTokens: number;
+  totalRequests: number;
+  totalTurns: number;
+}): string[] {
+  const total = state.totalInputTokens + state.totalOutputTokens;
+  const lines: string[] = [];
+  lines.push(`${C.label("Token Usage")}  ${C.dim("(process total)")}`);
+  lines.push(`Input:       ${state.totalInputTokens.toLocaleString()} tokens`);
+  lines.push(`Output:      ${state.totalOutputTokens.toLocaleString()} tokens`);
+  if (state.totalCacheReadTokens > 0) {
+    lines.push(
+      `Cache read:  ${state.totalCacheReadTokens.toLocaleString()} tokens`,
+    );
+  }
+  lines.push(`Total:       ${total.toLocaleString()} tokens`);
+  lines.push(`Requests:    ${state.totalRequests}`);
+  lines.push(`Turns:       ${state.totalTurns}`);
+  return lines;
+}
+
 // ── Reasoning Rendering ──────────────────────────────────────────────
 
 /**

src/agent/llm-output.ts

@@ -365,6 +365,8 @@ export async function saveModule(
     description,
     author,
     mutable,
+    // Keep sourceHash in sync so the validator doesn't flag a mismatch
+    sourceHash: computeTruncatedHash(source),
     metadataCache: {
       extractedFromHash: currentHash,
       exports,

src/agent/module-store.ts

@@ -143,6 +143,16 @@ export async function handleSlashCommand(
       console.log();
       return true;
 
+    case "/tokens": {
+      const { formatTokenSummary } = await import("./llm-output.js");
+      const lines = formatTokenSummary(state);
+      for (const line of lines) {
+        console.log(`  ${line}`);
+      }
+      console.log();
+      return true;
+    }
+
     case "/reasoning": {
       // /reasoning conversation <level> — set conversation reasoning effort
       // /reasoning audit <level>        — set audit reasoning effort (min: medium)

src/agent/slash-commands.ts

@@ -240,6 +240,23 @@ export interface AgentState {
    * additionalContext on every onUserPromptSubmitted.
    */
   lastGuidance: string | null;
+
+  // ── Token Tracking ───────────────────────────────────────────────
+
+  /** Cumulative input tokens across all LLM requests this session. */
+  totalInputTokens: number;
+
+  /** Cumulative output tokens across all LLM requests this session. */
+  totalOutputTokens: number;
+
+  /** Cumulative cache-read tokens across all LLM requests this session. */
+  totalCacheReadTokens: number;
+
+  /** Total number of LLM API requests (one per assistant.usage event). */
+  totalRequests: number;
+
+  /** Number of user turns (messages sent) this session. */
+  totalTurns: number;
 }
 
 // ── Factory ──────────────────────────────────────────────────────────
@@ -317,5 +334,12 @@ export function createAgentState(
     hasCalledListModules: false,
     modulesInspected: new Set<string>(),
     lastGuidance: null,
+
+    // Token tracking
+    totalInputTokens: 0,
+    totalOutputTokens: 0,
+    totalCacheReadTokens: 0,
+    totalRequests: 0,
+    totalTurns: 0,
   };
 }

src/agent/state.ts

@@ -115,6 +115,12 @@ DISCOVERY (never guess — always check):
   Do NOT guess parameter names — they are ALL listed in typeDefinitions.
   For specific function details, call module_info(name, "functionName").
 
+BUILDING REUSABLE MODULES:
+  When you identify a missing capability (like a format library), don't just
+  describe the gap — use register_module to build a reusable module that fills
+  it. Modules persist across sessions and compound in value over time.
+  Import your module with: import { fn } from "ha:<name>"
+
 PLUGINS: Require explicit enable via manage_plugin.
   Host plugin functions return values directly (not Promises).
   You CAN use async/await — it works — but await on a plugin call