agenter-app 1.0.2 → 1.1.0

package/Agenter.vbs

@@ -1,5 +1,5 @@
 ' Double-click (or use the shortcut) to open Agenter without a console window.
-' "Agenter.vbs server" only starts the background server (used at Windows login).
+' "Agenter.vbs server" only starts the background server and tray icon (used at Windows login).
 Set fso = CreateObject("Scripting.FileSystemObject")
 dir = fso.GetParentFolderName(WScript.ScriptFullName)
 cmd = "node """ & dir & "\open.js"""

package/README.md

@@ -29,16 +29,22 @@ From a clone instead: `npm run install-hooks` and `npm run shortcuts`, then `npm
 ## Running it
 
 You mostly don't have to: **the server starts itself** the first time any Claude session fires a hook,
-and keeps running in the background. Just open the window when you want it:
+and keeps running in the background, with an icon in the Windows system tray. Closing the window leaves
+it running there. Click the icon to open the dashboard.
+
+**To stop it, right-click the tray icon and choose Quit Agenter.** That closes the windows and stops the
+server. Anything waiting goes back to VS Code, and turns Agenter is running are stopped. Hooks won't restart
+it; it stays off until you open Agenter again.
 
 | Way | What it does |
 |---|---|
 | **Agenter shortcut** (Desktop / Start Menu / taskbar) | Opens the dashboard in its own app window and starts the server if needed. No console. |
 | `agenter` | Same thing, from a terminal. |
 | `agenter start` | Runs the server in the foreground with logs (handy for debugging). |
-| `agenter shortcuts --startup` | Also starts the server silently when you log in to Windows. |
+| `agenter doctor` | Checks the hooks, port, Claude Code and login, and says how to fix anything that's wrong. Start here if sessions don't show up. |
+| `agenter shortcuts` | Creates the shortcuts, and starts Agenter in the system tray when you log in to Windows. |
 
-Set `AGENTER_AUTOSTART=0` to stop hooks from starting the server.
+Set `AGENTER_AUTOSTART=0` to stop hooks from starting the server, or `AGENTER_TRAY=0` to hide the tray icon.
 Dashboard settings are kept in `~/.agenter/settings.json`.
 
 To remove everything: `agenter uninstall`, then `npm uninstall -g agenter-app`.
@@ -74,7 +80,8 @@ Each session has a **Drive from** switch in its header.
   reply from Agenter the VS Code panel shows its spinner, and an idle session waits for VS Code.
 - **Agenter**: Agenter runs the turns itself with the Claude Code that ships with the VS Code extension
   (`claude -p --resume <session>`), in the same session. Nothing ever waits on VS Code, idle and closed
-  sessions can be continued, permission prompts and questions come to Agenter, and **Stop** ends a running turn.
+  sessions can be continued, permission prompts and questions come to Agenter and wait there for your answer
+  while a dashboard is open, and **Stop** ends a running turn and everything it started.
   The VS Code panel doesn't show these turns until you reopen the session there (Claude panel → session
   history), and don't type in VS Code's panel for that session at the same time.
 
@@ -145,7 +152,10 @@ forwards the event to the local server (`server.js`) and prints the server's ans
   and nothing new gets held, and anything already waiting goes back to VS Code after 5 seconds.
 - **Dashboard closed?** Same, after 15 seconds.
 - **Interrupt in VS Code** while something is waiting? The dashboard item disappears.
-- The server only listens on `127.0.0.1` and rejects requests from other websites.
+- The server only listens on `127.0.0.1`, rejects requests from other websites, and requires the token in
+  `~/.agenter/token`. Hooks read it from there, and the Agenter shortcut and `agenter` sign the dashboard in,
+  so open it that way rather than from a bookmark on a new browser. The token keeps out other Windows users
+  and anything that can only make HTTP requests. A program running as you can still read the file.
 
 ## Plan usage
 

package/cli.js

@@ -84,8 +84,9 @@ Usage: agenter [command]
   install          Add Agenter's hooks to ~/.claude/settings.json (backed up first)
                    and, on Windows, Desktop and Start Menu shortcuts
   uninstall        Remove the hooks and shortcuts
+  doctor           Check hooks, port, Claude Code and login, and say how to fix what's wrong
   start            Run the server in the foreground with logs
-  shortcuts        (Re)create the Windows shortcuts; --startup also starts the server at login
+  shortcuts        (Re)create the Windows shortcuts, and start Agenter in the tray at login
   version          Print the version
 
 After installing, reload your VS Code windows so Claude sessions pick up the hooks.`;
