local-commander-agent 0.3.3 → 0.3.4

package/README.md

@@ -1,18 +1,46 @@
 # Local Commander Agent
 
-Windows 11 x64 bootstrap package for Local Commander.
+**Connect your AI assistant to your Windows computer through [Local Commander](https://localcmd.app).** The agent lets an authorized MCP client work with local files, run explicitly approved commands, and access approved localhost services on your paired computer.
 
-## Install and pair
+> **Requires the Local Commander service at https://localcmd.app.** This npm package is its Windows companion, not a standalone MCP server, an offline AI assistant, or a JavaScript SDK. Installing the package alone is not enough: you need a Local Commander account, an approved device pairing, a running agent, an internet connection, and an authorized MCP connection from your AI client. Local management commands such as status and stop do not require the service to be online.
 
-```powershell
-npx local-commander-agent@latest
-```
+[Website and sign-in](https://localcmd.app) · [Support](https://localcmd.app/support) · [Privacy](https://localcmd.app/privacy)
+
+## Before you start
+
+Use **Windows 11 x64** and a currently supported Node.js LTS version meeting the package's Node.js 20+ minimum. Node.js/npm are needed to launch `npx`; the installed background agent includes its own Node runtime. You do not need Docker, WSL, a repository checkout, a database, or administrator rights for normal setup. Your AI client must support authenticated remote MCP connections; availability depends on the client and workspace policy.
+
+## Install and connect
+
+1. Open PowerShell or Windows Terminal as your normal Windows user and run:
+
+   ```powershell
+   npx local-commander-agent@latest
+   ```
 
-The bootstrap installs the self-contained Local Commander runtime under the current user's `%LOCALAPPDATA%LocalCommander` directory, opens the browser pairing flow, lets the user choose a workspace, enables per-user autostart and starts the background agent.
+2. The installer opens a browser. Sign in to [Local Commander](https://localcmd.app), check the displayed pairing code, and approve this computer. Approve only a pairing you just started yourself.
+3. Choose filesystem access in the local Windows dialog:
+   - **All connected drives — read and write:** approve all currently available drive letters shown in the dialog at once. There is no folder picker or separate approval for each drive.
+   - **Selected folders:** choose one folder in the folder picker. It starts read/write; more folders and write permission can be added later.
 
-Node.js 20+ is required only to run npm/npx. The installed agent uses its bundled Node runtime.
+   Cancel leaves existing permissions unchanged. On first setup, cancellation stops before enabling autostart or starting the agent. Existing grants are preserved when repeating installation or updating: an update never opts you into all drives.
+4. After the terminal reports that Local Commander is installed and running, connect your AI client to the remote MCP endpoint:
 
-## Management
+   ```text
+   https://localcmd.app/mcp
+   ```
+
+   Complete the browser authorization with the same Local Commander account. Device pairing and AI-client authorization are separate steps. This package does not expose a local stdio MCP server, so do not configure it as `command: npx` in an AI client's stdio-server settings.
+
+You can close the installation terminal. The agent runs in the background and starts when this Windows user signs in. The PC must be awake and online for remote AI tasks. As a first test, ask the connected assistant to list the files in a folder you approved.
+
+## What “all connected drives” means
+
+It expands the **filesystem scope** to the drive letters shown at the moment you consent. It includes available local fixed and removable drives. Mapped network drives and `subst` letters are not included. New drive letters, unavailable drives and unmounted volumes are not automatically added; run `configure-access` again after making the desired drive available. Grants are path/drive-letter based, not tied to a particular removable disk's hardware identity: reusing an approved letter gives access under that letter.
+
+This is not administrator access or an unrestricted shell. Windows permissions, protected Local Commander state/runtime and secret-file filters still apply to file tools. Direct command execution and localhost ports remain separately controlled. Read/write access is powerful: an assistant may read personal documents or change accessible files, and writing startup items, scripts or Git hooks can make programs run later as you. Treat drive-wide write access like permission to run programs. Folder controls are not an OS sandbox for an executable you separately allow. ChatGPT/Claude or your workspace may still ask for their own action confirmations.
+
+## Manage the installation
 
 ```powershell
 npx local-commander-agent@latest status
@@ -20,41 +48,69 @@ npx local-commander-agent@latest start
 npx local-commander-agent@latest stop
 npx local-commander-agent@latest restart
 npx local-commander-agent@latest update
-npx local-commander-agent@latest approve-workspace
 npx local-commander-agent@latest uninstall
 ```
 
-## Workspace permissions
+`status` reports the local installed version, process and pairing state; it is not proof of a healthy cloud relay connection. Installation files and per-user state live under `%LOCALAPPDATA%\LocalCommander`. Updating preserves enrollment and permissions. Close or finish active AI tasks before restarting or updating.
+
+Normal uninstall preserves protected enrollment state for reinstallation. To also remove this computer's local enrollment and permissions:
+
+```powershell
+npx local-commander-agent@latest uninstall --purge-state
+```
+
+Uninstall never deletes your project folders. For a lost or untrusted computer, also revoke its access through your Local Commander account; removing local files is not a substitute for cloud revocation.
+
+## Change access later
+
+Run these commands yourself on the paired computer. Install the release containing these commands with `update` before using them on an older installation.
+
+```powershell
+npx local-commander-agent@latest configure-access
+npx local-commander-agent@latest approve-workspace
+npx local-commander-agent@latest workspaces
+npx local-commander-agent@latest revoke-workspace <workspaceGrantId>
+```
+
+`configure-access` reopens the all-drives/selected-folder choice. **It replaces the current set of filesystem grants and clears their command and localhost permissions.** Choosing a restricted folder actually removes the old broader grants. `approve-workspace` adds another read/write folder without replacing the existing set. `workspaces` shows the grant IDs and permissions to use with the other commands. A successful change restarts an already-running agent to synchronize grants; cancellation does not restart it. A revoked drive is not silently re-added in the background.
 
-A newly approved workspace is read-only. Only the person at this PC can widen it; the AI client, MCP calls and the cloud cannot.
+To enable or remove individual capabilities, replace the placeholders with a grant ID from `workspaces` and an executable path that actually exists on your PC:
 
 ```powershell
-npx local-commander-agent@latest workspaces                                   # list workspaceGrantId and permissions
 npx local-commander-agent@latest allow-write <workspaceGrantId>
 npx local-commander-agent@latest allow-command <workspaceGrantId> node "C:\Program Files\nodejs\node.exe"
 npx local-commander-agent@latest allow-localhost <workspaceGrantId> 3000
+
 npx local-commander-agent@latest deny-write <workspaceGrantId>
 npx local-commander-agent@latest deny-command <workspaceGrantId> node
 npx local-commander-agent@latest deny-localhost <workspaceGrantId> 3000
 ```
 
-`allow-command` takes the command name the AI will use and the absolute path of that executable. A running agent restarts automatically to apply the change.
+`allow-command` associates an exact executable with the name the assistant uses; it does not accept a shell command string. Capability changes are local owner actions, not MCP settings the assistant can silently widen. The all-drives decision always requires the local dialog; there is no `--yes` or environment flag to approve it.
 
-To also remove the protected Local Commander enrollment/state during uninstall:
+## Troubleshooting
 
-```powershell
-npx local-commander-agent@latest uninstall --purge-state
-```
+| Symptom | What to check |
+| --- | --- |
+| `npx` is not recognized | Install supported Node.js LTS, then open a new terminal. |
+| Unsupported OS or architecture | This package targets Windows x64, not macOS, Linux or Windows ARM64. |
+| Pairing does not complete | Open https://localcmd.app, verify your account and internet access, then rerun the install command to resume. Do not share pairing codes. |
+| `ACCESS_SETUP_CANCELLED` | No filesystem grant was saved by that dialog. Rerun setup and choose the intended scope. |
+| `STATE_CHANGED` | Local account/policy/permissions changed while the dialog was open. Review current state and reopen the dialog. |
+| `WORKSPACE_INVALID` | Choose an existing ordinary folder, not a link or protected state directory. Use the all-drives choice for drive roots. |
+| `LOCAL_PERMISSION_REQUIRED` | Inspect `workspaces`; enable only the exact write/command/localhost capability needed. |
+| `PATH_NOT_ALLOWED` | The target is outside the grant, resolves elsewhere through a link, or is protected. Do not bypass the boundary with another tool. |
+| Paired and running, but the AI cannot reach the PC | Check that the PC is awake/online and that the AI client's remote MCP connection is authorized to the same account. Check service status/support. |
 
-Uninstall never removes user project files.
+For help, use [Local Commander support](https://localcmd.app/support) or email [peter.mamrukov@localcmd.app](mailto:peter.mamrukov@localcmd.app). Share error codes and the installed version, not keys, tokens, pairing codes, private state files or unredacted logs.
 
-## Control plane
+## Operator-only: a different control plane
 
-The package defaults to `https://localcmd.app`. A staging or self-hosted control plane can be selected only at first pairing with:
+Normal customers should not change the service origin. An operator testing a compatible staging or self-hosted **complete Local Commander service** may set the origin before first pairing:
 
 ```powershell
-$env:LC_CONTROL_PLANE_ORIGIN="https://your-control-plane.example"
+$env:LC_CONTROL_PLANE_ORIGIN = "https://your-control-plane.example"
 npx local-commander-agent@latest
 ```
 
-The enrollment stores the selected origin for later relay connections.
+Enrollment retains the chosen origin. Changing this variable does not move an already paired device or turn the package into a standalone MCP server. Account/device enrollment, OAuth, the control plane and relay are still required.

package/bin/localcommander.mjs

@@ -13,7 +13,7 @@ const DEFAULT_ORIGIN = String(PACKAGE_META.localCommander?.controlPlaneOrigin ||
 const RUNTIME_FILES = ["LocalCommanderAgent.exe", "OwnerBridge.exe", "JobHost.exe", "agent.mjs", "node.exe", "NODE-LICENSE.txt"];
 const RUN_KEY = "HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Run";
 const RUN_VALUE = "LocalCommanderAgent";
-const MAX_STDIO = 64 * 1024;
+const MAX_STDIO = 1024 * 1024;
 
 function fail(code) {
   const error = new Error(code);
@@ -231,14 +231,30 @@ async function pair(runtimeDir) {
   if (!opened) fail("PAIRING_RESPONSE_INVALID");
   process.stdout.write("Device paired.\n");
 }
+async function configureAccess(runtimeDir) {
+  const result = execAgent(runtimeDir, ["configure-access"], 300_000);
+  if (result.status !== 0) fail(result.stderr.trim() || "ACCESS_CONFIGURATION_FAILED");
+  const answer = result.stdout.trim();
+  if (answer === "ACCESS_CANCELLED") return false;
+  if (answer !== "ACCESS_CONFIGURED") fail("ACCESS_CONFIGURATION_INVALID");
+  return true;
+}
+async function restartIfRunning() {
+  const record = await readProcessRecord();
+  if (record && pidAlive(record.pid)) { await stopAgent(); await startAgent(); }
+}
 async function approveWorkspace(runtimeDir) {
   const result = execAgent(runtimeDir, ["approve-workspace"], 180_000);
   if (result.status !== 0) fail(result.stderr.trim() || "WORKSPACE_APPROVAL_FAILED");
-  process.stdout.write(result.stdout || "Workspace selection finished.\n");
+  const answer = result.stdout.trim();
+  if (answer === "WORKSPACE_CANCELLED") return false;
+  if (answer !== "WORKSPACE_APPROVED") fail("WORKSPACE_APPROVAL_INVALID");
+  process.stdout.write("Workspace approved.\n");
+  return true;
 }
 // Owner-only local permission surface. These run the installed runtime's own
 // commands on this PC; the cloud, the AI client and MCP calls cannot reach them.
-const PERMISSION_COMMANDS = { "allow-write": 1, "deny-write": 1, "allow-command": 3, "deny-command": 2, "allow-localhost": 2, "deny-localhost": 2 };
+const PERMISSION_COMMANDS = { "revoke-workspace": 1, "allow-write": 1, "deny-write": 1, "allow-command": 3, "deny-command": 2, "allow-localhost": 2, "deny-localhost": 2 };
 async function listWorkspaces(runtimeDir) {
   const result = execAgent(runtimeDir, ["list-workspaces"], 15_000);
   if (result.status !== 0) fail(result.stderr.trim() || "WORKSPACE_LIST_FAILED");
@@ -247,7 +263,8 @@ async function listWorkspaces(runtimeDir) {
 }
 async function changePermission(runtimeDir, command, args) {
   if (args.length !== PERMISSION_COMMANDS[command]) fail("ARGUMENT_INVALID");
-  const result = execAgent(runtimeDir, [command, ...args], 30_000);
+  // Covers the 60 s native owner review plus DPAPI/state work (see planning/OWNER_PERMISSIONS.md).
+  const result = execAgent(runtimeDir, [command, ...args], 90_000);
   if (result.status !== 0) fail(result.stderr.trim() || "PERMISSION_UPDATE_FAILED");
   const record = await readProcessRecord();
   if (record && pidAlive(record.pid)) {
@@ -339,11 +356,11 @@ async function bootstrap({ chooseWorkspace = true } = {}) {
   if (!identity.paired) await pair(runtimeDir);
   if (chooseWorkspace) {
     const list = execAgent(runtimeDir, ["list-workspaces"], 15_000);
-    let count = 0;
-    if (list.status === 0) {
-      try { const parsed = JSON.parse(list.stdout || "[]"); count = Array.isArray(parsed) ? parsed.length : 0; } catch {}
-    }
-    if (count === 0) await approveWorkspace(runtimeDir);
+    if (list.status !== 0) fail("WORKSPACE_LIST_FAILED");
+    let existing;
+    try { existing = JSON.parse(list.stdout); } catch { fail("WORKSPACE_LIST_INVALID"); }
+    if (!Array.isArray(existing)) fail("WORKSPACE_LIST_INVALID");
+    if (existing.length === 0 && !(await configureAccess(runtimeDir))) fail("ACCESS_SETUP_CANCELLED");
   }
   registerAutostart(runtimeDir);
   await startAgent();
@@ -375,7 +392,9 @@ function help() {
     "  npx local-commander-agent@latest stop         stop background agent",
     "  npx local-commander-agent@latest restart      restart background agent",
     "  npx local-commander-agent@latest update       install this package version and restart",
-    "  npx local-commander-agent@latest approve-workspace",
+    "  npx local-commander-agent@latest configure-access  choose all connected drives or selected folders",
+    "  npx local-commander-agent@latest approve-workspace add another read/write folder",
+    "  npx local-commander-agent@latest revoke-workspace <workspaceGrantId>",
     "  npx local-commander-agent@latest workspaces    list approved workspaces and permissions",
     "  npx local-commander-agent@latest allow-write <workspaceGrantId>",
     "  npx local-commander-agent@latest allow-command <workspaceGrantId> <name> <absolute-executable-path>",
@@ -428,11 +447,22 @@ async function main() {
     process.stdout.write(JSON.stringify(await statusObject(), null, 2) + "\n");
     return;
   }
+  if (command === "configure-access") {
+    if (args.length) fail("ARGUMENT_INVALID");
+    const current = await readCurrent();
+    if (!current) fail("AGENT_NOT_INSTALLED");
+    if (await configureAccess(current.runtimeDir)) {
+      await restartIfRunning();
+      process.stdout.write("Filesystem access configured.\n");
+    } else process.stdout.write("Access selection cancelled; existing permissions were preserved.\n");
+    return;
+  }
   if (command === "approve-workspace") {
     if (args.length) fail("ARGUMENT_INVALID");
     const current = await readCurrent();
     if (!current) fail("AGENT_NOT_INSTALLED");
-    await approveWorkspace(current.runtimeDir);
+    if (await approveWorkspace(current.runtimeDir)) await restartIfRunning();
+    else process.stdout.write("Workspace selection cancelled.\n");
     return;
   }
   if (command === "workspaces" || Object.hasOwn(PERMISSION_COMMANDS, command)) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "local-commander-agent",
-  "version": "0.3.3",
-  "description": "One-command Windows bootstrap for the Local Commander agent.",
+  "version": "0.3.4",
+  "description": "Windows companion for Local Commander: connect AI clients to local files, approved commands and localhost. Requires https://localcmd.app.",
   "type": "module",
   "bin": {
     "localcommander": "bin/localcommander.mjs"
@@ -37,5 +37,10 @@
   ],
   "localCommander": {
     "controlPlaneOrigin": "https://localcmd.app"
+  },
+  "homepage": "https://localcmd.app",
+  "bugs": {
+    "url": "https://localcmd.app/support",
+    "email": "peter.mamrukov@localcmd.app"
   }
 }