@krishivpb60/aether-ai-cli 1.1.9 → 1.3.0

package/.agents/teamwork_preview_worker_verification/handoff.md

@@ -0,0 +1,187 @@
+# Handoff Report — E2E Verification of Aether AI CLI
+
+This report documents the E2E verification steps and findings for the Aether AI CLI codebase on Windows.
+
+## 1. Observation
+
+### Local Package Linking
+Command run: `npm.cmd link` in project root `C:\Users\naina\.gemini\antigravity\scratch\aether-ai-cli`.
+Output:
+```
+added 1 package, and audited 3 packages in 2s
+
+found 0 vulnerabilities
+```
+Global links were successfully created in `C:\Users\naina\AppData\Roaming\npm` for the `aether` binary.
+
+### Unit Tests
+Command run: `npm.cmd test` in project root `C:\Users\naina\.gemini\antigravity\scratch\aether-ai-cli`.
+Output:
+```
+> @krylo-60/aether-ai-cli@1.0.0 test
+> node --test
+
+▶ Configuration Loading Suite
+  ✔ getConfigPath should return path inside temporary home (5.6146ms)
+  ✔ loadConfig should return empty object if file does not exist (7.768ms)
+  ✔ saveConfig and loadConfig should save and load config file (22.7313ms)
+  ✔ getConfigValue and setConfigValue read and write specific keys (15.9586ms)
+  ✔ listConfig should mask sensitive keys (6.8407ms)
+  ✔ getAIConfig Priority: config file overrides process.env (6.4427ms)
+  ✔ getAIConfig supports fallback for any custom key ending with _API_KEY from process.env (2.9901ms)
+  ✔ isValidConfigKey checks key formats and known keys (1.7146ms)
+✔ Configuration Loading Suite (81.3576ms)
+▶ Offline Math Fallback & Krylo Suite
+  ✔ detectMathExpression identifies valid mathematical expressions (1.4379ms)
+  ✔ detectMathExpression rejects non-math and invalid expressions (0.3137ms)
+  ✔ solveMath evaluates simple math expressions correctly (0.5413ms)
+  ✔ solveMath converts ^ to ** correctly for exponentiation (1.483ms)
+  ✔ solveMath handles floats and division (0.3561ms)
+  ✔ solveMath returns null on syntax error or unsafe code (0.3782ms)
+  ✔ generateKryloReply responds to help and shortcut keywords (0.4279ms)
+  ✔ generateKryloReply responds to status and diagnostic keywords (0.2695ms)
+  ✔ generateKryloReply responds to matrix/rain/color keywords (0.3643ms)
+  ✔ generateKryloReply responds to who/name/creator keywords (0.35ms)
+  ✔ generateKryloReply falls back to random terminal responses (0.2222ms)
+✔ Offline Math Fallback & Krylo Suite (10.6275ms)
+▶ File Parser & Context Suite
+  ✔ parseFile parses a standard .txt file successfully (12.0737ms)
+  ✔ parseFile parses a code .js file successfully (4.4388ms)
+  ✔ parseFile parses a .json file successfully (7.8301ms)
+  ✔ parseFile parses a .csv file successfully (4.0536ms)
+  ✔ parseFile truncates content exceeding 30,000 characters (43.5665ms)
+  ✔ parseFile throws error on unsupported extension (3.1508ms)
+  ✔ parseFile throws error when file does not exist (1.3021ms)
+  ✔ parseFile throws error on directory path without supported extension (0.5618ms)
+  ✔ parseFile throws error on directory path with supported extension (2.5804ms)
+  ✔ formatContext returns formatted template string (0.4367ms)
+  ✔ formatContext formats KB/MB file sizes correctly (0.2397ms)
+✔ File Parser & Context Suite (91.4076ms)
+▶ Universal AI Router Suite
+  ✔ routePrompt routes to local math solver when pure math expression (3.1517ms)
+  ✔ routePrompt routes to active providers in order of priority (1.6104ms)
+  ✔ routePrompt falls back to next provider if priority provider fails (1.3292ms)
+  ✔ routePrompt handles Google extra key rotation and failover (2.8772ms)
+  ✔ routePrompt falls back to Krylo companion when no providers are configured (1.3161ms)
+  ✔ routePrompt falls back to Krylo companion when all providers fail (1.1711ms)
+✔ Universal AI Router Suite (18.7375ms)
+▶ Cyberpunk UX and Streaming Suite
+  ✔ createSpinner should return custom frames and 80ms interval (3.5346ms)
+  ✔ separator should adjust length dynamically based on terminal width (0.4046ms)
+  ✔ routePrompt calls callOpenAICompatible and streams tokens (3.4326ms)
+✔ Cyberpunk UX and Streaming Suite (9.0996ms)
+ℹ tests 44
+ℹ suites 0
+ℹ pass 44
+ℹ fail 0
+ℹ cancelled 0
+ℹ skipped 0
+ℹ todo 0
+ℹ duration_ms 335.5458
+```
+
+### Global Command Execution: aether --help
+Command run: `& "$env:APPDATA\npm\aether.cmd" --help`
+Output:
+```
+Usage: aether [options] [command]
+
+Aether Core AI v110 — Universal AI Gateway CLI
+  Supports 13+ AI providers • Free & paid models • Local fallbacks
+
+Options:
+  -v, --version              output the version number
+  -h, --help                 display help for command
+
+Commands:
+  chat [options]             Start an interactive chat session
+  ask [options] <prompt...>  Send a single prompt and get a response
+  config                     Manage API keys and settings
+  providers [options]        List all supported AI providers and their status
+  models [provider]          List available models for a provider
+  modes                      List all reasoning modes
+  status                     Show system status & configured providers
+  setup                      Interactive guided setup for API keys
+```
+
+### Global Command Execution: aether config path
+Command run: `& "$env:APPDATA\npm\aether.cmd" config path`
+Output:
+```
+ CONFIG  C:\Users\naina\.aether\config.json
+```
+
+### Global Command Execution: Math Fallback Query
+Command run: `& "$env:APPDATA\npm\aether.cmd" ask "2 + 2 * (10 - 5)"`
+Output:
+```
+   MODE  Titan Fusion v110 • Layer 110
+- Routing through failover mesh...
+
+ AETHER  via local • Node 0
+────────────────────────────────────────────────────────────────────────────
+
+  🤖 [LOCAL MATH SOLVER]
+     Expression: 2+2*(10-5)
+     Result: 12
+────────────────────────────────────────────────────────────────────────────
+```
+
+### Git Status Check
+Command run: `git status`
+Output:
+```
+On branch main
+Changes not staged for commit:
+  (use "git add <file>..." to update what will be committed)
+  (use "git restore <file>..." to discard changes in working directory)
+	modified:   package.json
+	modified:   src/ai/router.js
+	modified:   src/ai/universal.js
+	modified:   src/chat.js
+	modified:   src/cli.js
+	modified:   src/ui/banner.js
+	modified:   src/ui/spinner.js
+	modified:   src/ui/theme.js
+
+Untracked files:
+  (use "git add <file>..." to include in what will be committed)
+	test/
+
+no changes added to commit (use "git add" and/or "git commit -a")
+```
+
+---
+
+## 2. Logic Chain
+
+1. **Local Link Establishment**: The output from `npm.cmd link` confirms that the package is successfully registered in Node's global path.
+2. **Command Executability**: Since the terminal PATH of the current shell did not automatically refresh, invoking `aether` directly failed. However, calling the generated batch script `& "$env:APPDATA\npm\aether.cmd"` succeeded, demonstrating that Commander configuration and binary entrypoints are fully operational.
+3. **Core Command Compliance**: 
+   - `aether --help` successfully parsed parameters and returned the standard Commander help menu with all expected commands.
+   - `aether config path` output the expected Cyberpunk formatted config path `C:\Users\naina\.aether\config.json`.
+4. **Math Query Offline Routing**: The output of `aether ask "2 + 2 * (10 - 5)"` verifies that the prompt was correctly classified as a pure mathematical expression, bypassed remote AI networks, and routed to node 0 (the local math solver), producing the correct result `12`.
+5. **Unit Test Coverage**: The `npm.cmd test` execution successfully discovered 44 tests across 5 suites, and all 44 passed with 0 failures, verifying all unit levels of logic (configs, math evaluation, UI parsing, fallback routers, spinners).
+6. **Repository Status**: `git status` shows modifications in `src/` and `package.json` and a new `test/` directory, which represents the files implemented by other worker agents during prior tasks in this milestone. No other untracked or dirty state from verification is present.
+
+---
+
+## 3. Caveats
+
+- Since this verification ran on Windows, PowerShell execution policies blocked direct command resolution for `npm` (forcing `npm.cmd`) and the path to global command required invoking `aether.cmd` via the full path `%APPDATA%\npm\aether.cmd` or PowerShell invocation notation.
+
+---
+
+## 4. Conclusion
+
+The Aether AI CLI package is fully operational. Commander configurations, E2E routing to Node 0 (local math solver), unit tests (all 44 pass), config path display, and package linkage are verified and working as expected.
+
+---
+
+## 5. Verification Method
+
+To re-verify locally:
+1. Run `npm.cmd test` in the project root directory.
+2. Run `& "$env:APPDATA\npm\aether.cmd" --help` to verify command routing.
+3. Run `& "$env:APPDATA\npm\aether.cmd" config path`.
+4. Run `& "$env:APPDATA\npm\aether.cmd" ask "2 + 2 * (10 - 5)"`.

