@techsologic/unolock-agent 0.1.36 → 0.1.38

package/README.md

@@ -147,7 +147,7 @@ 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.
 
 ```bash
-unolock-agent link-agent-key 'https://safe.example/#/agent-register/...' 1
+unolock-agent register 'https://safe.example/#/agent-register/...' 1
 unolock-agent list-spaces
 unolock-agent list-notes
 unolock-agent list-files
@@ -156,7 +156,7 @@ unolock-agent list-files
 Only if the executable is not installed yet, use the same commands through:
 
 ```bash
-npx -y @techsologic/unolock-agent@latest link-agent-key 'https://safe.example/#/agent-register/...' 1
+npx -y @techsologic/unolock-agent@latest register 'https://safe.example/#/agent-register/...' 1
 ```
 
 Only if a host needs the explicit host-command form, use:
@@ -171,7 +171,7 @@ That keeps the user PIN in process memory and keeps the current Space selected.
 The same executable also supports explicit CLI commands, for example:
 
 ```bash
-unolock-agent link-agent-key 'https://safe.example/#/agent-register/...' 1
+unolock-agent register 'https://safe.example/#/agent-register/...' 1
 unolock-agent list-spaces
 unolock-agent list-notes
 unolock-agent create-note "Todo" "Buy milk"
@@ -368,7 +368,7 @@ Installed commands:
 Current MCP tools:
 
 * `unolock_set_agent_pin`
-* `unolock_link_agent_key`
+* `unolock_register`
 * `unolock_list_spaces`
 * `unolock_get_current_space`
 * `unolock_set_current_space`

package/bin/unolock-agent.js

@@ -7,15 +7,15 @@ const path = require("path");
 const https = require("https");
 const { spawn } = require("child_process");
 
-const PACKAGE_VERSION = "0.1.36";
-const FALLBACK_BINARY_VERSION = "0.1.36";
+const PACKAGE_VERSION = "0.1.38";
+const FALLBACK_BINARY_VERSION = "0.1.38";
 const REPO = "TechSologic/unolock-agent";