@@ -107,8 +108,16 @@ After installing, reload your VS Code windows so Claude sessions pick up the hoo
     case 'start':
       status = node('server.js', rest);
       break;
+    case 'doctor': {
+      const { runChecks, format } = require('./lib/doctor');
+      const { findClaude, findCodex } = require('./server');
+      const results = await runChecks({ findClaude, findCodex });
+      console.log(format(results));
+      status = results.some((r) => r.status === 'fail') ? 1 : 0;
+      break;
+    }
     case 'shortcuts':
-      status = shortcuts(rest.includes('--startup') ? ['-Startup'] : []);
+      status = shortcuts(['-Startup']);
       break;
     case 'version':
     case '--version':

package/hook.js

@@ -2,16 +2,21 @@
 // Claude Code hook bridge. Claude Code runs this for every hook event and pipes the
 // event JSON on stdin. We forward it to the Agenter server and print whatever it
 // answers. If the server isn't running we start it in the background (unless
-// AGENTER_AUTOSTART=0) and exit silently so Claude behaves normally this time.
+// AGENTER_AUTOSTART=0, or you quit the app) and exit silently so Claude behaves
+// normally this time.
 'use strict';
+const fs = require('node:fs');
 const http = require('node:http');
+const os = require('node:os');
 const path = require('node:path');
 const { spawn } = require('node:child_process');
