@openagentsinc/pylon 0.1.2 → 0.1.4

package/README.md

@@ -10,7 +10,10 @@ available.
 
 ```bash
 npx @openagentsinc/pylon
-npx @openagentsinc/pylon --version 0.0.1-rc4
+bunx @openagentsinc/pylon
+npm install -g @openagentsinc/pylon && pylon
+bun install -g @openagentsinc/pylon && pylon
+npx @openagentsinc/pylon --version 0.0.1-rc10
 npx @openagentsinc/pylon --no-launch
 npx @openagentsinc/pylon --download-curated-cache --model gemma-4-e2b --diagnostic-repeats 2
 npx @openagentsinc/pylon --verbose
@@ -18,19 +21,29 @@ npx @openagentsinc/pylon --verbose
 
 The launcher:
 
-- resolves the latest tagged `pylon-v...` release by default, or a specific
-  tagged `Pylon` version when `--version` is provided
+- supports direct `npx` / `bunx` execution plus global `npm install -g` /
+  `bun install -g` installs with the same `pylon` command
+- checks GitHub for the latest tagged `pylon-v...` release on each default run,
+  or resolves a specific tagged `Pylon` version when `--version` is provided
 - resolves the correct `pylon-v<version>-<os>-<arch>.tar.gz` asset for the
   current machine
 - falls back to the exact tagged source checkout and builds `pylon` plus
   `pylon-tui` locally when no matching release asset exists for the machine
 - prompts before installing the Rust toolchain via `rustup` if a source build
   is needed and `cargo` / `rustc` are missing
+- emits best-effort anonymous installer telemetry to `openagents.com` so the
+  public stats page can show install starts, completions, source-build fallbacks,
+  Rust prompts, and smoke-test outcomes
 - downloads the archive and published SHA-256 checksum
 - verifies the checksum before extracting
 - caches the unpacked binaries under `~/.openagents/pylon/bootstrap/`
+- never links or copies those cached standalone binaries into a shared global
+  bin directory, so the package-managed `pylon` launcher remains the command on
+  `PATH`
 - prints status lines such as release resolution, runtime checks, and local
   model scanning while it runs
+- ends first run with an explicit verdict such as `fully online`, `runtime
+  ready`, or `installed but runtime missing`, plus exact next-step guidance
 - runs `pylon --help`, `init`, `status --json`, and `inventory --json`
 - runs `pylon gemma diagnose <model> --json`
 - only runs `pylon gemma download <model>` when `--download-curated-cache` is
@@ -39,6 +52,13 @@ The launcher:
 - falls back to `curl` for release metadata and asset downloads when the Node
   fetch path fails in constrained network contexts
 - opens `pylon-tui` by default after the smoke path unless `--no-launch` is set
+- does not try to install or register a local runtime automatically; the
+  bootstrap stays honest about the separate Ollama-compatible runtime
+  prerequisite instead of mutating the host behind the user's back
+
+Set `OPENAGENTS_DISABLE_TELEMETRY=1` to disable installer telemetry, or
+`OPENAGENTS_TELEMETRY_URL=http://127.0.0.1:8000/api/telemetry/events` to point
+the launcher at a non-production telemetry endpoint.
 
 ## Publish
 
@@ -46,5 +66,6 @@ Publish directly from this package directory:
 
 ```bash
 cd packages/pylon-bootstrap
+npm pack --dry-run
 npm publish
 ```

package/bin/pylon

