@openagentsinc/pylon 0.1.2 → 0.1.3

package/README.md

@@ -10,6 +10,9 @@ available.
 
 ```bash
 npx @openagentsinc/pylon
+bunx @openagentsinc/pylon
+npm install -g @openagentsinc/pylon && pylon
+bun install -g @openagentsinc/pylon && pylon
 npx @openagentsinc/pylon --version 0.0.1-rc4
 npx @openagentsinc/pylon --no-launch
 npx @openagentsinc/pylon --download-curated-cache --model gemma-4-e2b --diagnostic-repeats 2
@@ -18,8 +21,10 @@ 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
@@ -29,8 +34,13 @@ The launcher:
 - 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 +49,9 @@ 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
 
 ## Publish
 
@@ -46,5 +59,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.3",
   "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,6 +7,7 @@ import {
   bootstrapInstalledPylon,
   ensureReleaseInstall,
   launchInstalledPylonTui,
+  resolveBootstrapOutcome,
   renderBootstrapSummary,
 } from "./index.js";
 
@@ -67,6 +68,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 +77,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.
@@ -244,7 +249,12 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
   if (options.json) {
     console.log(JSON.stringify(summary, null, 2));
   } else {
-    reporter?.success("Pylon bootstrap complete");
+    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(

package/src/index.js

@@ -17,6 +17,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") {
@@ -1133,7 +1134,7 @@ 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);
@@ -1483,14 +1484,99 @@ 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}`,
     `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 +1635,7 @@ export function renderBootstrapSummary(summary) {
     }
   }
 
+  lines.push(...renderBootstrapNextSteps(summary, outcome));
+
   return lines.join("\n");
 }