@techsologic/unolock-agent 0.1.32 → 0.1.34

package/README.md

@@ -14,7 +14,6 @@ For skill-aware agents, the primary starting point is the UnoLock agent-access s
 * `https://github.com/TechSologic/unolock-agent/blob/main/skills/unolock-agent-access/SKILL.md`
 
 That skill is the agent-facing onboarding layer.
-The local UnoLock `stdio` MCP is the implementation layer underneath it.
 
 For OpenClaw, this package can also be installed as a plugin so OpenClaw can load the same skill natively.
 
@@ -49,7 +48,7 @@ For normal customer use, the strongest deployment uses a production-ready:
 * Secure Enclave
 * or equivalent platform-backed non-exportable key store
 
-If the host cannot provide one of those, the MCP can still fall back to a lower-assurance software provider. When that happens, the MCP reports the reduced assurance clearly and makes the reduced-assurance tradeoff visible instead of pretending it met UnoLock's preferred key-storage requirements.
+If the host cannot provide one of those, UnoLock Agent can still fall back to a lower-assurance software provider. When that happens, UnoLock reports the reduced assurance clearly and makes the reduced-assurance tradeoff visible instead of pretending it met UnoLock's preferred key-storage requirements.
 
 That tradeoff is intentional. Agentic Safe Access exists to keep AI access as close as possible to UnoLock's normal device-bound security model without pretending every host can satisfy the same storage guarantees.
 
@@ -60,7 +59,7 @@ UnoLock Agent is designed to work across a wide range of agent environments.
 The strongest deployments are environments that can provide device-bound, non-exportable key storage in a normal user-controlled session. That includes:
 
 * desktop AI assistants
-* local stdio MCP hosts such as Claude Desktop or Cursor
+* local AI hosts such as Claude Desktop or Cursor
 * user-controlled workstations, laptops, and VMs with TPM/vTPM access
 * macOS hosts that can use either Secure Enclave or a non-exportable Keychain-backed key
 * Windows or WSL hosts that can use either TPM-backed keys or the non-exportable Windows CNG fallback
@@ -104,7 +103,7 @@ Prerequisite:
 * Free and Inheritance can share their single included Safe space with one extra Agent Key.
 * Sovereign and HighRisk are still the right tiers for broader multi-Space and collaboration-heavy agent workflows.
 
-The current MCP layer proves the hardest integration seam first:
+The current agent runtime proves the hardest integration seam first:
 
 * live local `/start` flow compatibility
 * ML-DSA signature verification
@@ -117,8 +116,8 @@ Safe creation remains a human/browser responsibility, matching the product model
 
 * human admin creates a Safe
 * human admin creates an agent access key for that Safe
-* MCP registers to the existing Safe
-* MCP later authenticates and uses the shared Safe API surface for agent memory, notes, checklists, and secrets
+* UnoLock Agent registers to the existing Safe
+* UnoLock Agent later authenticates and uses the shared Safe API surface for agent memory, notes, checklists, and secrets
 
 ## Quick start
 
@@ -131,7 +130,7 @@ Run this from the repo root after the local server is up on `http://127.0.0.1:30
 ./scripts/run_local_e2e_readonly.sh
 ```
 
-For real MCP hosts, see:
+For host configuration and implementation details, see:
 
 * [Install Guide](docs/install.md)
 * [macOS Quick Start](docs/macos.md)
@@ -154,14 +153,14 @@ npx -y @techsologic/unolock-agent@latest list-notes
 npx -y @techsologic/unolock-agent@latest list-files
 ```
 
-For hosts that need MCP configuration, use the same executable in explicit MCP mode:
+Only if a host needs the explicit host-command form, use the same executable with:
 
-* MCP hosts launch `npx -y @techsologic/unolock-agent@latest mcp`.
+* Hosts that require this command shape launch `npx -y @techsologic/unolock-agent@latest mcp`.
 * The host writes JSON-RPC to `stdin` and reads JSON-RPC from `stdout`.
-* The `mcp` subcommand uses the local UnoLock daemon and auto-starts it if needed.
+* The `mcp` subcommand starts and uses the local UnoLock runtime automatically.
 * On a fresh host, the first start can take longer because local cryptographic code may need to be compiled or prepared.
 
-That keeps the user PIN in process memory, keeps the current Space selected, and hides local process details from the agent.
+That keeps the user PIN in process memory and keeps the current Space selected.
 
 The same executable also supports explicit CLI commands, for example:
 
@@ -173,13 +172,13 @@ unolock-agent create-note "Todo" "Buy milk"
 unolock-agent list-files
 ```
 
-Use the explicit `mcp` subcommand for daemon-backed stdio MCP mode. All other subcommands are daemon-backed CLI mode. Running `unolock-agent` with no arguments prints usage.
+Use the explicit `mcp` subcommand only for hosts that require that command shape. Running `unolock-agent` with no arguments prints usage.
 
