@techsologic/unolock-agent 0.1.42 → 0.1.43

package/README.md

@@ -87,7 +87,7 @@ Agent-first onboarding site:
 Recommended customer install source:
 
 * UnoLock's built-in local runtime/CLI with a GitHub Release binary when available
-* `npx -y @techsologic/unolock-agent@latest` as the easiest Node/npm CLI path
+* `npm install -g @techsologic/unolock-agent` as the primary npm install path
 * `pipx install` as the fallback source install path when no release binary is available yet
 
 If you are new to UnoLock itself, start with these docs first:
@@ -144,7 +144,11 @@ For host configuration and implementation details, see:
 * [OpenClaw plugin config example](examples/openclaw-plugin-config.json)
 
 For skill-aware agents, start with the skill above.
-For direct agent use, prefer the CLI. If `unolock-agent` is already installed, use it directly. Only use `npx -y @techsologic/unolock-agent@latest ...` when the executable is not installed yet. Run the command you need directly.
+For direct agent use, install the CLI once, then run `unolock-agent` directly.
+
+```bash
+npm install -g @techsologic/unolock-agent
+```
 
 ```bash
 unolock-agent register 'https://safe.example/#/agent-register/...' 1
@@ -153,15 +157,9 @@ unolock-agent list-notes
 unolock-agent list-files
 ```
 
-Only if the executable is not installed yet, use the same commands through:
-
-```bash
-npx -y @techsologic/unolock-agent@latest register 'https://safe.example/#/agent-register/...' 1
-```
-
 Only if a host needs the explicit host-command form, use:
 
-* `npx -y @techsologic/unolock-agent@latest mcp`
+* `unolock-agent mcp`
 * The host writes JSON-RPC to `stdin` and reads JSON-RPC from `stdout`.
 * The `mcp` subcommand starts and uses UnoLock automatically.
 * On a fresh host, the first start can take longer because local cryptographic code may need to be compiled or prepared.
@@ -214,7 +212,7 @@ For the best customer experience, prefer GitHub Release binaries over source ins
 
 ## Preferred Customer Install
 
-When available, prefer the built-in UnoLock local runtime plus the npm wrapper or release binary.
+When available, prefer the built-in UnoLock local runtime plus either a global npm install or a release binary.
 
 For an agent-first public onboarding flow, send users or agents to:
 
@@ -224,16 +222,13 @@ When available, prefer the standalone GitHub Release binaries instead of install
 
 That avoids most of the Python packaging and source-build overhead for customers.
 
-If your host environment is already Node/npm-oriented, you can also use the npm wrapper:
+If your host environment is already Node/npm-oriented, install the CLI globally:
 
 ```bash
-npx -y @techsologic/unolock-agent@latest --version
+npm install -g @techsologic/unolock-agent
+unolock-agent --version
 ```
 
-The wrapper downloads the correct GitHub Release binary for the current platform on first use and then reuses the cached copy.
-
-On restart, the npm wrapper now checks GitHub Releases for a newer stable binary and will update its cached binary between tasks when a newer release is available.
-
 The npm package is both:
 
 * the normal UnoLock executable package
@@ -246,13 +241,13 @@ Project home:
 Use it as a command that OpenClaw can launch, for example:
 
 ```bash
-npx -y @techsologic/unolock-agent@latest mcp
+unolock-agent mcp
 ```
 
 For hosts that require the command form, use the explicit `mcp` argument:
 
 ```bash
-npx -y @techsologic/unolock-agent@latest mcp
+unolock-agent mcp
 ```
 
 That is the preferred host-facing launch shape.
@@ -279,10 +274,9 @@ Or, through the MCP itself, call:
 
 Preferred channel behavior:
 
-* built-in daemon + `npx -y @techsologic/unolock-agent@latest`
-  * preferred low-friction path
-  * on restart, the npm wrapper checks GitHub Releases and can fetch the latest stable binary
-  * npm publishing is only needed when the wrapper itself changes
+* global npm install
+  * preferred low-friction npm path
+  * update with `npm install -g @techsologic/unolock-agent@latest`, then restart UnoLock
 * direct GitHub Release binary
   * replace the binary manually, then restart the UnoLock MCP
 * Python package install