+const { readToken } = require('./lib/token');
 
 const PORT = Number(process.env.AGENTER_PORT) || 4317;
 
 function startServer() {
   if (process.env.AGENTER_AUTOSTART === '0') return;
+  if (fs.existsSync(path.join(os.homedir(), '.agenter', 'stopped'))) return;
   try {
     spawn(process.execPath, [path.join(__dirname, 'server.js'), '--no-open'], { detached: true, stdio: 'ignore', windowsHide: true }).unref();
   } catch {}
@@ -27,7 +32,7 @@ process.stdin.on('end', () => {
       port: PORT,
       path: '/hook',
       method: 'POST',
-      headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(input) },
+      headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(input), 'x-agenter-token': readToken() },
     },
     (res) => {
       let body = '';

package/install.js

@@ -10,18 +10,7 @@ const SETTINGS = path.join(os.homedir(), '.claude', 'settings.json');
 const HOOK_SCRIPT = path.join(__dirname, 'hook.js').replace(/\\/g, '/');
 const COMMAND = `node "${HOOK_SCRIPT}"`;
 
-// timeout is in seconds. Events that can wait for you get an hour.
-const EVENTS = {
-  SessionStart: { timeout: 10 },
-  SessionEnd: { timeout: 10 },
-  UserPromptSubmit: { timeout: 10 },
-  PreToolUse: { matcher: '*', timeout: 3600 },
-  PostToolUse: { matcher: '*', timeout: 10 },
-  PermissionRequest: { matcher: '*', timeout: 3600 },
-  Notification: { timeout: 10 },
-  Stop: { timeout: 3600 },
-  SubagentStop: { timeout: 10 },
-};
+const EVENTS = require('./lib/hook-events');
 
 const uninstall = process.argv.includes('--uninstall');
 

package/lib/diff.js

@@ -0,0 +1,126 @@
+'use strict';
+// Line diffs for the file changes Claude asks permission for (Edit, MultiEdit, Write).
+// Built on the server so the dashboard only has to draw rows, and so it can be tested.
+const fs = require('node:fs');
+const path = require('node:path');
+
+const CONTEXT = 3; // unchanged lines kept around each change
+const MAX_ROWS = 300; // rows sent per file; the rest is summarised
+const MAX_FILE_BYTES = 512 * 1024; // bigger files aren't read to diff a Write against
+const MAX_CELLS = 1_500_000; // LCS table size; beyond this fall back to "all replaced"
+
+const lines = (text) => {
+  text = String(text ?? '').replace(/\r\n/g, '\n');
+  return text === '' ? [] : text.split('\n');
+};
+
+// Ops: { type: 'ctx' | 'del' | 'add', text }. Common start and end are peeled off first,
+// so the usual small edit in a big block costs almost nothing.
+function lineDiff(oldText, newText) {
+  const a = lines(oldText);
+  const b = lines(newText);
+  let head = 0;
+  while (head < a.length && head < b.length && a[head] === b[head]) head++;
+  let tail = 0;
+  while (tail < a.length - head && tail < b.length - head && a[a.length - 1 - tail] === b[b.length - 1 - tail]) tail++;
+
+  const ops = [];
+  for (let i = 0; i < head; i++) ops.push({ type: 'ctx', text: a[i] });
+  const am = a.slice(head, a.length - tail);
+  const bm = b.slice(head, b.length - tail);
+  middle(am, bm, ops);
+  for (let i = a.length - tail; i < a.length; i++) ops.push({ type: 'ctx', text: a[i] });
+  return ops;
+}
+
+function middle(a, b, ops) {
+  const n = a.length;
+  const m = b.length;
+  if (!n || !m || (n + 1) * (m + 1) > MAX_CELLS) {
+    for (const text of a) ops.push({ type: 'del', text });
+    for (const text of b) ops.push({ type: 'add', text });
+    return;
+  }
+  // dp[i][j] = length of the longest common subsequence of a[i..] and b[j..]
+  const w = m + 1;
+  const dp = new Uint32Array((n + 1) * w);
+  for (let i = n - 1; i >= 0; i--) {
+    for (let j = m - 1; j >= 0; j--) {
+      dp[i * w + j] = a[i] === b[j] ? dp[(i + 1) * w + j + 1] + 1 : Math.max(dp[(i + 1) * w + j], dp[i * w + j + 1]);
+    }
+  }
+  let i = 0;
+  let j = 0;
+  while (i < n && j < m) {
+    if (a[i] === b[j]) ops.push({ type: 'ctx', text: a[i++] }), j++;
+    else if (dp[(i + 1) * w + j] >= dp[i * w + j + 1]) ops.push({ type: 'del', text: a[i++] });
+    else ops.push({ type: 'add', text: b[j++] });
+  }
+  while (i < n) ops.push({ type: 'del', text: a[i++] });
+  while (j < m) ops.push({ type: 'add', text: b[j++] });
+}
+
+// Keeps changes plus `context` lines around them; long unchanged runs become one
+// { type: 'skip', count } row. Rows past `maxRows` become { type: 'more', count }.
+function compact(ops, context = CONTEXT, maxRows = MAX_ROWS) {
+  const keep = new Array(ops.length).fill(false);
+  ops.forEach((op, i) => {
+    if (op.type === 'ctx') return;
+    for (let k = Math.max(0, i - context); k <= Math.min(ops.length - 1, i + context); k++) keep[k] = true;
+  });
+  const rows = [];
+  let skipped = 0;
+  const flush = () => {
+    if (skipped) rows.push({ type: 'skip', count: skipped });
+    skipped = 0;
+  };
+  ops.forEach((op, i) => {
+    if (keep[i]) (flush(), rows.push(op));
+    else skipped++;
+  });
+  flush();
+  if (rows.length <= maxRows) return rows;
+  const omitted = rows.slice(maxRows).reduce((n, r) => n + (r.type === 'skip' ? r.count : 1), 0);
+  return [...rows.slice(0, maxRows), { type: 'more', count: omitted }];
+}
+
+function summarize(file, oldText, newText, extra = {}) {
+  const ops = lineDiff(oldText, newText);
+  return {
+    file,
+    ...extra,
+    added: ops.filter((o) => o.type === 'add').length,
+    removed: ops.filter((o) => o.type === 'del').length,
+    rows: compact(ops),
+  };
+}
+
+// The file as it is now, or null when it's missing, too big, or not text.
+function readExisting(file) {
+  try {
+    if (fs.statSync(file).size > MAX_FILE_BYTES) return undefined;
+    const text = fs.readFileSync(file, 'utf8');
+    return text.includes('\0') ? undefined : text;
+  } catch {
+    return null;
+  }
+}
+
+// What a permission prompt for this tool would change: an array with one entry per file
+// change, or null for tools that don't edit files (or when it can't be worked out).
+function buildDiffs(tool, input, { cwd = '', read = readExisting } = {}) {
+  try {
+    if (!input || typeof input !== 'object') return null;
+    const file = input.file_path;
+    if (tool === 'Edit') return [summarize(file, input.old_string, input.new_string)];
+    if (tool === 'MultiEdit' && Array.isArray(input.edits)) return input.edits.map((e) => summarize(file, e.old_string, e.new_string));
+    if (tool === 'Write' && typeof file === 'string') {
+      const existing = read(path.resolve(cwd || '.', file));
+      if (existing === undefined) return null; // there, but we can't show it
+      return [summarize(file, existing ?? '', input.content, { isNew: existing === null })];
+    }
+  } catch {}
+  return null;
+}
+
+module.exports = { lineDiff, compact, buildDiffs, CONTEXT, MAX_ROWS };

package/lib/doctor.js

@@ -0,0 +1,151 @@
+'use strict';
+// `agenter doctor`: checks the things that silently stop Agenter from working.
+// Every check reads what it needs from ctx, so tests can point it at a temp home folder.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const http = require('node:http');
+const EVENTS = require('./hook-events');
+
+const ok = (name, detail) => ({ name, status: 'ok', detail });
+const warn = (name, detail, fix) => ({ name, status: 'warn', detail, fix });
+const fail = (name, detail, fix) => ({ name, status: 'fail', detail, fix });
+
+const readJson = (file) => {
+  try {
+    return { value: JSON.parse(fs.readFileSync(file, 'utf8')) };
+  } catch (error) {
+    return { error: error.code === 'ENOENT' ? 'missing' : error.message };
+  }
+};
+
+// Is there an executable called `name` (with the usual Windows extensions) on PATH?
+function onPath(name, env, platform) {
+  const exts = platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+  for (const dir of (env.PATH || env.Path || '').split(path.delimiter)) {
+    for (const ext of exts) if (dir && fs.existsSync(path.join(dir, name + ext))) return true;
+  }
+  return false;
+}
+
+function checkNode(ctx) {
+  const major = Number(String(ctx.nodeVersion).replace(/^v/, '').split('.')[0]);
+  return major >= 18 ? ok('Node.js', `v${String(ctx.nodeVersion).replace(/^v/, '')}`) : fail('Node.js', `${ctx.nodeVersion} is too old (Agenter needs 18+)`, 'Install a current Node.js LTS.');
+}
+
+function checkHooks(ctx) {
+  const name = 'Claude hooks';
+  const file = path.join(ctx.home, '.claude', 'settings.json');
+  const { value, error } = readJson(file);
+  if (error === 'missing') return fail(name, `${file} doesn't exist yet`, 'Run: agenter install');
+  if (error) return fail(name, `${file} isn't valid JSON (${error})`, 'Fix the file, then run: agenter install');
+
+  // Hooks of ours, by event, with the script path each one runs.
+  const ours = {};
+  const scripts = new Set();
+  for (const [event, groups] of Object.entries(value.hooks || {})) {
+    for (const h of (Array.isArray(groups) ? groups : []).flatMap((g) => g?.hooks || [])) {
+      const script = typeof h?.command === 'string' && h.command.match(/"([^"]*[\\/]hook\.js)"/)?.[1];
+      if (!script || !(script.replace(/\\/g, '/') === ctx.hookScript || /agenter/i.test(script))) continue;
+      (ours[event] ||= []).push(script);
+      scripts.add(script);
+    }
+  }
+  if (!scripts.size) return fail(name, "Agenter's hooks aren't in ~/.claude/settings.json, so no sessions will show up", 'Run: agenter install');
+
+  const stale = [...scripts].filter((s) => !fs.existsSync(s));
+  if (stale.length) return fail(name, `a hook points at a file that no longer exists: ${stale[0]}`, 'Run: agenter install (it replaces the old hooks)');
+  const elsewhere = [...scripts].filter((s) => s.replace(/\\/g, '/') !== ctx.hookScript);
+  if (elsewhere.length) return warn(name, `hooks point at another copy of Agenter: ${elsewhere[0]}`, 'Run: agenter install to point them at this one');
+  const missing = Object.keys(EVENTS).filter((e) => !ours[e]);
+  if (missing.length) return warn(name, `no hook for: ${missing.join(', ')}`, 'Run: agenter install');
+  if (!onPath('node', ctx.env, ctx.platform)) return fail(name, 'the hooks run `node`, but node isn\'t on your PATH', 'Add Node.js to PATH, then reload VS Code.');
+  return ok(name, `${Object.keys(EVENTS).length} events installed`);
+}
+
+function checkClaude(ctx) {
+  const bin = ctx.findClaude();
+  return bin
+    ? ok('Claude Code', bin)
+    : warn('Claude Code', "couldn't find it, so \"Drive from Agenter\" and New session won't work (watching and approving still do)", 'Install the Claude Code VS Code extension, or set AGENTER_CLAUDE to the path of claude.exe.');
+}
+
+function checkLogin(ctx) {
+  const name = 'Plan usage login';
+  if (ctx.env.AGENTER_USAGE === '0') return ok(name, 'turned off (AGENTER_USAGE=0)');
+  const { value, error } = readJson(path.join(ctx.home, '.claude', '.credentials.json'));
+  if (error === 'missing') return warn(name, 'no Claude subscription login found, so the usage bars stay empty', 'Sign in with Claude Code using a Claude subscription.');
+  if (error) return warn(name, `couldn't read the saved login (${error})`);
+  const oauth = value.claudeAiOauth;
+  if (!oauth?.accessToken) return warn(name, 'saved login has no subscription token (API-key logins have no plan usage)');
+  if (oauth.expiresAt && oauth.expiresAt < ctx.now) return warn(name, 'saved login has expired; it renews the next time Claude runs');
+  return ok(name, oauth.subscriptionType ? `${oauth.subscriptionType} plan` : 'signed in');
+}
+
+function checkSettings(ctx) {
+  const name = 'Agenter settings';
+  const file = path.join(ctx.home, '.agenter', 'settings.json');
+  const { error } = readJson(file);
+  if (error === 'missing') return ok(name, 'none saved yet (defaults)');
+  return error ? warn(name, `${file} isn't valid JSON, so your settings are ignored (${error})`, 'Fix or delete the file.') : ok(name, file);
+}
+
+async function checkServer(ctx) {
+  const name = `Server (port ${ctx.port})`;
+  const state = await ctx.probeServer(ctx.port);
+  if (state === 'agenter') return ok(name, 'running');
+  if (state === 'other') return fail(name, `something else is using port ${ctx.port}`, 'Close it, or set AGENTER_PORT to another port (for both Agenter and your terminal).');
+  return ok(name, 'not running (it starts itself on the first Claude event, or run: agenter)');
+}
+
+function checkCodex(ctx) {
+  const bin = ctx.findCodex();
+  return bin ? ok('Codex', bin) : ok('Codex', 'not found (only needed to steer Codex sessions)');
+}
+
+// Asks whatever is listening on the port whether it's Agenter.
+function probeServer(port) {
+  return new Promise((resolve) => {
+    const req = http.get({ host: '127.0.0.1', port, path: '/', timeout: 1500 }, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (c) => body.length < 4096 && (body += c));
+      res.on('end', () => resolve(/agenter/i.test(body) ? 'agenter' : 'other'));
+    });
+    req.on('timeout', () => (req.destroy(), resolve('other')));
+    req.on('error', (e) => resolve(e.code === 'ECONNREFUSED' ? 'none' : 'other'));
+  });
+}
+
+async function runChecks(overrides = {}) {
+  const ctx = {
+    home: os.homedir(),
+    env: process.env,
+    platform: process.platform,
+    nodeVersion: process.version,
+    now: Date.now(),
+    port: Number(process.env.AGENTER_PORT) || 4317,
+    hookScript: path.join(__dirname, '..', 'hook.js').replace(/\\/g, '/'),
+    findClaude: () => null,
+    findCodex: () => null,
+    probeServer,
+    ...overrides,
+  };
+  return [checkNode(ctx), checkHooks(ctx), await checkServer(ctx), checkClaude(ctx), checkLogin(ctx), checkSettings(ctx), checkCodex(ctx)];
+}
+
+const MARK = { ok: '✓', warn: '!', fail: '✗' };
+
+function format(results) {
+  const lines = [];
+  for (const r of results) {
+    lines.push(`${MARK[r.status]} ${r.name}: ${r.detail}`);
+    if (r.fix && r.status !== 'ok') lines.push(`    → ${r.fix}`);
+  }
+  const bad = results.filter((r) => r.status === 'fail').length;
+  const odd = results.filter((r) => r.status === 'warn').length;
+  lines.push('', bad ? `${bad} problem${bad === 1 ? '' : 's'} found.` : odd ? 'Working, with some things to look at.' : 'All good.');
+  return lines.join('\n');
+}
+
+module.exports = { runChecks, format, checkHooks, checkLogin, checkSettings, checkServer, checkNode, onPath, probeServer };