-Once the local stdio MCP is running, the normal flow is:
+Once the local UnoLock Agent is running, the normal flow is:
 
 * call normal UnoLock tools
-* provide the one-time Agent Key URL and PIN together when the MCP asks for setup
-* let the MCP keep and use the current Space by default for normal work
+* provide the one-time Agent Key URL and PIN together when UnoLock asks for setup
+* let UnoLock keep and use the current Space by default for normal work
 
 If you prefer manual install from source:
 
@@ -197,9 +196,9 @@ python3 -m unolock_mcp config-check
 ```
 
 For normal customer and agent onboarding, do not drive the CLI `bootstrap` command directly.
-Let the MCP guide the normal flow.
+Let UnoLock guide the normal flow.
 
-macOS support is still alpha. The MCP now prefers Secure Enclave when it works cleanly and otherwise falls back to a non-exportable macOS Keychain key for broader compatibility. If you are evaluating it on Apple Silicon, start with:
+macOS support is still alpha. UnoLock Agent now prefers Secure Enclave when it works cleanly and otherwise falls back to a non-exportable macOS Keychain key for broader compatibility. If you are evaluating it on Apple Silicon, start with:
 
 * [macOS Quick Start](docs/macos.md)
 
@@ -231,7 +230,7 @@ On restart, the npm wrapper now checks GitHub Releases for a newer stable binary
 
 The npm package is both:
 
-* the normal MCP command package
+* the normal UnoLock executable package
 * an OpenClaw plugin package that ships the UnoLock skill
 
 Project home:
@@ -244,7 +243,7 @@ Use it as a command that OpenClaw can launch, for example:
 npx -y @techsologic/unolock-agent@latest mcp
 ```
 
-For MCP hosts, use the explicit `mcp` argument:
+For hosts that require the command form, use the explicit `mcp` argument:
 
 ```bash
 npx -y @techsologic/unolock-agent@latest mcp

package/bin/unolock-agent.js

@@ -7,9 +7,48 @@ const path = require("path");
 const https = require("https");
 const { spawn } = require("child_process");
 
-const PACKAGE_VERSION = "0.1.32";
-const FALLBACK_BINARY_VERSION = "0.1.32";
+const PACKAGE_VERSION = "0.1.34";
+const FALLBACK_BINARY_VERSION = "0.1.34";
 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} ...
+
+UnoLock Agent commands.
+
+positional arguments:
+  link-agent-key         Link a one-time UnoLock Agent Key URL and PIN to 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.
+  set-current-space      Set the current UnoLock space.
+  list-records           List notes and checklists in the current space.
+  list-notes             List notes in the current space.
+  list-checklists        List checklists in the current space.
+  get-record             Get one note or checklist by record_ref.
+  create-note            Create a note in the current space.
+  update-note            Update an existing note.
+  append-note            Append text to an existing note.
+  rename-record          Rename a note or checklist.
+  create-checklist       Create a checklist in the current space.
+  set-checklist-item-done
+                         Set one checklist item's done state.
+  add-checklist-item     Add an item to a checklist.
+  remove-checklist-item  Remove an item from a checklist.
+  list-files             List Cloud files in the current space.
+  get-file               Get metadata for one Cloud file.
+  download-file          Download a Cloud file to the local filesystem.
+  upload-file            Upload a local file into the current space.
+  rename-file            Rename a Cloud file.
+  replace-file           Replace a Cloud file with local content.
+  delete-file            Delete a Cloud file.
+  tpm-diagnose           Diagnose TPM/vTPM readiness for the UnoLock agent MCP.
+  tpm-check              Fail-fast check for production-ready TPM/vTPM/platform-backed key access.
+  self-test              Run a one-shot UnoLock Agent readiness check.
+  mcp                    Run the UnoLock stdio MCP server.
+
+options:
+  -h, --help             show this help message and exit
+  --version              show program's version number and exit
+`;
 
 function platformAssetInfo() {
   const platform = process.platform;
@@ -173,12 +212,26 @@ function writeReleaseMetadata(releaseVersion) {
   );
 }
 
-async function resolveReleaseVersion() {
+function cachedReleaseVersion() {
   const override = normalizeVersion(process.env.UNOLOCK_AGENT_BINARY_VERSION);
   if (override) {
     return override;
   }
   const metadata = readReleaseMetadata();
+  if (metadata && typeof metadata.releaseVersion === "string" && fs.existsSync(binaryPath(metadata.releaseVersion))) {
+    return metadata.releaseVersion;
+  }
+  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);
@@ -187,9 +240,6 @@ async function resolveReleaseVersion() {
       return latest;
     }
   } catch (error) {
-    if (metadata && typeof metadata.releaseVersion === "string" && fs.existsSync(binaryPath(metadata.releaseVersion))) {
-      return metadata.releaseVersion;
-    }
     process.stderr.write(`Warning: ${error.message}. Falling back to bundled release ${FALLBACK_BINARY_VERSION}.\n`);
   }
   writeReleaseMetadata(FALLBACK_BINARY_VERSION);