package/bin/install-binary.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const {
+  PACKAGE_VERSION,
+  binaryUrl,
+  ensureDir,
+  ensureExecutable,
+  fetchToFile,
+  installedBinaryPath,
+} = require("./unolock-agent-common");
+
+async function main() {
+  const dest = installedBinaryPath();
+  if (fs.existsSync(dest)) {
+    ensureExecutable(dest);
+    return;
+  }
+  ensureDir(path.dirname(dest));
+  process.stderr.write(`Installing UnoLock agent ${PACKAGE_VERSION} for ${process.platform}/${process.arch}...\n`);
+  await fetchToFile(binaryUrl(PACKAGE_VERSION), dest);
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exit(1);
+  });
+}

package/bin/unolock-agent-common.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+"use strict";
+
+const fs = require("fs");
+const https = require("https");
+const path = require("path");
+
+const packageJson = require("../package.json");
+
+const PACKAGE_VERSION = packageJson.version;
+const REPO = "TechSologic/unolock-agent";
+
+function platformAssetInfo() {
+  const platform = process.platform;
+  const arch = process.arch;
+  if (platform === "linux" && arch === "x64") {
+    return { asset: "unolock-agent-linux-x86_64", executable: "unolock-agent-linux-x86_64" };
+  }
+  if (platform === "darwin" && arch === "arm64") {
+    return { asset: "unolock-agent-macos-arm64", executable: "unolock-agent-macos-arm64" };
+  }
+  if (platform === "darwin" && arch === "x64") {
+    return { asset: "unolock-agent-macos-x86_64", executable: "unolock-agent-macos-x86_64" };
+  }
+  if (platform === "win32" && arch === "x64") {
+    return { asset: "unolock-agent-windows-amd64.exe", executable: "unolock-agent-windows-amd64.exe" };
+  }
+  throw new Error(`Unsupported platform for UnoLock agent binary: ${platform}/${arch}`);
+}
+
+function installRoot() {
+  return path.join(__dirname, "..", "vendor");
+}
+
+function installedBinaryPath() {
+  const { executable } = platformAssetInfo();
+  return path.join(installRoot(), executable);
+}
+
+function binaryUrl(releaseVersion = PACKAGE_VERSION) {
+  if (process.env.UNOLOCK_AGENT_BINARY_URL) {
+    return process.env.UNOLOCK_AGENT_BINARY_URL;
+  }
+  const { asset } = platformAssetInfo();
+  return `https://github.com/${REPO}/releases/download/v${releaseVersion}/${asset}`;
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true, mode: 0o755 });
+}
+
+function ensureExecutable(dest) {
+  if (process.platform !== "win32" && fs.existsSync(dest)) {
+    fs.chmodSync(dest, 0o755);
+  }
+}
+
+function fetchToFile(url, dest) {
+  return new Promise((resolve, reject) => {
+    const temp = `${dest}.download`;
+    const request = https.get(url, (response) => {
+      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+        response.resume();
+        fetchToFile(response.headers.location, dest).then(resolve, reject);
+        return;
+      }
+      if (response.statusCode !== 200) {
+        response.resume();
+        reject(new Error(`Failed to download UnoLock agent binary: HTTP ${response.statusCode}`));
+        return;
+      }
+      const file = fs.createWriteStream(temp, { mode: 0o755 });
+      response.pipe(file);
+      file.on("finish", () => {
+        file.close((closeErr) => {
+          if (closeErr) {
+            reject(closeErr);
+            return;
+          }
+          fs.renameSync(temp, dest);
+          ensureExecutable(dest);
+          resolve();
+        });
+      });
+      file.on("error", (error) => {
+        file.close(() => {
+          try {
+            fs.unlinkSync(temp);
+          } catch {}
+          reject(error);
+        });
+      });
+    });
+    request.on("error", reject);
+  });
+}
+
+module.exports = {
+  PACKAGE_VERSION,
+  binaryUrl,
+  ensureDir,
+  ensureExecutable,
+  fetchToFile,
+  installRoot,
+  installedBinaryPath,
+  platformAssetInfo,
+};

