@swestash/agent-lens 0.13.0 → 0.13.1

package/README.md

@@ -43,6 +43,23 @@ agent-lens service install         # periodic collect+ingest AND the always-on U
 agent-lens watch                   # a resident process that collects+ingests on file change
 ```
 
+No configuration is required to start: with no config file, Agent Lens collects the single default
+source `~/.claude`.
+
+### Where your data lives
+
+Installed from npm, the archive and SQLite store go to a per-user data directory:
+
+| Platform | Data directory |
+| --- | --- |
+| Linux | `$XDG_DATA_HOME/agent-lens`, else `~/.local/share/agent-lens` |
+| macOS | `~/Library/Application Support/agent-lens` |
+| Windows | `%LOCALAPPDATA%\agent-lens` |
+
+Set `AGENT_LENS_DATA` to put it elsewhere — that is the only way to relocate the archive, which the
+SQLite store and triage sidecar follow. `agent-lens config` prints the resolved paths and where each
+value came from.
+
 ### Commands
 
 | Command | What it does |
@@ -51,8 +68,10 @@ agent-lens watch                   # a resident process that collects+ingests on
 | `agent-lens ingest` | Normalize the archive into the SQLite store. |
 | `agent-lens serve` | Serve the web UI + read-only API at `http://127.0.0.1:4477`. |
 | `agent-lens watch` | Foreground resident: collect + ingest on file change. |
-| `agent-lens metrics` | Print store metrics to the terminal. |
+| `agent-lens metrics` | Re-run classification, security detection, error typing, and file-change indexing over an already-ingested store. |
+| `agent-lens export <sessionId>` | Write a session to a shareable Markdown file — redacted by default (`--level secrets\|structure`, `--no-redact` to opt out). |
 | `agent-lens service <install\|uninstall\|status> [collector\|server\|all]` | Install/manage OS services (systemd / launchd / Windows Task Scheduler). |
+| `agent-lens config` | Print the effective configuration — sources, paths, server binding — and where each value came from. |
 
 ## Privacy
 

package/dist/agent-lens.js

@@ -1264,6 +1264,14 @@ function classifyToolError(resultSummary) {
   return { type: "other", kind: errorKind("other") };
 }
 
