@thinremote/thinr-cli 1.3.2 → 1.3.4

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## [1.3.4] - 2026-09-24
+
+### Fixed
+
+- `thinr_script_delete` resolves the script by the name the agent reports, so
+  both `battery` and `battery.sh` remove the same file. It used to build the
+  path from the argument verbatim, which meant following its own description
+  ("without extension") returned a bare 404. A name that matches nothing now
+  lists the scripts that are registered.
+
+### Changed
+
+- `thinr_script_write` refuses a name that would replace one of the device's
+  built-in resources (`monitoring`, `system`, `cmd`, `update`, `agent`) unless
+  `force: true` is passed. Installing `monitoring.sh` used to shadow the real
+  monitoring resource silently. Its description now also states that the
+  script runs with the agent's privileges, root in a system install.
+- `thinr_devices` shows when each device last changed state: `connected since`
+  for a live one, `offline since` for a dead one. The timestamp was already in
+  the response; finding out whether something dropped minutes or months ago
+  meant a trip to the monitoring history.
+- `thinr_ls` explains that `/` resolves to the agent's base directory while
+  every other absolute path is literal, and a listing of `/` now says which
+  directory it came from. Nothing is confined to that directory, so reading a
+  `/` listing as the root filesystem was an easy wrong conclusion to draw.
+- `thinr_profiles` states that profiles are not accounts, and that `user`
+  addresses another account on the same server.
+
+## [1.3.3] - 2026-09-24
+
+### Changed
+
+- MCP tools take the target device as `device_id`. A tool argument named
+  `device` never reaches this server through Claude Desktop's remote-devices
+  bridge, which claims that name for its own call routing and strips it, so
+  every tool needing a device failed with `device is required` however the
+  caller spelled the call, while tools without one worked. Reproduced on one
+  machine with one binary: a direct JSON-RPC call succeeded, the same call
+  through Claude Desktop arrived without the field, and renaming the argument
+  fixed it with nothing else changed. `device` is no longer accepted.
+
 ## [1.3.2] - 2026-09-24
 
 ### Fixed

package/lib/mcp/tools-alarms.js

@@ -43,9 +43,7 @@ function normalizeSeverityInput(value) {
     for (const v of arr) {
         const parsed = parseAlarmSeverity(v);
         if (parsed === undefined) {
-            throw inputError(
-                `Unknown alarm severity "${v}". Valid: low, medium, high, critical.`,
-            );
+            throw inputError(`Unknown alarm severity "${v}". Valid: low, medium, high, critical.`);
         }
         out.push(parsed);
     }
@@ -195,7 +193,8 @@ async function toolAlarmInstanceUpdate(args) {
         content: [
             {
                 type: 'text',
-                text: `Updated ${args.instance} → state=${stateLabel}` +
+                text:
+                    `Updated ${args.instance} → state=${stateLabel}` +
                     (updated?.annotation ? `, annotation="${updated.annotation}"` : ''),
             },
         ],
@@ -228,9 +227,7 @@ async function toolAlarmRules(args) {
         return `${enabled}  ${id}${name}${desc}`;
     });
     return {
-        content: [
-            { type: 'text', text: `${rules.length} alarm rule(s):\n${lines.join('\n')}` },
-        ],
+        content: [{ type: 'text', text: `${rules.length} alarm rule(s):\n${lines.join('\n')}` }],
         isError: false,
     };
 }

package/lib/mcp/tools-buckets.js

