@pencil-agent/nano-pencil 1.9.4 → 1.9.5

package/dist/core/agent-session.d.ts

@@ -24,6 +24,8 @@ import type { ResourceLoader } from "./resource-loader.js";
 import type { BranchSummaryEntry, SessionManager } from "./session-manager.js";
 import type { SettingsManager } from "./settings-manager.js";
 import type { BashOperations } from "./tools/bash.js";
+import type { UsageTracker } from "./usage-tracker.js";
+import type { UsageStats } from "./usage-tracker.js";
 /** Parsed skill block from a user message */
 export interface ParsedSkillBlock {
     name: string;
@@ -86,6 +88,8 @@ export interface AgentSessionConfig {
     extensionRunnerRef?: {
         current?: ExtensionRunner;
     };
+    /** Optional global usage tracker for day/month/total stats */
+    usageTracker?: UsageTracker;
 }
 export interface ExtensionBindings {
     uiContext?: ExtensionUIContext;
@@ -169,6 +173,7 @@ export declare class AgentSession {
     private _modelRegistry;
     private _toolRegistry;
     private _baseSystemPrompt;
+    private _usageTracker?;
     constructor(config: AgentSessionConfig);
     /** Model registry for API key resolution and model discovery */
     get modelRegistry(): ModelRegistry;
@@ -579,8 +584,15 @@ export declare class AgentSession {
     private _extractUserMessageText;
     /**
      * Get session statistics.
+     * Token and cost totals are computed from session entries (same as footer) so they
+     * remain accurate after compaction. Message counts and tool counts use in-memory state.
      */
     getSessionStats(): SessionStats;
+    /**
+     * Get global usage statistics (by day, by month, total).
+     * Returns empty stats if no usage tracker is configured.
+     */
+    getUsageStats(): UsageStats;
     getContextUsage(): ContextUsage | undefined;
     /**
      * Export session to HTML.

package/dist/core/agent-session.js

@@ -118,6 +118,7 @@ export class AgentSession {
     _toolRegistry = new Map();
     // Base system prompt (without extension appends) - used to apply fresh appends each turn
     _baseSystemPrompt = "";
+    _usageTracker;
     constructor(config) {
         this.agent = config.agent;
         this.sessionManager = config.sessionManager;
@@ -131,6 +132,7 @@ export class AgentSession {
         this._soulManager = config.soulManager;
         this._initialActiveToolNames = config.initialActiveToolNames;
         this._baseToolsOverride = config.baseToolsOverride;
+        this._usageTracker = config.usageTracker;
         // Always subscribe to agent events for internal handling
         // (session persistence, extensions, auto-compaction, retry logic)
         this._unsubscribeAgent = this.agent.subscribe(this._handleAgentEvent);
@@ -196,9 +198,11 @@ export class AgentSession {
             // Track assistant message for auto-compaction (checked on agent_end)
             if (event.message.role === "assistant") {
                 this._lastAssistantMessage = event.message;
+                // Record global usage for day/month/total stats
+                const assistantMsg = event.message;
+                this._usageTracker?.record(assistantMsg.usage, assistantMsg.timestamp);
                 // Reset retry counter immediately on successful assistant response
                 // This prevents accumulation across multiple LLM calls within a turn
-                const assistantMsg = event.message;
                 if (assistantMsg.stopReason !== "error" && this._retryAttempt > 0) {
                     this._emit({
                         type: "auto_retry_end",
@@ -2354,6 +2358,8 @@ export class AgentSession {
     }
     /**
      * Get session statistics.
+     * Token and cost totals are computed from session entries (same as footer) so they
+     * remain accurate after compaction. Message counts and tool counts use in-memory state.
      */
     getSessionStats() {
         const state = this.state;
@@ -2366,10 +2372,10 @@ export class AgentSession {
         let totalCacheRead = 0;
         let totalCacheWrite = 0;
         let totalCost = 0;
-        for (const message of state.messages) {
-            if (message.role === "assistant") {
-                const assistantMsg = message;
-                toolCalls += assistantMsg.content.filter((c) => c.type === "toolCall").length;
+        // Use entries for token/cost so totals match footer and persist after compaction
+        for (const entry of this.sessionManager.getEntries()) {
+            if (entry.type === "message" && entry.message.role === "assistant") {
+                const assistantMsg = entry.message;
                 totalInput += assistantMsg.usage.input;
                 totalOutput += assistantMsg.usage.output;
                 totalCacheRead += assistantMsg.usage.cacheRead;
@@ -2377,6 +2383,13 @@ export class AgentSession {
                 totalCost += assistantMsg.usage.cost.total;
             }
         }
+        // Tool call count from state (entries don't change this)
+        for (const message of state.messages) {
+            if (message.role === "assistant") {
+                const assistantMsg = message;
+                toolCalls += assistantMsg.content.filter((c) => c.type === "toolCall").length;
+            }
+        }
         return {
             sessionFile: this.sessionFile,
             sessionId: this.sessionId,
@@ -2395,6 +2408,20 @@ export class AgentSession {
             cost: totalCost,
         };
     }
+    /**
+     * Get global usage statistics (by day, by month, total).
+     * Returns empty stats if no usage tracker is configured.
+     */
+    getUsageStats() {
+        if (!this._usageTracker) {
+            return {
+                total: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 },
+                byDay: {},
+                byMonth: {},
+            };
+        }
+        return this._usageTracker.getUsageStats();
+    }
     getContextUsage() {
         const model = this.model;
         if (!model)

package/dist/core/index.d.ts

@@ -2,6 +2,8 @@
  * Core modules shared between all run modes.
  */
 export { AgentSession, type AgentSessionConfig, type AgentSessionEvent, type AgentSessionEventListener, type ModelCycleResult, type PromptOptions, type SessionStats, } from "./agent-session.js";
+export type { UsageStats, UsageTotals } from "./usage-tracker.js";
+export { UsageTracker } from "./usage-tracker.js";
 export { type BashExecutorOptions, type BashResult, executeBash, executeBashWithOperations, } from "./bash-executor.js";
 export type { CompactionResult } from "./compaction/index.js";
 export { createEventBus, type EventBus, type EventBusController, } from "./event-bus.js";

package/dist/core/index.js

@@ -2,6 +2,7 @@
  * Core modules shared between all run modes.
  */
 export { AgentSession, } from "./agent-session.js";
+export { UsageTracker } from "./usage-tracker.js";
 export { executeBash, executeBashWithOperations, } from "./bash-executor.js";
 export { createEventBus, } from "./event-bus.js";
 // Extensions system

package/dist/core/sdk.js

@@ -12,6 +12,7 @@ import { DefaultResourceLoader } from "./resource-loader.js";
 import { SessionManager } from "./session-manager.js";
 import { SettingsManager } from "./settings-manager.js";
 import { time } from "./timings.js";
+import { UsageTracker } from "./usage-tracker.js";
 import { isSoulEnabled, createSoulManager, } from "./soul-integration.js";
 import { allTools, bashTool, codingTools, createBashTool, createCodingTools, createEditTool, createFindTool, createGrepTool, createLsTool, createReadOnlyTools, createReadTool, createWriteTool, editTool, findTool, grepTool, lsTool, readOnlyTools, readTool, writeTool, } from "./tools/index.js";
 export { 
@@ -275,6 +276,7 @@ export async function createAgentSession(options = {}) {
             console.warn(`Failed to initialize Soul: ${error}`);
         }
     }
+    const usageTracker = new UsageTracker(agentDir);
     const session = new AgentSession({
         agent,
         sessionManager,
@@ -287,6 +289,7 @@ export async function createAgentSession(options = {}) {
         initialActiveToolNames,
         extensionRunnerRef,
         soulManager,
+        usageTracker,
     });
     const extensionsResult = resourceLoader.getExtensions();
     return {

package/dist/core/slash-commands.js

@@ -17,6 +17,7 @@ export const BUILTIN_SLASH_COMMANDS = [
     { name: "copy", description: "Copy last agent message to clipboard" },
     { name: "name", description: "Set session display name" },
     { name: "session", description: "Show session info and stats" },
+    { name: "usage", description: "Show token usage (today, month, total)" },
     { name: "changelog", description: "Show changelog entries" },
     { name: "hotkeys", description: "Show all keyboard shortcuts" },
     { name: "fork", description: "Create a new fork from a previous message" },

package/dist/core/usage-tracker.d.ts

@@ -0,0 +1,39 @@
+import type { Usage } from "@pencil-agent/ai";
+export interface UsageTotals {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+}
+export interface UsageStats {
+    total: UsageTotals;
+    byDay: Record<string, UsageTotals>;
+    byMonth: Record<string, UsageTotals>;
+}
+/**
+ * Tracks token usage across all sessions and runs.
+ *
+ * Writes an append-only JSONL log (usage.jsonl) plus a small running total file
+ * (usage-total.json) for fast "global total" queries.
+ */
+export declare class UsageTracker {
+    private agentDir;
+    private usageLogPath;
+    private totalPath;
+    constructor(agentDir: string);
+    /**
+     * Record usage for a single assistant response.
+     *
+     * Safe to call frequently; errors are swallowed so as not to affect the agent.
+     */
+    record(usage: Usage, timestampMs?: number): void;
+    /**
+     * Get aggregated usage statistics:
+     * - total: global totals across all time
+     * - byDay: grouped by YYYY-MM-DD
+     * - byMonth: grouped by YYYY-MM
+     */
+    getUsageStats(): UsageStats;
+}
+//# sourceMappingURL=usage-tracker.d.ts.map

package/dist/core/usage-tracker.js

@@ -0,0 +1,168 @@
+import { mkdirSync, existsSync, readFileSync, writeFileSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+function emptyTotals() {
+    return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+}
+function addInto(target, delta) {
+    target.input += delta.input;
+    target.output += delta.output;
+    target.cacheRead += delta.cacheRead;
+    target.cacheWrite += delta.cacheWrite;
+    target.cost += delta.cost;
+}
+/**
+ * Tracks token usage across all sessions and runs.
+ *
+ * Writes an append-only JSONL log (usage.jsonl) plus a small running total file
+ * (usage-total.json) for fast "global total" queries.
+ */
+export class UsageTracker {
+    agentDir;
+    usageLogPath;
+    totalPath;
+    constructor(agentDir) {
+        this.agentDir = agentDir;
+        this.usageLogPath = join(agentDir, "usage.jsonl");
+        this.totalPath = join(agentDir, "usage-total.json");
+    }
+    /**
+     * Record usage for a single assistant response.
+     *
+     * Safe to call frequently; errors are swallowed so as not to affect the agent.
+     */
+    record(usage, timestampMs) {
+        try {
+            // Ensure base directory exists
+            if (!existsSync(this.agentDir)) {
+                mkdirSync(this.agentDir, { recursive: true });
+            }
+            const date = timestampMs ? new Date(timestampMs) : new Date();
+            const iso = date.toISOString();
+            const day = iso.slice(0, 10); // YYYY-MM-DD
+            const month = iso.slice(0, 7); // YYYY-MM
+            const delta = {
+                input: usage.input ?? 0,
+                output: usage.output ?? 0,
+                cacheRead: usage.cacheRead ?? 0,
+                cacheWrite: usage.cacheWrite ?? 0,
+                cost: usage.cost?.total ?? 0,
+            };
+            // Append one line to usage.jsonl
+            const logEntry = JSON.stringify({
+                date: day,
+                month,
+                input: delta.input,
+                output: delta.output,
+                cacheRead: delta.cacheRead,
+                cacheWrite: delta.cacheWrite,
+                cost: delta.cost,
+            });
+            appendFileSync(this.usageLogPath, logEntry + "\n");
+            // Update running total (best-effort)
+            let total = emptyTotals();
+            if (existsSync(this.totalPath)) {
+                try {
+                    const raw = readFileSync(this.totalPath, "utf8");
+                    const parsed = JSON.parse(raw);
+                    total = {
+                        input: parsed.input ?? 0,
+                        output: parsed.output ?? 0,
+                        cacheRead: parsed.cacheRead ?? 0,
+                        cacheWrite: parsed.cacheWrite ?? 0,
+                        cost: parsed.cost ?? 0,
+                    };
+                }
+                catch {
+                    // Ignore parse errors and start fresh
+                    total = emptyTotals();
+                }
+            }
+            addInto(total, delta);
+            writeFileSync(this.totalPath, JSON.stringify(total));
+        }
+        catch {
+            // Swallow all errors - usage tracking must never break the agent
+        }
+    }
+    /**
+     * Get aggregated usage statistics:
+     * - total: global totals across all time
+     * - byDay: grouped by YYYY-MM-DD
+     * - byMonth: grouped by YYYY-MM
+     */
+    getUsageStats() {
+        const total = emptyTotals();
+        const byDay = Object.create(null);
+        const byMonth = Object.create(null);
+        // Load global total if available
+        if (existsSync(this.totalPath)) {
+            try {
+                const raw = readFileSync(this.totalPath, "utf8");
+                const parsed = JSON.parse(raw);
+                total.input = parsed.input ?? 0;
+                total.output = parsed.output ?? 0;
+                total.cacheRead = parsed.cacheRead ?? 0;
+                total.cacheWrite = parsed.cacheWrite ?? 0;
+                total.cost = parsed.cost ?? 0;
+            }
+            catch {
+                // Ignore and fall back to computing from log
+                total.input = 0;
+                total.output = 0;
+                total.cacheRead = 0;
+                total.cacheWrite = 0;
+                total.cost = 0;
+            }
+        }
+        if (existsSync(this.usageLogPath)) {
+            try {
+                const raw = readFileSync(this.usageLogPath, "utf8");
+                const lines = raw.split("\n");
+                for (const line of lines) {
+                    const trimmed = line.trim();
+                    if (!trimmed)
+                        continue;
+                    let entry;
+                    try {
+                        entry = JSON.parse(trimmed);
+                    }
+                    catch {
+                        continue;
+                    }
+                    const day = typeof entry.date === "string" ? entry.date : undefined;
+                    const month = typeof entry.month === "string" ? entry.month : undefined;
+                    const delta = {
+                        input: Number(entry.input) || 0,
+                        output: Number(entry.output) || 0,
+                        cacheRead: Number(entry.cacheRead) || 0,
+                        cacheWrite: Number(entry.cacheWrite) || 0,
+                        cost: Number(entry.cost) || 0,
+                    };
+                    // If total file was missing or corrupt, rebuild it from log
+                    if (!existsSync(this.totalPath)) {
+                        addInto(total, delta);
+                    }
+                    if (day) {
+                        if (!byDay[day])
+                            byDay[day] = emptyTotals();
+                        addInto(byDay[day], delta);
+                    }
+                    if (month) {
+                        if (!byMonth[month])
+                            byMonth[month] = emptyTotals();
+                        addInto(byMonth[month], delta);
+                    }
+                }
+                // If we had to rebuild total, persist it for next time
+                if (!existsSync(this.totalPath)) {
+                    writeFileSync(this.totalPath, JSON.stringify(total));
+                }
+            }
+            catch {
+                // Ignore log read errors
+            }
+        }
+        return { total, byDay, byMonth };
+    }
+}
+//# sourceMappingURL=usage-tracker.js.map

package/dist/modes/interactive/components/footer.js

@@ -197,6 +197,33 @@ export class FooterComponent {
         const remainder = statsLine.slice(statsLeft.length); // padding + rightSide
         const dimRemainder = theme.fg("dim", remainder);
         const lines = [theme.fg("dim", pwd), dimStatsLeft + dimRemainder];
+        // Global usage line: Today | Month | Total (only when any has data)
+        const usageStats = this.session.getUsageStats();
+        const todayKey = new Date().toISOString().slice(0, 10);
+        const monthKey = new Date().toISOString().slice(0, 7);
+        const today = usageStats.byDay[todayKey];
+        const month = usageStats.byMonth[monthKey];
+        const total = usageStats.total;
+        const hasGlobal = (today && (today.input > 0 || today.output > 0)) ||
+            (month && (month.input > 0 || month.output > 0)) ||
+            total.input > 0 ||
+            total.output > 0;
+        if (hasGlobal) {
+            const seg = (label, t) => `${label}: ↑${formatTokens(t.input)} ↓${formatTokens(t.output)}`;
+            const parts = [];
+            if (today && (today.input > 0 || today.output > 0)) {
+                parts.push(seg("Today", today));
+            }
+            if (month && (month.input > 0 || month.output > 0)) {
+                parts.push(seg("Month", month));
+            }
+            if (total.input > 0 || total.output > 0) {
+                parts.push(seg("Total", total));
+            }
+            if (parts.length > 0) {
+                lines.push(theme.fg("dim", truncateToWidth(parts.join(" | "), width, theme.fg("dim", "..."))));
+            }
+        }
         // Add extension statuses on a single line, sorted by key alphabetically
         const extensionStatuses = this.footerData.getExtensionStatuses();
         if (extensionStatuses.size > 0) {

package/dist/modes/interactive/interactive-mode.d.ts

@@ -302,6 +302,7 @@ export declare class InteractiveMode {
     private handleCopyCommand;
     private handleNameCommand;
     private handleSessionCommand;
+    private handleUsageCommand;
     private handleChangelogCommand;
     /**
      * Capitalize keybinding for display (e.g., "ctrl+c" -> "Ctrl+C").

package/dist/modes/interactive/interactive-mode.js

@@ -1579,6 +1579,11 @@ export class InteractiveMode {
                 this.editor.setText("");
                 return;
             }
+            if (text === "/usage") {
+                this.handleUsageCommand();
+                this.editor.setText("");
+                return;
+            }
             if (text === "/changelog") {
                 this.handleChangelogCommand();
                 this.editor.setText("");
@@ -3594,6 +3599,33 @@ export class InteractiveMode {
         this.chatContainer.addChild(new Text(info, 1, 0));
         this.ui.requestRender();
     }
+    handleUsageCommand() {
+        const stats = this.session.getUsageStats();
+        const todayKey = new Date().toISOString().slice(0, 10);
+        const monthKey = new Date().toISOString().slice(0, 7);
+        const today = stats.byDay[todayKey] ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+        const month = stats.byMonth[monthKey] ?? { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0 };
+        const total = stats.total;
+        const formatBlock = (label, t) => {
+            let block = `${theme.bold(label)}\n`;
+            block += `${theme.fg("dim", "Input:")} ${t.input.toLocaleString()}\n`;
+            block += `${theme.fg("dim", "Output:")} ${t.output.toLocaleString()}\n`;
+            if (t.cacheRead > 0)
+                block += `${theme.fg("dim", "Cache Read:")} ${t.cacheRead.toLocaleString()}\n`;
+            if (t.cacheWrite > 0)
+                block += `${theme.fg("dim", "Cache Write:")} ${t.cacheWrite.toLocaleString()}\n`;
+            if (t.cost > 0)
+                block += `${theme.fg("dim", "Cost:")} $${t.cost.toFixed(4)}\n`;
+            return block;
+        };
+        let info = `${theme.bold("Token Usage")}\n\n`;
+        info += formatBlock("Today", today) + "\n";
+        info += formatBlock("This Month", month) + "\n";
+        info += formatBlock("Total", total);
+        this.chatContainer.addChild(new Spacer(1));
+        this.chatContainer.addChild(new Text(info, 1, 0));
+        this.ui.requestRender();
+    }
     handleChangelogCommand() {
         const changelogPath = getChangelogPath();
         const allEntries = parseChangelog(changelogPath);

package/dist/modes/print-mode.js

@@ -85,6 +85,22 @@ export async function runPrintMode(session, options) {
                     console.log(content.text);
                 }
             }
+            // Output token usage for this response
+            const u = assistantMsg.usage;
+            if (u.input > 0 || u.output > 0 || u.cacheRead > 0 || u.cacheWrite > 0 || (u.cost?.total ?? 0) > 0) {
+                const parts = [];
+                if (u.input > 0)
+                    parts.push(`input ${u.input.toLocaleString()}`);
+                if (u.output > 0)
+                    parts.push(`output ${u.output.toLocaleString()}`);
+                if (u.cacheRead > 0)
+                    parts.push(`cacheRead ${u.cacheRead.toLocaleString()}`);
+                if (u.cacheWrite > 0)
+                    parts.push(`cacheWrite ${u.cacheWrite.toLocaleString()}`);
+                if (u.cost?.total != null && u.cost.total > 0)
+                    parts.push(`cost $${u.cost.total.toFixed(4)}`);
+                console.error(`Tokens: ${parts.join(", ")}`);
+            }
         }
     }
     // Ensure stdout is fully flushed before returning

package/dist/modes/rpc/rpc-client.d.ts

@@ -6,6 +6,7 @@
 import type { AgentEvent, AgentMessage, ThinkingLevel } from "@pencil-agent/agent-core";
 import type { ImageContent } from "@pencil-agent/ai";
 import type { SessionStats } from "../../core/agent-session.js";
+import type { UsageStats } from "../../core/usage-tracker.js";
 import type { BashResult } from "../../core/bash-executor.js";
 import type { CompactionResult } from "../../core/compaction/index.js";
 import type { RpcSessionState, RpcSlashCommand } from "./rpc-types.js";
@@ -153,6 +154,10 @@ export declare class RpcClient {
      * Get session statistics.
      */
     getSessionStats(): Promise<SessionStats>;
+    /**
+     * Get global token usage statistics (today, by month, total).
+     */
+    getUsageStats(): Promise<UsageStats>;
     /**
      * Export session to HTML.
      */

package/dist/modes/rpc/rpc-client.js

@@ -237,6 +237,13 @@ export class RpcClient {
         const response = await this.send({ type: "get_session_stats" });
         return this.getData(response);
     }
+    /**
+     * Get global token usage statistics (today, by month, total).
+     */
+    async getUsageStats() {
+        const response = await this.send({ type: "get_usage_stats" });
+        return this.getData(response);
+    }
     /**
      * Export session to HTML.
      */

package/dist/modes/rpc/rpc-mode.js

@@ -384,6 +384,10 @@ export async function runRpcMode(session) {
                 const stats = session.getSessionStats();
                 return success(id, "get_session_stats", stats);
             }
+            case "get_usage_stats": {
+                const usageStats = session.getUsageStats();
+                return success(id, "get_usage_stats", usageStats);
+            }
             case "export_html": {
                 const path = await session.exportToHtml(command.outputPath);
                 return success(id, "export_html", { path });

package/dist/modes/rpc/rpc-types.d.ts

@@ -7,6 +7,7 @@
 import type { AgentMessage, ThinkingLevel } from "@pencil-agent/agent-core";
 import type { ImageContent, Model } from "@pencil-agent/ai";
 import type { SessionStats } from "../../core/agent-session.js";
+import type { UsageStats } from "../../core/usage-tracker.js";
 import type { BashResult } from "../../core/bash-executor.js";
 import type { CompactionResult } from "../../core/compaction/index.js";
 export type RpcCommand = {
@@ -86,6 +87,9 @@ export type RpcCommand = {
 } | {
     id?: string;
     type: "get_session_stats";
+} | {
+    id?: string;
+    type: "get_usage_stats";
 } | {
     id?: string;
     type: "export_html";
@@ -261,6 +265,12 @@ export type RpcResponse = {
     command: "get_session_stats";
     success: true;
     data: SessionStats;
+} | {
+    id?: string;
+    type: "response";
+    command: "get_usage_stats";
+    success: true;
+    data: UsageStats;
 } | {
     id?: string;
     type: "response";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pencil-agent/nano-pencil",
-  "version": "1.9.4",
+  "version": "1.9.5",
   "description": "CLI writing agent with read, bash, edit, write tools and session management. Based on pi; supports DashScope Coding Plan. Soul enabled by default for AI personality evolution.",
   "type": "module",
   "bin": {