@@ -0,0 +1,26 @@
+#!/bin/sh
+
+set -eu
+
+SCRIPT_PATH="$0"
+while [ -L "$SCRIPT_PATH" ]; do
+  LINK_TARGET=$(readlink "$SCRIPT_PATH")
+  case "$LINK_TARGET" in
+    /*) SCRIPT_PATH="$LINK_TARGET" ;;
+    *) SCRIPT_PATH="$(dirname -- "$SCRIPT_PATH")/$LINK_TARGET" ;;
+  esac
+done
+
+SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$SCRIPT_PATH")" && pwd)
+LAUNCHER_JS="${SCRIPT_DIR}/pylon.js"
+
+if command -v node >/dev/null 2>&1; then
+  exec node "$LAUNCHER_JS" "$@"
+fi
+
+if command -v bun >/dev/null 2>&1; then
+  exec bun "$LAUNCHER_JS" "$@"
+fi
+
+echo "pylon launcher requires Node.js or Bun on PATH." >&2
+exit 1

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@openagentsinc/pylon",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Bootstrap the standalone OpenAgents Pylon release asset and run first-run smoke checks.",
   "type": "module",
   "bin": {
-    "pylon": "./bin/pylon.js"
+    "pylon": "./bin/pylon"
   },
   "files": [
     "bin",

package/src/cli.js

@@ -7,8 +7,16 @@ import {
   bootstrapInstalledPylon,
   ensureReleaseInstall,
   launchInstalledPylonTui,
+  resolveBootstrapOutcome,
+  resolvePlatformTarget,
   renderBootstrapSummary,
 } from "./index.js";
+import {
+  createTelemetryClient,
+  detectPackageInvoker,
+  installSourceForTelemetry,
+  telemetryFailureContext,
+} from "./telemetry.js";
 
 function parseIntegerFlag(value, label) {
   const parsed = Number.parseInt(value, 10);
@@ -67,6 +75,8 @@ function createReporter({ enableColor = process.stdout.isTTY && !process.env.NO_
 export function usage() {
   return `Usage:
   npx @openagentsinc/pylon [options]
+  bunx @openagentsinc/pylon [options]
+  pylon [options]
 
 Description:
   Download the latest tagged standalone Pylon release asset for this machine,
@@ -74,7 +84,9 @@ Description:
   asset exists for the local platform, fetch the exact tagged source checkout
   and build it locally instead. Cache the binaries, run the first-run smoke
   path, and then open the Pylon terminal UI by default with live status
-  updates.
+  updates. The launcher checks GitHub for newer tagged pylon-v... releases on
+  each default run, but only caches the standalone binaries under the local
+  bootstrap root; it does not replace your global npm or bun pylon command.
 
 Options:
   --version <x.y.z>                    Resolve a specific Pylon release.
@@ -216,6 +228,7 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
     ensureReleaseInstallImpl = ensureReleaseInstall,
     bootstrapInstalledPylonImpl = bootstrapInstalledPylon,
     launchInstalledPylonTuiImpl = launchInstalledPylonTui,
+    createTelemetryClientImpl = createTelemetryClient,
   } = dependencies;
   const options = parseArgs(argv);
   if (options.help) {
@@ -224,46 +237,109 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
   }
 
   const reporter = options.json ? null : createReporter();
+  const startedAt = Date.now();
+  const target = (() => {
+    try {
+      return resolvePlatformTarget(options.platform, options.arch);
+    } catch {
+      return {
+        os: process.platform,
+        arch: process.arch,
+      };
+    }
+  })();
+  const telemetryClient =
+    dependencies.telemetryClient ??
+    createTelemetryClientImpl({
+      fetchImpl: dependencies.fetchImpl ?? globalThis.fetch,
+    });
+  const sharedTelemetry = {
+    requested_version: options.version ?? "latest",
+    os: target.os,
+    arch: target.arch,
+    platform_key: `${target.os}-${target.arch}`,
+    npm_or_bun_invoker: detectPackageInvoker(),
+  };
 
-  const install = await ensureReleaseInstallImpl(options, {
-    ...dependencies,
-    onStatus: reporter?.status,
-  });
-  const summary = await bootstrapInstalledPylonImpl(
-    {
-      ...options,
-      ...install,
-      version: install.version,
-    },
-    {
+  telemetryClient?.emit?.("installer_started", sharedTelemetry);
+
+  let install = null;
+
+  try {
+    install = await ensureReleaseInstallImpl(options, {
       ...dependencies,
       onStatus: reporter?.status,
-    },
-  );
+      telemetryClient,
+    });
+    const summary = await bootstrapInstalledPylonImpl(
+      {
+        ...options,
+        ...install,
+        version: install.version,
+      },
+      {
+        ...dependencies,
+        onStatus: reporter?.status,
+        telemetryClient,
+      },
+    );
+
+    telemetryClient?.emit?.("installer_finished", {
+      ...sharedTelemetry,
+      release_tag: summary.tagName,
+      release_commit: install.sourceCommit ?? null,
+      duration_ms: Date.now() - startedAt,
+      result: "success",
+      install_source: installSourceForTelemetry(
+        summary.installMethod ?? install.installMethod,
+        Boolean(summary.cached),
+      ),
+    });
+    await telemetryClient?.flush?.();
 
-  if (options.json) {
-    console.log(JSON.stringify(summary, null, 2));
-  } else {
-    reporter?.success("Pylon bootstrap complete");
-    console.log(renderBootstrapSummary(summary));
-    if (!options.noLaunch) {
-      await launchInstalledPylonTuiImpl(
-        {
-          ...options,
-          ...install,
-          version: install.version,
-        },
-        {
-          ...dependencies,
-          onStatus: reporter?.status,
-        },
-      );
+    if (options.json) {
+      console.log(JSON.stringify(summary, null, 2));
     } else {
-      reporter?.warning(
-        "Skipped Pylon terminal UI launch",
-        "pass no flag to open pylon-tui by default",
-      );
+      const outcome = resolveBootstrapOutcome(summary);
+      if (outcome.level === "success") {
+        reporter?.success(`Pylon ${outcome.verdict}`, outcome.detail);
+      } else {
+        reporter?.warning(`Pylon ${outcome.verdict}`, outcome.detail);
+      }
+      console.log(renderBootstrapSummary(summary));
+      if (!options.noLaunch) {
+        await launchInstalledPylonTuiImpl(
+          {
+            ...options,
+            ...install,
+            version: install.version,
+          },
+          {
+            ...dependencies,
+            onStatus: reporter?.status,
+          },
+        );
+      } else {
+        reporter?.warning(
+          "Skipped Pylon terminal UI launch",
+          "pass no flag to open pylon-tui by default",
+        );
+      }
     }
+    return summary;
+  } catch (error) {
+    telemetryClient?.emit?.("installer_finished", {
+      ...sharedTelemetry,
+      release_tag: install?.tagName ?? null,
+      release_commit: install?.sourceCommit ?? null,
+      duration_ms: Date.now() - startedAt,
+      result: "failed",
+      install_source: install
+        ? installSourceForTelemetry(install.installMethod, Boolean(install.cached))
+        : null,
+      ...telemetryFailureContext(error, "launcher"),
+    });
+    await telemetryClient?.flush?.();
+    throw error;
   }
-  return summary;
 }

package/src/index.js

@@ -5,6 +5,12 @@ import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import readline from "node:readline/promises";
+import {
+  installSourceForTelemetry,
+  telemetryFailureContext,
+} from "./telemetry.js";
+
+export { createTelemetryClient } from "./telemetry.js";
 
 export const DEFAULT_RELEASE_REPO = "OpenAgentsInc/openagents";
 export const DEFAULT_RELEASE_API_BASE = "https://api.github.com";
@@ -17,6 +23,7 @@ export const DEFAULT_FETCH_TIMEOUT_MS = 15_000;
 const PYLON_RELEASE_TAG_PREFIX = "pylon-v";
 const RELEASE_ASSET_INSTALL_METHOD = "release_asset";
 const SOURCE_BUILD_INSTALL_METHOD = "source_build";
+const PREFERRED_RUNTIME_MODEL_NAME = "gemma4:e4b";
 
 function emitStatus(onStatus, message, detail = null) {
   if (typeof onStatus === "function") {
@@ -30,10 +37,82 @@ function emitVerboseStatus(onStatus, verbose, message, detail = null) {
   }
 }
 
+function emitTelemetry(telemetryClient, eventName, properties = {}) {
+  if (typeof telemetryClient?.emit === "function") {
+    void telemetryClient.emit(eventName, properties);
+  }
+}
+
 function normalizeVersion(value) {
   return value.replace(/^pylon-v/, "").replace(/^v/, "");
 }
 
+function parseComparableVersion(value) {
+  const normalized = normalizeVersion(value).trim();
+  const match = normalized.match(
+    /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+?)(\d+)?)?$/,
+  );
+  if (!match) {
+    return null;
+  }
+
+  return {
+    normalized,
+    major: Number.parseInt(match[1], 10),
+    minor: Number.parseInt(match[2], 10),
+    patch: Number.parseInt(match[3], 10),
+    prereleaseLabel: match[4] ?? null,
+    prereleaseNumber:
+      match[5] != null ? Number.parseInt(match[5], 10) : null,
+  };
+}
+
+function comparePylonReleaseTags(leftTagName, rightTagName) {
+  const left = parseComparableVersion(leftTagName);
+  const right = parseComparableVersion(rightTagName);
+
+  if (!left && !right) {
+    return String(leftTagName).localeCompare(String(rightTagName));
+  }
+  if (!left) {
+    return -1;
+  }
+  if (!right) {
+    return 1;
+  }
+
+  for (const key of ["major", "minor", "patch"]) {
+    if (left[key] !== right[key]) {
+      return left[key] > right[key] ? 1 : -1;
+    }
+  }
+
+  if (left.prereleaseLabel == null && right.prereleaseLabel == null) {
+    return 0;
+  }
+  if (left.prereleaseLabel == null) {
+    return 1;
+  }
+  if (right.prereleaseLabel == null) {
+    return -1;
+  }
+
+  const labelComparison = left.prereleaseLabel.localeCompare(
+    right.prereleaseLabel,
+  );
+  if (labelComparison !== 0) {
+    return labelComparison;
+  }
+
+  const leftNumber = left.prereleaseNumber ?? 0;
+  const rightNumber = right.prereleaseNumber ?? 0;
+  if (leftNumber !== rightNumber) {
+    return leftNumber > rightNumber ? 1 : -1;
+  }
+
+  return left.normalized.localeCompare(right.normalized);
+}
+
 function createBootstrapError(message, context = {}) {
   const error = new Error(message);
   Object.assign(error, context);
@@ -496,14 +575,31 @@ export function isPylonReleaseTag(tagName) {
   );
 }
 
-export function selectLatestPylonRelease(releases) {
+function releaseHasTargetAssets(release, target) {
+  if (!target || !release?.tag_name) {
+    return false;
+  }
+
+  const { archiveName, checksumName } = buildAssetNames(release.tag_name, target);
+  const assetNames = new Set(
+    (Array.isArray(release.assets) ? release.assets : [])
+      .map((asset) => asset?.name)
+      .filter(Boolean),
+  );
+  return assetNames.has(archiveName) && assetNames.has(checksumName);
+}
+
+export function selectLatestPylonRelease(releases, target = null) {
   if (!Array.isArray(releases)) {
     throw new Error("GitHub release lookup did not return a release list.");
   }
 
-  const release = releases.find(
-    (candidate) => !candidate?.draft && isPylonReleaseTag(candidate?.tag_name),
-  );
+  const candidates = releases
+    .filter((candidate) => !candidate?.draft && isPylonReleaseTag(candidate?.tag_name))
+    .sort((left, right) => comparePylonReleaseTags(right.tag_name, left.tag_name));
+  const release =
+    candidates.find((candidate) => releaseHasTargetAssets(candidate, target)) ??
+    candidates[0];
   if (!release) {
     throw new Error(
       `GitHub release lookup did not find any published ${PYLON_RELEASE_TAG_PREFIX} releases.`,
@@ -521,6 +617,7 @@ export async function fetchReleaseMetadata({
   apiBase = DEFAULT_RELEASE_API_BASE,
   repo = DEFAULT_RELEASE_REPO,
   version = null,
+  target = null,
 } = {}) {
   const normalizedVersion = normalizeRequestedVersion(version);
   const endpoint = normalizedVersion
@@ -537,7 +634,7 @@ export async function fetchReleaseMetadata({
       ? "GitHub tagged release lookup"
       : "GitHub release list lookup",
   });
-  return normalizedVersion ? payload : selectLatestPylonRelease(payload);
+  return normalizedVersion ? payload : selectLatestPylonRelease(payload, target);
 }
 
 export function selectReleaseAssets(release, target) {
@@ -712,6 +809,7 @@ async function ensureRustToolchain({
   fetchImpl,
   runProcessImpl,
   onStatus,
+  telemetryClient,
   promptImpl = promptForApproval,
   commandExistsImpl = commandExists,
   env = process.env,
@@ -724,44 +822,70 @@ async function ensureRustToolchain({
     return toolchainEnv;
   }
 
+  emitTelemetry(telemetryClient, "installer_rust_missing", {
+    os: target.os,
+    arch: target.arch,
+  });
+
   emitStatus(
     onStatus,
     "Rust toolchain required for source build",
     `${target.os}-${target.arch}`,
   );
 
+  emitTelemetry(telemetryClient, "installer_rust_install_prompt_shown", {
+    os: target.os,
+    arch: target.arch,
+  });
   const approved = await promptImpl(
     `Rust is required to build Pylon from source for ${target.os}-${target.arch}. Install the official Rust toolchain now via rustup?`,
   );
   if (!approved) {
+    emitTelemetry(telemetryClient, "installer_rust_install_declined", {
+      os: target.os,
+      arch: target.arch,
+    });
     throw new Error(
       `Rust is required to build Pylon from source.\nInstall it manually and rerun:\n${rustInstallCommand()}`,
     );
   }
 
-  emitStatus(onStatus, "Installing Rust toolchain", "official rustup installer");
-  const scriptPayload = await fetchText(fetchImpl, rustupInitUrl, {
-    headers: {
-      accept: "text/plain",
-      "user-agent": "@openagentsinc/pylon bootstrap",
-    },
-    runProcessImpl,
-    onStatus,
-    stage: "Rust toolchain installer download",
+  emitTelemetry(telemetryClient, "installer_rust_install_approved", {
+    os: target.os,
+    arch: target.arch,
   });
-  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "pylon-rustup-"));
-  const scriptPath = path.join(tempDir, "rustup-init.sh");
 
+  emitStatus(onStatus, "Installing Rust toolchain", "official rustup installer");
   try {
+    const scriptPayload = await fetchText(fetchImpl, rustupInitUrl, {
+      headers: {
+        accept: "text/plain",
+        "user-agent": "@openagentsinc/pylon bootstrap",
+      },
+      runProcessImpl,
+      onStatus,
+      stage: "Rust toolchain installer download",
+    });
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "pylon-rustup-"));
+    const scriptPath = path.join(tempDir, "rustup-init.sh");
     await fs.writeFile(scriptPath, scriptPayload);
     await fs.chmod(scriptPath, 0o755);
-    await runProcessImpl("sh", [scriptPath, "-y"], {
-      cwd: tempDir,
-      env: toolchainEnv,
-      stdio: "inherit",
+    try {
+      await runProcessImpl("sh", [scriptPath, "-y"], {
+        cwd: tempDir,
+        env: toolchainEnv,
+        stdio: "inherit",
+      });
+    } finally {
+      await fs.rm(tempDir, { recursive: true, force: true });
+    }
+  } catch (error) {
+    emitTelemetry(telemetryClient, "installer_rust_install_failed", {
+      os: target.os,
+      arch: target.arch,
+      ...telemetryFailureContext(error, "rust_install"),
     });
-  } finally {
-    await fs.rm(tempDir, { recursive: true, force: true });
+    throw error;
   }
 
   toolchainEnv = withPrependedPath(env, path.join(os.homedir(), ".cargo", "bin"));
@@ -778,6 +902,10 @@ async function ensureRustToolchain({
     "Rust toolchain installed",
     path.join(os.homedir(), ".cargo", "bin"),
   );
+  emitTelemetry(telemetryClient, "installer_rust_install_completed", {
+    os: target.os,
+    arch: target.arch,
+  });
   return toolchainEnv;
 }
 
@@ -792,6 +920,7 @@ async function installSourceBuild(
     fetchImpl,
     runProcessImpl,
     onStatus,
+    telemetryClient,
     promptImpl = promptForApproval,
     commandExistsImpl = commandExists,
   },
@@ -811,6 +940,13 @@ async function installSourceBuild(
     "Prebuilt asset missing; falling back to source build",
     `${selected.tagName} for ${target.os}-${target.arch}`,
   );
+  emitTelemetry(telemetryClient, "installer_prebuilt_asset_missing", {
+    release_tag: selected.tagName,
+    release_commit: selected.targetCommitish ?? null,
+    os: target.os,
+    arch: target.arch,
+    platform_key: `${target.os}-${target.arch}`,
+  });
 
   if (!(await commandExistsImpl("git", process.env))) {
     throw new Error(
@@ -823,6 +959,7 @@ async function installSourceBuild(
     fetchImpl,
     runProcessImpl,
     onStatus,
+    telemetryClient,
     promptImpl,
     commandExistsImpl,
   });
@@ -896,6 +1033,13 @@ async function installSourceBuild(
       "Building Pylon from source",
       `${selected.tagName} (${sourceCommit.slice(0, 12)})`,
     );
+    emitTelemetry(telemetryClient, "installer_source_build_started", {
+      release_tag: selected.tagName,
+      release_commit: sourceCommit,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
+    });
     await runProcessImpl(buildCommand[0], buildCommand.slice(1), {
       cwd: repoDir,
       env: buildEnv,
@@ -937,6 +1081,17 @@ async function installSourceBuild(
       "Installed source-built binaries",
       `${selected.tagName} for ${target.os}-${target.arch}`,
     );
+    emitTelemetry(telemetryClient, "installer_source_build_completed", {
+      release_tag: selected.tagName,
+      release_commit: sourceCommit,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
+      install_source: installSourceForTelemetry(
+        SOURCE_BUILD_INSTALL_METHOD,
+        false,
+      ),
+    });
 
     return {
       ...selected,
@@ -949,6 +1104,14 @@ async function installSourceBuild(
       sourceCommit,
     };
   } catch (error) {
+    emitTelemetry(telemetryClient, "installer_source_build_failed", {
+      release_tag: selected.tagName,
+      release_commit: selected.targetCommitish ?? null,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
+      ...telemetryFailureContext(error, "source_build"),
+    });
     const message = error instanceof Error ? error.message : String(error);
     throw new Error(
       `${message}\nManual source-build fallback:\n${manualBuildInstructions}`,
@@ -1012,6 +1175,9 @@ async function findLatestCachedInstall(installRoot, target) {
         pylonTuiPath,
         expectedSha256: manifest.sha256 ?? null,
         cached: true,
+        installMethod: manifest.installMethod ?? RELEASE_ASSET_INSTALL_METHOD,
+        sourceCloneUrl: manifest.sourceCloneUrl ?? null,
+        sourceCommit: manifest.sourceCommit ?? null,
         mtimeMs: manifestStat.mtimeMs,
       });
     } catch {
@@ -1123,6 +1289,7 @@ export async function ensureReleaseInstall(
     fetchImpl = globalThis.fetch,
     runProcessImpl = runProcess,
     onStatus = null,
+    telemetryClient = null,
     promptImpl = promptForApproval,
     commandExistsImpl = commandExists,
   } = {},
@@ -1133,32 +1300,45 @@ export async function ensureReleaseInstall(
 
   emitStatus(
     onStatus,
-    "Resolving latest tagged Pylon release",
+    "Checking for newer tagged Pylon releases",
     options.version ? `requested ${options.version}` : "default release track",
   );
   const target = resolvePlatformTarget(options.platform, options.arch);
   const installRoot = options.installRoot ?? defaultInstallRoot();
   if (options.version) {
     const requestedPaths = buildInstallPaths(installRoot, options.version, target);
+    const requestedManifest = await readInstallManifest(requestedPaths.manifestPath);
     const requestedCached =
       (await pathExists(requestedPaths.pylonPath)) &&
       (await pathExists(requestedPaths.pylonTuiPath));
     if (requestedCached) {
+      const installMethod =
+        requestedManifest?.installMethod ?? RELEASE_ASSET_INSTALL_METHOD;
       emitStatus(
         onStatus,
-        "Using cached standalone binaries",
+        installMethod === SOURCE_BUILD_INSTALL_METHOD
+          ? "Using cached source-built binaries"
+          : "Using cached standalone binaries",
         `pylon-v${normalizeVersion(options.version)} for ${target.os}-${target.arch}`,
       );
+      emitTelemetry(telemetryClient, "installer_cached_install_reused", {
+        release_tag: `pylon-v${normalizeVersion(options.version)}`,
+        release_commit: requestedManifest?.sourceCommit ?? null,
+        os: target.os,
+        arch: target.arch,
+        platform_key: `${target.os}-${target.arch}`,
+        install_source: installSourceForTelemetry(installMethod, true),
+      });
       return {
         version: normalizeVersion(options.version),
         tagName: `pylon-v${normalizeVersion(options.version)}`,
         target,
         ...requestedPaths,
-        expectedSha256: await fs
-          .readFile(requestedPaths.manifestPath, "utf8")
-          .then((payload) => JSON.parse(payload).sha256)
-          .catch(() => null),
+        expectedSha256: requestedManifest?.sha256 ?? null,
         cached: true,
+        installMethod,
+        sourceCloneUrl: requestedManifest?.sourceCloneUrl ?? null,
+        sourceCommit: requestedManifest?.sourceCommit ?? null,
       };
     }
   }
@@ -1173,6 +1353,14 @@ export async function ensureReleaseInstall(
       apiBase: options.apiBase ?? DEFAULT_RELEASE_API_BASE,
       repo: options.repo ?? DEFAULT_RELEASE_REPO,
       version: options.version ?? null,
+      target,
+    });
+    emitTelemetry(telemetryClient, "installer_release_resolved", {
+      release_tag: release?.tag_name ?? null,
+      release_commit: release?.target_commitish ?? null,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
     });
   } catch (error) {
     const cached = !options.version
@@ -1181,9 +1369,19 @@ export async function ensureReleaseInstall(
     if (cached) {
       emitStatus(
         onStatus,
-        "Using cached standalone binaries",
+        cached.installMethod === SOURCE_BUILD_INSTALL_METHOD
+          ? "Using cached source-built binaries"
+          : "Using cached standalone binaries",
         `release lookup failed; falling back to ${cached.tagName}`,
       );
+      emitTelemetry(telemetryClient, "installer_cached_install_reused", {
+        release_tag: cached.tagName,
+        release_commit: cached.sourceCommit ?? null,
+        os: target.os,
+        arch: target.arch,
+        platform_key: `${target.os}-${target.arch}`,
+        install_source: installSourceForTelemetry(cached.installMethod, true),
+      });
       return cached;
     }
 
@@ -1204,6 +1402,14 @@ export async function ensureReleaseInstall(
   let missingAssetsError = null;
   try {
     selected = selectReleaseAssets(release, target);
+    emitTelemetry(telemetryClient, "installer_prebuilt_asset_found", {
+      release_tag: selected.tagName,
+      release_commit: release?.target_commitish ?? null,
+      asset_name: selected.archiveAsset.name,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
+    });
   } catch (error) {
     if (!(error instanceof MissingReleaseAssetsError)) {
       throw error;
@@ -1234,6 +1440,14 @@ export async function ensureReleaseInstall(
         : "Using cached standalone binaries",
       `${selected.tagName} for ${target.os}-${target.arch}`,
     );
+    emitTelemetry(telemetryClient, "installer_cached_install_reused", {
+      release_tag: selected.tagName,
+      release_commit: manifest?.sourceCommit ?? release?.target_commitish ?? null,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
+      install_source: installSourceForTelemetry(installMethod, true),
+    });
     return {
       ...selected,
       ...paths,
@@ -1258,6 +1472,7 @@ export async function ensureReleaseInstall(
         fetchImpl,
         runProcessImpl,
         onStatus,
+        telemetryClient,
         promptImpl,
         commandExistsImpl,
       },
@@ -1292,20 +1507,62 @@ export async function ensureReleaseInstall(
       "Downloading standalone binaries",
       selected.archiveAsset.name,
     );
-    await downloadFile(fetchImpl, selected.archiveAsset.url, paths.archivePath, {
-      runProcessImpl,
-      onStatus,
-      verbose: Boolean(options.verbose),
-      stage: "Release archive download",
+    emitTelemetry(telemetryClient, "installer_prebuilt_download_started", {
+      release_tag: selected.tagName,
+      asset_name: selected.archiveAsset.name,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
     });
+    try {
+      await downloadFile(fetchImpl, selected.archiveAsset.url, paths.archivePath, {
+        runProcessImpl,
+        onStatus,
+        verbose: Boolean(options.verbose),
+        stage: "Release archive download",
+      });
+      emitTelemetry(telemetryClient, "installer_prebuilt_download_completed", {
+        release_tag: selected.tagName,
+        asset_name: selected.archiveAsset.name,
+        os: target.os,
+        arch: target.arch,
+        platform_key: `${target.os}-${target.arch}`,
+      });
+    } catch (error) {
+      emitTelemetry(telemetryClient, "installer_prebuilt_download_failed", {
+        release_tag: selected.tagName,
+        asset_name: selected.archiveAsset.name,
+        os: target.os,
+        arch: target.arch,
+        platform_key: `${target.os}-${target.arch}`,
+        ...telemetryFailureContext(error, "prebuilt_download"),
+      });
+      throw error;
+    }
   }
 
   const actualSha256 = await sha256File(paths.archivePath);
   if (actualSha256 !== expectedSha256) {
+    emitTelemetry(telemetryClient, "installer_checksum_failed", {
+      release_tag: selected.tagName,
+      asset_name: selected.archiveAsset.name,
+      os: target.os,
+      arch: target.arch,
+      platform_key: `${target.os}-${target.arch}`,
+      error_stage: "checksum_verify",
+      error_code: "sha256_mismatch",
+    });
     throw new Error(
       `SHA-256 verification failed for ${selected.archiveAsset.name}: expected ${expectedSha256}, got ${actualSha256}.`,
     );
   }
+  emitTelemetry(telemetryClient, "installer_checksum_verified", {
+    release_tag: selected.tagName,
+    asset_name: selected.archiveAsset.name,
+    os: target.os,
+    arch: target.arch,
+    platform_key: `${target.os}-${target.arch}`,
+  });
 
   emitStatus(
     onStatus,
@@ -1347,6 +1604,9 @@ export async function ensureReleaseInstall(
     target,
     expectedSha256,
     cached: false,
+    installMethod: RELEASE_ASSET_INSTALL_METHOD,
+    sourceCloneUrl: null,
+    sourceCommit: null,
   };
 }
 
@@ -1355,6 +1615,7 @@ export async function bootstrapInstalledPylon(
   {
     runProcessImpl = runProcess,
     onStatus = null,
+    telemetryClient = null,
   } = {},
 ) {
   const pylonPath = path.resolve(options.pylonPath);
@@ -1364,108 +1625,157 @@ export async function bootstrapInstalledPylon(
     options.diagnosticRepeats ?? DEFAULT_DIAGNOSTIC_REPEATS;
   const diagnosticMaxOutputTokens =
     options.diagnosticMaxOutputTokens ?? DEFAULT_DIAGNOSTIC_MAX_OUTPUT_TOKENS;
+  emitTelemetry(telemetryClient, "installer_smoke_test_started", {
+    release_tag: options.tagName ?? `pylon-v${options.version}`,
+    release_commit: options.sourceCommit ?? null,
+    os: options.target?.os ?? null,
+    arch: options.target?.arch ?? null,
+    platform_key:
+      options.target?.os && options.target?.arch
+        ? `${options.target.os}-${options.target.arch}`
+        : null,
+    install_source: installSourceForTelemetry(
+      options.installMethod,
+      Boolean(options.cached),
+    ),
+  });
 
-  emitStatus(onStatus, "Verifying Pylon binary", path.basename(pylonPath));
-  await runPylonCommand(pylonPath, ["--help"], options, runProcessImpl);
-  emitStatus(onStatus, "Bootstrapping local Pylon identity");
-  const init = await runPylonJson(pylonPath, ["init"], options, runProcessImpl);
-  emitStatus(onStatus, "Checking runtime health");
-  const status = await runPylonJson(
-    pylonPath,
-    ["status", "--json"],
-    options,
-    runProcessImpl,
-  );
-  emitStatus(onStatus, "Scanning for local models");
-  const inventory = await runPylonJson(
-    pylonPath,
-    ["inventory", "--json"],
-    options,
-    runProcessImpl,
-  );
-
-  let download = null;
-  if (!options.skipModelDownload) {
-    emitStatus(onStatus, "Downloading curated model bundle", model);
-    download = await runPylonJson(
+  try {
+    emitStatus(onStatus, "Verifying Pylon binary", path.basename(pylonPath));
+    await runPylonCommand(pylonPath, ["--help"], options, runProcessImpl);
+    emitStatus(onStatus, "Bootstrapping local Pylon identity");
+    const init = await runPylonJson(pylonPath, ["init"], options, runProcessImpl);
+    emitStatus(onStatus, "Checking runtime health");
+    const status = await runPylonJson(
       pylonPath,
-      ["gemma", "download", model, "--json"],
+      ["status", "--json"],
       options,
       runProcessImpl,
     );
-  } else {
-    emitStatus(
-      onStatus,
-      "Skipping optional curated GGUF cache",
-      "use --download-curated-cache to prefetch Hugging Face weights",
+    emitStatus(onStatus, "Scanning for local models");
+    const inventory = await runPylonJson(
+      pylonPath,
+      ["inventory", "--json"],
+      options,
+      runProcessImpl,
     );
-  }
 
-  let diagnostic = null;
-  if (!options.skipDiagnostics) {
-    emitStatus(onStatus, "Running first-run diagnostic", model);
-    try {
-      diagnostic = await runPylonJson(
+    let download = null;
+    if (!options.skipModelDownload) {
+      emitStatus(onStatus, "Downloading curated model bundle", model);
+      download = await runPylonJson(
         pylonPath,
-        [
-          "gemma",
-          "diagnose",
-          model,
-          "--max-output-tokens",
-          String(diagnosticMaxOutputTokens),
-          "--repeats",
-          String(diagnosticRepeats),
-          "--json",
-        ],
+        ["gemma", "download", model, "--json"],
         options,
         runProcessImpl,
       );
-    } catch (error) {
-      if (!isUnsupportedGemmaDiagnoseError(error)) {
-        throw error;
-      }
+    } else {
       emitStatus(
         onStatus,
-        "Skipping first-run diagnostic",
-        "installed Pylon release does not expose gemma diagnose",
+        "Skipping optional curated GGUF cache",
+        "use --download-curated-cache to prefetch Hugging Face weights",
       );
     }
-  } else {
-    emitStatus(onStatus, "Skipping first-run diagnostic", model);
-  }
 
-  const diagnosticResult =
-    diagnostic?.results?.find((result) => result.model_id === model) ??
-    diagnostic?.results?.[0] ??
-    null;
+    let diagnostic = null;
+    if (!options.skipDiagnostics) {
+      emitStatus(onStatus, "Running first-run diagnostic", model);
+      try {
+        diagnostic = await runPylonJson(
+          pylonPath,
+          [
+            "gemma",
+            "diagnose",
+            model,
+            "--max-output-tokens",
+            String(diagnosticMaxOutputTokens),
+            "--repeats",
+            String(diagnosticRepeats),
+            "--json",
+          ],
+          options,
+          runProcessImpl,
+        );
+      } catch (error) {
+        if (!isUnsupportedGemmaDiagnoseError(error)) {
+          throw error;
+        }
+        emitStatus(
+          onStatus,
+          "Skipping first-run diagnostic",
+          "installed Pylon release does not expose gemma diagnose",
+        );
+      }
+    } else {
+      emitStatus(onStatus, "Skipping first-run diagnostic", model);
+    }
 
-  emitStatus(
-    onStatus,
-    "Bootstrap complete",
-    diagnosticResult?.status
-      ? `diagnostic ${diagnosticResult.status}`
-      : "smoke path complete",
-  );
+    const diagnosticResult =
+      diagnostic?.results?.find((result) => result.model_id === model) ??
+      diagnostic?.results?.[0] ??
+      null;
 
-  return {
-    version: options.version,
-    tagName: options.tagName ?? `pylon-v${options.version}`,
-    target: options.target,
-    cached: Boolean(options.cached),
-    binaries: {
-      pylon: pylonPath,
-      pylonTui: pylonTuiPath,
-    },
-    configPath: init?.config_path ?? options.configPath ?? null,
-    pylonHome: options.pylonHome ? path.resolve(options.pylonHome) : null,
-    init,
-    status,
-    inventory,
-    model,
-    download,
-    diagnostic,
-    diagnosticResult,
-  };
+    emitStatus(
+      onStatus,
+      "Bootstrap complete",
+      diagnosticResult?.status
+        ? `diagnostic ${diagnosticResult.status}`
+        : "smoke path complete",
+    );
+    emitTelemetry(telemetryClient, "installer_smoke_test_completed", {
+      release_tag: options.tagName ?? `pylon-v${options.version}`,
+      release_commit: options.sourceCommit ?? null,
+      os: options.target?.os ?? null,
+      arch: options.target?.arch ?? null,
+      platform_key:
+        options.target?.os && options.target?.arch
+          ? `${options.target.os}-${options.target.arch}`
+          : null,
+      install_source: installSourceForTelemetry(
+        options.installMethod,
+        Boolean(options.cached),
+      ),
+      diagnostic_status: diagnosticResult?.status ?? null,
+    });
+
+    return {
+      version: options.version,
+      tagName: options.tagName ?? `pylon-v${options.version}`,
+      target: options.target,
+      cached: Boolean(options.cached),
+      installMethod: options.installMethod ?? RELEASE_ASSET_INSTALL_METHOD,
+      binaries: {
+        pylon: pylonPath,
+        pylonTui: pylonTuiPath,
+      },
+      configPath: init?.config_path ?? options.configPath ?? null,
+      pylonHome: options.pylonHome ? path.resolve(options.pylonHome) : null,
+      init,
+      status,
+      inventory,
+      model,
+      download,
+      diagnostic,
+      diagnosticResult,
+    };
+  } catch (error) {
+    emitTelemetry(telemetryClient, "installer_smoke_test_failed", {
+      release_tag: options.tagName ?? `pylon-v${options.version}`,
+      release_commit: options.sourceCommit ?? null,
+      os: options.target?.os ?? null,
+      arch: options.target?.arch ?? null,
+      platform_key:
+        options.target?.os && options.target?.arch
+          ? `${options.target.os}-${options.target.arch}`
+          : null,
+      install_source: installSourceForTelemetry(
+        options.installMethod,
+        Boolean(options.cached),
+      ),
+      ...telemetryFailureContext(error, "smoke_test"),
+    });
+    throw error;
+  }
 }
 
 export async function launchInstalledPylonTui(
@@ -1483,14 +1793,100 @@ export async function launchInstalledPylonTui(
   });
 }
 
+export function resolveBootstrapOutcome(summary) {
+  const runtimeState =
+    summary.status?.snapshot?.runtime?.authoritative_status ?? "unknown";
+  const localGemma = summary.status?.snapshot?.availability?.local_gemma ?? {};
+  const readyModel = localGemma.ready_model ?? null;
+  const localGemmaError = localGemma.last_error ?? null;
+  const diagnosticStatus = summary.diagnosticResult?.status ?? null;
+
+  if (runtimeState === "online") {
+    return {
+      level: "success",
+      verdict: "fully online",
+      detail: readyModel
+        ? `loaded runtime model ${readyModel}`
+        : "eligible local Gemma supply is online",
+    };
+  }
+
+  if (readyModel) {
+    return {
+      level: "success",
+      verdict: "runtime ready",
+      detail: `loaded runtime model ${readyModel}`,
+    };
+  }
+
+  const loweredError = (localGemmaError ?? "").toLowerCase();
+  if (loweredError.includes("/api/tags") || loweredError.includes("not reachable")) {
+    return {
+      level: "warning",
+      verdict: "installed but runtime missing",
+      detail:
+        "no Ollama-compatible local runtime is answering /api/tags yet",
+    };
+  }
+
+  if (
+    diagnosticStatus &&
+    diagnosticStatus !== "completed" &&
+    diagnosticStatus !== "passed" &&
+    diagnosticStatus !== "healthy"
+  ) {
+    return {
+      level: "warning",
+      verdict: "installed but runtime not yet usable",
+      detail: diagnosticStatus,
+    };
+  }
+
+  return {
+    level: "warning",
+    verdict: "installed",
+    detail: "complete the local runtime setup before bringing the node online",
+  };
+}
+
+function renderBootstrapNextSteps(summary, outcome) {
+  const lines = [
+    "Launcher path: use the same npx/bunx command again, or install globally and run `pylon`.",
+  ];
+
+  if (outcome.verdict === "fully online" || outcome.verdict === "runtime ready") {
+    lines.push("Next step: open the TUI with `pylon`, or keep using the package-managed launcher.");
+    return lines;
+  }
+
+  if (summary.target?.os === "darwin") {
+    lines.push(
+      "Runtime setup (macOS default): `brew install ollama`, `brew services start ollama`, `ollama pull gemma4:e4b`.",
+    );
+  } else {
+    lines.push(
+      "Runtime setup: start an Ollama-compatible local runtime at `local_gemma_base_url` and load `gemma4:e4b`.",
+    );
+  }
+  lines.push(
+    "Persistent PATH command: `npm install -g @openagentsinc/pylon` or `bun install -g @openagentsinc/pylon`, then run `pylon`.",
+  );
+  return lines;
+}
+
 export function renderBootstrapSummary(summary) {
+  const outcome = resolveBootstrapOutcome(summary);
   const lines = [
+    `Onboarding verdict: ${outcome.verdict}`,
+    `Verdict detail: ${outcome.detail}`,
     `Pylon release: ${summary.version} (${summary.target.os}-${summary.target.arch})`,
     `Archive source: ${summary.tagName}`,
+    `Install source: ${installSourceForTelemetry(summary.installMethod, summary.cached).replaceAll("_", " ")}`,
     `Installed from cache: ${summary.cached ? "yes" : "no"}`,
     `Pylon binary: ${summary.binaries.pylon}`,
     `Pylon TUI: ${summary.binaries.pylonTui}`,
     `Config path: ${summary.configPath ?? "unknown"}`,
+    `Preferred runtime model name: ${PREFERRED_RUNTIME_MODEL_NAME}`,
   ];
 
   const statusState =
@@ -1549,5 +1945,7 @@ export function renderBootstrapSummary(summary) {
     }
   }
 
+  lines.push(...renderBootstrapNextSteps(summary, outcome));
+
   return lines.join("\n");
 }

package/src/telemetry.js

@@ -0,0 +1,160 @@
+import { randomUUID } from "node:crypto";
+
+export const DEFAULT_TELEMETRY_ENDPOINT =
+  "https://openagents.com/api/telemetry/events";
+const DEFAULT_TELEMETRY_TIMEOUT_MS = 2_000;
+
+function timedSignal(timeoutMs = DEFAULT_TELEMETRY_TIMEOUT_MS) {
+  if (typeof AbortSignal?.timeout === "function") {
+    return {
+      signal: AbortSignal.timeout(timeoutMs),
+      dispose() {},
+    };
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  return {
+    signal: controller.signal,
+    dispose() {
+      clearTimeout(timer);
+    },
+  };
+}
+
+function cleanString(value, fallback = null) {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : fallback;
+}
+
+function normalizeProperties(properties = {}) {
+  try {
+    return JSON.parse(JSON.stringify(properties ?? {}));
+  } catch {
+    return {};
+  }
+}
+
+export function detectPackageInvoker(env = process.env) {
+  const userAgent = cleanString(env.npm_config_user_agent);
+  if (userAgent?.includes("bun/")) {
+    return "bun";
+  }
+  if (userAgent?.includes("npm/")) {
+    return "npm";
+  }
+
+  const execPath = cleanString(env.npm_execpath);
+  if (execPath?.includes("bun")) {
+    return "bun";
+  }
+  if (execPath?.includes("npm")) {
+    return "npm";
+  }
+
+  return "unknown";
+}
+
+export function installSourceForTelemetry(installMethod, cached) {
+  if (installMethod === "source_build") {
+    return cached ? "cached_source_build" : "source_build";
+  }
+
+  return cached ? "cached_prebuilt" : "prebuilt";
+}
+
+export function telemetryFailureContext(error, fallbackStage = "unknown") {
+  const cause = error?.cause ?? null;
+  const stage = cleanString(error?.stage)?.toLowerCase().replace(/[^a-z0-9]+/g, "_");
+  const code =
+    cleanString(error?.code) ??
+    cleanString(error?.errno) ??
+    cleanString(cause?.code) ??
+    cleanString(cause?.errno) ??
+    (typeof error?.httpStatus === "number" ? `http_${error.httpStatus}` : null) ??
+    "unknown";
+  const message =
+    (error instanceof Error ? error.message : String(error)).split("\n")[0] ??
+    "unknown error";
+
+  return {
+    error_stage: stage || fallbackStage,
+    error_code: code,
+    error_message: message.slice(0, 240),
+  };
+}
+
+export function createTelemetryClient({
+  endpoint = process.env.OPENAGENTS_TELEMETRY_URL ?? DEFAULT_TELEMETRY_ENDPOINT,
+  fetchImpl = globalThis.fetch,
+  anonymousActorId = randomUUID(),
+  sessionId = anonymousActorId,
+  installId = anonymousActorId,
+  appVersion = null,
+  sourceSurface = "installer",
+} = {}) {
+  const pending = new Set();
+  const enabled =
+    typeof fetchImpl === "function" &&
+    Boolean(cleanString(endpoint)) &&
+    process.env.OPENAGENTS_DISABLE_TELEMETRY !== "1";
+
+  async function post(payload) {
+    if (!enabled) {
+      return false;
+    }
+
+    const timeout = timedSignal();
+    try {
+      const response = await fetchImpl(endpoint, {
+        method: "POST",
+        headers: {
+          accept: "application/json",
+          "content-type": "application/json",
+        },
+        body: JSON.stringify(payload),
+        signal: timeout.signal,
+      });
+      return response.ok;
+    } catch {
+      return false;
+    } finally {
+      timeout.dispose();
+    }
+  }
+
+  return {
+    endpoint,
+    anonymousActorId,
+    sessionId,
+    installId,
+    emit(eventName, properties = {}) {
+      const promise = post({
+        event_name: eventName,
+        source_surface: sourceSurface,
+        occurred_at: new Date().toISOString(),
+        anonymous_actor_id: anonymousActorId,
+        session_id: sessionId,
+        install_id: installId,
+        app_version: cleanString(appVersion),
+        properties: normalizeProperties(properties),
+      });
+      pending.add(promise);
+      promise.finally(() => {
+        pending.delete(promise);
+      });
+      return promise;
+    },
+    async flush() {
+      const current = [...pending];
+      if (current.length === 0) {
+        return;
+      }
+      await Promise.allSettled(current);
+    },
+  };
+}