@tspappsen/elamax 1.2.6 → 1.2.7

package/README.md

@@ -162,7 +162,7 @@ When developing locally, `npm run dev` starts the daemon in watch mode, but it d
 
 ```bash
 # One-time install
-git clone https://github.com/burkeholland/max.git
+git clone https://github.com/lauraeus/max-assistant.git
 cd max
 npm install
 
@@ -242,11 +242,12 @@ Max-Watchdog is a second, ops-only Max instance that monitors and repairs the ma
 │  @MaxBot on Telegram   │     │  Port 7778              │
 │  General-purpose AI    │     │  @WatchdogBot           │
 │  Skills, workers, etc. │     │  Ops-only: health,      │
-└────────────────────────┘     │  restart, logs, shell   │
+│  Usage ledger          │     │  restart, logs, usage   │
+└────────────────────────┘     │  reporting, shell       │
                                └─────────────────────────┘
 ```
 
-Two fully isolated instances: separate home directories, separate SQLite databases, separate bot tokens, separate ports, separate pm2 processes. Zero shared state.
+Two mostly isolated instances: separate home directories, separate primary SQLite databases, separate bot tokens, separate ports, and separate pm2 processes. For premium-usage reporting, watchdog may open the main Max SQLite database in **read-only** mode via `MAIN_MAX_HOME` to query the append-only `request_usage` ledger. Watchdog never writes to main Max's DB.
 
 ### Watchdog setup
 
@@ -273,6 +274,8 @@ The watchdog has its own Copilot-powered AI session with these ops tools:
 | Tool | Description |
 |------|-------------|
 | `check_main_max` | Check if main Max is running (pm2 status + HTTP health) |
+| `get_main_usage_summary` | Summarize estimated request usage from main Max over `today`, `24h`, `7d`, or `30d` |
+| `get_main_premium_usage` | Show estimated premium usage plus recent premium-billed events from main Max |
 | `restart_main_max` | Restart the main Max pm2 process |
 | `read_main_logs` | Read the last N lines of main Max's daemon log |
 | `server_health` | Report hostname, uptime, memory, disk, load average |
@@ -281,6 +284,46 @@ The watchdog has its own Copilot-powered AI session with these ops tools:
 
 The watchdog does **not** have workers, skills, or long-term memory — it's purpose-built for ops.
 
+### Premium usage tracking
+
+Main Max now records a compact per-turn usage ledger in its local SQLite database. Each completed turn stores metadata such as:
+
+- selected `model`
+- routed `tier` (`fast`, `standard`, `premium`, or `null`)
+- routing `reason`
+- `billingMultiplier`
+- whether the turn was a routed premium turn and/or an estimated premium-billed turn
+- prompt/response character counts
+
+This ledger is intentionally **metadata-only** — it does not store raw prompt or response bodies for usage accounting.
+
+Watchdog reads this ledger from main Max in **read-only** mode and can answer questions like:
+
+- "How many premium requests did Max use today?"
+- "Which model consumed the most premium traffic this week?"
+- "Show me recent premium-billed events"
+
+Premium usage is reported as a **best-effort estimate** based on route decisions and Copilot model metadata (`billing.multiplier`). It is useful for ops visibility, but it is **not** an authoritative GitHub billing ledger.
+
+### Example prompts
+
+You usually do **not** need to name the underlying tool. Ask in plain English and let Max-Watchdog choose the right action.
+
+Examples:
+
+- "Show premium usage today."
+- "How many premium requests did Max use in the last 24 hours?"
+- "Give me a 7-day usage summary."
+- "Which model consumed the most premium traffic this week?"
+- "Show recent premium-billed events."
+
+If you want to be more explicit, these also work:
+
+- "Run `get_main_usage_summary` for `today`."
+- "Run `get_main_usage_summary` for `7d`."
+- "Run `get_main_premium_usage` for `24h`."
+- "Run `get_main_premium_usage` for `today` with 10 recent events."
+
 ### Dual-instance pm2 deployment
 
 ```bash
@@ -313,5 +356,5 @@ Watchdog: "Main Max is back online (pid 4521)."
 | `MAX_PROFILE` | _(unset)_ | Profile name; `watchdog` for the ops instance |
 | `MAX_HOME` | `~/.max` or `~/.max-<profile>` | Override the home directory |
 | `MAIN_MAX_PM2_NAME` | `max` | pm2 process name of the main Max instance |
-| `MAIN_MAX_HOME` | `~/.max` | Home directory of the main Max instance |
+| `MAIN_MAX_HOME` | `~/.max` | Home directory of the main Max instance; watchdog uses this to read logs and query the main usage ledger read-only |
 | `MAIN_MAX_API_PORT` | `7777` | HTTP API port of the main Max instance |

package/dist/copilot/classifier.js

@@ -8,7 +8,7 @@ const SYSTEM_PROMPT = `You are a message complexity classifier for an AI assista
 
 Tiers:
 - FAST: Greetings, thanks, acknowledgments, simple yes/no, trivial factual questions ("what time is it?", "hello", "thanks"), casual chat with no technical depth.
