agentworth 0.1.16 → 0.1.18

package/README.md

@@ -3,10 +3,10 @@
 Official npm launcher for **AgentWorth** — discover, normalize, and understand AI-agent histories locally.
 
 ```bash
-npx agentworth
+npx -y agentworth@latest
 ```
 
-When run with no arguments, `npx agentworth` defaults to launching the local web UI (`serve --open`). All native subcommands and flags are forwarded transparently to the native binary.
+When run with no arguments, `npx -y agentworth@latest` defaults to launching the local web UI (`serve --open`). All native subcommands and flags are forwarded transparently to the native binary.
 
 ---
 
@@ -17,7 +17,7 @@ When run with no arguments, `npx agentworth` defaults to launching the local web
 Launch the local interactive UI:
 
 ```bash
-npx agentworth
+npx -y agentworth@latest
 ```
 
 ### CLI Subcommands
@@ -25,45 +25,45 @@ npx agentworth
 Scan and index local agent histories across 11 agent adapters:
 
 ```bash
-npx agentworth scan
+npx -y agentworth@latest scan
 ```
 
 View summary statistics across all indexed traces:
 
 ```bash
-npx agentworth stats
+npx -y agentworth@latest stats
 ```
 
 Inspect token rollups, costs, and rolling pacing:
 
 ```bash
-npx agentworth usage --period day
-npx agentworth usage --pacing
+npx -y agentworth@latest usage --period day
+npx -y agentworth@latest usage --pacing
 ```
 
 Trace file modifications back to the AI agent session and prompt:
 
 ```bash
-npx agentworth blame src/main.rs
+npx -y agentworth@latest blame src/main.rs
 ```
 
 List indexed sessions with filtering by adapter or model:
 
 ```bash
-npx agentworth traces --limit 20
-npx agentworth traces --adapter claude_code --json
+npx -y agentworth@latest traces --limit 20
+npx -y agentworth@latest traces --adapter claude_code --json
 ```
 
 Inspect a specific session with timeline and outcome analysis:
 
 ```bash
-npx agentworth inspect <session-id>
+npx -y agentworth@latest inspect <session-id>
 ```
 
 Export traces safely with automatic secret and path redaction:
 
 ```bash
-npx agentworth export <session-id> --redact --format atif --output session.atif.json
+npx -y agentworth@latest export <session-id> --redact --format atif --output session.atif.json
 ```
 
 ---
@@ -94,7 +94,7 @@ You can also install the native AgentWorth binary directly:
 | **Standalone Script** | `curl -fsSL https://agentworth.dev/install.sh | sh` | Installs the pre-built native binary directly to `~/.local/bin`. |
 | **Homebrew** | `brew install unfoundbox-crew/tap/agentworth` | Installs via official Homebrew tap. |
 | **Cargo (Native)** | `cargo install agentworth-cli` | Compiles and installs `agentworth` and its short alias `archie` to `~/.cargo/bin`. |
-| **NPX (Instant)** | `npx agentworth` | Zero-install runner that detects or downloads the native binary. |
+| **NPX (Instant)** | `npx -y agentworth@latest` | Zero-install runner that detects or downloads the native binary. |
 
 ---
 

package/lib/resolver.js