package/lib/hook-events.js

@@ -0,0 +1,14 @@
+'use strict';
+// The Claude Code hook events Agenter installs, shared by install.js and `agenter doctor`.
+// timeout is in seconds. Events that can wait for you get an hour.
+module.exports = {
+  SessionStart: { timeout: 10 },
+  SessionEnd: { timeout: 10 },
+  UserPromptSubmit: { timeout: 10 },
+  PreToolUse: { matcher: '*', timeout: 3600 },
+  PostToolUse: { matcher: '*', timeout: 10 },
+  PermissionRequest: { matcher: '*', timeout: 3600 },
+  Notification: { timeout: 10 },
+  Stop: { timeout: 3600 },
+  SubagentStop: { timeout: 10 },
+};

package/lib/limits.js

@@ -0,0 +1,25 @@
+'use strict';
+// Turning plan-usage responses (Anthropic and Codex) into the limits the dashboard shows.
+
+const LIMIT_LABELS = { session: '5-hour session', weekly_all: 'Weekly · all models', weekly_opus: 'Weekly · Opus', weekly_sonnet: 'Weekly · Sonnet' };
+
+function normalizeLimits(j) {
+  if (Array.isArray(j.limits) && j.limits.length) {
+    return j.limits
+      .filter((l) => typeof l.percent === 'number')
+      .map((l) => ({ kind: l.kind, label: LIMIT_LABELS[l.kind] || String(l.kind).replace(/_/g, ' '), percent: l.percent, severity: l.severity || null, resetsAt: l.resets_at || null }));
+  }
+  // Older response shape.
+  const pick = (key, kind) => j[key] && typeof j[key].utilization === 'number' && { kind, label: LIMIT_LABELS[kind], percent: j[key].utilization, severity: null, resetsAt: j[key].resets_at || null };
+  return [pick('five_hour', 'session'), pick('seven_day', 'weekly_all'), pick('seven_day_opus', 'weekly_opus'), pick('seven_day_sonnet', 'weekly_sonnet')].filter(Boolean);
+}
+
+function codexWindowLabel(minutes) {
+  if (minutes === 300) return '5-hour session';
+  if (minutes === 10080) return 'Weekly';
+  if (minutes % 1440 === 0) return `${minutes / 1440}-day`;
+  if (minutes % 60 === 0) return `${minutes / 60}-hour`;
+  return `${minutes}-minute`;
+}
+
+module.exports = { LIMIT_LABELS, normalizeLimits, codexWindowLabel };

