tokentrax-agent 0.0.0-stage → 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josh Greene
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,111 @@
-# Temporary Holding Version
+# tokentrax-agent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The remote half of [TokenTrax](https://github.com/jeshuwah/TokenTrax). It runs
+on any machine with a context-mode-enabled AI harness — pi, Claude Code,
+Cursor, Codex, Gemini CLI, and 13 others — reads that machine's session
+data, and reports it to a central TokenTrax dashboard.
+
+The dashboard then shows one machine list with every machine's sessions,
+tokens, cost and context-reduction percentage.
+
+## Install
+
+```bash
+npm install -g tokentrax-agent
+tokentrax-agent setup --server http://your-dashboard:7680 --key <sync-key>
+```
+
+`setup` does the rest: it writes the configuration, checks that the native
+SQLite binding actually loads, installs a systemd user service and timer,
+and enables the timer. The machine now reports its usage every 5 minutes.
+
+No npm? Bootstrap straight from the repository:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/jeshuwah/TokenTrax/main/agent/install.sh \
+  | bash -s -- --server http://your-dashboard:7680 --key <sync-key>
+```
+
+Requires Node.js 20 or newer.
+
+### If the SQLite binding will not load
+
+`better-sqlite3` is a native module. npm 12 and newer block dependency
+install scripts by default, so the binding is never fetched or built — and
+`require()` succeeds anyway, so the failure only shows up when a database is
+opened.
+
+```bash
+npm install-scripts approve better-sqlite3
+npm rebuild better-sqlite3
+```
+
+`tokentrax-agent setup` checks for this and tells you if it finds it.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `setup` | Configure the machine, install the timer, enable it. |
+| `sync` | Send new sessions to the server. `--auto` never fails the caller. |
+| `status` | Show the current configuration, the machine id and the cursor. |
+| `init` | Install post-session hooks (harnesses that support them). |
+| `uninstall` | Remove post-session hooks. |
+
+## Configuration
+
+Configuration lives in `~/.tokentrax/agent.env` (mode 0600). The agent
+reads this file itself on every run — you do **not** need to `source` it.
+That matters because a harness launched from a desktop launcher never
+sources a shell profile, and the sync would then have no server URL.
+
+```bash
+TOKENTRAX_SERVER_URL=http://your-dashboard:7680   # required
+TOKENTRAX_SYNC_KEY=...                            # required, matches the server
+TOKENTRAX_MACHINE_ID=my-laptop                    # optional, default: a hash
+TOKENTRAX_TRACK_PROJECT=hash                      # hash | full | dirname | none
+TOKENTRAX_ENV_FILE=/path/to/env                  # optional, override the path
+```
+
+Real environment variables always win over the env file.
+
+`TOKENTRAX_TRACK_PROJECT` controls how much of your project path is
+reported. The default `hash` sends a SHA-256 prefix and nothing else; `full`
+sends the absolute path.
+
+## How it works
+
+Two sources of data are joined per session:
+
+- **context-mode SessionDB** (`<adapter-home>/context-mode/sessions/*.db`) —
+  bytes avoided and returned, tool calls, events, reduction percentage.
+- **Harness transcripts** — for pi, `~/.pi/agent/sessions/<project>/*.jsonl`,
+  which carry per-turn `message.usage` with token counts and costs.
+
+The two are matched on project directory and session start time. A
+transcript that context-mode never recorded is still reported, with its
+token and cost data.
+
+## Sync mechanism
+
+A **systemd user timer**, not a post-session hook.
+
+Hooks are installed by `init` for harnesses that support them, but the
+harness with the most data — pi — has no hook mechanism at all, so a hook
+would silently never fire there. The timer works for every harness, present
+and future, and keeps running when you are logged out (`Linger=yes`).
+
+```bash
+systemctl --user list-timers tokentrax-agent.timer
+journalctl --user -u tokentrax-agent.service -n 20
+```
+
+## Privacy
+
+Nothing leaves the machine except session metadata and usage numbers, and
+only to the one dashboard URL you configure. With the default
+`TOKENTRAX_TRACK_PROJECT=hash` the dashboard never sees a project path.
+
+## License
+
+MIT

package/bin/agent.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../src/cli');

package/install.sh

@@ -0,0 +1,125 @@
+#!/usr/bin/env bash
+#
+# Bootstrap the TokenTrax remote agent on this machine.
+#
+#   curl -fsSL https://raw.githubusercontent.com/jeshuwah/TokenTrax/main/agent/install.sh \
+#     | bash -s -- --server http://your-dashboard:7680 --key <sync-key>
+#
+# Or from a clone of the repository:
+#
+#   ./agent/install.sh --server http://your-dashboard:7680 --key <sync-key>
+#
+# Installs the agent into ~/.tokentrax/agent, then runs `tokentrax-agent
+# setup` to write the configuration and enable the sync timer.
+#
+# Options:
+#   --server <url>      TokenTrax server URL            (required)
+#   --key <key>         sync key, matches the server    (required)
+#   --machine-id <id>   name this machine in the dashboard
+#   --interval <min>    sync interval in minutes        (default 5)
+#   --track <level>     hash | full | dirname | none    (default hash)
+#   --dir <path>        install location (default ~/.tokentrax/agent)
+#   --no-timer          configure only, do not install the systemd timer
+#   --help              this message
+
+set -euo pipefail
+
+REPO_URL="${TOKENTRAX_REPO_URL:-https://github.com/jeshuwah/TokenTrax.git}"
+INSTALL_DIR="${TOKENTRAX_AGENT_DIR:-$HOME/.tokentrax/agent}"
+
+SERVER=""
+KEY=""
+MACHINE_ID=""
+INTERVAL=""
+TRACK=""
+NO_TIMER=""
+
+die() { printf '\033[31m✗\033[0m %s\n' "$*" >&2; exit 1; }
+info() { printf '\033[36m›\033[0m %s\n' "$*"; }
+ok() { printf '\033[32m✓\033[0m %s\n' "$*"; }
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --server)    SERVER="${2:-}"; shift 2 ;;
+    --key)       KEY="${2:-}"; shift 2 ;;
+    --machine-id) MACHINE_ID="${2:-}"; shift 2 ;;
+    --interval)  INTERVAL="${2:-}"; shift 2 ;;
+    --track)     TRACK="${2:-}"; shift 2 ;;
+    --dir)       INSTALL_DIR="${2:-}"; shift 2 ;;
+    --no-timer)  NO_TIMER="1"; shift ;;
+    --server=*)   SERVER="${1#*=}"; shift ;;
+    --key=*)      KEY="${1#*=}"; shift ;;
+    --machine-id=*) MACHINE_ID="${1#*=}"; shift ;;
+    --interval=*)  INTERVAL="${1#*=}"; shift ;;
+    --track=*)     TRACK="${1#*=}"; shift ;;
+    --dir=*)       INSTALL_DIR="${1#*=}"; shift ;;
+    -h|--help)   sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) die "unknown option: $1 (try --help)" ;;
+  esac
+done
+
+[ -n "$SERVER" ] || die "--server is required"
+[ -n "$KEY" ] || die "--key is required"
+
+# ── Node ─────────────────────────────────────────────────────────────────────
+command -v node >/dev/null 2>&1 || die "node is not installed. Install Node.js 20 or newer."
+NODE_MAJOR="$(node -p 'process.versions.node.split(".")[0]')"
+[ "$NODE_MAJOR" -ge 20 ] || die "node $(node -v) is too old — need 20 or newer"
+ok "node $(node -v)"
+
+# ── Source ───────────────────────────────────────────────────────────────────
+# If we're running from inside a clone, use it. Otherwise clone.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ -f "$SCRIPT_DIR/package.json" ] && [ -d "$SCRIPT_DIR/src" ]; then
+  SRC_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+  info "using the repository at $SRC_DIR"
+else
+  mkdir -p "$(dirname "$INSTALL_DIR")"
+  if [ -d "$INSTALL_DIR/.git" ]; then
+    info "updating $INSTALL_DIR"
+    git -C "$INSTALL_DIR" pull --ff-only
+  else
+    info "cloning into $INSTALL_DIR"
+    git clone --depth 1 "$REPO_URL" "$INSTALL_DIR"
+  fi
+  SRC_DIR="$INSTALL_DIR"
+fi
+
+# ── Dependencies ─────────────────────────────────────────────────────────────
+cd "$SRC_DIR/agent"
+info "installing dependencies"
+npm install --no-audit --no-fund
+
+# npm 12+ blocks dependency install scripts by default, and better-sqlite3
+# needs its install script to fetch or build the native binding. require()
+# succeeds either way, so the failure only shows up when a database is
+# opened.
+if npm install-scripts ls >/dev/null 2>&1; then
+  info "approving better-sqlite3's install script (npm 12+ blocks these by default)"
+  npm install-scripts approve better-sqlite3 >/dev/null 2>&1 || true
+  npm rebuild better-sqlite3 >/dev/null 2>&1 || true
+else
+  npm rebuild better-sqlite3 >/dev/null 2>&1 || true
+fi
+
+if ! node -e "const D=require('better-sqlite3'); const d=new D(':memory:'); d.prepare('SELECT 1').get(); d.close();" 2>/dev/null; then
+  die "better-sqlite3 could not open a database. Run:
+     npm install-scripts approve better-sqlite3
+     npm rebuild better-sqlite3"
+fi
+ok "better-sqlite3 loads"
+
+# ── Configure and enable ─────────────────────────────────────────────────────
+SETUP_ARGS=(setup --server "$SERVER" --key "$KEY")
+[ -n "$MACHINE_ID" ] && SETUP_ARGS+=(--machine-id "$MACHINE_ID")
+[ -n "$INTERVAL" ] && SETUP_ARGS+=(--interval "$INTERVAL")
+[ -n "$TRACK" ] && SETUP_ARGS+=(--track-project "$TRACK")
+[ -n "$NO_TIMER" ] && SETUP_ARGS+=(--no-timer)
+
+node "$SRC_DIR/agent/bin/agent.js" "${SETUP_ARGS[@]}"
+
+ok "TokenTrax remote agent installed in $SRC_DIR/agent"
+echo
+echo "Next:"
+echo "  tokentrax-agent status    # confirm it can see the server"
+echo "  systemctl --user list-timers tokentrax-agent.timer"

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "tokentrax-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.2.0",
+  "description": "Remote agent for TokenTrax — reports AI-harness session usage from any machine to a central TokenTrax dashboard",
+  "type": "commonjs",
+  "main": "src/cli.js",
+  "bin": {
+    "tokentrax-agent": "bin/agent.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "install.sh",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test src/*.test.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jeshuwah/TokenTrax.git",
+    "directory": "agent"
+  },
+  "keywords": [
+    "tokentrax",
+    "agent",
+    "telemetry",
+    "usage",
+    "tokens",
+    "cost",
+    "pi",
+    "codex",
+    "claude",
+    "cursor"
+  ],
+  "author": "Josh Greene",
+  "license": "MIT",
+  "dependencies": {
+    "better-sqlite3": "^12.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/adapters.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Canonical adapter registry — single source of truth.
+//
+// Resolution is deferred to call time (resolveAdapterHome) so tests and
+// future env overrides (TOKENTRAX_HOME) don't lock in stale paths.
+//
+// Names are the canonical identifiers used as `record.adapter` downstream.
+//   - `antigravity` and `antigravity-cli` both live under ~/.gemini but
+//     identify as separate harnesses to the dashboard.
+//   - `vscode-copilot` and `jetbrains-copilot` keep the `-copilot` suffix
+//     so downstream consumers can distinguish editor-embedded adapters from
+//     CLI-only ones (`copilot-cli`).
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Static descriptor — only stores `name` and a `homeRelative` path.
+ * The absolute `home` and `sessionsDir` are derived per call via
+ * `resolveAdapterHome` / `buildAdapterEntry` so that os.homedir() changes
+ * (e.g. test monkey-patches) are honored.
+ *
+ * @typedef {Object} AdapterDescriptor
+ * @property {string} name        Canonical adapter name
+ * @property {string} homeRel     Path relative to homedir (may include subdirs)
+ */
+
+const ADAPTER_DESCRIPTORS = Object.freeze([
+  { name: 'claude-code',       homeRel: '.claude' },
+  { name: 'gemini-cli',        homeRel: '.gemini' },
+  { name: 'antigravity',       homeRel: '.gemini' },
+  { name: 'antigravity-cli',   homeRel: '.gemini' },
+  { name: 'openclaw',          homeRel: '.openclaw' },
+  { name: 'codex',             homeRel: '.codex' },
+  { name: 'cursor',            homeRel: '.cursor' },
+  { name: 'vscode-copilot',    homeRel: '.vscode' },
+  { name: 'copilot-cli',       homeRel: '.copilot' },
+  { name: 'kiro',              homeRel: '.kiro' },
+  { name: 'pi',                homeRel: '.pi' },
+  { name: 'omp',               homeRel: '.omp' },
+  { name: 'qwen-code',         homeRel: '.qwen' },
+  { name: 'kilo',              homeRel: '.config/kilo' },
+  { name: 'opencode',          homeRel: '.config/opencode' },
+  { name: 'zed',               homeRel: '.config/zed' },
+  { name: 'jetbrains-copilot', homeRel: '.config/JetBrains' },
+]);
+
+/**
+ * Resolve the absolute home directory for a known adapter name.
+ * @param {string} name
+ * @returns {string|undefined} absolute path, or undefined if name is unknown
+ */
+function resolveAdapterHome(name) {
+  const desc = ADAPTER_DESCRIPTORS.find((d) => d.name === name);
+  if (!desc) return undefined;
+  return path.join(os.homedir(), desc.homeRel);
+}
+
+/**
+ * Build the absolute-path record for an adapter descriptor.
+ * @param {AdapterDescriptor} desc
+ * @returns {{name: string, home: string, sessionsDir: string}}
+ */
+function buildAdapterEntry(desc) {
+  const home = path.join(os.homedir(), desc.homeRel);
+  return {
+    name: desc.name,
+    home,
+    sessionsDir: path.join(home, 'context-mode', 'sessions'),
+  };
+}
+
+/**
+ * Public, eagerly-computed ADAPTER_DIRS — kept for back-compat with the
+ * existing import in session-parser.js. Resolved once at module load, so
+ * if os.homedir() ever becomes dynamic, callers should use
+ * `resolveAdapterHome(name)` instead.
+ */
+const ADAPTER_DIRS = Object.freeze(ADAPTER_DESCRIPTORS.map(buildAdapterEntry));
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Detection
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Check if an adapter is installed (has context-mode sessions or settings).
+ * Resolves home on each call so live filesystem changes are honored.
+ */
+function detectAdapter(adapter) {
+  const home = resolveAdapterHome(adapter.name) || adapter.home;
+  const sessionsDir = path.join(home, 'context-mode', 'sessions');
+  const settingsJson = path.join(home, 'settings.json');
+  const settingsToml = path.join(home, 'settings.toml');
+  // Codex-specific: settings live at <home>/hooks.json, not settings.json/toml
+  const hooksJson = path.join(home, 'hooks.json');
+  const hasSessions = fs.existsSync(sessionsDir);
+  const hasSettings =
+    fs.existsSync(settingsJson) ||
+    fs.existsSync(settingsToml) ||
+    (adapter.name === 'codex' && fs.existsSync(hooksJson));
+  return { ...adapter, home, sessionsDir, hasSessions, hasSettings };
+}
+
+/**
+ * Detect all installed adapters.
+ * Returns adapters that have EITHER context-mode sessions OR settings.
+ */
+function detectInstalled() {
+  return ADAPTER_DESCRIPTORS
+    .map((d) => detectAdapter(buildAdapterEntry(d)))
+    .filter((a) => a.hasSessions || a.hasSettings);
+}
+
+module.exports = {
+  ADAPTER_DIRS,
+  ADAPTER_DESCRIPTORS,
+  resolveAdapterHome,
+  detectInstalled,
+};