@@ -9,7 +9,7 @@ async function toolBucketRead(args) {
         );
     const data = await getBucketData({
         bucket: args.bucket,
-        device: args.device,
+        device: args.device_id,
         user: args.user,
         items: args.items || 10,
         sort: args.sort || 'desc',
@@ -22,9 +22,7 @@ async function toolBucketRead(args) {
         group_by: args.group_by,
     });
     const text =
-        Array.isArray(data) && data.length === 0
-            ? 'No data'
-            : JSON.stringify(data, null, 2);
+        Array.isArray(data) && data.length === 0 ? 'No data' : JSON.stringify(data, null, 2);
     return {
         content: [{ type: 'text', text }],
         isError: false,
@@ -49,10 +47,9 @@ Custom buckets may not share the \`monitoring\` schema — don't assume a \`devi
                     description:
                         'Bucket ID as declared in the product profile (e.g. "monitoring", or a custom one like "sensors", "events").',
                 },
-                device: {
+                device_id: {
                     type: 'string',
-                    description:
-                        'Device ID. Omit for a one-row-per-device fleet view.',
+                    description: 'Device ID. Omit for a one-row-per-device fleet view.',
                 },
                 items: {
                     type: 'number',
@@ -61,8 +58,7 @@ Custom buckets may not share the \`monitoring\` schema — don't assume a \`devi
                 },
                 minutes: {
                     type: 'number',
-                    description:
-                        'Get data from the last N minutes. Alternative to min_ts/max_ts.',
+                    description: 'Get data from the last N minutes. Alternative to min_ts/max_ts.',
                 },
                 min_ts: { type: 'number', description: 'Minimum timestamp in milliseconds' },
                 max_ts: {

package/lib/mcp/tools-devices.js

@@ -10,11 +10,22 @@ async function toolDevices(args) {
     const filter = query ? { name: query } : {};
     const devices = await getDevices(filter, args.user);
 
+    // `connection.ts` is when the state last changed, so it reads as
+    // "connected since" for a live device and "offline since" for a dead
+    // one. Showing it saves a trip to the monitoring history to find out
+    // whether something dropped a minute ago or back in July.
+    const since = (d) => {
+        const ts = d.connection?.ts;
+        if (!ts) return '';
+        const when = new Date(ts).toISOString().replace('T', ' ').slice(0, 16);
+        return d.connection?.active ? `  connected since ${when}` : `  offline since ${when}`;
+    };
+
     const renderLine = (d) => {
         const status = d.connection?.active ? 'online ' : 'offline';
         const label = d.name ? ` (${d.name})` : '';
         const product = d.type && d.type !== 'Generic' ? ` [${d.type}]` : '';
-        return `${status}  ${d.device}${label}${product}`;
+        return `${status}  ${d.device}${label}${product}${since(d)}`;
     };
 
     if (!query) {
@@ -39,7 +50,7 @@ async function toolDevices(args) {
 }
 
 async function toolDeviceInfo(args) {
-    const { api: deviceApi } = getAPI(args.device, args.user);
+    const { api: deviceApi } = getAPI(args.device_id, args.user);
     const parts = [];
 
     // Server-side record first — surfaces the assigned product,
@@ -47,7 +58,7 @@ async function toolDeviceInfo(args) {
     // can't see. Best effort: don't fail the whole tool if the
     // record can't be read.
     try {
-        const record = await getDevice(args.device, args.user);
+        const record = await getDevice(args.device_id, args.user);
         const meta = [];
         if (record.device) meta.push(`device:        ${record.device}`);
         if (record.name) meta.push(`name:          ${record.name}`);
@@ -120,7 +131,7 @@ async function toolDeviceInfo(args) {
 }
 
 async function toolDeviceSetProduct(args) {
-    const device = args.device;
+    const device = args.device_id;
     if (!device) throw inputError('device is required');
     if (args.product === undefined || args.product === null)
         throw inputError('product is required (pass "" to unassign)');
@@ -133,7 +144,7 @@ async function toolDeviceSetProduct(args) {
 }
 
 async function toolDeviceDelete(args) {
-    const device = args.device;
+    const device = args.device_id;
     if (!device) throw inputError('device is required');
     const removed = await deleteDevice(device, args.user);
     return {
@@ -182,10 +193,10 @@ export const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['device'],
+            required: ['device_id'],
         },
         handler: toolDeviceInfo,
     },
@@ -196,14 +207,14 @@ export const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 product: {
                     type: 'string',
                     description: 'Product ID to assign, or empty string "" to unassign.',
                 },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['device', 'product'],
+            required: ['device_id', 'product'],
         },
         handler: toolDeviceSetProduct,
     },
@@ -214,10 +225,10 @@ export const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                device: { type: 'string', description: 'Device ID to delete.' },
+                device_id: { type: 'string', description: 'Device ID to delete.' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['device'],
+            required: ['device_id'],
         },
         handler: toolDeviceDelete,
     },

package/lib/mcp/tools-exec.js

@@ -5,7 +5,7 @@ import { BYTES, TIMEOUTS } from '../constants.js';
 import { getAPI } from './helpers.js';
 
 async function toolExec(args) {
-    const { api } = getAPI(args.device, args.user);
+    const { api } = getAPI(args.device_id, args.user);
     // Default guards against hung commands locking the session; callers
     // override for known-long operations. Knob lives in lib/constants.js.
     const timeout =
@@ -33,7 +33,7 @@ async function toolExec(args) {
 }
 
 async function toolUpdate(args) {
-    const { api: deviceApi } = getAPI(args.device, args.user);
+    const { api: deviceApi } = getAPI(args.device_id, args.user);
     const payload = {
         action: args.action,
         channel: args.channel || 'latest',
@@ -46,7 +46,7 @@ async function toolUpdate(args) {
 }
 
 async function toolMonitoring(args) {
-    const device = args.device;
+    const device = args.device_id;
     const user = args.user;
 
     // Real-time: read the device's `monitoring` resource directly.
@@ -143,11 +143,11 @@ export const tools = [
             type: 'object',
             properties: {
                 command: { type: 'string', description: 'Shell command to execute' },
-                device: { type: 'string', description: 'Device ID (from thinr_devices)' },
+                device_id: { type: 'string', description: 'Device ID (from thinr_devices)' },
                 timeout: { type: 'number', description: 'Timeout in seconds (default: 30)' },
                 user: { type: 'string', description: 'API user (for admin impersonation)' },
             },
-            required: ['command', 'device'],
+            required: ['command', 'device_id'],
         },
         handler: toolExec,
     },
@@ -157,7 +157,7 @@ export const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 action: {
                     type: 'string',
                     description: '"check" to check for updates, "apply" to install the update',
@@ -165,7 +165,7 @@ export const tools = [
                 channel: { type: 'string', description: 'Update channel (default: "latest")' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['action', 'device'],
+            required: ['action', 'device_id'],
         },
         handler: toolUpdate,
     },
@@ -185,14 +185,15 @@ Modes:
                     description:
                         'If true, get live data directly from the device. If false/omitted, query historical data from the monitoring bucket.',
                 },
-                device: {
+                device_id: {
                     type: 'string',
                     description:
                         'Device ID. Required for realtime. Omit for a one-row-per-device fleet view.',
                 },
                 items: {
                     type: 'number',
-                    description: 'Number of data points to return (default: 10). In multi-device mode set ≥ number of devices (e.g. 200) since each device contributes one row.',
+                    description:
+                        'Number of data points to return (default: 10). In multi-device mode set ≥ number of devices (e.g. 200) since each device contributes one row.',
                 },
                 minutes: {
                     type: 'number',
@@ -205,12 +206,18 @@ Modes:
                 },
                 sort: {
                     type: 'string',
-                    description: 'Sort order by timestamp: "asc" or "desc" (default: "desc"). Does NOT sort by metric — do that client-side on the result.',
+                    description:
+                        'Sort order by timestamp: "asc" or "desc" (default: "desc"). Does NOT sort by metric — do that client-side on the result.',
+                },
+                agg: {
+                    type: 'string',
+                    description:
+                        'Time-window size for windowed aggregation: "5m", "10m", "1h", "6h". Only meaningful with a specific device. For a per-device single value across the whole range, omit `agg` and pass `agg_type` alone.',
                 },
-                agg: { type: 'string', description: 'Time-window size for windowed aggregation: "5m", "10m", "1h", "6h". Only meaningful with a specific device. For a per-device single value across the whole range, omit `agg` and pass `agg_type` alone.' },
                 agg_type: {
                     type: 'string',
-                    description: 'Reducer applied to each group/window. Supported: "mean", "max", "min", "sum", "count", "first", "last", "median", "spread" (max-min), "stddev". Most common for monitoring: max, mean, min.',
+                    description:
+                        'Reducer applied to each group/window. Supported: "mean", "max", "min", "sum", "count", "first", "last", "median", "spread" (max-min), "stddev". Most common for monitoring: max, mean, min.',
                 },
                 fields: {
                     type: 'string',

package/lib/mcp/tools-filesystem.js

@@ -5,7 +5,7 @@ import { getAPI } from './helpers.js';
 import { inputError } from '../errors.js';
 
 async function toolRead(args) {
-    const { api } = getAPI(args.device, args.user);
+    const { api } = getAPI(args.device_id, args.user);
     const content = await api.readFile(args.path);
     return {
         content: [{ type: 'text', text: content.toString('utf8') }],
@@ -14,7 +14,7 @@ async function toolRead(args) {
 }
 
 async function toolWrite(args) {
-    const { api } = getAPI(args.device, args.user);
+    const { api } = getAPI(args.device_id, args.user);
     await api.writeFile(args.path, Buffer.from(args.content, 'utf8'));
     return {
         content: [{ type: 'text', text: `Written ${args.content.length} bytes to ${args.path}` }],
@@ -23,8 +23,26 @@ async function toolWrite(args) {
 }
 
 async function toolLs(args) {
-    const { api } = getAPI(args.device, args.user);
-    const entries = await api.listDir(args.path || '/', args.include_hidden || false);
+    const { api } = getAPI(args.device_id, args.user);
+    const requested = args.path || '/';
+    const entries = await api.listDir(requested, args.include_hidden || false);
+
+    // "/" is the agent's base directory, not the filesystem root, while every
+    // other absolute path is literal. Listing "/" on an agent based in
+    // /var/log and reading it as the root is an easy and wrong conclusion to
+    // draw, so say which directory these entries actually came from.
+    let header = '';
+    if (requested === '/') {
+        try {
+            const root = await api.info('/');
+            if (root?.path && root.path !== '/') {
+                header = `listing ${root.path} (the agent's base directory, which "/" resolves to)\n`;
+            }
+        } catch {
+            // Labelling is a convenience; a listing without it still stands.
+        }
+    }
+
     const lines = entries.map((e) => {
         const type = e.type === 'directory' ? 'd' : '-';
         const mode = e.mode || 'rwxr-xr-x';
@@ -32,13 +50,13 @@ async function toolLs(args) {
         return `${type}${mode} ${size} ${e.name}`;
     });
     return {
-        content: [{ type: 'text', text: lines.join('\n') || '(empty directory)' }],
+        content: [{ type: 'text', text: header + (lines.join('\n') || '(empty directory)') }],
         isError: false,
     };
 }
 
 async function toolMkdir(args) {
-    const { api } = getAPI(args.device, args.user);
+    const { api } = getAPI(args.device_id, args.user);
     await api.mkdir(args.path);
     return {
         content: [{ type: 'text', text: `Created directory: ${args.path}` }],
@@ -47,7 +65,7 @@ async function toolMkdir(args) {
 }
 
 async function toolRm(args) {
-    const { api } = getAPI(args.device, args.user);
+    const { api } = getAPI(args.device_id, args.user);
     await api.delete(args.path, args.recursive !== false);
     return {
         content: [{ type: 'text', text: `Deleted: ${args.path}` }],
@@ -56,7 +74,7 @@ async function toolRm(args) {
 }
 
 async function toolMv(args) {
-    const { api } = getAPI(args.device, args.user);
+    const { api } = getAPI(args.device_id, args.user);
     await api.move(args.source, args.destination, args.overwrite || false);
     return {
         content: [{ type: 'text', text: `Moved: ${args.source} → ${args.destination}` }],
@@ -75,7 +93,7 @@ async function toolPush(args) {
     const remotePath = args.destination.endsWith('/')
         ? args.destination + basename(localPath)
         : args.destination;
-    const { api } = getAPI(args.device, args.user);
+    const { api } = getAPI(args.device_id, args.user);
     const content = await readLocalFile(localPath);
     await api.writeFile(remotePath, content);
     return {
@@ -99,7 +117,7 @@ async function toolPull(args) {
     const localPath = args.destination.endsWith('/')
         ? resolvePath(args.destination, basename(args.source))
         : resolvePath(args.destination);
-    const { api } = getAPI(args.device, args.user);
+    const { api } = getAPI(args.device_id, args.user);
     const buf = await api.readFile(args.source);
     await writeLocalFile(localPath, buf);
     return {
@@ -121,10 +139,10 @@ export const tools = [
             type: 'object',
             properties: {
                 path: { type: 'string', description: 'Absolute file path on the device' },
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['path', 'device'],
+            required: ['path', 'device_id'],
         },
         handler: toolRead,
     },
@@ -136,28 +154,32 @@ export const tools = [
             properties: {
                 path: { type: 'string', description: 'Absolute file path on the device' },
                 content: { type: 'string', description: 'File content to write' },
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['path', 'content', 'device'],
+            required: ['path', 'content', 'device_id'],
         },
         handler: toolWrite,
     },
     {
         name: 'thinr_ls',
-        description: `List directory contents on a remote device. Paths are absolute on the device filesystem (e.g., "/", "/etc", "/var/log"). Subject to the OS user the agent runs as; check whoami (or thinr_device_info) before assuming write access to system paths like /etc. Use include_hidden to see dotfiles.`,
+        description: `List directory contents on a remote device. Paths are absolute on the device filesystem (e.g., "/etc", "/var/log"), with one exception: "/" on its own resolves to the agent's base directory (\`fs_base_path\` in thinr_device_info), which for a system install is usually /var/log. The listing says which directory it came from when the two differ. Nothing is confined to that directory — "/etc" reads the real /etc — so do not read a "/" listing as the root filesystem. Subject to the OS user the agent runs as; check whoami (or thinr_device_info) before assuming write access to system paths. Use include_hidden to see dotfiles.`,
         inputSchema: {
             type: 'object',
             properties: {
-                path: { type: 'string', description: 'Directory path (default: /)' },
+                path: {
+                    type: 'string',
+                    description:
+                        'Directory path. Absolute and literal, except "/", which means the agent\'s base directory (default: "/").',
+                },
                 include_hidden: {
                     type: 'boolean',
                     description: 'Include hidden files (default: false)',
                 },
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['device'],
+            required: ['device_id'],
         },
         handler: toolLs,
     },
@@ -168,10 +190,10 @@ export const tools = [
             type: 'object',
             properties: {
                 path: { type: 'string', description: 'Directory path to create' },
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['path', 'device'],
+            required: ['path', 'device_id'],
         },
         handler: toolMkdir,
     },
@@ -186,10 +208,10 @@ export const tools = [
                     type: 'boolean',
                     description: 'Delete directory contents recursively (default: true)',
                 },
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['path', 'device'],
+            required: ['path', 'device_id'],
         },
         handler: toolRm,
     },
@@ -205,10 +227,10 @@ export const tools = [
                     type: 'boolean',
                     description: 'Overwrite destination if exists (default: false)',
                 },
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['source', 'destination', 'device'],
+            required: ['source', 'destination', 'device_id'],
         },
         handler: toolMv,
     },
@@ -227,10 +249,10 @@ export const tools = [
                     description:
                         'Absolute path on the device. Trailing "/" keeps the source basename.',
                 },
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['source', 'destination', 'device'],
+            required: ['source', 'destination', 'device_id'],
         },
         handler: toolPush,
     },
@@ -249,10 +271,10 @@ export const tools = [
                     description:
                         'Local file path (absolute or relative to the MCP server CWD). Trailing "/" keeps the source basename.',
                 },
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['source', 'destination', 'device'],
+            required: ['source', 'destination', 'device_id'],
         },
         handler: toolPull,
     },

package/lib/mcp/tools-install.js

@@ -41,7 +41,7 @@ async function toolAgentInstallCommand(args) {
     const url = `${scheme}://get.thinremote.io/${script}`;
 
     const agentArgs = ['install', '--token', shQuote(config.token)];
-    if (args.device) agentArgs.push('--device', shQuote(args.device));
+    if (args.device_id) agentArgs.push('--device', shQuote(args.device_id));
     if (args.product) agentArgs.push('--product', shQuote(args.product));
     if (args.overwrite) agentArgs.push('--overwrite');
     if (args.no_start) agentArgs.push('--no-start');
@@ -83,7 +83,7 @@ async function toolAgentInstallCommand(args) {
         command,
         '',
         'Notes:',
-        '- The command embeds the active profile\'s API token — treat it as a credential.',
+        "- The command embeds the active profile's API token — treat it as a credential.",
         '- Installing the system service needs root. Pass `sudo: true` if the target host is not already root.',
         '- The agent reads the target server from the JWT, so `--host` is not needed.',
     ];
@@ -106,10 +106,10 @@ export const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                device: {
+                device_id: {
                     type: 'string',
                     description:
-                        'Custom device identifier. Omit to let the agent default to the target host\'s hostname.',
+                        "Custom device identifier. Omit to let the agent default to the target host's hostname.",
                 },
                 product: {
                     type: 'string',
@@ -127,8 +127,7 @@ export const tools = [
                 },
                 no_verify_ssl: {
                     type: 'boolean',
-                    description:
-                        'Disable TLS certificate verification (for self-signed servers).',
+                    description: 'Disable TLS certificate verification (for self-signed servers).',
                 },
                 channel: {
                     type: 'string',

package/lib/mcp/tools-playbook.js

@@ -170,15 +170,15 @@ Response carries a consolidated report: devices visited, ok / failed counts, and
                 },
                 target_product: {
                     type: 'string',
-                    description: 'Override the playbook\'s target.product.',
+                    description: "Override the playbook's target.product.",
                 },
                 target_group: {
                     type: 'string',
-                    description: 'Override the playbook\'s target.group.',
+                    description: "Override the playbook's target.group.",
                 },
                 target_devices: {
                     type: 'array',
-                    description: 'Override the playbook\'s target.devices with an explicit list.',
+                    description: "Override the playbook's target.devices with an explicit list.",
                 },
                 concurrency: {
                     type: 'number',
@@ -187,7 +187,7 @@ Response carries a consolidated report: devices visited, ok / failed counts, and
                 fail_fast: {
                     type: 'boolean',
                     description:
-                        'Stop dequeueing new devices on the first failure (default: playbook\'s own value).',
+                        "Stop dequeueing new devices on the first failure (default: playbook's own value).",
                 },
                 continue_on_error: {
                     type: 'boolean',
@@ -196,8 +196,7 @@ Response carries a consolidated report: devices visited, ok / failed counts, and
                 },
                 vars: {
                     type: 'object',
-                    description:
-                        'Merge into the playbook\'s `vars` block before substitution.',
+                    description: "Merge into the playbook's `vars` block before substitution.",
                 },
                 user: {
                     type: 'string',

package/lib/mcp/tools-products.js

@@ -141,20 +141,14 @@ async function toolProductUpdate(args) {
 
     const fields = Object.keys(patch);
     if (fields.length === 0) {
-        throw inputError(
-            'at least one of name, description, enabled, icon must be provided',
-        );
+        throw inputError('at least one of name, description, enabled, icon must be provided');
     }
 
     await updateProduct(args.product, args.user, patch);
 
-    const summary = fields
-        .map((f) => (f === 'config' ? 'icon' : f))
-        .join(', ');
+    const summary = fields.map((f) => (f === 'config' ? 'icon' : f)).join(', ');
     return {
-        content: [
-            { type: 'text', text: `Updated product "${args.product}" (${summary}).` },
-        ],
+        content: [{ type: 'text', text: `Updated product "${args.product}" (${summary}).` }],
         isError: false,
     };
 }
@@ -430,7 +424,7 @@ async function toolProductPlaybookWrite(args) {
 async function toolProductPlaybookRun(args) {
     if (!args.product) throw inputError('product is required');
     if (!args.name) throw inputError('name is required');
-    if (!args.device) throw inputError('device is required (single-device only)');
+    if (!args.device_id) throw inputError('device is required (single-device only)');
 
     const entry = await findProductPlaybook(args.product, args.name, args.user);
     if (!entry) {
@@ -453,7 +447,7 @@ async function toolProductPlaybookRun(args) {
         throw inputError(err.message);
     }
 
-    pb.target.devices = [args.device];
+    pb.target.devices = [args.device_id];
     pb.target.product = args.product;
     pb.target.group = null;
 
@@ -463,7 +457,7 @@ async function toolProductPlaybookRun(args) {
             dry_run: true,
             product: args.product,
             name: args.name,
-            device: args.device,
+            device: args.device_id,
             variables: listVariables(pb),
             vars: resolvedScope,
             steps: plan,
@@ -475,11 +469,10 @@ async function toolProductPlaybookRun(args) {
     }
 
     const all = await getDevices({ product: args.product }, args.user);
-    const device =
-        all.find((d) => d.device === args.device) || {
-            device: args.device,
-            connection: { active: false },
-        };
+    const device = all.find((d) => d.device === args.device_id) || {
+        device: args.device_id,
+        connection: { active: false },
+    };
 
     const results = await runPlaybook(pb, [device], {
         user: args.user,
@@ -492,7 +485,7 @@ async function toolProductPlaybookRun(args) {
     const payload = {
         product: args.product,
         name: args.name,
-        device: args.device,
+        device: args.device_id,
         mode: args.check ? 'check' : 'apply',
         ok: !!result?.ok,
         result,
@@ -508,9 +501,7 @@ async function toolProductPlaybookRollout(args) {
     if (!args.name) throw inputError('name is required');
 
     const batchSize =
-        Number.isFinite(args.batch_size) && args.batch_size > 0
-            ? Math.floor(args.batch_size)
-            : 5;
+        Number.isFinite(args.batch_size) && args.batch_size > 0 ? Math.floor(args.batch_size) : 5;
     const failureThreshold =
         args.failure_threshold === undefined || args.failure_threshold === null
             ? DEFAULT_FAILURE_THRESHOLD
@@ -1455,9 +1446,10 @@ Pass \`dry_run: true\` to get the resolved plan without contacting the device. P
                     type: 'string',
                     description: 'Playbook name as registered in the product index.',
                 },
-                device: {
+                device_id: {
                     type: 'string',
-                    description: 'Target device ID (single-device only). Pick any device of the product.',
+                    description:
+                        'Target device ID (single-device only). Pick any device of the product.',
                 },
                 vars: {
                     type: 'object',
@@ -1477,7 +1469,7 @@ Pass \`dry_run: true\` to get the resolved plan without contacting the device. P
                 },
                 user: { type: 'string', description: 'API user (admin impersonation).' },
             },
-            required: ['product', 'name', 'device'],
+            required: ['product', 'name', 'device_id'],
         },
         handler: toolProductPlaybookRun,
     },

package/lib/mcp/tools-profile.js

@@ -401,7 +401,8 @@ Gotchas:
                 },
                 enabled: {
                     type: 'boolean',
-                    description: 'Default: true. Set to false to stage a definition without activating it.',
+                    description:
+                        'Default: true. Set to false to stage a definition without activating it.',
                 },
                 user: { type: 'string', description: 'API user.' },
             },

package/lib/mcp/tools-profiles.js

@@ -19,7 +19,7 @@ export const tools = [
     {
         name: 'thinr_profiles',
         description:
-            'List configured CLI profiles (each profile targets a different ThinRemote server). Use the returned profile name as the optional `profile` parameter on any other tool to target that environment for a single call.',
+            'List configured CLI profiles (each profile targets a different ThinRemote server). Use the returned profile name as the optional `profile` parameter on any other tool to target that environment for a single call.\n\nProfiles are not accounts. Every tool also takes an optional `user`, which addresses another account on the same server when the profile has admin rights — so a device belonging to `demo` is reached with `user: "demo"`, not by looking for a profile of that name.',
         inputSchema: {
             type: 'object',
             properties: {},

package/lib/mcp/tools-properties.js

@@ -3,7 +3,7 @@ import { getDeviceProperties, getDeviceProperty, setDeviceProperty } from '../pr
 import { inputError } from '../errors.js';
 
 async function toolPropertyGet(args) {
-    const device = args.device;
+    const device = args.device_id;
     if (!device)
         throw inputError('No device specified. Use thinr_devices to list available devices.');
     if (args.property) {
@@ -22,7 +22,7 @@ async function toolPropertyGet(args) {
 }
 
 async function toolPropertySet(args) {
-    const device = args.device;
+    const device = args.device_id;
     if (!device)
         throw inputError('No device specified. Use thinr_devices to list available devices.');
     if (!args.property) throw inputError('property is required');
@@ -51,10 +51,10 @@ export const tools = [
                     description:
                         'Property name. Omit to list the names of all properties on the device.',
                 },
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['device'],
+            required: ['device_id'],
         },
         handler: toolPropertyGet,
     },
@@ -69,10 +69,10 @@ export const tools = [
                     description:
                         'Any JSON-serialisable value (string, number, boolean, object, array).',
                 },
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['property', 'value', 'device'],
+            required: ['property', 'value', 'device_id'],
         },
         handler: toolPropertySet,
     },

package/lib/mcp/tools-resources.js

@@ -3,7 +3,7 @@ import { callDeviceResource, listDeviceResourcesWithSchemas } from '../resource.
 import { inputError } from '../errors.js';
 
 async function toolResourceList(args) {
-    const device = args.device;
+    const device = args.device_id;
     if (!device)
         throw inputError('No device specified. Use thinr_devices to list available devices.');
     const entries = await listDeviceResourcesWithSchemas(device, { user: args.user });
@@ -22,7 +22,7 @@ async function toolResourceList(args) {
 }
 
 async function toolResourceCall(args) {
-    const device = args.device;
+    const device = args.device_id;
     if (!device)
         throw inputError('No device specified. Use thinr_devices to list available devices.');
     if (!args.resource) throw inputError('resource is required');
@@ -47,10 +47,10 @@ export const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['device'],
+            required: ['device_id'],
         },
         handler: toolResourceList,
     },
@@ -68,10 +68,10 @@ export const tools = [
                     description:
                         'JSON object with the input parameters declared by the resource. Omit or pass {} for input-less resources.',
                 },
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['resource', 'device'],
+            required: ['resource', 'device_id'],
         },
         handler: toolResourceCall,
     },

package/lib/mcp/tools-scripts.js

@@ -1,10 +1,10 @@
 // @ts-check
-import { callDeviceResource, readDeviceResource } from '../resource.js';
+import { callDeviceResource, getDeviceResources, readDeviceResource } from '../resource.js';
 import { inputError } from '../errors.js';
 import { getAPI } from './helpers.js';
 
 async function toolScriptList(args) {
-    const device = args.device;
+    const device = args.device_id;
     if (!device)
         throw inputError('No device specified. Use thinr_devices to list available devices.');
     const info = await readDeviceResource(device, '$scripts/info', { user: args.user });
@@ -25,7 +25,7 @@ async function toolScriptList(args) {
 }
 
 async function toolScriptWrite(args) {
-    const device = args.device;
+    const device = args.device_id;
     if (!device)
         throw inputError('No device specified. Use thinr_devices to list available devices.');
     if (!args.name) throw inputError('name is required');
@@ -45,6 +45,27 @@ async function toolScriptWrite(args) {
     }
     const scriptPath = `${baseDir}/${args.name}`;
 
+    // The agent registers scripts at the root of the device's resource
+    // namespace, so a script named after a built-in resource replaces it and
+    // the device silently stops answering the real one. Refuse unless the
+    // caller says that is the intent. A name that already belongs to one of
+    // this device's own scripts is an update, not a collision.
+    const registeredName = args.name.replace(/\.[^./]+$/, '');
+    if (!args.force) {
+        const [native, current] = await Promise.all([
+            getDeviceResources(device, { user: args.user }).catch(() => ({})),
+            Promise.resolve(Array.isArray(info?.scripts) ? info.scripts : []),
+        ]);
+        const isOwnScript = current.some((s) => s.name === registeredName);
+        if (!isOwnScript && Object.prototype.hasOwnProperty.call(native, registeredName)) {
+            throw inputError(
+                `"${registeredName}" is already a resource on this device, and installing this ` +
+                    `script would replace it. Rename the script, or pass force: true if replacing ` +
+                    `it is what you want.`,
+            );
+        }
+    }
+
     await deviceApi.writeFile(scriptPath, args.content, true);
 
     const chmod = await deviceApi.exec(`chmod +x ${JSON.stringify(scriptPath)}`, 10);
@@ -53,9 +74,6 @@ async function toolScriptWrite(args) {
     }
 
     const reloaded = await callDeviceResource(device, '$scripts/reload', {}, { user: args.user });
-    // The agent registers resources by the file's stem, so "battery.sh"
-    // becomes scripts/battery. Match the same way to echo back the schema.
-    const registeredName = args.name.replace(/\.[^./]+$/, '');
     const found = Array.isArray(reloaded?.scripts)
         ? reloaded.scripts.find((s) => s.name === registeredName)
         : null;
@@ -76,7 +94,7 @@ async function toolScriptWrite(args) {
 }
 
 async function toolScriptDelete(args) {
-    const device = args.device;
+    const device = args.device_id;
     if (!device)
         throw inputError('No device specified. Use thinr_devices to list available devices.');
     if (!args.name) throw inputError('name is required');
@@ -90,7 +108,21 @@ async function toolScriptDelete(args) {
     if (!/^[A-Za-z0-9._-]+$/.test(args.name)) {
         throw inputError(`Invalid script name "${args.name}"`);
     }
-    const scriptPath = `${baseDir}/${args.name}`;
+
+    // Callers name a script either way round: `battery` as it appears in the
+    // resource list, or `battery.sh` as it sits on disk. Resolve against what
+    // the agent reports so both land on the same file, and say what is there
+    // when neither matches instead of letting a 404 through.
+    const scripts = Array.isArray(info?.scripts) ? info.scripts : [];
+    const stem = args.name.replace(/\.[^./]+$/, '');
+    const match = scripts.find((s) => s.name === stem || s.path?.endsWith(`/${args.name}`));
+    if (!match) {
+        const registered = scripts.map((s) => s.name).join(', ') || 'none';
+        throw inputError(
+            `No script named "${args.name}" on this device. Registered: ${registered}.`,
+        );
+    }
+    const scriptPath = match.path || `${baseDir}/${args.name}`;
 
     await deviceApi.delete(scriptPath, false);
     const reloaded = await callDeviceResource(device, '$scripts/reload', {}, { user: args.user });
@@ -99,7 +131,7 @@ async function toolScriptDelete(args) {
         content: [
             {
                 type: 'text',
-                text: `Removed script "${args.name}". ${remaining} script(s) remain registered.`,
+                text: `Removed script "${match.name}" (${scriptPath}). ${remaining} script(s) remain registered.`,
             },
         ],
         isError: false,
@@ -113,10 +145,10 @@ export const tools = [
         inputSchema: {
             type: 'object',
             properties: {
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['device'],
+            required: ['device_id'],
         },
         handler: toolScriptList,
     },
@@ -124,12 +156,15 @@ export const tools = [
         name: 'thinr_script_write',
         description: `Install or replace a custom script on the device and reload the scripts extension so the new resource is immediately callable.
 
-Scripts turn an ad-hoc operation into a reusable, typed, discoverable resource on the device. Prefer this over thinr_exec when you want to formalise a recurring task (read sensors, rotate a log, run a backup, collect a health report) so it becomes a persistent resource with an input/output schema that future tool calls can introspect and invoke via thinr_resource_call. A script named \`battery.sh\` is registered as the resource \`battery\` — collisions with native resources (e.g. \`monitoring\`, \`system\`) overwrite them, so pick a name that doesn't clash.
+Scripts turn an ad-hoc operation into a reusable, typed, discoverable resource on the device. Prefer this over thinr_exec when you want to formalise a recurring task (read sensors, rotate a log, run a backup, collect a health report) so it becomes a persistent resource with an input/output schema that future tool calls can introspect and invoke via thinr_resource_call. A script named \`battery.sh\` is registered as the resource \`battery\`. A name that already belongs to a built-in resource (\`monitoring\`, \`system\`, \`cmd\`, \`update\`, \`agent\`) would replace it and leave the device no longer answering the real one, so this tool refuses that unless you pass \`force: true\`.
+
+The script runs with the agent's privileges, which for a system install means root. Installing one grants permanent remote execution of that code on the device; treat it like adding a service, not like running a command.
 
 Script contract:
 - Must be executable code (any interpreter works — add a shebang like \`#!/bin/bash\` or \`#!/usr/bin/env python3\`).
 - When invoked with \`--describe\`, it should print a JSON object with \`input\` and/or \`output\` sample objects on stdout (e.g. \`{"input": {"path": ""}, "output": {"size": 0, "mtime": 0}}\`). These populate the resource's schema.
 - When invoked normally, the full input JSON object is passed on stdin; stdout is parsed as JSON. If stdout is a JSON object, its keys become the output fields; otherwise the value is exposed under \`output\`. Non-zero exit codes surface as errors.
+- Emit JSON that matches the \`--describe\` schema. Interpolating values you do not control (hostnames, command output, file contents) into a hand-built string breaks on the first quote or backslash; use \`jq\`, or \`python3 -c\` with \`json.dumps\` and the value passed through the environment. Output landing under \`output\` means the JSON was invalid, not that the raw form was accepted.
 
 This tool writes the script, makes it executable, and calls the agent's \`$scripts/reload\` so the change takes effect without restarting the agent.`,
         inputSchema: {
@@ -140,14 +175,19 @@ This tool writes the script, makes it executable, and calls the agent's \`$scrip
                     description:
                         'Script filename. The file extension (e.g. .sh, .py) is stripped to form the resource name, so battery.sh registers as the resource "battery".',
                 },
+                force: {
+                    type: 'boolean',
+                    description:
+                        "Install even when the resulting resource name replaces one of the device's built-in resources.",
+                },
                 content: {
                     type: 'string',
                     description: 'Full script source code, including shebang.',
                 },
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['name', 'content', 'device'],
+            required: ['name', 'content', 'device_id'],
         },
         handler: toolScriptWrite,
     },
@@ -162,10 +202,10 @@ This tool writes the script, makes it executable, and calls the agent's \`$scrip
                     description:
                         'Name of the script to remove (must match the file basename, without extension).',
                 },
-                device: { type: 'string', description: 'Device ID' },
+                device_id: { type: 'string', description: 'Device ID' },
                 user: { type: 'string', description: 'API user' },
             },
-            required: ['name', 'device'],
+            required: ['name', 'device_id'],
         },
         handler: toolScriptDelete,
     },

package/lib/mcp/tools-tokens.js

@@ -115,13 +115,11 @@ async function toolTokenDelete(args) {
 // ─── Device-level tokens ────────────────────────────────────────────
 
 async function toolDeviceTokenList(args) {
-    if (!args.device) throw inputError('device is required');
-    const tokens = await listDeviceTokens(args.device, args.user);
+    if (!args.device_id) throw inputError('device is required');
+    const tokens = await listDeviceTokens(args.device_id, args.user);
     if (tokens.length === 0) {
         return {
-            content: [
-                { type: 'text', text: `No device tokens on device "${args.device}".` },
-            ],
+            content: [{ type: 'text', text: `No device tokens on device "${args.device_id}".` }],
             isError: false,
         };
     }
@@ -129,7 +127,7 @@ async function toolDeviceTokenList(args) {
         content: [
             {
                 type: 'text',
-                text: `${tokens.length} device token(s) on "${args.device}":\n${JSON.stringify(tokens, null, 2)}`,
+                text: `${tokens.length} device token(s) on "${args.device_id}":\n${JSON.stringify(tokens, null, 2)}`,
             },
         ],
         isError: false,
@@ -137,11 +135,11 @@ async function toolDeviceTokenList(args) {
 }
 
 async function toolDeviceTokenCreate(args) {
-    if (!args.device) throw inputError('device is required');
+    if (!args.device_id) throw inputError('device is required');
     if (!args.token_name) throw inputError('token_name is required');
 
     const doc = await createDeviceToken(
-        args.device,
+        args.device_id,
         {
             token_name: args.token_name,
             token_resources: args.token_resources,
@@ -153,7 +151,7 @@ async function toolDeviceTokenCreate(args) {
         content: [
             {
                 type: 'text',
-                text: `Created device token "${args.token_name}" on "${args.device}".\n${JSON.stringify(doc, null, 2)}`,
+                text: `Created device token "${args.token_name}" on "${args.device_id}".\n${JSON.stringify(doc, null, 2)}`,
             },
         ],
         isError: false,
@@ -161,16 +159,16 @@ async function toolDeviceTokenCreate(args) {
 }
 
 async function toolDeviceTokenDelete(args) {
-    if (!args.device) throw inputError('device is required');
+    if (!args.device_id) throw inputError('device is required');
     if (!args.token_id) throw inputError('token_id is required');
-    const removed = await deleteDeviceToken(args.device, args.token_id, args.user);
+    const removed = await deleteDeviceToken(args.device_id, args.token_id, args.user);
     return {
         content: [
             {
                 type: 'text',
                 text: removed
-                    ? `Deleted device token "${args.token_id}" from "${args.device}".`
-                    : `Device token "${args.token_id}" was not configured on "${args.device}".`,
+                    ? `Deleted device token "${args.token_id}" from "${args.device_id}".`
+                    : `Device token "${args.token_id}" was not configured on "${args.device_id}".`,
             },
         ],
         isError: false,
@@ -318,10 +316,10 @@ ${EXPIRY_NOTE}`,
         inputSchema: {
             type: 'object',
             properties: {
-                device: { type: 'string', description: 'Device ID.' },
+                device_id: { type: 'string', description: 'Device ID.' },
                 user: { type: 'string', description: 'API user.' },
             },
-            required: ['device'],
+            required: ['device_id'],
         },
         handler: toolDeviceTokenList,
     },
@@ -336,7 +334,7 @@ Example: a token that lets a remote script call only the \`monitoring\` and \`re
         inputSchema: {
             type: 'object',
             properties: {
-                device: { type: 'string', description: 'Device ID.' },
+                device_id: { type: 'string', description: 'Device ID.' },
                 token_name: { type: 'string', description: 'Display name for the new token.' },
                 token_resources: {
                     type: 'array',
@@ -350,7 +348,7 @@ Example: a token that lets a remote script call only the \`monitoring\` and \`re
                 },
                 user: { type: 'string', description: 'API user.' },
             },
-            required: ['device', 'token_name'],
+            required: ['device_id', 'token_name'],
         },
         handler: toolDeviceTokenCreate,
     },
@@ -360,11 +358,11 @@ Example: a token that lets a remote script call only the \`monitoring\` and \`re
         inputSchema: {
             type: 'object',
             properties: {
-                device: { type: 'string', description: 'Device ID.' },
+                device_id: { type: 'string', description: 'Device ID.' },
                 token_id: { type: 'string', description: 'Token id to remove.' },
                 user: { type: 'string', description: 'API user.' },
             },
-            required: ['device', 'token_id'],
+            required: ['device_id', 'token_id'],
         },
         handler: toolDeviceTokenDelete,
     },

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@thinremote/thinr-cli",
-    "version": "1.3.2",
+    "version": "1.3.4",
     "description": "CLI for ThinRemote — remote management for IoT devices, with an MCP server for AI clients",
     "main": "bin/thinr.js",
     "bin": {