@arthovlabs/liber 0.5.1 → 0.5.3

package/README.md

@@ -57,90 +57,152 @@ LiBER agents are equipped with a first-class toolset:
 
 ## 🚀 Quick Start
 
-### Install from npm
+### Requirements
+
+| Need | Version | For |
+|---|---|---|
+| **Node.js** | 18+ (20 recommended) | the CLI, the daemon, every tool |
+| **npm** | ships with Node | install and global link |
+| **Git** | any | source install, workspace/git panels |
+| Python 3.10+ | optional | the `liber tui` dashboard (textual + httpx) |
+| Docker | optional | the container sandbox; without it commands run in Constrained Language Mode |
+| Chrome or Edge | optional | the `browser` tool (launched headless on demand) |
+
+### Option A — install from npm (fastest)
 
 ```bash
 npm i -g @arthovlabs/liber
-liber --version
+liber --version          # prints the installed version
 ```
 
-Both commands are installed: `liber` (CLI / TUI) and `liberd` (daemon).
+No global install wanted? `npx @arthovlabs/liber --version` runs it once.
 
-### Or from source
+### Option B — install from GitHub (source)
 
 ```bash
 git clone https://github.com/june-arthov/LiBER-.git
 cd LiBER-
-npm install
-npm link
 ```
 
-> **Linux/WSL: use the full setup script** — it handles the pieces `npm link`
-> needs sudo for, creates an isolated `.venv` for the Python TUI (textual + httpx),
-> and copies `.env` from the template:
->
-> ```bash
-> bash scripts/setup.sh
-> ```
->
-> Manual fallback: `sudo npm link` (or run `node bin/liber` without linking) and
-> `python3 -m pip install --user textual httpx` for the TUI.
-
-*(Optional Python TUI dependencies)*
+**Linux / macOS / WSL — one command does the lot** (node deps, global link, an
+isolated `.venv` for the Python TUI, and `.env` from the template):
+
 ```bash
-pip install rich textual httpx
+bash scripts/setup.sh
 ```
 
-### 2. Configuration
+**Windows (PowerShell):**
 
-Create your local `.env`:
-```bash
-cp .env.example .env
-```
-Add your API key (e.g. Ollama Cloud or OpenAI compatible):
-```env
-OLLAMA_CLOUD_API_KEY=your_key_here
+```powershell
+npm install
+npm link                 # puts `liber` and `liberd` on PATH
+Copy-Item .env.example .env
 ```
 
-### 3. Usage
+If `liber` is still "not recognized", npm's global prefix is not on PATH —
+`npm config get prefix` prints it, and its bin directory is what needs adding.
+
+**Manual fallback on Linux/WSL** when `npm link` hits `EACCES`:
+`sudo npm link`, or skip linking entirely and run `node bin/liber`.
+TUI dependencies by hand: `python3 -m pip install --user textual httpx`.
+
+### Option C — Windows installer (Program Files, with a wizard)
+
+From a source checkout, stage the payload once and then run the wizard:
 
-#### Start the Background Daemon
 ```powershell
-liber spawn
+powershell -ExecutionPolicy Bypass -File installer\build.ps1   # bundles the app + Node runtime
+installer\LiBER-Setup.cmd                                      # double-click works too
 ```
 
-#### Launch Interactive LiBER Terminal
+The wizard asks for an install folder (default `C:\Program Files\LiBER`) and a
+data folder (default `%LOCALAPPDATA%\LiBER`), then:
+
+- copies the app, its dependencies and the desktop shell into Program Files,
+- keeps **your data** — sessions, memory, vault, logs, `.env` — in your own profile,
+  so a read-only program directory never blocks the agent,
+- creates Start Menu and desktop shortcuts that start the daemon and then the window,
+- registers **Apps & features** → uninstall (or run `uninstall.ps1` directly),
+- offers to launch LiBER when it finishes.
+
+Silent install, for a script or a lab machine:
+
 ```powershell
-liber
+powershell -ExecutionPolicy Bypass -File installer\LiBER-Setup.ps1 -Silent `
+  -InstallDir "C:\Program Files\LiBER" -DataDir "$env:LOCALAPPDATA\LiBER" -NoLaunch
 ```
-*Available slash commands inside the terminal: `/help`, `/status`, `/tools`, `/model`, `/logs`, `/clear`, `/tui`, `/exit`.*
 