@@ -209,8 +259,16 @@ async function ensureBinary() {
 }
 
 async function main() {
-  const { dest, releaseVersion } = await ensureBinary();
   const forwardedArgs = process.argv.length > 2 ? process.argv.slice(2) : [];
+  if (forwardedArgs.length === 0 || forwardedArgs[0] === "-h" || forwardedArgs[0] === "--help") {
+    process.stdout.write(TOP_LEVEL_USAGE);
+    return;
+  }
+  if (forwardedArgs[0] === "--version") {
+    process.stdout.write(`${PACKAGE_VERSION}\n`);
+    return;
+  }
+  const { dest, releaseVersion } = await ensureBinary();
   const child = spawn(dest, forwardedArgs, {
     stdio: "inherit",
     env: {

package/openclaw-plugin/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "unolock-agent-access",
   "name": "UnoLock Agent Access",
-  "description": "Ships the UnoLock agent-access skill for OpenClaw. The skill uses the local UnoLock stdio MCP.",
+  "description": "Ships the UnoLock agent-access skill for OpenClaw.",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

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

@@ -6,7 +6,7 @@ description: Guides an AI agent through connecting to a user's UnoLock Safe with
 # UnoLock Agent Access
 
 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. The CLI is the simplest way to work with UnoLock. The same executable also supports MCP for hosts that specifically require it.
+This skill uses the local `unolock-agent` executable on the user's device.
 
 ## Preferred Workflow
 
@@ -30,20 +30,12 @@ This skill uses the local `unolock-agent` executable on the user's device. The C
 - `unolock-agent list-files`, `unolock-agent get-file <archive_id>`, `unolock-agent download-file ...`, `unolock-agent upload-file ...`, `unolock-agent rename-file ...`, `unolock-agent replace-file ...`, `unolock-agent delete-file ...`: read and manage Cloud files
 - `unolock-agent get-record <record_ref>` and `unolock-agent rename-record ...`: inspect or rename an existing note or checklist
 
-## MCP Fallback
-
-If the host specifically requires MCP instead of CLI:
-
-- run `npx -y @techsologic/unolock-agent@latest mcp`
-- write MCP JSON-RPC to `stdin` and read it from `stdout`
-- let the `mcp` subcommand auto-start and proxy through the local UnoLock daemon
-
 ## Key Rules
 
-- prefer CLI commands over MCP when the host supports direct command execution
 - give the agent the Agent Key URL and PIN together for first setup
 - if a command reports that the PIN is needed, run `unolock-agent set-agent-pin '<pin>'` and retry the original command
 - keep the PIN in UnoLock process memory only
+- if a host explicitly requires the host-command form, use `npx -y @techsologic/unolock-agent@latest mcp`
 
 ## User-Facing Model
 

package/package.json

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

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

@@ -6,7 +6,7 @@ description: Guides an AI agent through connecting to a user's UnoLock Safe with
 # UnoLock Agent Access
 
 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. The CLI is the simplest way to work with UnoLock. The same executable also supports MCP for hosts that specifically require it.
+This skill uses the local `unolock-agent` executable on the user's device.
 
 ## Preferred Workflow
 
@@ -31,20 +31,12 @@ This skill uses the local `unolock-agent` executable on the user's device. The C
 - `unolock-agent list-files`, `unolock-agent get-file <archive_id>`, `unolock-agent download-file ...`, `unolock-agent upload-file ...`, `unolock-agent rename-file ...`, `unolock-agent replace-file ...`, `unolock-agent delete-file ...`: read and manage Cloud files
 - `unolock-agent get-record <record_ref>` and `unolock-agent rename-record ...`: inspect or rename an existing note or checklist
 
-## MCP Fallback
-
-If the host specifically requires MCP instead of CLI:
-
-- run `npx -y @techsologic/unolock-agent@latest mcp`
-- write MCP JSON-RPC to `stdin` and read it from `stdout`
-- let the `mcp` subcommand auto-start and proxy through the local UnoLock daemon
-
 ## Key Rules
 
-- prefer CLI commands over MCP when the host supports direct command execution
 - give the agent the Agent Key URL and PIN together for first setup
 - if a command reports that the PIN is needed, run `unolock-agent set-agent-pin '<pin>'` and retry the original command
 - keep the PIN in UnoLock process memory only
+- if a host explicitly requires the host-command form, use `npx -y @techsologic/unolock-agent@latest mcp`
 
 ## User-Facing Model