+// ../core/dist/user-error.js
+var UserError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UserError";
+  }
+};
+
 // ../core/dist/pricing.js
 var SYNTHETIC_MODEL = "<synthetic>";
 function unpricedModels(models) {
@@ -1495,7 +1503,7 @@ function resolveDbPath(override, cfg = readConfigFile()) {
 function validatePort(value, source) {
   const n = typeof value === "number" ? value : Number(String(value).trim());
   if (!Number.isInteger(n) || n < 1 || n > 65535) {
-    throw new Error(`agent-lens: invalid port from ${source}: '${value}' (expected an integer 1-65535)`);
+    throw new UserError(`invalid port from ${source}: '${value}' (expected an integer 1-65535)`);
   }
   return n;
 }
@@ -1608,12 +1616,12 @@ function loadSources() {
     if (!s || !s.label || !s.configDir)
       continue;
     if (seen.has(s.label))
-      throw new Error(`duplicate source label: ${s.label}`);
+      throw new UserError(`duplicate source label: ${s.label}`);
     seen.add(s.label);
     out.push({ label: s.label, agent: s.agent || "claude-code", configDir: expandPath(s.configDir) });
   }
   if (!out.length)
-    throw new Error("no valid sources configured");
+    throw new UserError("no valid sources configured");
   return out;
 }
 function loadExcludes() {
@@ -1854,7 +1862,7 @@ function collectAll(opts = {}) {
   ensureDir(archiveBase);
   const stats = { sources: 0, scanned: 0, copied: 0, appended: 0, diverged: 0, compacted: 0, snapshots: 0 };
   if (!sources.length)
-    throw new Error("no sources configured");
+    throw new UserError("no sources configured");
   for (const source of sources) {
     stats.sources++;
     collectSource(source, archiveBase, excludedDirs, runTs, stats, log);
@@ -1908,7 +1916,7 @@ function acquireLock(lockPath, staleMs = 6 * 60 * 60 * 1e3) {
 import { spawnSync as spawnSync2 } from "node:child_process";
 import { mkdirSync as mkdirSync3, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir as homedir2, platform as platform3, userInfo } from "node:os";
-import { join as join5 } from "node:path";
+import { join as join5, resolve as resolve2 } from "node:path";
 var DEFAULT_HOURS = [9, 13, 17, 21];
 function currentUser() {
   try {
@@ -1929,14 +1937,14 @@ function parseTargets(spec) {
     return ["collector", "server"];
   if (spec === "collector" || spec === "server")
     return [spec];
-  throw new Error(`invalid target '${spec}' (expected: collector | server | all)`);
+  throw new UserError(`invalid target '${spec}' (expected: collector | server | all)`);
 }
 function parseHours(spec) {
   if (!spec)
     return DEFAULT_HOURS;
   const hours = spec.split(",").map((s) => Number.parseInt(s.trim(), 10)).filter((n) => Number.isInteger(n) && n >= 0 && n <= 23);
   if (!hours.length)
-    throw new Error(`invalid hours '${spec}' (expected comma-separated 0-23, e.g. 9,13,17,21)`);
+    throw new UserError(`invalid hours '${spec}' (expected comma-separated 0-23, e.g. 9,13,17,21)`);
   return [...new Set(hours)].sort((a, b) => a - b);
 }
 function serverEnv() {
@@ -1948,10 +1956,26 @@ function serverEnv() {
     env.AGENT_LENS_HOST = host;
   return env;
 }
+function pathEnv() {
+  const env = {};
+  if (process.env.AGENT_LENS_DATA)
+    env.AGENT_LENS_DATA = resolveDataDir();
+  if (process.env.AGENT_LENS_CONFIG)
+    env.AGENT_LENS_CONFIG = resolve2(process.env.AGENT_LENS_CONFIG);
+  return env;
+}
+function reportBakedEnv(env) {
+  for (const [k, v] of Object.entries(env))
+    console.log(`agent-lens service:   ${k}=${v}`);
+}
 function onCalendarHours(hours) {
   return hours.map((h) => String(h).padStart(2, "0")).join(",") + ":00";
 }
-function systemdCollectorService(node, cli2) {
+function systemdEnvLines(env) {
+  return Object.entries(env).map(([k, v]) => `Environment=${k}=${v}
+`).join("");
+}
+function systemdCollectorService(node, cli2, env = {}) {
   return `[Unit]
 Description=Agent Lens \u2014 collect + ingest Claude Code session traces
 
@@ -1959,7 +1983,7 @@ Description=Agent Lens \u2014 collect + ingest Claude Code session traces
 Type=oneshot
 # Absolute node + CLI paths: systemd user services don't inherit the interactive PATH.
 ExecStart=${node} ${cli2} collect --then-ingest
-Nice=10
+${systemdEnvLines(env)}Nice=10
 IOSchedulingClass=idle
 `;
 }
@@ -1978,8 +2002,7 @@ WantedBy=timers.target
 `;
 }
 function systemdServerService(node, cli2, env = {}) {
-  const envLines = Object.entries(env).map(([k, v]) => `Environment=${k}=${v}
-`).join("");
+  const envLines = systemdEnvLines(env);
   return `[Unit]
 Description=Agent Lens \u2014 local web UI + read-only API server
 After=network.target
@@ -2000,7 +2023,17 @@ Nice=10
 WantedBy=default.target
 `;
 }
-function launchdCollectorPlist(node, cli2, hours, logPath) {
+function launchdEnvDict(env) {
+  if (!Object.keys(env).length)
+    return "";
+  const entries = Object.entries(env).map(([k, v]) => `    <key>${k}</key><string>${v}</string>`).join("\n");
+  return `  <key>EnvironmentVariables</key>
+  <dict>
+${entries}
+  </dict>
+`;
+}
+function launchdCollectorPlist(node, cli2, hours, logPath, env = {}) {
   const cal = hours.map((h) => `    <dict><key>Hour</key><integer>${h}</integer><key>Minute</key><integer>0</integer></dict>`).join("\n");
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -2018,18 +2051,14 @@ function launchdCollectorPlist(node, cli2, hours, logPath) {
   <array>
 ${cal}
   </array>
-  <key>StandardOutPath</key><string>${logPath}</string>
+${launchdEnvDict(env)}  <key>StandardOutPath</key><string>${logPath}</string>
   <key>StandardErrorPath</key><string>${logPath}</string>
 </dict>
 </plist>
 `;
 }
 function launchdServerPlist(node, cli2, logPath, env = {}) {
-  const envDict = Object.entries(env).length ? `  <key>EnvironmentVariables</key>
-  <dict>
-${Object.entries(env).map(([k, v]) => `    <key>${k}</key><string>${v}</string>`).join("\n")}
-  </dict>
-` : "";
+  const envDict = launchdEnvDict(env);
   return `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -2068,22 +2097,25 @@ function linuxInstall(targets, node, cli2, hours) {
   }
   const dir = systemdUnitDir();
   mkdirSync3(dir, { recursive: true });
+  const paths = pathEnv();
   if (targets.includes("collector")) {
-    writeFileSync2(join5(dir, SYSTEMD_COLLECTOR_SERVICE), systemdCollectorService(node, cli2));
+    writeFileSync2(join5(dir, SYSTEMD_COLLECTOR_SERVICE), systemdCollectorService(node, cli2, paths));
     writeFileSync2(join5(dir, SYSTEMD_COLLECTOR_TIMER), systemdCollectorTimer(hours));
   }
   if (targets.includes("server")) {
-    writeFileSync2(join5(dir, SYSTEMD_SERVER_SERVICE), systemdServerService(node, cli2, serverEnv()));
+    writeFileSync2(join5(dir, SYSTEMD_SERVER_SERVICE), systemdServerService(node, cli2, { ...paths, ...serverEnv() }));
   }
   sh("systemctl", ["--user", "daemon-reload"]);
   if (targets.includes("collector")) {
     sh("systemctl", ["--user", "enable", "--now", SYSTEMD_COLLECTOR_TIMER]);
     console.log(`agent-lens service: installed collector timer (${onCalendarHours(hours)})`);
+    reportBakedEnv(paths);
     sh("systemctl", ["--user", "list-timers", SYSTEMD_COLLECTOR_TIMER, "--no-pager"]);
   }
   if (targets.includes("server")) {
     sh("systemctl", ["--user", "enable", "--now", SYSTEMD_SERVER_SERVICE]);
     console.log("agent-lens service: installed server daemon");
+    reportBakedEnv({ ...paths, ...serverEnv() });
     sh("systemctl", ["--user", "status", SYSTEMD_SERVER_SERVICE, "--no-pager"]);
   }
   const user = currentUser();
@@ -2135,17 +2167,21 @@ function macInstall(targets, node, cli2, hours) {
   const agents = join5(homedir2(), "Library", "LaunchAgents");
   mkdirSync3(agents, { recursive: true });
   const dataDir = resolveDataDir(findRepoRoot());
+  const paths = pathEnv();
   if (targets.includes("collector")) {
     const plist = launchdPlistPath(LAUNCHD_COLLECTOR_LABEL);
-    writeFileSync2(plist, launchdCollectorPlist(node, cli2, hours, join5(dataDir, "schedule.log")));
+    writeFileSync2(plist, launchdCollectorPlist(node, cli2, hours, join5(dataDir, "schedule.log"), paths));
     macBootstrap(plist);
     console.log(`agent-lens service: installed collector agent ${LAUNCHD_COLLECTOR_LABEL} (hours ${hours.join(",")})`);
+    reportBakedEnv(paths);
   }
   if (targets.includes("server")) {
     const plist = launchdPlistPath(LAUNCHD_SERVER_LABEL);
-    writeFileSync2(plist, launchdServerPlist(node, cli2, join5(dataDir, "server.log"), serverEnv()));
+    const env = { ...paths, ...serverEnv() };
+    writeFileSync2(plist, launchdServerPlist(node, cli2, join5(dataDir, "server.log"), env));
     macBootstrap(plist);
     console.log(`agent-lens service: installed server agent ${LAUNCHD_SERVER_LABEL}`);
+    reportBakedEnv(env);
   }
 }
 function macUninstall(targets) {
@@ -2166,6 +2202,13 @@ function winCollectorTaskName(hour) {
   return `${WINDOWS_COLLECTOR_PREFIX}_${String(hour).padStart(2, "0")}`;
 }
 function windowsInstall(targets, node, cli2, hours) {
+  const unbakeable = Object.entries({ ...pathEnv(), ...serverEnv() });
+  if (unbakeable.length) {
+    console.log("agent-lens service: Task Scheduler cannot carry environment variables. Set these");
+    console.log("agent-lens service: for your user account so the task sees them, then reinstall:");
+    for (const [k, v] of unbakeable)
+      console.log(`agent-lens service:   setx ${k} "${v}"`);
+  }
   if (targets.includes("collector")) {
     const tr = `"${node}" "${cli2}" collect --then-ingest`;
     for (const h of hours) {
@@ -6127,6 +6170,13 @@ async function runWatch(opts = {}) {
 function version() {
   return resolveVersion().version;
 }
+function die(e) {
+  if (e instanceof UserError) {
+    console.error(`agent-lens: ${e.message}`);
+    process.exit(1);
+  }
+  throw e;
+}
 function withLock(fn) {
   const lockPath = join12(resolveDataDir(findRepoRoot()), ".agent-lens.lock");
   const lock = acquireLock(lockPath);
@@ -6158,12 +6208,7 @@ cli.command("ingest", "Build/update the SQLite projection from the archive").opt
   withLock(() => runIngest(argv));
 });
 cli.command("serve", "Serve the web UI + read-only API on 127.0.0.1").option("--port <n>", "HTTP port (overrides AGENT_LENS_PORT / config server.port; default 4477)").option("--host <host>", "Bind host (overrides AGENT_LENS_HOST / config server.host; loopback only unless AGENT_LENS_ALLOW_NONLOCAL=1)").option("--db <path>", "SQLite DB path (overrides AGENT_LENS_DB / config db)").action(async (opts) => {
-  try {
-    await startServer({ port: opts.port, host: opts.host, db: opts.db });
-  } catch (e) {
-    console.error(e instanceof Error ? e.message : String(e));
-    process.exit(1);
-  }
+  await startServer({ port: opts.port, host: opts.host, db: opts.db });
 });
 cli.command("watch", "Watch sources and collect + ingest on change (resident process)").option("--interval <sec>", "Also run on a fixed interval (seconds)").option("--poll", "Use polling \u2014 for network filesystems where fs events don't fire").action(async (opts) => {
   await runWatch({ intervalSec: opts.interval ? Number(opts.interval) : void 0, poll: !!opts.poll });
@@ -6202,14 +6247,7 @@ cli.command("config", "Show the effective configuration (sources, paths, server)
   const repoRoot = findRepoRoot();
   const dataDir = resolveDataDir(repoRoot);
   const configFile = resolveConfigFile(repoRoot, dataDir);
-  let server;
-  try {
-    server = resolveServerConfig();
-  } catch (e) {
-    console.error(e instanceof Error ? e.message : String(e));
-    process.exit(1);
-  }
-  const { port, host, portOrigin, hostOrigin } = server;
+  const { port, host, portOrigin, hostOrigin } = resolveServerConfig();
   const { path: dbPath, origin: dbOrigin } = resolveDbPath();
   const archive = resolveArchiveDir(repoRoot);
   const triageDb = triageDbFor(dbPath);
@@ -6237,5 +6275,10 @@ cli.command("config", "Show the effective configuration (sources, paths, server)
 });
 cli.help();
 cli.version(version());
-cli.parse();
+process.on("unhandledRejection", die);
+try {
+  cli.parse();
+} catch (e) {
+  die(e);
+}
 //# sourceMappingURL=agent-lens.js.map