package/.agents/teamwork_preview_worker_verification/progress.md

@@ -0,0 +1,16 @@
+# progress.md
+Last visited: 2026-06-25T09:47:50-04:00
+
+## Current Status
+- Linked package locally with `npm.cmd link`.
+- Successfully ran all 44 unit tests with 100% pass rate.
+- Tested global `aether --help` command successfully.
+- Tested global `aether config path` command successfully.
+- Tested global math query `aether ask "2 + 2 * (10 - 5)"` successfully (routes to Node 0, returns 12).
+- Ran `git status` to verify repository files status.
+- Ready to write handoff.md.
+
+## Plan
+1. Write handoff.md.
+2. Update BRIEFING.md.
+3. Send completion message to main agent.

package/HIGHLIGHTS.md

@@ -0,0 +1,12 @@
+# Aether CLI v1.3.0 Highlights
+- **Token Telemetry Tracker**: Real-time prompt and completion token statistics shown on every chat turn.
+- **Session Telemetry `/tokens`**: A new slash command displaying detailed model-by-model session token breakdowns and total exchange stats.
+- **Toggle Telemetry**: Enable or disable display using `aether config set SHOW_TOKENS false`.
+
+# Aether CLI v1.1.9 Highlights
+- **Node 18 Compatibility**: Resolves `ReadableStream` reference errors inside the Node 18 CI test runner.
+- **Auto-Updater**: Checks for updates once every 24 hours on launch and updates the CLI automatically.
+- **Release Highlights**: Prompts and renders version release notes on launch.
+- **Customizable Control**: Toggle behavior using `aether config set AUTO_UPDATE false` and `aether config set SHOW_HIGHLIGHTS false`.
+- **Autopilot Safety Levels**: Added autonomous capabilities controlled by `/autopilot` setting.
+- **Chat History Selector**: View and switch past chat logs with `/history`.