@@ -9,6 +9,80 @@ import { fileURLToPath } from 'node:url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
+// -----------------------------------------------------------------------------
+// The brand line
+// -----------------------------------------------------------------------------
+// The launcher's first run is an onboarding screen, so it prints the same one-line Archie
+// form the CLI and the install script do -- packages/ui/brand/archie/archie-tui.txt:
+//
+//   (o) archie  downloading  ----------.......  68%  15.9 / 22.2 MB
+//
+// The lamp is the state, the label says what is happening, the rest is evidence. Glyph set
+// is docs/DESIGN.md's: ASCII, U+2500-259F, and the five extras. No emoji, no colour: this
+// goes to stderr, which lands in CI logs and pipes with the colour stripped. Everything
+// here writes to stderr so `npx agentworth stats --json | jq` still works.
+
+const BRAND_LABEL_WIDTH = 11;
+
+/** Fixed overhead of the wide layout: the lamp, the name, the label, the percent, the sizes. */
+const BRAND_WIDE_OVERHEAD = 50;
+/** The same for the narrow layout, which drops the label. */
+const BRAND_NARROW_OVERHEAD = 28;
+/** Below this the label gives way -- the CLI's ARCHIE_BLOCK_MIN_COLUMNS rule, same shape. */
+const BRAND_WIDE_MIN = 56;
+
+function brandColumns() {
+  const raw = process.stderr.columns || Number(process.env.COLUMNS) || 80;
+  return Math.min(100, Math.max(46, raw));
+}
+
+/** ` (*) archie  installed    archie in ~/.agentworth/bin/v0.1.16` */
+export function brandLine(lamp, label, rest) {
+  return ` (${lamp}) archie  ${label.padEnd(BRAND_LABEL_WIDTH)}  ${rest}`;
+}
+
+function mib(bytes) {
+  return (bytes / 1048576).toFixed(1);
+}
+
+/**
+ * One redraw of the download line. Pure string building so the layout is testable without
+ * a socket: `cols` and `unicode` are injected rather than read off the terminal.
+ */
+export function downloadLine(done, total, { cols = 80, unicode = true, lamp = 'o' } = {}) {
+  const fill = unicode ? '─' : '-';
+  const track = unicode ? '·' : '.';
+
+  // A server that sent no Content-Length gets bytes and no bar: a bar with a made-up
+  // denominator is a progress indicator that lies.
+  if (!total || total < 100) {
+    return brandLine(lamp, 'downloading', `${mib(done)} MB`);
+  }
+
+  const pct = Math.min(100, Math.floor((done / total) * 100));
+  const pctCell = `${String(pct).padStart(3)}%`;
+
+  if (cols >= BRAND_WIDE_MIN) {
+    const bw = Math.min(28, Math.max(6, cols - BRAND_WIDE_OVERHEAD));
+    const on = Math.round((pct * bw) / 100);
+    return brandLine(
+      lamp,
+      'downloading',
+      `${fill.repeat(on)}${track.repeat(bw - on)}  ${pctCell}  ${mib(done)} / ${mib(total)} MB`,
+    );
+  }
+
+  const bw = Math.min(20, Math.max(6, cols - BRAND_NARROW_OVERHEAD));
+  const on = Math.round((pct * bw) / 100);
+  return ` (${lamp}) archie  ${fill.repeat(on)}${track.repeat(bw - on)}  ${pctCell}  ${mib(done)} MB`;
+}
+
+/** `~/.agentworth/bin/v0.1.16` rather than the expanded home, so the line fits 80 columns. */
+function tilde(p) {
+  const home = os.homedir();
+  return home && p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+}
+
 /**
  * Returns the normalized platform key (e.g. darwin-arm64, linux-x64, win32-x64).
  *
@@ -167,7 +241,7 @@ export function findCargoTargetBinary(startDir, binName = getBinaryName()) {
  * @param {number} [redirects=5]
  * @returns {Promise<void>}
  */
