@kunal_dutt/token-lens 0.2.28 → 0.2.29

package/types/src/core/coach.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Plan coach: helps people get the most out of the subscription they pay for,
+ * on the model they already use. Where a usage meter only says "62% used",
+ * this says where the usage went, how many more messages are left at the
+ * current pace, what is draining it, and what to do before it runs out.
+ *
+ * It also catches sends that cost a lot and do no work (a "thanks" in a long
+ * chat re-reads the whole chat; a question already answered above) before
+ * they are sent. Nothing here changes what the model is asked or answers:
+ * every insight is about the person's own choice to send, and moving to a
+ * new chat is always optional.
+ *
+ * Pure and platform-free: the Mac watcher feeds it what it reads, and only
+ * numbers and short hashes are kept (never text).
+ */
+import { type Plan } from "./plans";
+/** Claude's 5-hour session window. */
+export declare const SESSION_MS: number;
+/** FNV-1a, so "seen before" needs no copy of the text. */
+export declare function shortHash(s: string): string;
+/** Plan named in Claude's own window, e.g. the "Max plan" under your name in the sidebar. */
+export declare function planFromClaudeWindow(text: string): Plan | null;
+export interface UsageReading {
+    /** When it was read (ms). */
+    at: number;
+    sessionPct?: number;
+    /** When the session window resets (ms), if the page said. */
+    sessionResetsAt?: number;
+    weekPct?: number;
+    weekResetsAt?: number;
+    /** Words as shown, e.g. "Thu 9:00 AM". */
+    weekResetsText?: string;
+}
+/**
+ * Claude's usage page (Settings > Usage) or a usage banner, as read from the
+ * window: "Current session … Resets in 3 hr 20 min … 45% used", "Weekly
+ * limits … All models … Resets Thu 9:00 AM … 30% used". Null if it isn't one.
+ */
+export declare function readClaudeUsagePage(text: string, now: number): UsageReading | null;
+export interface Send {
+    at: number;
+    /** Tokens the message made the model read: the chat it re-read plus the message. */
+    tokens: number;
+    /** Hash of the chat it was sent in. */
+    chat: string;
+}
+/** Everything the coach keeps between restarts: numbers and hashes only. */
+export interface CoachData {
+    sends: Send[];
+    readings: UsageReading[];
+    /** Session % per 1,000 tokens read, learned from two meter readings. */
+    pctPer1k?: number;
+}
+export interface ChatShare {
+    chat: string;
+    title?: string;
+    tokens: number;
+    messages: number;
+    share: number;
+}
+export interface CoachReport {
+    plan: Plan | null;
+    planSource: "set" | "app" | "unknown";
+    session: {
+        messages: number;
+        tokens: number;
+        since: number;
+    };
+    week: {
+        messages: number;
+        tokens: number;
+    };
+    /** Latest meter reading, carried forward by what was sent since. */
+    sessionPct?: number;
+    sessionResetsAt?: number;
+    weekPct?: number;
+    weekResetsAt?: number;
+    weekResetsText?: string;
+    meterAgeMin?: number;
+    /** Messages left before the session limit, at the current chat's size and in a fresh chat. */
+    left?: {
+        here: number;
+        fresh: number;
+    };
+    topChats: ChatShare[];
+    /** One line per insight, most useful first. */
+    insights: string[];
+}
+export interface CoachInput {
+    data: CoachData;
+    now: number;
+    plan: Plan | null;
+    planSource: CoachReport["planSource"];
+    /** The chat open now: its hash, title and size. */
+    current?: {
+        chat: string;
+        title?: string;
+        tokens: number;
+    };
+    /** Titles by chat hash, from this run (never saved). */
+    titles?: Map<string, string>;
+}
+/** Keep a week of sends and a session's worth of readings. */
+export declare function prune(data: CoachData, now: number): CoachData;
+/** Add a meter reading, learning how much of the session each 1,000 tokens uses. */
+export declare function addReading(data: CoachData, r: UsageReading): CoachData;
+export declare function coach(input: CoachInput): CoachReport;
+/** A message that asks for nothing new, so sending it only re-reads the chat. */
+export declare function isAcknowledgement(draft: string): boolean;
+/** True when this draft was already sent in the chat (its answer is above). */
+export declare function askedBefore(draft: string, chatText: string): boolean;
+/** Paragraph hashes of a long draft, for spotting the same text pasted into chat after chat. */
+export declare function pasteBlocks(draft: string): string[];

package/types/src/core/index.d.ts

@@ -10,6 +10,7 @@ import { type ModelPricing, type ModelProfile } from "./models";
 import { type TaskInfo } from "./tasks";
 export * from "./advice";
 export * from "./budget";
+export * from "./coach";
 export * from "./compress";
 export * from "./cost";
 export * from "./compare";