package/aether_pip/cli.py

@@ -35,6 +35,7 @@ def main():
 
     try:
         # Run node aether.js passing all command line arguments
+        os.environ["AETHER_PACKAGER"] = "pip"
         cmd = ["node", aether_js] + sys.argv[1:]
         result = subprocess.run(cmd, check=False)
         sys.exit(result.returncode)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krishivpb60/aether-ai-cli",
-  "version": "1.1.9",
+  "version": "1.3.0",
   "description": "Aether Core AI — A cyberpunk command-line AI assistant with multi-mode reasoning, 12-node failover mesh, file context injection, and offline fallbacks.",
   "main": "src/cli.js",
   "bin": {

package/src/ai/router.js

@@ -11,6 +11,7 @@ import {
   callAnthropic,
   callCohere,
 } from "./universal.js";
+import { estimateTokens, recordTokenUsage } from "./tokens.js";
 
 /**
  * Routes a prompt through the universal AI failover mesh.
@@ -32,7 +33,10 @@ export async function routePrompt(prompt, systemPrompt, config, onToken, history
   if (mathExpr) {
     const mathResult = solveMath(mathExpr);
     if (mathResult) {
-      return { ...mathResult, provider: "local", node: 0 };
+      const pTokens = estimateTokens(systemPrompt + prompt);
+      const cTokens = estimateTokens(mathResult.text);
+      const usage = recordTokenUsage("local-math", pTokens, cTokens);
+      return { ...mathResult, provider: "local", node: 0, usage };
     }
   }
 
@@ -54,7 +58,10 @@ export async function routePrompt(prompt, systemPrompt, config, onToken, history
   // ── No providers configured → Krylo ────────────────────
   if (active.length === 0) {
     const kryloReply = generateKryloReply(prompt);
-    return { ...kryloReply, provider: "krylo-fallback", node: 0 };
+    const pTokens = estimateTokens(systemPrompt + prompt);
+    const cTokens = estimateTokens(kryloReply.text);
+    const usage = recordTokenUsage("krylo-local", pTokens, cTokens);
+    return { ...kryloReply, provider: "krylo-fallback", node: 0, usage };
   }
 
   // ── Try each provider in order ──────────────────────────
@@ -96,7 +103,11 @@ export async function routePrompt(prompt, systemPrompt, config, onToken, history
           );
       }
 
-      return { ...result, node: nodeIndex };
+      const pTokens = estimateTokens(systemPrompt + prompt + history.map(h => h.content).join(""));
+      const cTokens = estimateTokens(result.text);
+      const usage = recordTokenUsage(result.model, pTokens, cTokens);
+
+      return { ...result, node: nodeIndex, usage };
     } catch (err) {
       errors.push(`[Node ${nodeIndex} ${provider.name}] ${err.message}`);
       nodeIndex++;
@@ -105,10 +116,14 @@ export async function routePrompt(prompt, systemPrompt, config, onToken, history
 
   // ── Final Fallback: Krylo Companion ─────────────────────
   const kryloReply = generateKryloReply(prompt);
+  const pTokens = estimateTokens(systemPrompt + prompt + history.map(h => h.content).join(""));
+  const cTokens = estimateTokens(kryloReply.text);
+  const usage = recordTokenUsage("krylo-local", pTokens, cTokens);
   return {
     ...kryloReply,
     provider: "krylo-fallback",
     node: 0,
     errors,
+    usage,
   };
 }

package/src/ai/tokens.js

@@ -0,0 +1,101 @@
+// ═══════════════════════════════════════════════════════════
+// AETHER AI CLI — Real-time Token & Telemetry Tracker
+// Tracks input/output token counts and session usage metrics.
+// ═══════════════════════════════════════════════════════════
+
+// Session token accumulator
+let sessionTokens = {
+  prompt: 0,
+  completion: 0,
+  total: 0,
+  exchanges: 0,
+};
+
+// Model-by-model breakdown
+const modelBreakdown = {};
+
+/**
+ * Heuristically estimates the token count of a string based on character length.
+ * Standard rule of thumb: 1 token ≈ 4 characters.
+ * @param {string} text
+ * @returns {number}
+ */
+export function estimateTokens(text) {
+  if (!text) return 0;
+  return Math.ceil(text.length / 4);
+}
+
+/**
+ * Returns a copy of the current session token stats.
+ * @returns {{prompt: number, completion: number, total: number, exchanges: number}}
+ */
+export function getSessionTokenStats() {
+  return { ...sessionTokens };
+}
+
+/**
+ * Resets all accumulated session token statistics and breakdowns.
+ */
+export function resetSessionTokenStats() {
+  sessionTokens = {
+    prompt: 0,
+    completion: 0,
+    total: 0,
+    exchanges: 0,
+  };
+  // Clear object properties safely without losing reference
+  for (const key of Object.keys(modelBreakdown)) {
+    delete modelBreakdown[key];
+  }
+}
+
+/**
+ * Records token usage for a query.
+ * @param {string} model - The model name
+ * @param {number} promptTokens - Input prompt tokens count
+ * @param {number} completionTokens - Output completion tokens count
+ * @returns {{promptTokens: number, completionTokens: number, totalTokens: number}}
+ */
+export function recordTokenUsage(model, promptTokens, completionTokens) {
+  const modelName = model || "unknown-model";
+  const totalTokens = promptTokens + completionTokens;
+
+  // Update session totals
+  sessionTokens.prompt += promptTokens;
+  sessionTokens.completion += completionTokens;
+  sessionTokens.total += totalTokens;
+  sessionTokens.exchanges += 1;
+
+  // Update model breakdown
+  if (!modelBreakdown[modelName]) {
+    modelBreakdown[modelName] = {
+      prompt: 0,
+      completion: 0,
+      total: 0,
+      exchanges: 0,
+    };
+  }
+  modelBreakdown[modelName].prompt += promptTokens;
+  modelBreakdown[modelName].completion += completionTokens;
+  modelBreakdown[modelName].total += totalTokens;
+  modelBreakdown[modelName].exchanges += 1;
+
+  return {
+    promptTokens,
+    completionTokens,
+    totalTokens,
+  };
+}
+
+/**
+ * Returns the model-by-model token usage breakdown.
+ * @returns {object}
+ */
+export function getBreakdownByModel() {
+  // Deep clone modelBreakdown
+  const clone = {};
+  for (const [key, value] of Object.entries(modelBreakdown)) {
+    clone[key] = { ...value };
+  }
+  return clone;
+}

package/src/chat.js

@@ -45,6 +45,10 @@ import { MODES, DEFAULT_MODE, getModeByName } from "./modes.js";
 import { parseFile, formatContext } from "./file-parser.js";
 import { runMainframeHack } from "./ai/fallback.js";
 import { AGENT_INSTRUCTIONS } from "./agent.js";
+import { checkForUpdates } from "./updater.js";
+import { getSessionTokenStats, getBreakdownByModel, resetSessionTokenStats } from "./ai/tokens.js";
+
+
 
 // Configure marked dynamically for terminal output
 const getMarked = () => new Marked(markedTerminal({
@@ -67,6 +71,13 @@ export async function startChat(options = {}) {
   // Load AI config
   const aiConfig = await getAIConfig();
   
+  // Run update check
+  await checkForUpdates();
+
+  // Reset token stats for the new session
+  resetSessionTokenStats();
+
+  
   // Set theme from configuration
   const theme = aiConfig.THEME || "cyberpunk";
   setTheme(theme);
@@ -125,7 +136,7 @@ export async function startChat(options = {}) {
       "/help", "/mode", "/modes", "/attach", "/files", "/clear",
       "/providers", "/export", "/status", "/copy", "/exit", "/quit",
       "/theme", "/themes", "/history-clear", "/game", "/abort", "/cmd", "/write",
-      "/commit", "/run", "/history", "/autopilot"
+      "/commit", "/run", "/history", "/autopilot", "/tokens"
     ];
     const customCmds = aiConfig.CUSTOM_COMMANDS || {};
     const commands = [...builtIn, ...Object.keys(customCmds)];
@@ -298,11 +309,19 @@ export async function startChat(options = {}) {
           }
         }
 
+        const showTokens = aiConfig.SHOW_TOKENS !== "false";
+        let tokensText = "";
+        if (showTokens && result.usage) {
+          const { promptTokens, completionTokens } = result.usage;
+          tokensText = ` • ${promptTokens.toLocaleString()} in / ${completionTokens.toLocaleString()} out tokens`;
+        }
+
         console.log(separator("─"));
         console.log(
           "  " + colors.dim(`Node ${result.node} • ${result.provider}`) +
           (result.model ? colors.dim(` • ${result.model}`) : "") +
           colors.dim(` • ${elapsedSec}s${speedText}`) +
+          colors.dim(tokensText) +
           colors.dim(` • ${Math.floor(history.length / 2)} exchanges`)
         );
         console.log("");
@@ -404,7 +423,7 @@ export async function startChat(options = {}) {
         "/", "/help", "/mode", "/modes", "/attach", "/files", "/clear",
         "/providers", "/export", "/status", "/copy", "/exit", "/quit",
         "/theme", "/themes", "/history-clear", "/game", "/abort", "/cmd",
-        "/guess", "/write", "/commit", "/run", "/history", "/autopilot"
+        "/guess", "/write", "/commit", "/run", "/history", "/autopilot", "/tokens"
       ];
       
       const customCmds = aiConfig.CUSTOM_COMMANDS || {};
@@ -551,6 +570,10 @@ async function handleCommand(input, ctx) {
       await handleAutopilotSwitch(args, ctx);
       break;
 
+    case "/tokens":
+      await handleTokensDisplay(ctx);
+      break;
+
     case "/exit":
     case "/quit":
       ctx.rl.close();
@@ -582,6 +605,7 @@ function showHelp(aiConfig) {
   console.log(keyValue("/history", "List, switch, and resume past interactive chat sessions"));
   console.log(keyValue("/history-clear", "Clear saved persistent chat history"));
   console.log(keyValue("/autopilot <mode>", "View or switch agent autopilot level (off, safe, workspace, machine)"));
+  console.log(keyValue("/tokens", "View detailed session token usage and exchanges telemetry"));
   console.log(keyValue("/game", "Start the local mainframe hacking mini-game"));
   console.log(keyValue("/copy", "Copy the last assistant response to clipboard"));
   console.log(keyValue("/cmd <list|add|remove>", "Manage custom command shortcuts"));
@@ -1121,7 +1145,7 @@ async function handleCustomCommands(args, ctx) {
     const builtIn = [
       "/help", "/mode", "/modes", "/attach", "/files", "/clear",
       "/providers", "/export", "/status", "/copy", "/exit", "/quit",
-      "/theme", "/themes", "/history-clear", "/game", "/abort", "/cmd", "/guess"
+      "/theme", "/themes", "/history-clear", "/game", "/abort", "/cmd", "/guess", "/tokens"
     ];
     
     if (builtIn.includes(name.toLowerCase())) {
@@ -1333,3 +1357,40 @@ async function handleRunCommand(args, ctx) {
     });
   });
 }
+
+/**
+ * Interactive display of session token usage statistics.
+ */
+async function handleTokensDisplay(ctx) {
+  const stats = getSessionTokenStats();
+  const breakdown = getBreakdownByModel();
+
+  console.log("\n" + separator("━"));
+  console.log(colors.accent.bold("  ★  AETHER SESSION TOKEN TELEMETRY  ★"));
+  console.log(separator("─"));
+
+  const models = Object.keys(breakdown);
+  if (models.length === 0) {
+    console.log(colors.muted("  No queries executed in this session yet."));
+  } else {
+    // Print header
+    console.log(
+      colors.brand("  " + "Model".padEnd(35) + "Prompt".padStart(10) + "Completion".padStart(12) + "Total".padStart(10))
+    );
+    console.log(colors.dim("  " + "─".repeat(67)));
+    for (const [model, data] of Object.entries(breakdown)) {
+      const truncatedModel = model.length > 33 ? model.slice(0, 30) + "..." : model;
+      console.log(
+        "  " + colors.text(truncatedModel.padEnd(35)) +
+        colors.brand(data.prompt.toLocaleString().padStart(10)) +
+        colors.brand(data.completion.toLocaleString().padStart(12)) +
+        colors.accent.bold(data.total.toLocaleString().padStart(10))
+      );
+    }
+  }
+
+  console.log(separator("─"));
+  console.log("  " + colors.accent("Total Exchanges:") + colors.text(` ${stats.exchanges}`));
+  console.log("  " + colors.accent("Total Tokens:") + colors.text(`    Prompt: ${stats.prompt.toLocaleString()} | Completion: ${stats.completion.toLocaleString()} | Sum: `) + colors.brand.bold(stats.total.toLocaleString()));
+  console.log(separator("━") + "\n");
+}

package/src/config.js

@@ -173,7 +173,12 @@ export async function configExists() {
 export function isValidConfigKey(key) {
   const upper = key.toUpperCase();
   // Accept any API key or model override
-  if (upper.endsWith("_API_KEY") || upper.endsWith("_API_KEYS") || upper.endsWith("_MODEL") || upper === "THEME" || upper === "CUSTOM_COMMANDS" || upper === "AUTOPILOT") {
+  const allowedSpecialKeys = [
+    "THEME", "CUSTOM_COMMANDS", "AUTOPILOT", 
+    "AUTO_UPDATE", "SHOW_HIGHLIGHTS", "LAST_UPDATE_CHECK", "LAST_NOTIFIED_VERSION",
+    "SHOW_TOKENS"
+  ];
+  if (upper.endsWith("_API_KEY") || upper.endsWith("_API_KEYS") || upper.endsWith("_MODEL") || allowedSpecialKeys.includes(upper)) {
     return true;
   }
   // Accept known config keys