wisp-agents 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,12 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-17
+
+### Added
+
+- Anonymous usage stats and error reports via [PostHog](https://posthog.com): which agents, models and modes are used, run outcomes and timings, and errors (agent failures, server errors, crashes) with paths scrubbed. Never sends prompts, output, paths or project names. Turn it off in Settings → *Anonymous usage stats*, or with `WISP_TELEMETRY=0` / `DO_NOT_TRACK=1`; always off when `CI` is set. See the Telemetry section of the README.
+
 ## [0.4.0] - 2026-10-17
 
 ### Added
@@ -83,7 +89,8 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 - Session queue with follow-ups, answers to agent questions, terminal takeover and mark-as-done.
 - Older turns are folded, with a floating collapse-all button and back-to-top.
 
-[Unreleased]: https://github.com/M0xoo/wisp/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/M0xoo/wisp/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/M0xoo/wisp/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/M0xoo/wisp/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/M0xoo/wisp/compare/v0.2.2...v0.3.0
 [0.2.2]: https://github.com/M0xoo/wisp/compare/v0.2.1...v0.2.2

package/README.md

@@ -202,6 +202,21 @@ If the harness has no system-prompt flag, prepend `systemPrompt` to the first pr
 - [x] opencode adapter
 - [x] Cursor CLI adapter
 
+## Telemetry
+
+wisp sends anonymous usage stats and error reports to [PostHog](https://posthog.com) so we can see which agents people use and what breaks. The code is in [`server/telemetry.js`](server/telemetry.js).
+
+**What is sent:** a random install id (not tied to you or your machine), the wisp, OS, Node and agent CLI versions, and per run: agent, model, mode, effort, status, duration, token counts and cost, how many files changed, and which presentation block types came back. Errors include a stack trace and message with your home directory and file paths removed, cut to 500 characters.
+
+**Never sent:** prompts, replies, agent output, file contents, project names, paths or repo URLs.
+
+**Opt out** with any of these:
+- Settings → *Anonymous usage stats*
+- `WISP_TELEMETRY=0`
+- `DO_NOT_TRACK=1`
+
+It is also off whenever `CI` is set.
+
 ## Contributing
 
 Issues and PRs are welcome. wisp has no build step: edit `web/` or `server/`, then run `npm run dev` (or `npm run dev:web`) to see your changes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wisp-agents",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Launch coding agents, skip the transcript, read the presentation.",
   "type": "module",
   "bin": {

package/server/index.js

@@ -11,6 +11,7 @@ import { Runner, summarize, newId } from './runner.js';
 import { adapters, listAgents } from './adapters/index.js';
 import { welcomeSession } from './welcome.js';
 import { openInTerminal, TERMINALS, shq } from './terminal.js';
+import { Telemetry, envDisabled } from './telemetry.js';
 
 const WEB = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'web');
 
@@ -62,6 +63,29 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
   runner.on('finished', (f) => broadcast('finished', f));
   setInterval(() => broadcast('ping', {}), 25_000).unref();
 
+  const telemetry = new Telemetry(store);
+  const run = (s, t) => ({ agent: s.agent, model: s.model || 'default', mode: s.mode, effort: s.effort || 'default', followUp: s.turns.indexOf(t) > 0 });
+  runner.on('started', ({ session, turn }) => telemetry.track('turn_started', { ...run(session, turn), attachments: turn.attachments.length }));
+  runner.on('ended', ({ session, turn, interrupted, errorText }) => {
+    const blocks = turn.presentation?.blocks || [];
+    const st = turn.stats || {};
+    telemetry.track('turn_ended', {
+      ...run(session, turn),
+      status: interrupted ? 'interrupted' : turn.status, // done | error | stopped | interrupted
+      heroStatus: blocks.find((b) => b.type === 'hero')?.status,
+      durationMs: turn.endedAt - turn.startedAt,
+      blockCount: blocks.length,
+      blockTypes: [...new Set(blocks.map((b) => b.type))],
+      presentationFallback: !!turn.presentation?.fallback, // agent ignored or broke the wisp protocol
+      changedFiles: turn.changes.length,
+      inputTokens: st.inputTokens,
+      outputTokens: st.outputTokens,
+      costUsd: st.costUsd,
+    });
+    if (errorText) telemetry.captureError(new Error(errorText), { type: 'AgentError', ...run(session, turn) });
+  });
+  if (!envDisabled()) process.on('uncaughtExceptionMonitor', (err) => telemetry.crashed(err));
+
   const allowedHosts = new Set([`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`]);
 
   const server = http.createServer(async (req, res) => {
@@ -81,6 +105,7 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
       return serveStatic(res, url.pathname);
     } catch (err) {
       console.error(err);
+      if (!err.status || err.status >= 500) telemetry.captureError(err, { route: `${req.method} ${url.pathname.replace(/\/[a-f0-9]{8,}(?=\/|$)/g, '/:id')}` });
       send(res, err.status || 500, { error: err.message });
     }
   });
@@ -107,6 +132,7 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
         const body = await readJson(req);
         const s = store.get(body.session);
         if (!s) return send(res, 404, { error: 'no such session' });
+        telemetry.track('ask_user', { agent: s.agent });
         return send(res, 200, { id: runner.ask(s, body) });
       }
       if (id === 'ask' && action && m === 'GET') return send(res, 200, runner.pollAnswer(action));