-#### Launch Tactical Cyber-Obsidian TUI Dashboard
-```powershell
-liber tui
+`build.ps1 -SkipNode` leaves the 90 MB Node runtime out of the payload — the
+launcher then uses whatever `node` is on PATH, and says so if there is none.
+
+### 1. Give it a provider key
+
+```bash
+cp .env.example .env      # Windows: Copy-Item .env.example .env
 ```
-*Or directly via Python:*
-```powershell
-python bin/liber-tui.py
+
+Open `.env` and fill in the key for the provider you use — only one is needed:
+
+```env
+OLLAMA_CLOUD_API_KEY=...   # Ollama Cloud (https://ollama.com/v1)
+#OPENAI_API_KEY=sk-...     # any OpenAI-compatible vendor
+#ANTHROPIC_API_KEY=sk-ant-...
+#GEMINI_API_KEY=AIza...
 ```
 
-#### One-Shot CLI Execution
-```powershell
-liber chat dev-bot "audit project directory and verify package.json"
+Keys can also be stored in the encrypted vault and managed from the desktop shell
+(Settings → Providers / Vault & Secrets); a stored key wins over the environment.
+
+### 2. Start the daemon and prove it works
+
+```bash
+liber spawn            # background daemon on 127.0.0.1:4567
+liber ps               # fleet status — this must answer, not hang
+liber chat dev-bot "reply with exactly: ready"
 ```
 
-#### Manage Fleet
-```powershell
-liber ps          # Check agent fleet status and uptime
-liber logs -n 25  # View structured telemetry stream
-liber skills      # List procedural skills (liber skills <name> to print one)
-liber resume      # Continue an interrupted turn from .liber/turns/
-liber reset       # Clear the persisted conversation window
-liber bench       # Run the 8-case model-compliance benchmark (grounded, honesty, tools)
-liber desktop     # Launch the LiBER desktop shell (LiBER.exe — OpenCode-style UI)
-liber stop        # Gracefully shutdown daemon
+The last command is the real smoke test: a turn goes through the model, the
+grounding gate, and comes back with receipts.
+
+### 3. Pick a surface
+
+```bash
+liber                  # interactive CLI
+liber tui              # Textual dashboard (needs the Python deps)
+liber desktop          # LiBER.exe shell — source install only: the npm package
+                       # ships the runtime, not desktop/ (build: cd desktop && npx neu build)
+```
+
+All of them talk to the same daemon, so memory, sessions, budget and the audit
+logs are shared.
+
+### Command reference
+
+```bash
+liber spawn                 # start the daemon in the background
+liber stop                  # shut it down gracefully
+liber ps                    # agents, uptime, telemetry
+liber chat dev-bot "..."    # one-shot turn
+liber models                # list models from the live endpoint
+liber model <name>          # switch the active model
+liber logs -n 25            # structured telemetry stream
+liber skills [name]         # list or print a procedural skill
+liber resume [agentId]      # continue an interrupted turn
+liber reset                 # clear the persisted conversation window
+liber bench                 # run the model-compliance benchmark
 ```
 
+### If something goes wrong
+
+| Symptom | Cause and fix |
+|---|---|
+| `liber: command not found` | npm's global prefix is not on PATH — `npm config get prefix`, add its bin dir |
+| `EACCES` during `npm link` (Linux/WSL) | system node dir — `sudo npm link`, or run `node bin/liber` |
+| `liber ps` hangs or refuses | the daemon is not running — `liber spawn`; the token it writes is `.liber/daemon.token` |
+| `401` from a turn | no provider key resolved — check `.env`, or store it in the vault |
+| `liber tui` exits immediately | Python deps missing — `pip install textual httpx` |
+| Container backend silently absent | Docker daemon down — `GET /sandbox` says so, and commands fall back to Constrained Language Mode |
+
 ---
 
 ## 🧿 Zero-Hallucination Protocol
@@ -173,7 +235,7 @@ the cited receipt actually entails it. It is still not a proof system: the seman
 subtle unsupported claims or flag supported ones, and a verifier outage fails open (recorded as
 `semantic: error`, never silently as `pass`).
 