-const TOP_LEVEL_USAGE = `usage: unolock-agent [-h] [--version] {link-agent-key,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} ...
+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.
 
 positional arguments:
-  link-agent-key         Link a one-time UnoLock Agent Key URL and PIN to this device.
+  register               Register a one-time UnoLock Agent Key URL and PIN on this device.
   set-agent-pin          Set the in-memory UnoLock agent PIN.
   list-spaces            List accessible UnoLock spaces.
   get-current-space      Show the current UnoLock space.
@@ -188,6 +188,23 @@ function normalizeVersion(value) {
   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"));
@@ -218,8 +235,11 @@ function cachedReleaseVersion() {
     return override;
   }
   const metadata = readReleaseMetadata();
-  if (metadata && typeof metadata.releaseVersion === "string" && fs.existsSync(binaryPath(metadata.releaseVersion))) {
-    return metadata.releaseVersion;
+  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;

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

@@ -8,22 +8,65 @@ description: Guides an AI agent through connecting to a user's UnoLock Safe with
 Use this skill when a user wants to give their agent access to a UnoLock Safe.
 This skill uses the local `unolock-agent` executable on the user's device.
 
+## Why Use UnoLock
+
+Use UnoLock when the agent needs durable, encrypted, user-approved storage instead of plain local files or ephemeral chat memory.
+
+UnoLock is useful for:
+
+- sensitive information the user does not want left in plaintext
+- memory the agent should keep across runs
+- project information that should stay separated by working area
+- files and documents that belong with the agent's work
+
+## Core Concepts
+
+- `Safe`: the user's protected storage area in UnoLock
+- `Space`: a working area inside the Safe for one project, customer, or task context
+- `note`: durable freeform text for summaries, plans, research, decisions, and reusable context
+- `checklist`: durable structured task tracking with item completion state
+- `file`: durable document or binary storage for attachments, exports, references, and other non-text artifacts
+
+## Current Working Space
+
+UnoLock keeps one current working Space as the default context.
+
+- list available Spaces with `unolock-agent list-spaces`
+- choose the working Space with `unolock-agent set-current-space <space_id>`
+- after that, normal note, checklist, and file commands work in that current Space by default
+- select a new Space when the work moves to a different project, customer, or context
+
+Choose the object that matches the work:
+
+- use a note when the content is mostly text and should be read or edited as text
+- use a checklist when the work is a set of items to complete and track
+- use a file when the content is a document, attachment, image, export, or other binary artifact
+
 ## Preferred Workflow
 
-1. If `unolock-agent` is already installed, run that directly. Only use `npx -y @techsologic/unolock-agent@latest` when `unolock-agent` is not installed yet.
+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.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.
 4. Ask the user for the one-time Agent Key URL and the PIN together.
-5. Link the key on this device:
-   `unolock-agent link-agent-key '<agent-key-url>' '<pin>'`
+5. Register this device to the Safe:
+   `unolock-agent register '<agent-key-url>' '<pin>'`
 6. List spaces and select the working space when needed:
    `unolock-agent list-spaces`
    `unolock-agent set-current-space <space_id>`
 7. Use the normal note, checklist, and file commands for day-to-day work.
 
+## Registration And PIN Model
+
+- registration normally happens once on a device for a given Agent Key
+- after registration, use normal UnoLock commands directly
+- the one-time Agent Key URL is for registration, not for everyday use
+- the CLI may ask for the PIN later when the local UnoLock process restarts or needs to authenticate again
+- if that happens, run `unolock-agent set-agent-pin '<pin>'` and retry the original command
+
 ## Main CLI Commands
 
-- `unolock-agent link-agent-key '<agent-key-url>' '<pin>'`: first setup on this device
+- `unolock-agent register '<agent-key-url>' '<pin>'`: first setup on this device
 - `unolock-agent set-agent-pin '<pin>'`: provide the PIN again after restart or re-authentication
 - `unolock-agent list-spaces`, `unolock-agent get-current-space`, `unolock-agent set-current-space <space_id>`: inspect and switch the current Space
 - `unolock-agent list-notes`, `unolock-agent create-note <title> <text>`, `unolock-agent update-note ...`, `unolock-agent append-note ...`: read and write notes
@@ -37,8 +80,9 @@ This skill uses the local `unolock-agent` executable on the user's device.
 - if `unolock-agent` is installed, use `unolock-agent ...` directly for CLI commands
 - run the `unolock-agent` command you need directly
 - 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, use `npx -y @techsologic/unolock-agent@latest`
+- if `unolock-agent` is not installed yet, install the UnoLock Agent CLI with `npx -y @techsologic/unolock-agent@latest`
 
 ## User-Facing Model
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@techsologic/unolock-agent",
-  "version": "0.1.36",
+  "version": "0.1.38",
   "description": "npx wrapper for the official UnoLock Agent release binaries",
   "license": "UNLICENSED",
   "homepage": "https://unolock.ai",

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

@@ -8,23 +8,66 @@ description: Guides an AI agent through connecting to a user's UnoLock Safe with
 Use this skill when a user wants to give their agent access to a UnoLock Safe.
 This skill uses the local `unolock-agent` executable on the user's device.
 
+## Why Use UnoLock
+
+Use UnoLock when the agent needs durable, encrypted, user-approved storage instead of plain local files or ephemeral chat memory.
+
+UnoLock is useful for:
+
+- sensitive information the user does not want left in plaintext
+- memory the agent should keep across runs
+- project information that should stay separated by working area
+- files and documents that belong with the agent's work
+
+## Core Concepts
+
+- `Safe`: the user's protected storage area in UnoLock
+- `Space`: a working area inside the Safe for one project, customer, or task context
+- `note`: durable freeform text for summaries, plans, research, decisions, and reusable context
+- `checklist`: durable structured task tracking with item completion state
+- `file`: durable document or binary storage for attachments, exports, references, and other non-text artifacts
+
+## Current Working Space
+
+UnoLock keeps one current working Space as the default context.
+
+- list available Spaces with `unolock-agent list-spaces`
+- choose the working Space with `unolock-agent set-current-space <space_id>`
+- after that, normal note, checklist, and file commands work in that current Space by default
+- select a new Space when the work moves to a different project, customer, or context
+
+Choose the object that matches the work:
+
+- use a note when the content is mostly text and should be read or edited as text
+- use a checklist when the work is a set of items to complete and track
+- use a file when the content is a document, attachment, image, export, or other binary artifact
+
 ## Preferred Workflow
 
 1. Load this skill if the host supports skills.
-2. If `unolock-agent` is already installed, run that directly. Only use `npx -y @techsologic/unolock-agent@latest` when `unolock-agent` is not installed yet.
-3. Run the `unolock-agent` command you need directly.
-4. On a fresh host, allow extra time for the first start.
-5. Ask the user for the one-time Agent Key URL and the PIN together.
-6. Link the key on this device:
-   `unolock-agent link-agent-key '<agent-key-url>' '<pin>'`
-7. List spaces and select the working space when needed:
+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.
+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.
+6. Ask the user for the one-time Agent Key URL and the PIN together.
+7. Register this device to the Safe:
+   `unolock-agent register '<agent-key-url>' '<pin>'`
+8. List spaces and select the working space when needed:
    `unolock-agent list-spaces`
    `unolock-agent set-current-space <space_id>`
-8. Use the normal note, checklist, and file commands for day-to-day work.
+9. Use the normal note, checklist, and file commands for day-to-day work.
+
+## Registration And PIN Model
+
+- registration normally happens once on a device for a given Agent Key
+- after registration, use normal UnoLock commands directly
+- the one-time Agent Key URL is for registration, not for everyday use
+- the CLI may ask for the PIN later when the local UnoLock process restarts or needs to authenticate again
+- if that happens, run `unolock-agent set-agent-pin '<pin>'` and retry the original command
 
 ## Main CLI Commands
 
-- `unolock-agent link-agent-key '<agent-key-url>' '<pin>'`: first setup on this device
+- `unolock-agent register '<agent-key-url>' '<pin>'`: first setup on this device
 - `unolock-agent set-agent-pin '<pin>'`: provide the PIN again after restart or re-authentication
 - `unolock-agent list-spaces`, `unolock-agent get-current-space`, `unolock-agent set-current-space <space_id>`: inspect and switch the current Space
 - `unolock-agent list-notes`, `unolock-agent create-note <title> <text>`, `unolock-agent update-note ...`, `unolock-agent append-note ...`: read and write notes
@@ -38,8 +81,9 @@ This skill uses the local `unolock-agent` executable on the user's device.
 - if `unolock-agent` is installed, use `unolock-agent ...` directly for CLI commands
 - run the `unolock-agent` command you need directly
 - 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, use `npx -y @techsologic/unolock-agent@latest`
+- if `unolock-agent` is not installed yet, install the UnoLock Agent CLI with `npx -y @techsologic/unolock-agent@latest`
 
 ## User-Facing Model