package/bin/unolock-agent.js

@@ -2,17 +2,14 @@
 "use strict";
 
 const fs = require("fs");
-const os = require("os");
-const path = require("path");
-const https = require("https");
 const { spawn } = require("child_process");
 
-const PACKAGE_VERSION = "0.1.42";
-const FALLBACK_BINARY_VERSION = "0.1.42";
-const REPO = "TechSologic/unolock-agent";
-const INSTALL_LOCK_TIMEOUT_MS = 120000;
-const INSTALL_LOCK_STALE_MS = 300000;
-const INSTALL_LOCK_POLL_MS = 100;
+const {
+  PACKAGE_VERSION,
+  ensureExecutable,
+  installedBinaryPath,
+} = require("./unolock-agent-common");
+
 const TOP_LEVEL_USAGE = `usage: unolock-agent [-h] [--version] {register,set-agent-pin,list-spaces,get-current-space,set-current-space,list-records,list-notes,list-checklists,get-record,create-note,update-note,append-note,rename-record,create-checklist,set-checklist-item-done,add-checklist-item,remove-checklist-item,list-files,get-file,download-file,upload-file,rename-file,replace-file,delete-file,tpm-diagnose,tpm-check,self-test,mcp} ...
 
 UnoLock Agent commands.
@@ -53,317 +50,11 @@ options:
   --version              show program's version number and exit
 `;
 