-export function downloadFile(url, destPath, redirects = 5) {
+export function downloadFile(url, destPath, redirects = 5, onProgress = null) {
   return new Promise((resolve, reject) => {
     if (redirects < 0) {
       return reject(new Error('Too many redirects while downloading binary.'));
@@ -175,17 +249,30 @@ export function downloadFile(url, destPath, redirects = 5) {
 
     const request = https.get(url, { headers: { 'User-Agent': 'agentworth-npm-resolver' } }, (res) => {
       if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
-        return downloadFile(res.headers.location, destPath, redirects - 1).then(resolve, reject);
+        return downloadFile(res.headers.location, destPath, redirects - 1, onProgress).then(resolve, reject);
       }
 
       if (res.statusCode !== 200) {
         return reject(new Error(`Failed to download binary: HTTP ${res.statusCode} from ${url}`));
       }
 
+      // The asset is ~23 MB and the release CDN is often slow, so silence here reads as a
+      // hang. Content-Length comes off the final 200, never the 302 hops above.
+      const total = Number(res.headers['content-length']) || 0;
+      let received = 0;
+      if (onProgress) {
+        onProgress(0, total);
+        res.on('data', (chunk) => {
+          received += chunk.length;
+          onProgress(received, total);
+        });
+      }
+
       const fileStream = fs.createWriteStream(destPath);
       res.pipe(fileStream);
 
       fileStream.on('finish', () => {
+        if (onProgress) onProgress(received, total || received);
         fileStream.close(resolve);
       });
 
@@ -221,6 +308,110 @@ function pathBinaryMatchesVersion(binPath, expected) {
   }
 }
 
+/**
+ * The version a binary reports, or null if it cannot be asked. Any failure — missing
+ * binary, wrong arch, timeout, unparseable output — is a null, never a guess.
+ *
+ * @param {string} binPath
+ * @returns {string|null}
+ */
+export function readBinaryVersion(binPath) {
+  try {
+    const out = execFileSync(binPath, ['--version'], {
+      encoding: 'utf8',
+      timeout: 5000,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const match = out.match(/\d+\.\d+\.\d+/);
+    return match ? match[0] : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/** `0.1.17` -> `[0, 1, 17]`, or null when the string is not version-shaped. */
+function versionTriplet(v) {
+  const match = String(v || '').match(/(\d+)\.(\d+)\.(\d+)/);
+  return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : null;
+}
+
+/**
+ * The one line printed when the binary about to run is older than the package that is
+ * running it. Null on anything else — an equal or newer binary is fine, and a version
+ * either side could not be parsed is not evidence of staleness.
+ *
+ * This cannot see the case that hurts most, a bare `npx agentworth` reusing a months-old
+ * *package* from npx's own cache: the package version is then stale too, and both agree.
+ * `archie update` says that part; this covers a stale binary under a current package.
+ *
+ * @param {string|null} resolved - the version the resolved binary reports
+ * @param {string} expected - this package's own version
+ * @returns {string|null}
+ */
+export function staleBinaryNotice(resolved, expected) {
+  const a = versionTriplet(resolved);
+  const b = versionTriplet(expected);
+  if (!a || !b) return null;
+  for (let i = 0; i < 3; i += 1) {
+    if (a[i] !== b[i]) {
+      return a[i] < b[i]
+        ? brandLine('-', 'stale', `binary v${resolved} is older than agentworth v${expected}`)
+        : null;
+    }
+  }
+  return null;
+}
+
+/**
+ * The two resolution sources that hand back whatever binary is there without asking its
+ * version. Sources 3-7 already refuse a mismatch, and the download cache (8) is versioned
+ * by its own path, so only these two can serve something older than this package.
+ */
+const UNVERSIONED_SOURCES = new Set(['env:AGENTWORTH_BIN', 'vendor']);
+
+/**
+ * Drives the download line: redraws in place on a TTY, prints one line to anything else.
+ *
+ * A pipe or a CI log cannot move the cursor, so it gets the size once and silence after --
+ * a loop that scrolls is a loop that lies. The redraw is throttled to 200ms and the lamp
+ * alternates on each frame, which is the dig loop's rhythm and the only thing that moves
+ * while the first byte is still in flight.
+ */
+function startDownloadProgress() {
+  const tty = Boolean(process.stderr.isTTY);
+  const cols = brandColumns();
+  let frame = 0;
+  let last = 0;
+  let announced = false;
+  let drawn = false;
+
+  const tick = (done, total) => {
+    if (!tty) {
+      if (announced) return;
+      announced = true;
+      console.error(
+        total > 0
+          ? brandLine('*', 'downloading', `${(total / 1048576).toFixed(1)} MB`)
+          : brandLine('*', 'downloading', 'the native binary'),
+      );
+      return;
+    }
+    const now = Date.now();
+    const complete = total > 0 && done >= total;
+    if (!complete && drawn && now - last < 200) return;
+    last = now;
+    const lamp = complete ? '*' : frame++ % 2 === 0 ? '*' : 'o';
+    process.stderr.write(`\r${downloadLine(done, total, { cols, unicode: true, lamp })}\x1b[K`);
+    drawn = true;
+  };
+
+  const done = () => {
+    if (tty && drawn) process.stderr.write('\n');
+  };
+
+  return { tick, done };
+}
+
 /**
  * Downloads and extracts the precompiled native binary from GitHub Releases into the user's local cache.
  *
@@ -256,13 +447,18 @@ export async function downloadAndExtractBinary(options = {}) {
   const archiveName = `agentworth-v${version}-${targetTriple}.tar.gz`;
   const url = `https://github.com/unfoundbox-crew/agentworth/releases/download/v${version}/${archiveName}`;
 
-  if (!options.silent) {
-    console.error(`\x1b[36m⚡ AgentWorth native binary not found locally. Downloading v${version} for ${platform}-${arch}...\x1b[0m`);
-  }
-
   const archivePath = path.join(cacheDir, archiveName);
+  const progress = options.silent ? null : startDownloadProgress();
+
+  if (progress) {
+    console.error(brandLine('*', 'resolving', `v${version}  ${targetTriple}`));
+  }
 
-  await downloadFile(url, archivePath);
+  try {
+    await downloadFile(url, archivePath, 5, progress ? progress.tick : null);
+  } finally {
+    if (progress) progress.done();
+  }
 
   // No --force-local here: it was a Windows-only GNU tar workaround, and Windows
   // support was dropped in 8b837c3. BSD tar (macOS's default) doesn't recognize
@@ -289,7 +485,7 @@ export async function downloadAndExtractBinary(options = {}) {
   }
 
   if (!options.silent) {
-    console.error(`\x1b[32m✔ Successfully installed AgentWorth native binary to ${cachedBinary}\x1b[0m\n`);
+    console.error(brandLine('*', 'installed', `${binName} in ${tilde(cacheDir)}`));
   }
 
   return cachedBinary;
@@ -515,25 +711,19 @@ export function resolveBinary(options = {}) {
  * @returns {string}
  */
 export function formatMissingBinaryMessage(platformKey = getPlatformKey()) {
+  // The error beat: the torch goes out, the failure line prints under it, nothing moves
+  // afterwards. Same voice as the CLI's own screens -- a label, then the command.
   return [
-    `\x1b[31m✖ Error: AgentWorth native binary not found for ${platformKey}.\x1b[0m`,
-    '',
-    'AgentWorth requires the native binary to run. You can install or build it via:',
-    '',
-    '  \x1b[36m• Standalone install script:\x1b[0m',
-    '      curl -fsSL https://agentworth.dev/install.sh | sh',
-    '',
-    '  \x1b[36m• Cargo:\x1b[0m',
-    '      cargo install agentworth-cli',
+    brandLine(' ', 'error', `no native binary for ${platformKey}`),
     '',
-    '  \x1b[36m• Zero-install via npx:\x1b[0m',
-    '      npx -y agentworth',
+    '  archie is a Rust binary with an npm launcher in front of it. Install the binary',
+    '  with whichever of these matches how you got here:',
     '',
-    '  \x1b[36m• Download the release for your platform:\x1b[0m',
-    `      https://github.com/unfoundbox-crew/agentworth/releases/latest`,
-    '',
-    '  \x1b[36m• Set custom binary path:\x1b[0m',
-    '      export AGENTWORTH_BIN=/path/to/agentworth',
+    '    install script   curl -fsSL https://agentworth.dev/install.sh | sh',
+    '    cargo            cargo install agentworth-cli',
+    '    npx              npx -y agentworth@latest',
+    '    release          https://github.com/unfoundbox-crew/agentworth/releases/latest',
+    '    a build you own  export AGENTWORTH_BIN=/path/to/archie',
     '',
   ].join('\n');
 }
@@ -603,14 +793,23 @@ export function run(argv = process.argv.slice(2), options = {}) {
   // recursion guard in findPathBinary checks AGENTWORTH_LAUNCHER_ACTIVE). The npm version
   // is threaded through too, purely so `agentworth version`/`agentworth update` can report
   // it -- this launcher never reads it back itself.
-  const childEnv = buildChildEnv(options.env || process.env, getPackageVersion(options.baseDir || __dirname));
+  const packageVersion = getPackageVersion(options.baseDir || __dirname);
+
+  // Say so rather than run something old in silence. Only the sources that were never
+  // version-checked are asked, so the usual path costs no extra process.
+  if (UNVERSIONED_SOURCES.has(binaryResult.source)) {
+    const notice = staleBinaryNotice(readBinaryVersion(binaryResult.path), packageVersion);
+    if (notice) console.error(notice);
+  }
+
+  const childEnv = buildChildEnv(options.env || process.env, packageVersion);
   const result = spawnSync(binaryResult.path, resolvedArgs, {
     stdio: 'inherit',
     env: childEnv,
   });
 
   if (result.error) {
-    console.error(`\x1b[31m✖ Failed to execute ${binaryResult.path}:\x1b[0m`, result.error.message);
+    console.error(brandLine(' ', 'error', `could not run ${binaryResult.path}: ${result.error.message}`));
     return 1;
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentworth",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Discover, normalize, and understand AI-agent histories locally.",
   "type": "module",
   "main": "./lib/resolver.js",