package/src/adapters.test.js

@@ -0,0 +1,135 @@
+'use strict';
+
+const { test, describe } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// Load the module under test
+const { ADAPTER_DIRS, detectInstalled, resolveAdapterHome } = require('./adapters');
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ADAPTER_DIRS — single source of truth
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('ADAPTER_DIRS (canonical registry)', () => {
+  test('contains the documented set of 17 adapters', () => {
+    assert.strictEqual(ADAPTER_DIRS.length, 17,
+      `Expected 17 adapters, got ${ADAPTER_DIRS.length}: ${ADAPTER_DIRS.map(a => a.name).join(', ')}`);
+  });
+
+  test('every entry has name, home, sessionsDir', () => {
+    for (const entry of ADAPTER_DIRS) {
+      assert.ok(typeof entry.name === 'string' && entry.name.length > 0,
+        `name required (entry: ${JSON.stringify(entry)})`);
+      assert.ok(typeof entry.home === 'string' && entry.home.length > 0,
+        `home required for ${entry.name}`);
+      assert.ok(typeof entry.sessionsDir === 'string' && entry.sessionsDir.length > 0,
+        `sessionsDir required for ${entry.name}`);
+    }
+  });
+
+  test('sessionsDir always ends with context-mode/sessions', () => {
+    for (const entry of ADAPTER_DIRS) {
+      assert.ok(entry.sessionsDir.endsWith('context-mode/sessions'),
+        `${entry.name}: sessionsDir should end with context-mode/sessions, got: ${entry.sessionsDir}`);
+    }
+  });
+
+  test('home is absolute and uses homedir()', () => {
+    for (const entry of ADAPTER_DIRS) {
+      assert.ok(path.isAbsolute(entry.home),
+        `${entry.name}: home should be absolute, got: ${entry.home}`);
+      assert.ok(entry.home.startsWith(os.homedir()),
+        `${entry.name}: home should be under homedir(), got: ${entry.home}`);
+    }
+  });
+
+  test('includes the canonical required adapters', () => {
+    const names = ADAPTER_DIRS.map((e) => e.name);
+    for (const required of ['claude-code', 'pi', 'codex', 'gemini-cli', 'cursor', 'zed']) {
+      assert.ok(names.includes(required), `should include ${required}`);
+    }
+  });
+
+  test('every adapter name is unique', () => {
+    const names = ADAPTER_DIRS.map((e) => e.name);
+    assert.strictEqual(new Set(names).size, names.length,
+      `duplicate adapter name in registry: ${names.join(', ')}`);
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// resolveAdapterHome — deferred resolution so env/test overrides work
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('resolveAdapterHome', () => {
+  test('returns absolute path for a known adapter name', () => {
+    const home = resolveAdapterHome('pi');
+    assert.ok(path.isAbsolute(home));
+    assert.ok(home.startsWith(os.homedir()));
+    assert.ok(home.endsWith('.pi'));
+  });
+
+  test('returns undefined for an unknown adapter name', () => {
+    assert.strictEqual(resolveAdapterHome('nonexistent-adapter-xyz'), undefined);
+  });
+
+  test('is consistent across calls (stable for stable homedir)', () => {
+    const a = resolveAdapterHome('pi');
+    const b = resolveAdapterHome('pi');
+    assert.strictEqual(a, b, 'resolveAdapterHome should return same value for stable homedir');
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// detectInstalled
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('detectInstalled', () => {
+  test('returns array of adapter descriptors', () => {
+    const installed = detectInstalled();
+    assert.ok(Array.isArray(installed));
+    for (const a of installed) {
+      assert.ok(typeof a.name === 'string');
+      assert.ok(typeof a.home === 'string');
+      assert.ok(typeof a.hasSessions === 'boolean');
+      assert.ok(typeof a.hasSettings === 'boolean');
+    }
+  });
+
+  test('every returned adapter has at least sessions or settings', () => {
+    const installed = detectInstalled();
+    for (const a of installed) {
+      assert.ok(a.hasSessions || a.hasSettings,
+        `detected adapter should have sessions or settings: ${a.name}`);
+    }
+  });
+
+  test('does not return adapters whose home does not exist', () => {
+    const installed = detectInstalled();
+    for (const a of installed) {
+      assert.ok(fs.existsSync(a.home),
+        `detected adapter ${a.name} home should exist: ${a.home}`);
+    }
+  });
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Cross-module consistency: session-parser must use the same registry
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('session-parser uses canonical ADAPTER_DIRS', () => {
+  test('session-parser ADAPTER_DIRS export matches adapters.js ADAPTER_DIRS', () => {
+    const { ADAPTER_DIRS: parserDirs } = require('./session-parser');
+    assert.strictEqual(parserDirs.length, ADAPTER_DIRS.length,
+      'session-parser should re-export the canonical registry, not maintain its own');
+    for (let i = 0; i < parserDirs.length; i++) {
+      assert.strictEqual(parserDirs[i].name, ADAPTER_DIRS[i].name,
+        `name mismatch at index ${i}: ${parserDirs[i].name} vs ${ADAPTER_DIRS[i].name}`);
+      assert.strictEqual(parserDirs[i].home, ADAPTER_DIRS[i].home,
+        `home mismatch at index ${i}: ${parserDirs[i].home} vs ${ADAPTER_DIRS[i].home}`);
+    }
+  });
+});