@@ -148,7 +174,7 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
     }
 
     if (root === 'config') {
-      if (m === 'GET') return send(res, 200, { ...store.config, home: os.homedir(), cwd: process.cwd(), terminals: TERMINALS });
+      if (m === 'GET') return send(res, 200, { ...store.config, home: os.homedir(), cwd: process.cwd(), terminals: TERMINALS, telemetry: { available: !envDisabled(), enabled: telemetry.enabled } });
       if (m === 'PATCH') {
         const body = await readJson(req);
         if (body.defaults) Object.assign(store.config.defaults, body.defaults);
@@ -297,6 +323,7 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
           }
           openInTerminal({ cwd: s.cwd, argv, terminal: store.config.defaults.terminal || 'auto', custom: store.config.defaults.terminalCommand });
           s.takenOverAt = Date.now();
+          telemetry.track('takeover', { agent: s.agent, terminal: store.config.defaults.terminal || 'auto' });
           store.save(s);
           return send(res, 200, { command });
         }
@@ -341,6 +368,7 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
   const shutdown = () => {
     for (const s of store.all()) runner.stop(s);
     store.flush();
+    telemetry.persist();
   };
   if (handleSignals) {
     const exit = () => (shutdown(), process.exit(0));
@@ -353,7 +381,14 @@ export async function startServer({ port = 4477, host = '127.0.0.1', handleSigna
     server.listen(port, host, resolve);
   });
 
-  return { url: `http://localhost:${port}`, server, store, runner, shutdown };
+  if (telemetry.enabled) {
+    if (store.config.defaults.telemetryNotice !== 'seen') console.log('wisp sends anonymous usage stats and error reports (no prompts, paths or code). Opt out: Settings, or WISP_TELEMETRY=0 / DO_NOT_TRACK=1.');
+    listAgents()
+      .then((agents) => telemetry.track('app_started', { agentsInstalled: agents.filter((a) => a.available).map((a) => a.id), ...Object.fromEntries(agents.filter((a) => a.available).map((a) => [`${a.id}Version`, a.version])) }))
+      .catch(() => {});
+  }
+
+  return { url: `http://localhost:${port}`, server, store, runner, shutdown, telemetry };
 }
 
 function send(res, status, body) {

package/server/runner.js

@@ -220,6 +220,7 @@ export class Runner extends EventEmitter {
     session.unread = false;
     delete session.archived;
     this.#touch(session, { turn: turn.id });
+    this.emit('started', { session, turn });
 
     let released = false;
     let linger;
@@ -341,6 +342,7 @@ export class Runner extends EventEmitter {
     session.unread = !interrupted;
     this.store.save(session, { now: true });
     this.#touch(session, { turn: turn.id });
+    this.emit('ended', { session, turn, interrupted, errorText: ev.isError && !ev.stopped ? ev.text : '' });
     // The follow-up starts right away; don't notify for the run it replaced.
     if (!interrupted) this.emit('finished', { session: summarize(session, this.store) });
   }

package/server/telemetry.js

@@ -0,0 +1,132 @@
+// Anonymous usage analytics + error reports, sent to PostHog over its plain HTTP API (no SDK, to
+// stay dependency-free). What goes out is fixed values only — agent, model, mode, status, timings,
+// counts — never prompts, paths, project names or agent output. Error messages and stacks are
+// scrubbed of the home directory and truncated.
+//
+// Off when any of: no API key, DO_NOT_TRACK=1, WISP_TELEMETRY=0, CI, or "telemetry": "off" in
+// settings. See the Telemetry section of the README.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+
+// PostHog project API key: write-only, safe to ship in the client.
+const KEY = process.env.WISP_POSTHOG_KEY ?? 'phc_wowwZkbP8e4zYuwT67JtX6oxdPwkMWL5kKnrUmYYXhcD';
+const HOST = (process.env.WISP_POSTHOG_HOST || 'https://us.i.posthog.com').replace(/\/$/, '');
+const FLUSH_MS = 15_000;
+const MAX_QUEUE = 50;
+const TIMEOUT_MS = 3000;
+
+const VERSION = JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const truthy = (v) => !!v && !/^(0|false|no|off)$/i.test(v);
+
+export function envDisabled(env = process.env) {
+  return !KEY || truthy(env.DO_NOT_TRACK) || /^(0|false|no|off)$/i.test(env.WISP_TELEMETRY || '') || truthy(env.CI);
+}
+
+const ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+// Paths in messages and stacks would leak usernames and project names: wisp's own files keep
+// their package-relative path, anything else is cut down to its file name.
+export function scrub(text = '', { home = os.homedir(), root = ROOT } = {}) {
+  let s = String(text).split(root).join('<wisp>');
+  if (home) s = s.split(home).join('~');
+  // Any other absolute path keeps only its file name.
+  return s
+    .replace(/(?<![\w<>~.:/\\-])(?:~|[A-Za-z]:)?[/\\](?:[^\s'"`():/\\]+[/\\])+([^\s'"`():/\\]*)/g, (m, base) => `…/${base}`)
+    .slice(0, 500);
+}
+
+function frames(stack = '') {
+  return String(stack)
+    .split('\n')
+    .slice(1, 30)
+    .map((l) => l.trim().match(/^at (?:(.+?) \()?(.+?):(\d+):(\d+)\)?$/))
+    .filter(Boolean)
+    .map(([, fn, file, line, col]) => ({ platform: 'custom', lang: 'javascript', function: fn || '?', filename: scrub(file.replace(/^file:\/\//, '')), lineno: +line, colno: +col, in_app: file.includes(ROOT) && !file.includes('node_modules') }))
+    .reverse(); // PostHog wants the innermost frame last
+}
+
+export class Telemetry {
+  constructor(store, { shell = process.versions.electron ? 'electron' : 'browser' } = {}) {
+    this.store = store;
+    this.queue = [];
+    this.pendingFile = path.join(store.home, 'telemetry-pending.json');
+    this.common = {
+      $lib: 'wisp',
+      $process_person_profile: false, // anonymous events: no person profiles
+      version: VERSION,
+      os: process.platform,
+      osRelease: os.release(),
+      arch: process.arch,
+      node: process.versions.node,
+      electron: process.versions.electron || undefined,
+      shell,
+    };
+    this.timer = setInterval(() => this.flush(), FLUSH_MS);
+    this.timer.unref();
+    this.#sendPending();
+  }
+
+  get enabled() {
+    return !envDisabled() && this.store.config.defaults.telemetry !== 'off';
+  }
+
+  track(event, props = {}) {
+    if (!this.enabled) return;
+    if (!this.store.config.telemetryId) {
+      this.store.config.telemetryId = randomUUID(); // random per install, not tied to the machine or user
+      this.store.saveConfig();
+    }
+    this.queue.push({ event, timestamp: new Date().toISOString(), properties: { ...this.common, ...props, distinct_id: this.store.config.telemetryId } });
+    if (this.queue.length >= MAX_QUEUE) this.flush();
+  }
+
+  // PostHog error tracking format.
+  captureError(err, props = {}) {
+    const e = err instanceof Error ? err : new Error(String(err));
+    this.track('$exception', {
+      ...props,
+      $exception_list: [{ type: props.type || e.name || 'Error', value: scrub(e.message), mechanism: { handled: props.handled ?? true, synthetic: false }, stacktrace: { type: 'raw', frames: frames(e.stack) } }],
+    });
+  }
+
+  async flush() {
+    if (!this.queue.length) return;
+    const batch = this.queue.splice(0);
+    try {
+      await fetch(`${HOST}/batch/`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ api_key: KEY, batch }),
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+      });
+    } catch {} // offline or blocked: drop it, telemetry must never get in the way
+  }
+
+  // Shutdown and crashes leave no time for a request: write what's queued to disk (sync) and
+  // send it on the next start.
+  persist() {
+    clearInterval(this.timer);
+    if (!this.queue.length) return;
+    try {
+      fs.writeFileSync(this.pendingFile, JSON.stringify(this.queue.splice(0)));
+    } catch {}
+  }
+
+  crashed(err) {
+    if (!this.enabled) return;
+    this.captureError(err, { handled: false, type: err?.name || 'UncaughtException' });
+    this.persist();
+  }
+
+  #sendPending() {
+    try {
+      const pending = JSON.parse(fs.readFileSync(this.pendingFile, 'utf8'));
+      fs.rmSync(this.pendingFile, { force: true });
+      if (this.enabled && Array.isArray(pending)) this.queue.push(...pending.slice(-200));
+    } catch {}
+  }
+}

package/web/js/app.js

@@ -1701,6 +1701,7 @@ function openSettings() {
       <label class="custom-term" ${d.terminal === 'custom' ? '' : 'hidden'}><span>Terminal command</span>
         <input name="terminalCommand" value="${esc(d.terminalCommand || '')}" placeholder="alacritty --working-directory {cwd} -e {cmd}" spellcheck="false"></label>
       <div class="setting"><span>Desktop notifications</span><span class="notif-hint muted xs"></span><button class="switch" id="notif" role="switch"></button></div>
+      <div class="setting"><span>Anonymous usage stats</span><span class="tele-hint muted xs"></span><button class="switch" id="tele" role="switch"></button></div>
       <div class="agents">${S.agents
         .map((a) => `<div class="agent-row"><span class="dot ${a.available ? 'ok' : 'bad'}"></span><b>${esc(a.name)}</b><span class="muted">${esc(a.available ? a.version : a.error || 'not found')}</span></div>`)
         .join('')}<p class="muted xs">Pick the agent next to the model in the launcher. Others plug in via <code>server/adapters</code>.</p></div>
@@ -1733,6 +1734,28 @@ function openSettings() {
     paint();
   };
   paint();
+  // Agent, model, status, timings and scrubbed errors only; never prompts, paths or code.
+  const tele = $('#tele', node);
+  const paintTele = () => {
+    const t = S.config.telemetry || {};
+    tele.setAttribute('aria-checked', !!t.enabled);
+    tele.disabled = !t.available;
+    $('.tele-hint', node).textContent = !t.available ? 'Off (DO_NOT_TRACK, WISP_TELEMETRY=0 or CI)' : 'No prompts, paths or code';
+  };
+  tele.onclick = async () => {
+    await api('/config', { method: 'PATCH', body: { defaults: { telemetry: S.config.telemetry?.enabled ? 'off' : 'on' } } });
+    await loadConfig();
+    paintTele();
+  };
+  paintTele();
+}
+
+// Say once that anonymous stats are on, with a way out.
+function telemetryNotice() {
+  if (!S.config.telemetry?.enabled || S.config.defaults.telemetryNotice === 'seen') return;
+  S.config.defaults.telemetryNotice = 'seen';
+  api('/config', { method: 'PATCH', body: { defaults: { telemetryNotice: 'seen' } } }).catch(() => {});
+  toast('wisp sends anonymous usage stats and error reports. No prompts, paths or code.', { timeout: 10_000, action: { label: 'Settings', run: openSettings } });
 }
 
 function shortcuts() {
@@ -2041,4 +2064,5 @@ window.addEventListener('focus', () => {
   connect();
   route();
   $('#prompt')?.focus();
+  telemetryNotice();
 })();