-Run the enforcement suite with `npm test` (242 tests: a scripted model that hallucinates, gets
+Run the enforcement suite with `npm test` (296 cases at the time of writing: a scripted model that hallucinates, gets
 blocked, and is forced to read the file before answering; a 15-case grounding regression dataset;
 the terminal policy incl. per-stage pipeline evaluation; the approval-channel wiring; the budget
 guard; and the git/workspace surface). CI runs the suite on Linux and Windows via

package/bin/liber

@@ -225,10 +225,26 @@ async function getPrimaryAgent() {
   return 'dev-bot';
 }
 
+// A bare 401 from a directory without a token is the most common first-run
+// confusion, so say what to do instead of repeating the server sentence.
+function authHint(message = '') {
+  if (!/unauthori[sz]ed/i.test(String(message))) return '';
+  const token = auth.readToken();
+  return [
+    '',
+    '  No daemon token usable from this directory.',
+    '    • start a daemon here:            liber spawn',
+    '    • the token lives in:             .liber/daemon.token (workspace)',
+    '                                      ~/.liber/daemon.token (machine copy)',
+    '    • or point at another daemon:     set LIBER_TOKEN=<token>',
+    token ? '' : '    • nothing was found in either place just now.'
+  ].filter(Boolean).join('\n');
+}
+
 // Render formatted status table
 async function formatStatusTable() {
   const res = await requestDaemon('/ps');
-  if (!res.success) throw new Error(res.error);
+  if (!res.success) throw new Error(res.error + authHint(res.error));
 
   const lines = [];
   lines.push('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arthovlabs/liber",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "LiBER — autonomous agent orchestrator with a machine-enforced grounding gate and a skill library",
   "bin": {
     "liber": "bin/liber",

package/src/daemon/core/auth.js

@@ -183,15 +183,41 @@ function rotate(id) {
 }
 
 /* ── legacy helpers, kept so existing callers keep working ────────────────── */
+/** Machine-level copy, so a globally installed CLI can reach this daemon. */
+const machineTokenPath = () => path.join(require('os').homedir(), '.liber', 'daemon.token');
+
+/** Copy the workspace token to the machine path (0600), best effort. */
+function publishMachineToken(token = readWorkspaceToken()) {
+  if (!token) return null;
+  try {
+    const file = machineTokenPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, token, { encoding: 'utf8', mode: 0o600 });
+    return file;
+  } catch { return null; }
+}
+
+function readWorkspaceToken() {
+  try { return fs.readFileSync(tokenPath(), 'utf8').trim() || null; } catch { return null; }
+}
+
 function readToken() {
   if (process.env.LIBER_TOKEN) return process.env.LIBER_TOKEN.trim();
-  try { return fs.readFileSync(tokenPath(), 'utf8').trim() || null; } catch { return null; }
+  // Workspace first (a daemon per project), then the machine copy written by
+  // `liber spawn` — without the fallback, a globally installed CLI run in a
+  // fresh directory gets a bare 401 with no hint of what to do.
+  const local = readWorkspaceToken();
+  if (local) return local;
+  try { return fs.readFileSync(machineTokenPath(), 'utf8').trim() || null; } catch { return null; }
 }
 function ensureToken() {
-  const existing = readToken();
+  // The daemon must create its *workspace* token. Using readToken() here would
+  // adopt the machine-level copy and never write .liber/daemon.token, so two
+  // workspaces would end up sharing one token.
+  const existing = readWorkspaceToken();
   if (existing) return existing;
   const token = crypto.randomBytes(32).toString('hex');
-  fs.mkdirSync(DIR(), { recursive: true });
+  fs.mkdirSync(path.dirname(tokenPath()), { recursive: true });
   fs.writeFileSync(tokenPath(), token, { encoding: 'utf8', mode: 0o600 });
   return token;
 }
@@ -213,5 +239,5 @@ function isAuthorized(req, expected) {
 module.exports = {
   bootstrap, verify, touch, rateLimit, can, scopeFor, audit, create, list, revoke, rotate, hash,
   SCOPES, DEFAULT_LIMIT, FILE, AUDIT,
-  tokenPath, readToken, ensureToken, extract, safeEqual, isAuthorized
+  tokenPath, machineTokenPath, readToken, readWorkspaceToken, publishMachineToken, ensureToken, extract, safeEqual, isAuthorized
 };

package/src/daemon/core/workspace.js

@@ -26,8 +26,11 @@ function isGitRepo() {
 }
 
 function branch() {
+  // `rev-parse --abbrev-ref HEAD` prints the literal string "HEAD" on a detached
+  // checkout (CI tag builds do this), which is not a branch name — reporting it
+  // as one made the UI show a branch called HEAD and marked nothing current.
   const b = sh('git', ['rev-parse', '--abbrev-ref', 'HEAD']);
-  if (b && b.trim()) return b.trim();
+  if (b && b.trim() && b.trim() !== 'HEAD') return b.trim();
   const detached = sh('git', ['rev-parse', '--short', 'HEAD']);
   return detached ? `detached@${detached.trim()}` : null;
 }

package/src/daemon/liberd.js

@@ -195,6 +195,9 @@ class LiberDaemon {
       llmManager.initialize(config.agent.engine);
       policy.configure(config.policy || {});
       this.token = auth.ensureToken();
+      // A globally installed CLI may be run from any directory; give it a way to
+      // find this daemon without hunting for the workspace token.
+      auth.publishMachineToken(this.token);
 
       this.maxLoops = config.limits?.circuit_breaker?.max_loops || 12;
       if (config.memory?.persist !== false) {