-function platformAssetInfo() {
-  const platform = process.platform;
-  const arch = process.arch;
-  if (platform === "linux" && arch === "x64") {
-    return { asset: "unolock-agent-linux-x86_64", executable: "unolock-agent-linux-x86_64" };
-  }
-  if (platform === "darwin" && arch === "arm64") {
-    return { asset: "unolock-agent-macos-arm64", executable: "unolock-agent-macos-arm64" };
-  }
-  if (platform === "darwin" && arch === "x64") {
-    return { asset: "unolock-agent-macos-x86_64", executable: "unolock-agent-macos-x86_64" };
-  }
-  if (platform === "win32" && arch === "x64") {
-    return { asset: "unolock-agent-windows-amd64.exe", executable: "unolock-agent-windows-amd64.exe" };
-  }
-  throw new Error(`Unsupported platform for UnoLock agent binary: ${platform}/${arch}`);
-}
-
-function cacheRoot() {
-  if (process.platform === "win32") {
-    return process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
-  }
-  return process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
-}
-
-function metadataPath() {
-  return path.join(cacheRoot(), "unolock-agent", "release.json");
-}
-
-function installLockPath() {
-  return path.join(cacheRoot(), "unolock-agent", "install.lock");
-}
-
-function binaryPath(releaseVersion) {
-  const { executable } = platformAssetInfo();
-  return path.join(cacheRoot(), "unolock-agent", releaseVersion, executable);
-}
-
-function binaryUrl(releaseVersion) {
-  if (process.env.UNOLOCK_AGENT_BINARY_URL) {
-    return process.env.UNOLOCK_AGENT_BINARY_URL;
-  }
-  const { asset } = platformAssetInfo();
-  return `https://github.com/${REPO}/releases/download/v${releaseVersion}/${asset}`;
-}
-
-function ensureDir(dir) {
-  fs.mkdirSync(dir, { recursive: true, mode: 0o755 });
-}
-
-function sleep(ms) {
-  return new Promise((resolve) => {
-    setTimeout(resolve, ms);
-  });
-}
-
-function fetchToFile(url, dest) {
-  return new Promise((resolve, reject) => {
-    const temp = `${dest}.download`;
-    const request = https.get(url, (response) => {
-      if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
-        response.resume();
-        fetchToFile(response.headers.location, dest).then(resolve, reject);
-        return;
-      }
-      if (response.statusCode !== 200) {
-        response.resume();
-        reject(new Error(`Failed to download UnoLock agent binary: HTTP ${response.statusCode}`));
-        return;
-      }
-      const file = fs.createWriteStream(temp, { mode: 0o755 });
-      response.pipe(file);
-      file.on("finish", () => {
-        file.close((closeErr) => {
-          if (closeErr) {
-            reject(closeErr);
-            return;
-          }
-          fs.renameSync(temp, dest);
-          if (process.platform !== "win32") {
-            fs.chmodSync(dest, 0o755);
-          }
-          resolve();
-        });
-      });
-      file.on("error", (error) => {
-        file.close(() => {
-          try {
-            fs.unlinkSync(temp);
-          } catch {}
-          reject(error);
-        });
-      });
-    });
-    request.on("error", reject);
-  });
-}
-
-function fetchJson(url) {
-  return new Promise((resolve, reject) => {
-    const request = https.get(
-      url,
-      {
-        headers: {
-          "Accept": "application/vnd.github+json",
-          "User-Agent": "unolock-agent-npm-wrapper"
-        }
-      },
-      (response) => {
-        if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
-          response.resume();
-          fetchJson(response.headers.location).then(resolve, reject);
-          return;
-        }
-        if (response.statusCode !== 200) {
-          response.resume();
-          reject(new Error(`Failed to query UnoLock agent latest release: HTTP ${response.statusCode}`));
-          return;
-        }
-        let body = "";
-        response.setEncoding("utf8");
-        response.on("data", (chunk) => {
-          body += chunk;
-        });
-        response.on("end", () => {
-          try {
-            resolve(JSON.parse(body));
-          } catch (error) {
-            reject(error);
-          }
-        });
-      }
-    );
-    request.on("error", reject);
-  });
-}
-
-function normalizeVersion(value) {
-  if (!value || typeof value !== "string") {
-    return null;
-  }
-  const trimmed = value.trim();
-  if (!trimmed) {
-    return null;
-  }
-  return trimmed.startsWith("v") ? trimmed.slice(1) : trimmed;
-}
-
-function compareVersions(left, right) {
-  const leftParts = String(left || "").split(".").map((part) => Number.parseInt(part, 10) || 0);
-  const rightParts = String(right || "").split(".").map((part) => Number.parseInt(part, 10) || 0);
-  const length = Math.max(leftParts.length, rightParts.length);
-  for (let index = 0; index < length; index += 1) {
-    const leftValue = leftParts[index] || 0;
-    const rightValue = rightParts[index] || 0;
-    if (leftValue > rightValue) {
-      return 1;
-    }
-    if (leftValue < rightValue) {
-      return -1;
-    }
-  }
-  return 0;
-}
-
-function readReleaseMetadata() {
-  try {
-    return JSON.parse(fs.readFileSync(metadataPath(), "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function writeReleaseMetadata(releaseVersion) {
-  ensureDir(path.dirname(metadataPath()));
-  const dest = metadataPath();
-  const temp = `${dest}.tmp-${process.pid}`;
-  fs.writeFileSync(
-    temp,
-    JSON.stringify(
-      {
-        releaseVersion,
-        checkedAt: Date.now()
-      },
-      null,
-      2
-    ),
-    "utf8"
+function installedBinaryError() {
+  return (
+    "UnoLock Agent is not installed correctly. Reinstall it with `npm install -g @techsologic/unolock-agent` " +
+    "or use a GitHub release binary."
   );
-  fs.renameSync(temp, dest);
-}
-
-function cachedReleaseVersion() {
-  const override = normalizeVersion(process.env.UNOLOCK_AGENT_BINARY_VERSION);
-  if (override) {
-    return override;
-  }
-  const metadata = readReleaseMetadata();
-  const cached = metadata && typeof metadata.releaseVersion === "string" ? normalizeVersion(metadata.releaseVersion) : null;
-  if (cached && fs.existsSync(binaryPath(cached))) {
-    if (compareVersions(cached, FALLBACK_BINARY_VERSION) >= 0) {
-      return cached;
-    }
-  }
-  if (fs.existsSync(binaryPath(FALLBACK_BINARY_VERSION))) {
-    return FALLBACK_BINARY_VERSION;
-  }
-  return null;
-}
-
-async function resolveReleaseVersion() {
-  const cached = cachedReleaseVersion();
-  if (cached) {
-    return cached;
-  }
-  try {
-    const payload = await fetchJson(`https://api.github.com/repos/${REPO}/releases/latest`);
-    const latest = normalizeVersion(payload && payload.tag_name);
-    if (latest) {
-      writeReleaseMetadata(latest);
-      return latest;
-    }
-  } catch (error) {
-    process.stderr.write(`Warning: ${error.message}. Falling back to bundled release ${FALLBACK_BINARY_VERSION}.\n`);
-  }
-  writeReleaseMetadata(FALLBACK_BINARY_VERSION);
-  return FALLBACK_BINARY_VERSION;
-}
-
-function removeIfStale(lockPath) {
-  let stats;
-  try {
-    stats = fs.statSync(lockPath);
-  } catch (error) {
-    if (error && error.code === "ENOENT") {
-      return false;
-    }
-    throw error;
-  }
-  if (Date.now() - stats.mtimeMs < INSTALL_LOCK_STALE_MS) {
-    return false;
-  }
-  try {
-    fs.unlinkSync(lockPath);
-    return true;
-  } catch (error) {
-    if (error && error.code === "ENOENT") {
-      return true;
-    }
-    if (error && error.code === "EPERM") {
-      return false;
-    }
-    throw error;
-  }
-}
-
-async function acquireInstallLock() {
-  const lockPath = installLockPath();
-  ensureDir(path.dirname(lockPath));
-  const deadline = Date.now() + INSTALL_LOCK_TIMEOUT_MS;
-  while (true) {
-    try {
-      const fd = fs.openSync(lockPath, "wx", 0o600);
-      fs.writeFileSync(
-        fd,
-        JSON.stringify({ pid: process.pid, createdAt: Date.now() }),
-        "utf8"
-      );
-      return () => {
-        try {
-          fs.closeSync(fd);
-        } catch {}
-        try {
-          fs.unlinkSync(lockPath);
-        } catch {}
-      };
-    } catch (error) {
-      if (!error || error.code !== "EEXIST") {
-        throw error;
-      }
-      removeIfStale(lockPath);
-      if (Date.now() >= deadline) {
-        throw new Error("Timed out waiting for the UnoLock agent install lock");
-      }
-      await sleep(INSTALL_LOCK_POLL_MS);
-    }
-  }
-}
-
-async function ensureBinary() {
-  const cached = cachedReleaseVersion();
-  if (cached) {
-    const dest = binaryPath(cached);
-    if (fs.existsSync(dest)) {
-      return { dest, releaseVersion: cached };
-    }
-  }
-  const releaseLock = await acquireInstallLock();
-  try {
-    const releaseVersion = await resolveReleaseVersion();
-    const dest = binaryPath(releaseVersion);
-    if (fs.existsSync(dest)) {
-      return { dest, releaseVersion };
-    }
-    ensureDir(path.dirname(dest));
-    process.stderr.write(`Downloading UnoLock agent ${releaseVersion} for ${process.platform}/${process.arch}...\n`);
-    await fetchToFile(binaryUrl(releaseVersion), dest);
-    return { dest, releaseVersion };
-  } finally {
-    releaseLock();
-  }
 }
 
 async function main() {
@@ -376,14 +67,19 @@ async function main() {
     process.stdout.write(`${PACKAGE_VERSION}\n`);
     return;
   }
-  const { dest, releaseVersion } = await ensureBinary();
+
+  const dest = installedBinaryPath();
+  if (!fs.existsSync(dest)) {
+    throw new Error(installedBinaryError());
+  }
+  ensureExecutable(dest);
+
   const child = spawn(dest, forwardedArgs, {
     stdio: "inherit",
     env: {
       ...process.env,
-      UNOLOCK_AGENT_INSTALL_CHANNEL: "npm-wrapper",
-      UNOLOCK_AGENT_WRAPPER_VERSION: PACKAGE_VERSION,
-      UNOLOCK_AGENT_BINARY_VERSION: releaseVersion
+      UNOLOCK_AGENT_INSTALL_CHANNEL: "npm-install",
+      UNOLOCK_AGENT_BINARY_VERSION: PACKAGE_VERSION,
     }
   });
   child.on("exit", (code, signal) => {
@@ -406,12 +102,10 @@ if (require.main === module) {
   });
 } else {
   module.exports = {
-    acquireInstallLock,
-    compareVersions,
-    ensureBinary,
-    installLockPath,
-    metadataPath,
-    sleep,
-    writeReleaseMetadata,
+    PACKAGE_VERSION,
+    TOP_LEVEL_USAGE,
+    installedBinaryError,
+    installedBinaryPath,
+    main,
   };
 }

package/openclaw-plugin/skills/unolock-agent-access/SKILL.md

@@ -44,7 +44,7 @@ Choose the object that matches the work:
 
 ## Preferred Workflow
 
-1. If `unolock-agent` is not installed yet, install the UnoLock Agent CLI with `npx -y @techsologic/unolock-agent@latest`. If it is already installed, run `unolock-agent` directly.
+1. Install the UnoLock Agent CLI with `npm install -g @techsologic/unolock-agent`, then run `unolock-agent` directly.
 1.5. Run `unolock-agent` without arguments to get a usage statement when needed.
 2. Run the `unolock-agent` command you need directly.
 3. On a fresh host, allow extra time for the first start.
@@ -82,7 +82,7 @@ Choose the object that matches the work:
 - if a command reports that the PIN is needed, run `unolock-agent set-agent-pin '<pin>'` and retry the original command
 - if unsure which command to use next, run `unolock-agent --help`
 - keep the PIN in UnoLock process memory only
-- if `unolock-agent` is not installed yet, install the UnoLock Agent CLI with `npx -y @techsologic/unolock-agent@latest`
+- install the UnoLock Agent CLI with `npm install -g @techsologic/unolock-agent`
 
 ## User-Facing Model
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@techsologic/unolock-agent",
-  "version": "0.1.42",
-  "description": "npx wrapper for the official UnoLock Agent release binaries",
+  "version": "0.1.43",
+  "description": "UnoLock Agent CLI and local runtime",
   "license": "UNLICENSED",
   "homepage": "https://unolock.ai",
   "repository": {
@@ -14,6 +14,9 @@
   "bin": {
     "unolock-agent": "bin/unolock-agent.js"
   },
+  "scripts": {
+    "postinstall": "node bin/install-binary.js"
+  },
   "openclaw": {
     "extensions": [
       "./openclaw-plugin/index.js"

package/skills/unolock-agent-access/SKILL.md

@@ -45,7 +45,7 @@ Choose the object that matches the work:
 ## Preferred Workflow
 
 1. Load this skill if the host supports skills.
-2. If `unolock-agent` is not installed yet, install the UnoLock Agent CLI with `npx -y @techsologic/unolock-agent@latest`. If it is already installed, run `unolock-agent` directly.
+2. Install the UnoLock Agent CLI with `npm install -g @techsologic/unolock-agent`, then run `unolock-agent` directly.
 3. Run `unolock-agent` without arguments to get a usage statement when needed.
 4. Run the `unolock-agent` command you need directly.
 5. On a fresh host, allow extra time for the first start.
@@ -83,7 +83,7 @@ Choose the object that matches the work:
 - if a command reports that the PIN is needed, run `unolock-agent set-agent-pin '<pin>'` and retry the original command
 - if unsure which command to use next, run `unolock-agent --help`
 - keep the PIN in UnoLock process memory only
-- if `unolock-agent` is not installed yet, install the UnoLock Agent CLI with `npx -y @techsologic/unolock-agent@latest`
+- install the UnoLock Agent CLI with `npm install -g @techsologic/unolock-agent`
 
 ## User-Facing Model