-- STANDARD: Coding tasks, file operations, tool usage requests, moderate reasoning, questions about technical topics, requests to create/check/manage things, anything involving code or development workflow.
+- STANDARD: Coding tasks, file operations, tool usage requests, moderate reasoning, questions about technical topics, requests to create/check/manage things, anything involving code or development workflow. Short operational/reporting requests like "show premium usage today", "run get_main_usage_summary for today", or "show recent premium-billed events" are ALWAYS STANDARD.
 - PREMIUM: Complex architecture decisions, deep analysis, multi-step reasoning, comparing trade-offs, detailed explanations of complex topics, debugging intricate issues, designing systems, strategic planning.
 
 Rules:

package/dist/copilot/client.js

@@ -1,5 +1,24 @@
 import { CopilotClient } from "@github/copilot-sdk";
 let client;
+// Billing multiplier cache — populated at init, refreshed on reset
+const modelMultiplierCache = new Map();
+/** Populate the billing multiplier cache from the SDK model catalog. */
+export async function populateModelCache(c) {
+    try {
+        const models = await c.listModels();
+        modelMultiplierCache.clear();
+        for (const m of models) {
+            modelMultiplierCache.set(m.id, m.billing?.multiplier ?? 0);
+        }
+    }
+    catch (err) {
+        console.log(`[max] Failed to populate model cache: ${err instanceof Error ? err.message : err}`);
+    }
+}
+/** Get the billing multiplier for a model. Returns 0 if unknown. */
+export function getBillingMultiplier(modelId) {
+    return modelMultiplierCache.get(modelId) ?? 0;
+}
 export async function getClient() {
     if (!client) {
         client = new CopilotClient({
@@ -19,6 +38,7 @@ export async function resetClient() {
         catch { /* best-effort */ }
         client = undefined;
     }
+    modelMultiplierCache.clear();
     return getClient();
 }
 export async function stopClient() {

package/dist/copilot/orchestrator.js

@@ -6,10 +6,11 @@ import { config, DEFAULT_MODEL } from "../config.js";
 import { loadMcpConfig } from "./mcp-config.js";
 import { getSkillDirectories } from "./skills.js";
 import { resetClient } from "./client.js";
-import { logConversation, getState, setState, deleteState, getMemorySummary, getRecentConversation } from "../store/db.js";
+import { logConversation, getState, setState, deleteState, getMemorySummary, getRecentConversation, logUsageEvent } from "../store/db.js";
 import { IS_WATCHDOG, INSTRUCTIONS_DIR, SESSIONS_DIR } from "../paths.js";
 import { resolveModel } from "./router.js";
 import { watchInstructions, seedDefaultInstructions } from "./workspace-instructions.js";
+import { getBillingMultiplier, populateModelCache } from "./client.js";
 const MAX_RETRIES = 3;
 const RECONNECT_DELAYS_MS = [1_000, 3_000, 10_000];
 const HEALTH_CHECK_INTERVAL_MS = 30_000;
@@ -244,6 +245,8 @@ export async function initOrchestrator(client) {
     catch (err) {
         console.log(`[max] Could not validate model (will use '${config.copilotModel}' as-is): ${err instanceof Error ? err.message : err}`);
     }
+    // Populate billing multiplier cache for usage tracking
+    await populateModelCache(client);
     console.log(`[max] Loading ${Object.keys(mcpServers).length} MCP server(s): ${Object.keys(mcpServers).join(", ") || "(none)"}`);
     console.log(`[max] Skill directories: ${skillDirectories.join(", ") || "(none)"}`);
     console.log(`[max] Persistent session mode — conversation history maintained by SDK`);
@@ -327,6 +330,7 @@ async function processQueue() {
                     tier: null,
                     switched: false,
                     routerMode: "manual",
+                    reason: "attachments",
                 };
             }
             else {
@@ -406,6 +410,26 @@ export async function sendToOrchestrator(prompt, source, callback, options) {
                     logConversation("assistant", finalContent, sourceLabel);
                 }
                 catch { /* best-effort */ }
+                // Record usage event for premium tracking
+                try {
+                    const route = getLastRouteResult();
+                    if (route) {
+                        const multiplier = getBillingMultiplier(route.model);
+                        logUsageEvent({
+                            source: sourceLabel,
+                            model: route.model,
+                            tier: route.tier,
+                            routerMode: route.routerMode,
+                            reason: route.reason,
+                            billingMultiplier: multiplier,
+                            isPremiumTier: route.tier === "premium",
+                            isPremiumBilledEstimate: multiplier > 0,
+                            promptChars: prompt.length,
+                            responseChars: finalContent.length,
+                        });
+                    }
+                }
+                catch { /* best-effort — never fail the hot path */ }
                 return;
             }
             catch (err) {

package/dist/copilot/router.js

@@ -33,6 +33,15 @@ const FOLLOW_UP_PATTERNS = [
     "perfect", "+1", "please", "yep", "yup", "nope", "nah", "ok", "okay",
     "got it", "cool", "nice", "great", "alright", "right",
 ];
+const SIMPLE_USAGE_TOOL_PATTERNS = [
+    /\bget_main_usage_summary\b/i,
+    /\bget_main_premium_usage\b/i,
+    /\bshow\b.*\bpremium usage\b/i,
+    /\bshow\b.*\busage summary\b/i,
+    /\bhow many\b.*\bpremium requests\b/i,
+    /\brecent premium-billed events?\b/i,
+    /\bwhich model\b.*\bpremium traffic\b/i,
+];
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -49,6 +58,11 @@ function wordMatch(text, keyword) {
     const escaped = keyword.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
     return new RegExp(`\\b${escaped}\\b`, "i").test(text);
 }
+function isSimpleUsageToolRequest(text) {
+    if (text.length > 200)
+        return false;
+    return SIMPLE_USAGE_TOOL_PATTERNS.some((pattern) => pattern.test(text));
+}
 // ---------------------------------------------------------------------------
 // Config management
 // ---------------------------------------------------------------------------
@@ -90,24 +104,28 @@ async function classifyMessage(prompt, recentTiers, client) {
     const lower = text.toLowerCase();
     // Background tasks → always standard
     if (lower.startsWith("[background task completed]"))
-        return "standard";
+        return { tier: "standard", reason: "background" };
     // Short follow-ups inherit the previous tier
     if (text.length < 20 && recentTiers.length > 0) {
         const isFollowUp = FOLLOW_UP_PATTERNS.some((p) => lower === p || lower === p + ".");
         if (isFollowUp)
-            return recentTiers[0];
+            return { tier: recentTiers[0], reason: "follow-up" };
+    }
+    // Short reporting / tool-invocation prompts should never burn premium.
+    if (isSimpleUsageToolRequest(text)) {
+        return { tier: "standard", reason: "usage-tool" };
     }
     // LLM classification
     if (client) {
         const tier = await classifyWithLLM(client, text);
         if (tier) {
             console.log(`[max] Classifier: ${tier}`);
-            return tier;
+            return { tier, reason: "classifier" };
         }
     }
     // Fallback — standard is always safe
     console.log(`[max] Classifier (fallback): standard`);
-    return "standard";
+    return { tier: "standard", reason: "fallback" };
 }
 // ---------------------------------------------------------------------------
 // Main entry point
@@ -117,7 +135,7 @@ export async function resolveModel(prompt, currentModel, recentTiers, client) {
     // Router disabled → manual mode
     if (!config.enabled) {
         messagesSinceSwitch = Infinity;
-        return { model: currentModel, tier: null, switched: false, routerMode: "manual" };
+        return { model: currentModel, tier: null, switched: false, routerMode: "manual", reason: "manual" };
     }
     const text = sanitize(prompt);
     // 1. Check overrides first — they bypass cooldown
@@ -126,22 +144,22 @@ export async function resolveModel(prompt, currentModel, recentTiers, client) {
             const switched = rule.model !== currentModel;
             if (switched)
                 messagesSinceSwitch = 0;
-            return { model: rule.model, tier: null, overrideName: rule.name, switched, routerMode: "auto" };
+            return { model: rule.model, tier: null, overrideName: rule.name, switched, routerMode: "auto", reason: `override:${rule.name}` };
         }
     }
     // 2. Classify the message
-    const tier = await classifyMessage(prompt, recentTiers, client);
+    const { tier, reason: classificationReason } = await classifyMessage(prompt, recentTiers, client);
     const targetModel = config.tierModels[tier];
     const wouldSwitch = targetModel !== currentModel;
     // 3. Cooldown — prevent rapid switching
     if (wouldSwitch && messagesSinceSwitch < config.cooldownMessages) {
         messagesSinceSwitch++;
-        return { model: currentModel, tier, switched: false, routerMode: "auto" };
+        return { model: currentModel, tier, switched: false, routerMode: "auto", reason: "cooldown" };
     }
     if (wouldSwitch)
         messagesSinceSwitch = 0;
     else
         messagesSinceSwitch++;
-    return { model: targetModel, tier, switched: wouldSwitch, routerMode: "auto" };
+    return { model: targetModel, tier, switched: wouldSwitch, routerMode: "auto", reason: classificationReason === "classifier" ? `tier:${tier}` : classificationReason };
 }
 //# sourceMappingURL=router.js.map

package/dist/copilot/watchdog-tools.js

@@ -7,6 +7,8 @@ import { existsSync, readFileSync } from "fs";
 import { join } from "path";
 import { hostname, uptime, totalmem, freemem, platform, loadavg } from "os";
 import http from "http";
+import Database from "better-sqlite3";
+import { getUsageSummary, getRecentUsage } from "../store/db.js";
 /** All known pm2 names for the watchdog's own process.
  * Includes the derived name (max-<profile>) AND the pm2-injected process name. */
 function getOwnPm2Names() {
@@ -158,6 +160,18 @@ function buildMainStatus(status, httpStatus) {
         http: httpStatus.detail,
     };
 }
+/** Open main Max's SQLite database in read-only mode for usage queries. */
+function openMainMaxDb() {
+    const dbPath = join(MAIN_MAX_HOME, "max.db");
+    if (!existsSync(dbPath))
+        return null;
+    try {
+        return new Database(dbPath, { readonly: true });
+    }
+    catch {
+        return null;
+    }
+}
 export function createWatchdogTools() {
     return [
         defineTool("check_main_max", {
@@ -307,6 +321,62 @@ export function createWatchdogTools() {
                 };
             },
         }),
+        defineTool("get_main_usage_summary", {
+            description: "Get a summary of main Max's request usage for a time window. Reports estimated premium usage — not authoritative GitHub billing.",
+            parameters: z.object({
+                window: z.enum(["today", "24h", "7d", "30d"]).default("today").describe("Time window for the summary"),
+            }),
+            handler: async (args) => {
+                const db = openMainMaxDb();
+                if (!db) {
+                    return { ok: false, error: `Main Max database not found at ${join(MAIN_MAX_HOME, "max.db")}. Main Max may not have started yet.` };
+                }
+                try {
+                    const summary = getUsageSummary(args.window, db);
+                    return { ok: true, ...summary };
+                }
+                catch (err) {
+                    return { ok: false, error: `Failed to query usage: ${err instanceof Error ? err.message : String(err)}` };
+                }
+                finally {
+                    db.close();
+                }
+            },
+        }),
+        defineTool("get_main_premium_usage", {
+            description: "Get recent premium request events from main Max with an optional summary. Reports estimated premium usage — not authoritative GitHub billing.",
+            parameters: z.object({
+                window: z.enum(["today", "24h", "7d", "30d"]).default("today").describe("Time window for the summary"),
+                limit: z.number().int().min(1).max(100).default(20).describe("Max recent premium events to return"),
+            }),
+            handler: async (args) => {
+                const db = openMainMaxDb();
+                if (!db) {
+                    return { ok: false, error: `Main Max database not found at ${join(MAIN_MAX_HOME, "max.db")}. Main Max may not have started yet.` };
+                }
+                try {
+                    const summary = getUsageSummary(args.window, db);
+                    const recentPremium = getRecentUsage(args.limit, { premiumOnly: true }, db);
+                    return {
+                        ok: true,
+                        summary: {
+                            window: summary.window,
+                            totalRequests: summary.totalRequests,
+                            premiumTierCount: summary.premiumTierCount,
+                            premiumBilledEstimateCount: summary.premiumBilledEstimateCount,
+                        },
+                        recentPremiumEvents: recentPremium,
+                        estimated: true,
+                    };
+                }
+                catch (err) {
+                    return { ok: false, error: `Failed to query usage: ${err instanceof Error ? err.message : String(err)}` };
+                }
+                finally {
+                    db.close();
+                }
+            },
+        }),
     ];
 }
 //# sourceMappingURL=watchdog-tools.js.map

package/dist/setup.js

@@ -10,7 +10,7 @@ const CYAN = "\x1b[36m";
 const RESET = "\x1b[0m";
 const FALLBACK_MODELS = [
     { id: "claude-sonnet-4.6", label: "Claude Sonnet 4.6", desc: "Fast, great for most tasks" },
-    { id: "gpt-5.1", label: "GPT-5.1", desc: "OpenAI's fast model" },
+    { id: "gpt-5.4", label: "GPT-5.4", desc: "OpenAI's fast model" },
     { id: "gpt-4.1", label: "GPT-4.1", desc: "Free included model" },
 ];
 async function fetchModels() {

package/dist/store/db.js

@@ -44,6 +44,23 @@ export function getDb() {
         last_accessed DATETIME DEFAULT CURRENT_TIMESTAMP
       )
     `);
+        db.exec(`
+      CREATE TABLE IF NOT EXISTS request_usage (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        ts DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        source TEXT NOT NULL,
+        model TEXT NOT NULL,
+        tier TEXT,
+        router_mode TEXT NOT NULL,
+        reason TEXT,
+        billing_multiplier REAL NOT NULL DEFAULT 0,
+        is_premium_tier INTEGER NOT NULL DEFAULT 0,
+        is_premium_billed_estimate INTEGER NOT NULL DEFAULT 0,
+        prompt_chars INTEGER NOT NULL DEFAULT 0,
+        response_chars INTEGER NOT NULL DEFAULT 0
+      )
+    `);
+        db.exec(`CREATE INDEX IF NOT EXISTS idx_request_usage_ts ON request_usage(ts)`);
         // Migrate: if the table already existed with a stricter CHECK, recreate it
         try {
             db.prepare(`INSERT INTO conversation_log (role, content, source) VALUES ('system', '__migration_test__', 'test')`).run();
@@ -66,6 +83,8 @@ export function getDb() {
         }
         // Prune conversation log at startup
         db.prepare(`DELETE FROM conversation_log WHERE id NOT IN (SELECT id FROM conversation_log ORDER BY id DESC LIMIT 200)`).run();
+        // Prune usage events older than 90 days
+        db.prepare(`DELETE FROM request_usage WHERE ts < datetime('now', '-90 days')`).run();
     }
     return db;
 }
@@ -164,6 +183,62 @@ export function getMemorySummary() {
     });
     return sections.join("\n");
 }
+export function logUsageEvent(event) {
+    const db = getDb();
+    db.prepare(`
+    INSERT INTO request_usage (source, model, tier, router_mode, reason, billing_multiplier, is_premium_tier, is_premium_billed_estimate, prompt_chars, response_chars)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(event.source, event.model, event.tier, event.routerMode, event.reason ?? null, event.billingMultiplier, event.isPremiumTier ? 1 : 0, event.isPremiumBilledEstimate ? 1 : 0, event.promptChars, event.responseChars);
+}
+/** Compute a usage summary for the given time window. */
+export function getUsageSummary(window, dbInstance) {
+    const d = dbInstance ?? getDb();
+    const windowStart = resolveWindowStart(window);
+    const totals = d.prepare(`
+    SELECT
+      COUNT(*) as total,
+      SUM(is_premium_tier) as premium_tier,
+      SUM(is_premium_billed_estimate) as premium_billed
+    FROM request_usage WHERE ts >= ?
+  `).get(windowStart);
+    const byModel = {};
+    const modelRows = d.prepare(`
+    SELECT model, COUNT(*) as cnt FROM request_usage WHERE ts >= ? GROUP BY model ORDER BY cnt DESC
+  `).all(windowStart);
+    for (const r of modelRows)
+        byModel[r.model] = r.cnt;
+    const bySource = {};
+    const sourceRows = d.prepare(`
+    SELECT source, COUNT(*) as cnt FROM request_usage WHERE ts >= ? GROUP BY source ORDER BY cnt DESC
+  `).all(windowStart);
+    for (const r of sourceRows)
+        bySource[r.source] = r.cnt;
+    return {
+        window,
+        totalRequests: totals.total,
+        premiumTierCount: totals.premium_tier ?? 0,
+        premiumBilledEstimateCount: totals.premium_billed ?? 0,
+        byModel,
+        bySource,
+        estimated: true,
+    };
+}
+/** Get recent usage events, newest first. */
+export function getRecentUsage(limit, options, dbInstance) {
+    const d = dbInstance ?? getDb();
+    const boundedLimit = Math.max(1, Math.min(limit, 200));
+    const where = options?.premiumOnly ? `WHERE is_premium_billed_estimate = 1` : ``;
+    return d.prepare(`SELECT * FROM request_usage ${where} ORDER BY id DESC LIMIT ?`).all(boundedLimit);
+}
+function resolveWindowStart(window) {
+    switch (window) {
+        case "today": return new Date(new Date().setUTCHours(0, 0, 0, 0)).toISOString().replace("T", " ").replace("Z", "");
+        case "24h": return new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString().replace("T", " ").replace("Z", "");
+        case "7d": return new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString().replace("T", " ").replace("Z", "");
+        case "30d": return new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().replace("T", " ").replace("Z", "");
+        default: return new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString().replace("T", " ").replace("Z", "");
+    }
+}
 export function closeDb() {
     if (db) {
         db.close();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tspappsen/elamax",
-  "version": "1.2.6",
+  "version": "1.2.7",
   "description": "Max — a personal AI assistant for developers, built on the GitHub Copilot SDK",
   "bin": {
     "max": "dist/cli.js"