agentworth 0.1.17 → 0.1.19

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
 ```
 
 ---
@@ -92,9 +92,7 @@ You can also install the native AgentWorth binary directly:
 | Method | Command | Description |
 | :--- | :--- | :--- |
 | **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

@@ -308,6 +308,67 @@ 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.
  *
@@ -659,8 +720,7 @@ export function formatMissingBinaryMessage(platformKey = getPlatformKey()) {
     '  with whichever of these matches how you got here:',
     '',
     '    install script   curl -fsSL https://agentworth.dev/install.sh | sh',
-    '    cargo            cargo install agentworth-cli',
-    '    npx              npx -y agentworth',
+    '    npx              npx -y agentworth@latest',
     '    release          https://github.com/unfoundbox-crew/agentworth/releases/latest',
     '    a build you own  export AGENTWORTH_BIN=/path/to/archie',
     '',
@@ -732,7 +792,16 @@ 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,

package/package.json

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