package/lib/open-dashboard.js

@@ -4,6 +4,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const { spawn, exec } = require('node:child_process');
+const { getToken } = require('./token');
 
 function findAppBrowser() {
   if (process.platform !== 'win32') return null;
@@ -13,7 +14,9 @@ function findAppBrowser() {
   return null;
 }
 
-module.exports = function openDashboard(url) {
+module.exports = function openDashboard(baseUrl) {
+  // In the fragment, so it never reaches a server or a log. The page keeps it from there.
+  const url = `${baseUrl}/#token=${getToken()}`;
   const browser = findAppBrowser();
   if (browser) {
     const child = spawn(browser, [`--app=${url}`, '--window-size=1280,860'], { detached: true, stdio: 'ignore' });

package/lib/token.js

@@ -0,0 +1,47 @@
+'use strict';
+// The shared secret every caller of the local server must present, kept in
+// ~/.agenter/token. server.js checks it, hook.js sends it for any agent, and the launchers
+// hand it to the dashboard. It stays the same across restarts, so open dashboards and
+// running sessions keep working.
+//
+// This keeps out other Windows users on the machine and anything that can only make
+// HTTP requests to localhost. A program running as you can still read the file.
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const tokenFile = () => path.join(os.homedir(), '.agenter', 'token');
+
+function readToken() {
+  try {
+    return fs.readFileSync(tokenFile(), 'utf8').trim();
+  } catch {
+    return '';
+  }
+}
+
+// Creates the token the first time. 'wx' so two processes starting together agree on one.
+function getToken() {
+  const existing = readToken();
+  if (existing) return existing;
+  const file = tokenFile();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const token = crypto.randomBytes(32).toString('hex');
+  try {
+    fs.writeFileSync(file, token, { flag: 'wx', mode: 0o600 });
+    return token;
+  } catch (err) {
+    if (err.code === 'EEXIST') return readToken();
+    throw err;
+  }
+}
+
+function sameToken(given, expected) {
+  if (typeof given !== 'string' || !expected) return false;
+  const a = Buffer.from(given);
+  const b = Buffer.from(expected);
+  return a.length === b.length && crypto.timingSafeEqual(a, b);
+}
+
+module.exports = { getToken, readToken, sameToken, tokenFile };