@tensor.chat/companion 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 tensor.chat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# @tensor.chat/companion
+
+Lets your tensor.chat AI use this machine: read and edit files in folders you share,
+run shell commands, and fetch web pages through your own internet connection.
+
+The daemon only ever connects **outbound** to tensor.chat over a WebSocket. Nothing
+listens on your machine, no port has to be opened.
+
+## Install and pair
+
+```
+npx @tensor.chat/companion pair
+```
+
+The command prints a code such as `AB3D-7KQ2`. In tensor.chat open
+**Settings → Companion devices → Pair a device** and enter it. Then keep the daemon
+running:
+
+```
+npx @tensor.chat/companion run
+```
+
+In any chat, switch **Agentic** on and check the computer under **Connected computers**.
+It then appears as the folder `Devices/<name>/` in that chat's file tree.
+
+## What the AI can do, and where
+
+- **Shared folders** are set in the device settings on tensor.chat. Read, Write, Edit,
+  Glob and Grep only work inside them. Paths outside, including symlinks that point
+  outside, are refused on this machine.
+- **Shell commands** stay in tensor.chat's server sandbox by default. Only when you switch
+  **Shell on the device** on for a chat does the AI get a shell on this machine: it runs
+  in the first shared folder with your own rights and full network, and it is not
+  sandboxed — that is the point of a companion device. Git Bash is used on Windows when
+  it is installed, PowerShell otherwise; `tensor-companion shell <path>` overrides it.
+  A long-running command can be started as a background job and looked at later.
+- **Fetch** downloads a page or file through your connection and hands the text to the AI.
+
+## Approval
+
+Every device has an approval mode, chosen on tensor.chat:
+
+| Mode | Behaviour |
+|---|---|
+| Safety check decides (default) | A small model sorts each action into allow / ask / block. Anything unclear blocks. |
+| Ask me every time | Every write, edit, shell command and fetch of a new site waits for your OK in the chat. |
+| Allow everything | No questions. Only for machines where nothing can go wrong. |
+
+Reads (Read, Glob, Grep) never ask. An approval request shows up in the chat on every
+device you are logged in on and expires after five minutes; a denied action comes back
+to the AI as a failed tool call.
+
+## Files
+
+- `~/.tensor-companion/config.json` holds the pairing token (mode 0600). `TENSOR_COMPANION_HOME`
+  moves the folder.
+- `tensor-companion status` shows the pairing, `tensor-companion unpair` forgets it.
+  Remove the device on tensor.chat as well — that is what actually revokes the token.
+
+## Server-side install (headless)
+
+The same package runs on any Linux box with Node 20+:
+
+```
+npm install -g @tensor.chat/companion
+tensor-companion pair --server https://tensor.chat
+tensor-companion run
+```
+
+Wrap `run` in a systemd unit or `nohup` to keep it alive. Remember: the AI then acts
+with the rights of the user the daemon runs as. Do not run it as root.

package/bin/tensor-companion.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+'use strict';
+// tensor-companion — pair this machine with your tensor.chat account and keep it
+// available for the AI. Commands: pair, run, status, shell, unpair.
+
+const os = require('os');
+const config = require('../src/config');
+const { createDaemon, VERSION } = require('../src/daemon');
+
+const args = process.argv.slice(2);
+const cmd = args[0] || 'help';
+
+function opt(name, fallback) {
+  const i = args.indexOf(name);
+  return i !== -1 && args[i + 1] ? args[i + 1] : fallback;
+}
+
+function out(s) { process.stdout.write(s + '\n'); }
+
+async function postJson(base, route, body) {
+  const res = await fetch(base.replace(/\/+$/, '') + route, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body || {}),
+  });
+  let data = null;
+  try { data = await res.json(); } catch (_) {}
+  if (!res.ok) throw new Error((data && data.error) || `HTTP ${res.status}`);
+  return data;
+}
+
+async function pair() {
+  const server = opt('--server', config.load().serverUrl || config.DEFAULT_SERVER);
+  const name = opt('--name', os.hostname());
+  const start = await postJson(server, '/api/companion/pair/start', { platform: process.platform, hostname: os.hostname() });
+  const pretty = start.code.slice(0, 4) + '-' + start.code.slice(4);
+  out('');
+  out(`  Pairing code:  ${pretty}`);
+  out('');
+  out(`  Open ${server} → Settings → Companion devices → "Pair a device" and enter the code.`);
+  out(`  This code expires in ${Math.round(start.expiresInSec / 60)} minutes.`);
+  out('');
+  const deadline = Date.now() + start.expiresInSec * 1000;
+  while (Date.now() < deadline) {
+    await new Promise((r) => setTimeout(r, 3000));
+    const poll = await postJson(server, '/api/companion/pair/poll', { pollSecret: start.pollSecret });
+    if (poll.status === 'confirmed') {
+      const cfg = { ...config.load(), serverUrl: server, token: poll.token, deviceId: poll.deviceId, name: poll.name || name };
+      config.save(cfg);
+      out(`  Paired as "${cfg.name}". Config saved to ${config.configPath()}`);
+      out('  Start the daemon with: npx @tensor.chat/companion run');
+      return;
+    }
+    if (poll.status === 'expired') break;
+  }
+  throw new Error('the pairing code expired — run "npx @tensor.chat/companion pair" again');
+}
+
+function run() {
+  const cfg = config.load();
+  if (!cfg.token || !cfg.serverUrl) throw new Error('not paired yet — run "npx @tensor.chat/companion pair" first');
+  const stamp = () => new Date().toISOString().slice(11, 19);
+  const daemon = createDaemon({ serverUrl: cfg.serverUrl, token: cfg.token, shell: cfg.shell, log: (m) => out(`[${stamp()}] ${m}`) });
+  daemon.events.on('welcome', (w) => out(`[${stamp()}] ready as "${w.name || cfg.name}" (device ${w.deviceId})`));
+  daemon.events.on('config', (c) => {
+    const bad = c.roots.filter((r) => !r.ok);
+    out(`[${stamp()}] mode=${c.mode} shared folders: ${c.roots.length ? c.roots.map((r) => r.path + (r.ok ? '' : ` (${r.error})`)).join(', ') : '(none yet — add one in the device settings)'}`);
+    if (bad.length) out(`[${stamp()}] ${bad.length} shared folder(s) are not usable on this machine`);
+  });
+  daemon.events.on('call', (c) => out(`[${stamp()}] ${c.tool}: ${summarize(c.args)}`));
+  daemon.events.on('approval', (a) => out(`[${stamp()}] approval requested for ${a.tool}: ${a.summary || ''} — answer it in the chat`));
+  daemon.events.on('unauthorized', () => { out('the server rejected this device — pair again with "npx @tensor.chat/companion pair"'); process.exit(2); });
+  daemon.events.on('removed', () => { out('this device was removed in the account settings — exiting'); process.exit(3); });
+  daemon.start();
+  const stop = () => { daemon.stop(); setTimeout(() => process.exit(0), 200); };
+  process.on('SIGINT', stop);
+  process.on('SIGTERM', stop);
+}
+
+function summarize(a) {
+  if (!a || typeof a !== 'object') return '';
+  const s = a.command || a.path || a.pattern || a.url || '';
+  return String(s).replace(/\s+/g, ' ').slice(0, 100);
+}
+
+function status() {
+  const cfg = config.load();
+  out(`tensor-companion ${VERSION}`);
+  out(`config: ${config.configPath()}`);
+  out(`server: ${cfg.serverUrl || '(not paired)'}`);
+  out(`device: ${cfg.deviceId || '(not paired)'} ${cfg.name ? '"' + cfg.name + '"' : ''}`);
+  out(`shell:  ${cfg.shell || '(auto)'}`);
+}
+
+function shell() {
+  const cfg = config.load();
+  const value = args[1];
+  if (!value) throw new Error('usage: tensor-companion shell <path-to-shell|auto>');
+  if (value === 'auto') delete cfg.shell; else cfg.shell = value;
+  config.save(cfg);
+  out(`shell set to ${cfg.shell || '(auto)'}`);
+}
+
+function unpair() {
+  const cfg = config.load();
+  delete cfg.token;
+  delete cfg.deviceId;
+  config.save(cfg);
+  out('local pairing removed — also remove the device in the account settings');
+}
+
+function help() {
+  out(`tensor-companion ${VERSION}
+
+  tensor-companion pair [--server URL] [--name NAME]   pair this machine with your account
+  tensor-companion run                                 stay connected and run tools for the AI
+  tensor-companion status                              show the current pairing
+  tensor-companion shell <path|auto>                   choose the shell Bash commands run in
+  tensor-companion unpair                              forget the local pairing`);
+}
+
+(async () => {
+  try {
+    if (cmd === 'pair') await pair();
+    else if (cmd === 'run') run();
+    else if (cmd === 'status') status();
+    else if (cmd === 'shell') shell();
+    else if (cmd === 'unpair') unpair();
+    else help();
+  } catch (e) {
+    process.stderr.write(`error: ${e.message}\n`);
+    process.exit(1);
+  }
+})();

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@tensor.chat/companion",
+  "version": "0.1.0",
+  "description": "Lets your tensor.chat AI use this machine: files, shell and internet through your own connection.",
+  "license": "MIT",
+  "homepage": "https://tensor.chat",
+  "keywords": [
+    "tensor.chat",
+    "ai",
+    "companion",
+    "agent",
+    "remote-tools"
+  ],
+  "bin": {
+    "tensor-companion": "bin/tensor-companion.js"
+  },
+  "main": "src/daemon.js",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node bin/tensor-companion.js run"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "ws": "^8.21.3"
+  }
+}

package/src/config.js

@@ -0,0 +1,36 @@
+'use strict';
+// Where the daemon keeps its pairing: ~/.tensor-companion/config.json (0600).
+// TENSOR_COMPANION_HOME overrides the folder so several daemons or tests can coexist.
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const DEFAULT_SERVER = 'https://tensor.chat';
+
+function homeDir() {
+  return process.env.TENSOR_COMPANION_HOME || path.join(os.homedir(), '.tensor-companion');
+}
+
+function configPath() {
+  return path.join(homeDir(), 'config.json');
+}
+
+function load() {
+  try {
+    const cfg = JSON.parse(fs.readFileSync(configPath(), 'utf8'));
+    return cfg && typeof cfg === 'object' ? cfg : {};
+  } catch (_) {
+    return {};
+  }
+}
+
+function save(cfg) {
+  const dir = homeDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const tmp = configPath() + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, configPath());
+}
+
+module.exports = { DEFAULT_SERVER, homeDir, configPath, load, save };

package/src/daemon.js

@@ -0,0 +1,249 @@
+'use strict';
+// The Companion daemon: one outbound WebSocket to tensor.chat, tools executed on this
+// machine on request. The server decides WHAT runs (approval mode, budgets); this
+// side decides WHERE (the shared folders) and enforces the output caps.
+
+const os = require('os');
+const path = require('path');
+const EventEmitter = require('events');
+const WebSocket = require('ws');
+const { Roots } = require('./paths');
+const bash = require('./tools/bash');
+const files = require('./tools/files');
+const { fetchUrl } = require('./tools/fetch');
+const { extractTouched } = require('./tools/touched');
+const { Jobs } = require('./tools/jobs');
+
+const VERSION = require('../package.json').version;
+const RECONNECT_MIN_MS = 1000;
+const RECONNECT_MAX_MS = 60000;
+const MAX_CONCURRENT_CALLS = 4;
+const BACKGROUND_FIRST_LOOK_MS = 1500; // a background start still reports the first lines
+const FOREGROUND_DEFAULT_MS = 600000;
+
+function wsUrlFor(serverUrl) {
+  const u = new URL(serverUrl);
+  u.protocol = u.protocol === 'http:' ? 'ws:' : 'wss:';
+  u.pathname = u.pathname.replace(/\/+$/, '') + '/api/companion/ws';
+  u.search = '';
+  u.hash = '';
+  return u.href;
+}
+
+function isRoot() {
+  try { return typeof process.getuid === 'function' && process.getuid() === 0; } catch (_) { return false; }
+}
+
+function systemInfo(shell) {
+  let username = null;
+  try { username = os.userInfo().username; } catch (_) {}
+  return {
+    t: 'hello',
+    platform: process.platform,
+    release: os.release(),
+    arch: process.arch,
+    hostname: os.hostname(),
+    username,
+    isRoot: isRoot(),
+    version: VERSION,
+    node: process.version,
+    shell: bash.shellFor(shell).cmd,
+    shellKind: bash.shellFor(shell).kind,
+    cwd: process.cwd(),
+  };
+}
+
+function createDaemon({ serverUrl, token, shell, log } = {}) {
+  if (!serverUrl || !token) throw new Error('serverUrl and token are required');
+  const emitter = new EventEmitter();
+  const say = typeof log === 'function' ? log : () => {};
+  const roots = new Roots([]);
+  const running = new Map(); // call id → AbortController
+  const jobs = new Jobs();
+  const unsentExits = []; // job endings the server has not heard yet (offline at the time)
+  const state = { connected: false, deviceId: null, name: null, mode: null, roots: [], labels: [], reconnectMs: RECONNECT_MIN_MS, stopped: false, ws: null, timer: null };
+
+  function send(msg) {
+    if (!state.ws || state.ws.readyState !== WebSocket.OPEN) return false;
+    try { state.ws.send(JSON.stringify(msg)); return true; } catch (_) { return false; }
+  }
+
+  function applyConfig(msg) {
+    state.roots = Array.isArray(msg.roots) ? msg.roots.map(String) : [];
+    state.labels = Array.isArray(msg.labels) ? msg.labels.map(String) : [];
+    state.mode = msg.mode || null;
+    state.name = msg.name || state.name;
+    roots.set(state.roots, state.labels);
+    send({ t: 'roots_status', roots: roots.status() });
+    emitter.emit('config', { roots: roots.status(), mode: state.mode, name: state.name });
+  }
+
+  async function runTool(tool, args, signal, timeoutMs) {
+    const a = args && typeof args === 'object' ? args : {};
+    switch (tool) {
+      case 'bash': {
+        const cwdRes = a.cwd ? roots.resolve(a.cwd) : null;
+        if (cwdRes && cwdRes.error) return { ok: false, text: `(cannot run there — ${cwdRes.error})` };
+        const cwd = cwdRes ? cwdRes.abs : roots.primary();
+        if (!cwd) return { ok: false, text: '(no shared folder is available on this device — the user has to add one in the device settings)' };
+        const job = jobs.start(String(a.command || ''), { cwd, shell });
+        // A cancelled call (turn aborted, server timeout) takes its foreground job with
+        // it; a background job belongs to the chat, not to the call, and lives on.
+        const onAbort = () => { if (!a.background) jobs.kill(job.id); };
+        if (signal) signal.addEventListener('abort', onAbort, { once: true });
+        // The server cancels a call at timeoutMs; answering a little earlier keeps the job
+        // alive as a background job instead of letting the cancel kill it.
+        const limit = timeoutMs || FOREGROUND_DEFAULT_MS;
+        const waitMs = a.background ? BACKGROUND_FIRST_LOOK_MS : Math.max(1000, limit - Math.min(5000, Math.floor(limit / 4)));
+        const ended = await jobs.wait(job, waitMs);
+        if (signal) signal.removeEventListener('abort', onAbort);
+        if (ended) {
+          const r = jobs.result(job);
+          r.touched = extractTouched(roots, a.command, r.stdout, r.stderr);
+          delete r.stdout;
+          delete r.stderr;
+          jobs.poll(job.id); // the one-shot result already carried every line
+          return r;
+        }
+        // Still running: it becomes (or already was) a background job.
+        const p = jobs.poll(job.id);
+        return { ok: true, running: true, jobId: job.id, text: p.text, exitCode: null, truncated: false, timedOut: false, touched: [] };
+      }
+      case 'job': {
+        const job = jobs.get(a.jobId);
+        if (!job) return { ok: false, text: '(no such job on this device — it may have been forgotten after many newer ones)' };
+        if (a.action === 'kill') {
+          jobs.kill(job.id);
+          await jobs.wait(job, 3000);
+        }
+        const p = jobs.poll(job.id);
+        return { ok: true, jobId: job.id, running: p.status === 'running', status: p.status, exitCode: p.exitCode, jobMs: p.ms, text: p.text, skipped: p.skipped };
+      }
+      case 'read': return files.read(roots, a.path, { lines: a.lines });
+      case 'write': return files.write(roots, a.path, a.content, { overwrite: a.overwrite === true });
+      case 'edit': return files.edit(roots, a.path, a.edits);
+      case 'glob': return files.glob(roots, a.pattern);
+      case 'grep': return files.grep(roots, a.command);
+      case 'ls': return files.ls(roots, a.path);
+      case 'fetchfile': return files.fetchfile(roots, a.path, { maxBytes: a.maxBytes });
+      case 'fetch': return fetchUrl(a.url, { signal });
+      default: return { ok: false, text: `(unknown tool "${tool}" on the companion device)` };
+    }
+  }
+
+  async function onCall(msg) {
+    const id = String(msg.id);
+    if (running.size >= MAX_CONCURRENT_CALLS) {
+      send({ t: 'result', id, ok: false, text: '(the companion device is busy with other calls — try again in a moment)' });
+      return;
+    }
+    const ctrl = new AbortController();
+    running.set(id, ctrl);
+    emitter.emit('call', { id, tool: msg.tool, args: msg.args });
+    let r;
+    try {
+      r = await runTool(String(msg.tool || ''), msg.args, ctrl.signal, Number(msg.timeoutMs) || undefined);
+    } catch (e) {
+      r = { ok: false, text: `(tool error on the companion device: ${e && e.message ? e.message : e})` };
+    }
+    running.delete(id);
+    send({ t: 'result', id, ...r });
+    emitter.emit('result', { id, tool: msg.tool, ok: r.ok });
+  }
+
+  function flushExits() {
+    while (unsentExits.length) {
+      const m = unsentExits[0];
+      if (!send(m)) return;
+      unsentExits.shift();
+    }
+  }
+  jobs.on('exit', (r) => {
+    const m = { t: 'job_exit', jobId: r.jobId, status: r.status, exitCode: r.exitCode, ms: r.ms, tail: r.tail };
+    unsentExits.push(m);
+    flushExits();
+    emitter.emit('job_exit', r);
+  });
+
+  function onMessage(data) {
+    let msg = null;
+    try { msg = JSON.parse(data.toString('utf8')); } catch (_) { return; }
+    if (!msg || typeof msg.t !== 'string') return;
+    switch (msg.t) {
+      case 'welcome':
+        state.deviceId = msg.deviceId || state.deviceId;
+        applyConfig(msg);
+        emitter.emit('welcome', { deviceId: state.deviceId, name: state.name });
+        break;
+      case 'config': applyConfig(msg); break;
+      case 'call': onCall(msg); break;
+      case 'cancel': { const c = running.get(String(msg.id)); if (c) c.abort(); break; }
+      case 'approval': emitter.emit('approval', msg); break;
+      case 'approval_resolved': emitter.emit('approval_resolved', msg); break;
+      default: break;
+    }
+  }
+
+  function scheduleReconnect() {
+    if (state.stopped || state.timer) return;
+    const wait = state.reconnectMs;
+    state.reconnectMs = Math.min(RECONNECT_MAX_MS, Math.round(state.reconnectMs * 2));
+    state.timer = setTimeout(() => { state.timer = null; connect(); }, wait);
+    say(`reconnecting in ${Math.round(wait / 1000)} s`);
+  }
+
+  function connect() {
+    if (state.stopped) return;
+    const url = wsUrlFor(serverUrl);
+    let ws;
+    try {
+      ws = new WebSocket(url, { headers: { authorization: `Bearer ${token}` }, handshakeTimeout: 15000 });
+    } catch (e) {
+      say(`connect failed: ${e.message}`);
+      scheduleReconnect();
+      return;
+    }
+    state.ws = ws;
+    ws.on('open', () => {
+      state.connected = true;
+      state.reconnectMs = RECONNECT_MIN_MS;
+      send(systemInfo(shell));
+      flushExits();
+      say(`connected to ${serverUrl}`);
+      emitter.emit('connected');
+    });
+    ws.on('message', onMessage);
+    ws.on('unexpected-response', (_req, res) => {
+      const code = res && res.statusCode;
+      say(`server refused the connection (HTTP ${code})`);
+      if (code === 401) { state.stopped = true; emitter.emit('unauthorized'); }
+    });
+    ws.on('error', (e) => { say(`socket error: ${e.message}`); });
+    ws.on('close', (code, reason) => {
+      const was = state.connected;
+      state.connected = false;
+      state.ws = null;
+      for (const c of running.values()) c.abort();
+      if (was) emitter.emit('disconnected', { code, reason: reason ? reason.toString() : '' });
+      if (code === 4002) { say('this device was removed on the server'); state.stopped = true; emitter.emit('removed'); return; }
+      scheduleReconnect();
+    });
+  }
+
+  return {
+    events: emitter,
+    state,
+    start() { state.stopped = false; connect(); return this; },
+    stop() {
+      state.stopped = true;
+      if (state.timer) { clearTimeout(state.timer); state.timer = null; }
+      for (const c of running.values()) c.abort();
+      jobs.killAll();
+      if (state.ws) { try { state.ws.close(1000, 'daemon stopped'); } catch (_) {} try { state.ws.terminate(); } catch (_) {} state.ws = null; }
+    },
+    replyApproval(approvalId, decision) { return send({ t: 'approval_reply', approvalId, decision }); },
+    jobs,
+  };
+}
+
+module.exports = { createDaemon, wsUrlFor, systemInfo, VERSION };

package/src/paths.js

@@ -0,0 +1,108 @@
+'use strict';
+// Shared folders ("roots") and the one rule every file tool obeys: a path is only
+// usable when its real location lies inside a shared folder. Symlinks are resolved
+// on the existing part of the path, so a link that points out of the folder is
+// refused the same way a ../ escape is.
+
+const fs = require('fs');
+const path = require('path');
+
+const WIN = process.platform === 'win32';
+const norm = (p) => (WIN ? String(p).toLowerCase() : String(p));
+
+function realpathOrNull(p) {
+  try { return fs.realpathSync.native(p); } catch (_) { return null; }
+}
+
+// Real path of the deepest existing ancestor, with the missing tail re-appended —
+// so a file that does not exist yet still resolves to where it would be created.
+function realExisting(abs) {
+  let cur = abs;
+  const tail = [];
+  for (;;) {
+    const rp = realpathOrNull(cur);
+    if (rp) return tail.length ? path.join(rp, ...tail.reverse()) : rp;
+    const parent = path.dirname(cur);
+    if (parent === cur) return null;
+    tail.push(path.basename(cur));
+    cur = parent;
+  }
+}
+
+function isInside(abs, root) {
+  const rel = path.relative(norm(root), norm(abs));
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+class Roots {
+  constructor(list, labels) { this.set(list, labels); }
+
+  // labels: the tree prefix per root (server-assigned, e.g. "Devices/Devbox/game");
+  // a root without one is shown by its absolute path.
+  set(list, labels) {
+    this.entries = [];
+    const ls = Array.isArray(labels) ? labels : [];
+    let i = -1;
+    for (const raw of Array.isArray(list) ? list : []) {
+      i++;
+      const abs = path.resolve(String(raw));
+      const real = realpathOrNull(abs);
+      let ok = false;
+      let error = null;
+      try {
+        ok = !!real && fs.statSync(real).isDirectory();
+        if (!ok) error = real ? 'not a folder' : 'does not exist';
+      } catch (e) {
+        error = e.code === 'ENOENT' ? 'does not exist' : e.message;
+      }
+      this.entries.push({ path: abs, real, ok, error, label: ls[i] ? String(ls[i]).replace(/\/+$/, '') : null });
+    }
+  }
+
+  status() { return this.entries.map((e) => ({ path: e.path, ok: e.ok, error: e.error })); }
+
+  okRoots() { return this.entries.filter((e) => e.ok); }
+
+  primary() { const r = this.okRoots()[0]; return r ? r.real : null; }
+
+  // {abs, root} for a usable path, {error} otherwise. Relative paths count from the
+  // first shared folder.
+  resolve(p) {
+    const roots = this.okRoots();
+    if (!roots.length) return { error: 'no shared folder is available on this device — the user has to add one in the device settings' };
+    const raw = String(p == null ? '' : p).trim().replace(/[\u0000-\u001f]/g, '');
+    if (!raw) return { error: 'empty path' };
+    const viaTree = this.fromTree(raw);
+    if (!viaTree && /^devices\//i.test(raw.replace(/\\/g, '/')) && roots.some((r) => r.label)) return { error: `"${raw}" is not one of this computer's shared folders (${roots.map((r) => r.label || r.path).join(', ')})` };
+    const abs = viaTree ? viaTree.abs : path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(roots[0].real, raw);
+    const real = realExisting(abs);
+    if (!real) return { error: 'invalid path' };
+    for (const r of roots) if (isInside(real, r.real)) return { abs: real, root: r.real };
+    return { error: `"${raw}" is outside the shared folders (${roots.map((r) => r.path).join(', ')})` };
+  }
+
+  // How a path is shown to the model: as its tree path (label + relative part) when
+  // the root has a label, else relative inside the first folder, else absolute.
+  display(abs) {
+    for (const r of this.okRoots()) {
+      if (!isInside(abs, r.real)) continue;
+      const rel = path.relative(r.real, abs).split(path.sep).join('/');
+      if (r.label) return rel ? r.label + '/' + rel : r.label;
+      if (r === this.okRoots()[0]) return rel || '.';
+    }
+    return abs;
+  }
+
+  // The root a tree path belongs to (by label) → {abs} for the file it names.
+  fromTree(treePath) {
+    const p = String(treePath == null ? '' : treePath).trim().replace(/\\/g, '/');
+    for (const r of this.okRoots()) {
+      if (!r.label) continue;
+      if (p === r.label) return { abs: r.real, root: r.real };
+      if (p.startsWith(r.label + '/')) return { abs: path.join(r.real, ...p.slice(r.label.length + 1).split('/').filter(Boolean)), root: r.real };
+    }
+    return null;
+  }
+}
+
+module.exports = { Roots, isInside, realExisting };

package/src/tools/bash.js

@@ -0,0 +1,76 @@
+'use strict';
+// Which shell a command runs in on this machine, how its process tree is ended and how
+// its result reads. jobs.js starts the process. Nothing here is a sandbox: a command runs
+// with the daemon's own rights, which is the whole point of a companion device. The
+// fences are elsewhere — the approval mode on the server and the output cap here.
+
+const { spawn } = require('child_process');
+const fs = require('fs');
+
+const OUTPUT_CAP = 64 * 1024;
+const WIN = process.platform === 'win32';
+
+// Git Bash when it is installed (any drive, PATH first), else PowerShell. The
+// System32 and WindowsApps bash.exe are WSL launchers with another filesystem.
+function findGitBash() {
+  const path = require('path');
+  const seen = new Set();
+  const candidates = [];
+  for (const dir of String(process.env.PATH || '').split(';')) {
+    if (!dir || /\\(System32|WindowsApps)\\?$/i.test(dir)) continue;
+    candidates.push(path.join(dir, 'bash.exe'));
+  }
+  const bases = [process.env.ProgramFiles, process.env['ProgramFiles(x86)'], process.env.LOCALAPPDATA && path.join(process.env.LOCALAPPDATA, 'Programs')];
+  for (const base of bases) {
+    if (base) candidates.push(path.join(base, 'Git', 'bin', 'bash.exe'), path.join(base, 'Git', 'usr', 'bin', 'bash.exe'));
+  }
+  for (const c of candidates) {
+    const key = c.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    if (fs.existsSync(c)) return c;
+  }
+  return null;
+}
+
+function defaultShell() {
+  if (WIN) {
+    const gitBash = findGitBash();
+    if (gitBash) return { cmd: gitBash, args: ['-c'], kind: 'bash' };
+    return { cmd: 'powershell.exe', args: ['-NoProfile', '-NonInteractive', '-Command'], kind: 'powershell' };
+  }
+  for (const c of ['/bin/bash', '/usr/bin/bash', '/bin/sh']) if (fs.existsSync(c)) return { cmd: c, args: ['-c'], kind: 'bash' };
+  return { cmd: 'sh', args: ['-c'], kind: 'sh' };
+}
+
+function shellFor(configured) {
+  if (configured) {
+    const isPs = /powershell|pwsh/i.test(configured);
+    return { cmd: configured, args: isPs ? ['-NoProfile', '-NonInteractive', '-Command'] : ['-c'], kind: isPs ? 'powershell' : 'bash' };
+  }
+  return defaultShell();
+}
+
+function killTree(child) {
+  if (!child.pid) return;
+  if (WIN) {
+    try { spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true }); } catch (_) {}
+    return;
+  }
+  try { process.kill(-child.pid, 'SIGKILL'); } catch (_) {
+    try { child.kill('SIGKILL'); } catch (_) {}
+  }
+}
+
+function formatResult(r) {
+  let text = r.stdout;
+  if (r.stderr) text += (text ? '\n' : '') + '--- stderr ---\n' + r.stderr;
+  const notes = [];
+  if (r.exitCode !== 0 && r.exitCode != null) notes.push(`exit ${r.exitCode}`);
+  if (r.timedOut) notes.push('command hit the time limit and was killed');
+  if (r.truncated) notes.push('output truncated to the size cap');
+  if (notes.length) text += (text ? '\n' : '') + `(${notes.join('; ')})`;
+  return text || '(no output)';
+}
+
+module.exports = { shellFor, defaultShell, formatResult, killTree, OUTPUT_CAP };

package/src/tools/fetch.js

@@ -0,0 +1,70 @@
+'use strict';
+// Fetches a URL through this machine's own internet connection and returns a text
+// view: HTML is reduced to its visible text, JSON is pretty-printed, everything else
+// is shown as text when it is text at all.
+
+const MAX_BYTES = 2 * 1024 * 1024;
+const MAX_CHARS = 50000;
+const TIMEOUT_MS = 20000;
+
+function htmlToText(html) {
+  return String(html)
+    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<noscript[\s\S]*?<\/noscript>/gi, ' ')
+    .replace(/<!--[\s\S]*?-->/g, ' ')
+    .replace(/<\s*(br|p|div|li|tr|h[1-6]|section|article|header|footer|pre|blockquote)[^>]*>/gi, '\n')
+    .replace(/<[^>]+>/g, ' ')
+    .replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'")
+    .replace(/[ \t]+/g, ' ')
+    .replace(/\n\s*\n\s*\n+/g, '\n\n')
+    .trim();
+}
+
+async function fetchUrl(rawUrl, { signal, timeoutMs } = {}) {
+  let url;
+  try { url = new URL(String(rawUrl || '').trim()); } catch (_) { return { ok: false, text: '(invalid URL)' }; }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return { ok: false, text: '(only http and https URLs can be fetched)' };
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs || TIMEOUT_MS);
+  const onAbort = () => ctrl.abort();
+  if (signal) signal.addEventListener('abort', onAbort, { once: true });
+  try {
+    const res = await fetch(url, {
+      signal: ctrl.signal,
+      redirect: 'follow',
+      headers: { 'user-agent': 'tensor-companion/0.1 (+https://tensor.chat)', accept: 'text/html,application/xhtml+xml,application/json,text/plain,*/*;q=0.8' },
+    });
+    const type = String(res.headers.get('content-type') || '').toLowerCase();
+    const reader = res.body ? res.body.getReader() : null;
+    const chunks = [];
+    let size = 0;
+    let truncated = false;
+    if (reader) {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        size += value.length;
+        if (size > MAX_BYTES) { chunks.push(value.subarray(0, value.length - (size - MAX_BYTES))); truncated = true; try { await reader.cancel(); } catch (_) {} break; }
+        chunks.push(value);
+      }
+    }
+    const buf = Buffer.concat(chunks.map((c) => Buffer.from(c)));
+    if (buf.includes(0) && !/text|json|xml|html|javascript/.test(type)) {
+      return { ok: true, text: `${url.href}\nHTTP ${res.status} ${type || 'unknown type'}\n(binary content, ${size} bytes — not shown)` };
+    }
+    let body = buf.toString('utf8');
+    if (/html/.test(type) || /^\s*<(!doctype|html)/i.test(body)) body = htmlToText(body);
+    else if (/json/.test(type)) { try { body = JSON.stringify(JSON.parse(body), null, 2); } catch (_) {} }
+    if (body.length > MAX_CHARS) { body = body.slice(0, MAX_CHARS) + `\n… [truncated to ${MAX_CHARS} chars]`; truncated = true; }
+    return { ok: res.ok, text: `${url.href}\nHTTP ${res.status} ${type || ''}${truncated ? ' (truncated)' : ''}\n\n${body}` };
+  } catch (e) {
+    const why = ctrl.signal.aborted ? 'timed out' : (e && e.cause && e.cause.code) || (e && e.message) || 'failed';
+    return { ok: false, text: `(fetch of ${url.href} ${why})` };
+  } finally {
+    clearTimeout(timer);
+    if (signal) signal.removeEventListener('abort', onAbort);
+  }
+}
+
+module.exports = { fetchUrl, htmlToText, MAX_BYTES, MAX_CHARS };

package/src/tools/files.js

@@ -0,0 +1,349 @@
+'use strict';
+// Read / Write / Edit / Glob / Grep inside the shared folders. The wording of results
+// mirrors the server's file tools so the model sees one dialect whether a file lives
+// on the server or on this machine.
+
+const fs = require('fs');
+const path = require('path');
+
+const READ_CHAR_CAP = 50000;
+const WRITE_CHAR_CAP = 200000;
+const GREP_FILE_MAX_BYTES = 2 * 1024 * 1024;
+const GREP_MAX_MATCHES = 200;
+const GREP_RESULT_CAP = 6000;
+const GLOB_MAX_RESULTS = 500;
+const GLOB_MAX_VISITED = 50000;
+const GLOB_MAX_DEPTH = 16;
+const SKIP_DIRS = new Set(['node_modules', '.git', '.hg', '.svn', '__pycache__', '.cache', '.idea', '.vs']);
+
+const TEXT_EXT = new Set([
+  '.txt', '.md', '.markdown', '.csv', '.tsv', '.json', '.jsonl', '.xml',
+  '.yml', '.yaml', '.html', '.htm', '.css', '.js', '.mjs', '.cjs', '.ts',
+  '.tsx', '.jsx', '.py', '.rb', '.sh', '.bat', '.ps1', '.sql', '.ini',
+  '.cfg', '.conf', '.toml', '.log', '.srt', '.vtt', '.tex', '.c', '.h',
+  '.cpp', '.hpp', '.cc', '.cs', '.java', '.kt', '.go', '.rs', '.php',
+  '.lua', '.swift', '.m', '.gradle', '.properties', '.env', '.gitignore',
+  '.dockerfile', '.vue', '.svelte', '.scss', '.less', '.graphql', '.proto',
+]);
+
+function isTextName(name) {
+  const ext = path.extname(name).toLowerCase();
+  return !ext || TEXT_EXT.has(ext);
+}
+
+const ok = (text, extra) => ({ ok: true, text, ...(extra || {}) });
+const err = (text, extra) => ({ ok: false, text, ...(extra || {}) });
+
+function parseLineRange(spec) {
+  if (spec == null || spec === '') return null;
+  const m = /^\s*(\d+)\s*(?:-\s*(\d+)?)?\s*$/.exec(String(spec));
+  if (!m) return null;
+  const from = Math.max(1, parseInt(m[1], 10));
+  const to = m[2] ? Math.max(from, parseInt(m[2], 10)) : (String(spec).includes('-') ? Infinity : from);
+  return { from, to };
+}
+
+function renderTextView(content, range, label) {
+  const lines = content.split('\n');
+  const total = lines.length;
+  if (range) {
+    const from = Math.min(range.from, total);
+    const to = Math.min(range.to, total);
+    const slice = lines.slice(from - 1, to).join('\n');
+    const head = `(lines ${from}-${to} of ${total}, ${label})\n`;
+    return head + (slice.length > READ_CHAR_CAP ? slice.slice(0, READ_CHAR_CAP) + `\n… [truncated to ${READ_CHAR_CAP} chars — read a smaller range]` : slice);
+  }
+  if (content.length <= READ_CHAR_CAP) return content;
+  let used = 0;
+  let n = 0;
+  while (n < total && used + lines[n].length + 1 <= READ_CHAR_CAP) { used += lines[n].length + 1; n++; }
+  return lines.slice(0, n).join('\n') + `\n… [showing lines 1-${n} of ${total} — read more with lines="${n + 1}-${Math.min(total, n + 400)}"]`;
+}
+
+function read(roots, p, { lines } = {}) {
+  const r = roots.resolve(p);
+  if (r.error) return err(`(cannot read "${p}" — ${r.error})`);
+  let st = null;
+  try { st = fs.statSync(r.abs); } catch (_) {}
+  if (!st) return err(`(no such file: ${roots.display(r.abs)} — run Glob for the live file tree)`);
+  if (st.isDirectory()) return err(`(${roots.display(r.abs)} is a folder — use Glob to list it)`);
+  const touched = [r.abs];
+  if (!isTextName(r.abs)) return err(`(binary file, ${st.size} bytes — only text files can be read on a companion device)`, { touched, bytes: st.size });
+  if (st.size > 20 * 1024 * 1024) return err(`(file too large to read: ${st.size} bytes)`, { touched, bytes: st.size });
+  const content = fs.readFileSync(r.abs, 'utf8');
+  if (content.includes('\u0000')) return err(`(binary file, ${st.size} bytes — only text files can be read on a companion device)`, { touched, bytes: st.size });
+  if (!content.length) return ok('(empty file)', { touched });
+  return ok(renderTextView(content, parseLineRange(lines), roots.display(r.abs)), { touched });
+}
+
+function write(roots, p, content, { overwrite } = {}) {
+  const raw = String(p == null ? '' : p);
+  const r = roots.resolve(raw);
+  if (r.error) return err(`(cannot write "${raw}" — ${r.error})`);
+  if (/[\\/]$/.test(raw.trim())) {
+    fs.mkdirSync(r.abs, { recursive: true });
+    return ok(`(folder ${roots.display(r.abs)}/ is ready)`);
+  }
+  if (!isTextName(r.abs)) return err(`(cannot write "${raw}" — text formats only)`);
+  const body = String(content == null ? '' : content);
+  if (body.length > WRITE_CHAR_CAP) return err(`(content too long — max ${WRITE_CHAR_CAP} chars per Write)`);
+  let exists = false;
+  try { exists = fs.statSync(r.abs).isFile(); } catch (_) {}
+  if (exists && !overwrite) return err(`(${roots.display(r.abs)} already exists — nothing was written)`, { exists: true });
+  fs.mkdirSync(path.dirname(r.abs), { recursive: true });
+  fs.writeFileSync(r.abs, body, 'utf8');
+  return ok(`(${exists ? 'overwrote' : 'wrote'} ${roots.display(r.abs)}: ${body.length} chars, ${body.split('\n').length} lines)`, { touched: [r.abs] });
+}
+
+function countOccurrences(haystack, needle) {
+  if (!needle) return 0;
+  let n = 0;
+  let i = -1;
+  while ((i = haystack.indexOf(needle, i + 1)) !== -1) n++;
+  return n;
+}
+
+function edit(roots, p, edits) {
+  const r = roots.resolve(p);
+  if (r.error) return err(`(cannot edit "${p}" — ${r.error})`);
+  let st = null;
+  try { st = fs.statSync(r.abs); } catch (_) {}
+  if (!st || !st.isFile()) return err(`(no such file: ${roots.display(r.abs)})`);
+  if (!isTextName(r.abs)) return err(`(cannot edit ${roots.display(r.abs)} — text files only)`);
+  if (!Array.isArray(edits) || !edits.length) return err('(no edits given)');
+  const original = fs.readFileSync(r.abs, 'utf8');
+  if (original.includes('\u0000')) return err(`(cannot edit ${roots.display(r.abs)} — binary content)`);
+  const eol = original.includes('\r\n') ? '\r\n' : '\n';
+  let next = original;
+  let i = 0;
+  for (const e of edits) {
+    i++;
+    const search = String(e && e.search != null ? e.search : '');
+    const replace = String(e && e.replace != null ? e.replace : '');
+    const searchN = eol === '\r\n' ? search.replace(/\r?\n/g, '\r\n') : search;
+    const replaceN = eol === '\r\n' ? replace.replace(/\r?\n/g, '\r\n') : replace;
+    if (!searchN) return err(`(edit ${i}: empty search text)`);
+    const n = countOccurrences(next, searchN);
+    if (n === 0) return err(`(edit ${i}: search text not found in ${roots.display(r.abs)} — Read the file and copy the current text exactly)`);
+    if (n > 1) return err(`(edit ${i}: search text occurs ${n} times in ${roots.display(r.abs)} — include more context so it is unique)`);
+    next = next.replace(searchN, () => replaceN);
+  }
+  fs.writeFileSync(r.abs, next, 'utf8');
+  return ok(`(edited ${roots.display(r.abs)}: ${edits.length} replacement${edits.length === 1 ? '' : 's'})`, { touched: [r.abs] });
+}
+
+function globToRegex(pattern) {
+  let re = '';
+  const p = String(pattern).replace(/\\/g, '/');
+  for (let i = 0; i < p.length; i++) {
+    const c = p[i];
+    if (c === '*') {
+      if (p[i + 1] === '*') {
+        i++;
+        if (p[i + 1] === '/') { i++; re += '(?:.*/)?'; } else re += '.*';
+      } else re += '[^/]*';
+    } else if (c === '?') re += '[^/]';
+    else re += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp('^' + re + '$', process.platform === 'win32' ? 'i' : '');
+}
+
+function walk(root, onEntry) {
+  let visited = 0;
+  const rec = (dir, depth) => {
+    if (depth > GLOB_MAX_DEPTH || visited > GLOB_MAX_VISITED) return;
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+    for (const e of entries) {
+      visited++;
+      if (visited > GLOB_MAX_VISITED) return;
+      const abs = path.join(dir, e.name);
+      if (e.isDirectory()) {
+        if (SKIP_DIRS.has(e.name)) continue;
+        onEntry(abs, true);
+        rec(abs, depth + 1);
+      } else if (e.isFile()) onEntry(abs, false);
+    }
+  };
+  rec(root, 0);
+  return visited;
+}
+
+// A pattern written as the tree shows it ("Devices/Devbox/game/**", or just the device
+// folder "Devices/Devbox/**") narrows to that shared folder and continues relative to
+// it; anything else is matched relative to every shared folder, as before.
+function splitTreePattern(okRoots, pattern) {
+  const p = pattern.replace(/\\/g, '/');
+  const low = p.toLowerCase();
+  for (const r of okRoots) {
+    if (!r.label) continue;
+    const parent = r.label.slice(0, r.label.lastIndexOf('/'));
+    for (const [prefix, only] of [[r.label, [r]], [parent, okRoots]]) {
+      if (!prefix) continue;
+      if (low === prefix.toLowerCase()) return { roots: only, pattern: '*' };
+      if (low.startsWith(prefix.toLowerCase() + '/')) return { roots: only, pattern: p.slice(prefix.length + 1) || '*' };
+    }
+  }
+  return { roots: okRoots, pattern: p };
+}
+
+function glob(roots, rawPattern) {
+  if (!roots.okRoots().length) return err('(no shared folder is available on this device — the user has to add one in the device settings)');
+  let pattern = String(rawPattern == null ? '*' : rawPattern).trim();
+  let sortByName = false;
+  let offset = 0;
+  pattern = pattern.replace(/\s+--sort=name\b/, () => { sortByName = true; return ''; })
+    .replace(/\s+--offset=(\d+)\b/, (_, n) => { offset = parseInt(n, 10) || 0; return ''; }).trim() || '*';
+  const scoped = splitTreePattern(roots.okRoots(), pattern);
+  const okRoots = scoped.roots;
+  pattern = scoped.pattern;
+  const all = pattern === '*' || pattern === '**' || pattern === '**/*';
+  const re = all ? null : globToRegex(pattern.replace(/^\.\//, ''));
+  const hits = [];
+  for (const root of okRoots) {
+    walk(root.real, (abs, isDir) => {
+      const rel = path.relative(root.real, abs).split(path.sep).join('/');
+      if (!all && !re.test(rel) && !re.test(path.basename(abs))) return;
+      let st = null;
+      try { st = fs.statSync(abs); } catch (_) { return; }
+      hits.push({ abs, isDir, mtime: st.mtimeMs, size: st.size, label: roots.display(abs) + (isDir ? '/' : '') });
+    });
+  }
+  hits.sort(sortByName ? (a, b) => a.label.localeCompare(b.label) : (a, b) => b.mtime - a.mtime);
+  const total = hits.length;
+  const page = hits.slice(offset, offset + GLOB_MAX_RESULTS);
+  const header = `(shared folders: ${okRoots.map((r) => r.label || r.path).join(', ')}; ${total} match${total === 1 ? '' : 'es'}${total > page.length + offset ? `, showing ${offset + 1}-${offset + page.length}, page on with --offset=${offset + page.length}` : ''})`;
+  if (!total) return ok(header + '\n(no matches)');
+  return ok(header + '\n' + page.map((h) => h.label).join('\n'));
+}
+
+function splitArgs(cmd) {
+  const out = [];
+  const re = /"((?:[^"\\]|\\.)*)"|'([^']*)'|(\S+)/g;
+  let m;
+  while ((m = re.exec(cmd))) out.push(m[1] != null ? m[1].replace(/\\(["\\])/g, '$1') : (m[2] != null ? m[2] : m[3]));
+  return out;
+}
+
+function grep(roots, command) {
+  const cmd = String(command == null ? '' : command).trim().replace(/^grep\s+/i, '');
+  if (/\|/.test(cmd)) return err('(pipes are not supported in Grep on a companion device — use Bash for that)');
+  const args = splitArgs(cmd);
+  const flags = { i: false, n: false, l: false, c: false, F: false, v: false };
+  let offset = 0;
+  const include = [];
+  const positional = [];
+  for (const a of args) {
+    if (/^--offset=\d+$/.test(a)) offset = parseInt(a.slice(9), 10);
+    else if (/^--include=/.test(a)) include.push(globToRegex(a.slice(10)));
+    else if (/^-[a-zA-Z]+$/.test(a)) {
+      for (const f of a.slice(1)) {
+        if (f in flags) flags[f] = true;
+        else if (f !== 'r' && f !== 'R' && f !== 'E' && f !== 'H') return err(`(unsupported grep flag -${f} — use Bash for the full grep)`);
+      }
+    } else positional.push(a);
+  }
+  if (!positional.length) return err('(grep needs a pattern)');
+  const patternRaw = positional.shift();
+  let re;
+  try { re = new RegExp(flags.F ? patternRaw.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') : patternRaw, flags.i ? 'i' : ''); } catch (e) { return err(`(invalid pattern: ${e.message})`); }
+  const targets = positional.length ? positional : ['.'];
+  const files = [];
+  for (const t of targets) {
+    const r = roots.resolve(t);
+    if (r.error) return err(`(cannot search "${t}" — ${r.error})`);
+    let st = null;
+    try { st = fs.statSync(r.abs); } catch (_) { return err(`(no such file or folder: ${t})`); }
+    if (st.isDirectory()) walk(r.abs, (abs, isDir) => { if (!isDir) files.push(abs); });
+    else files.push(r.abs);
+  }
+  const lines = [];
+  let matches = 0;
+  let filesWithHits = 0;
+  for (const abs of files) {
+    if (!isTextName(abs)) continue;
+    if (include.length && !include.some((x) => x.test(path.basename(abs)))) continue;
+    let st = null;
+    try { st = fs.statSync(abs); } catch (_) { continue; }
+    if (st.size > GREP_FILE_MAX_BYTES) continue;
+    let content = '';
+    try { content = fs.readFileSync(abs, 'utf8'); } catch (_) { continue; }
+    if (content.includes('\u0000')) continue;
+    const label = roots.display(abs);
+    let fileHits = 0;
+    const fileLines = content.split('\n');
+    for (let i = 0; i < fileLines.length; i++) {
+      const hit = re.test(fileLines[i]);
+      if (hit === flags.v) continue;
+      fileHits++;
+      matches++;
+      if (flags.l || flags.c) continue;
+      if (matches <= offset) continue;
+      if (lines.length < GREP_MAX_MATCHES) lines.push(`${label}${flags.n ? ':' + (i + 1) : ''}:${fileLines[i].length > 300 ? fileLines[i].slice(0, 300) + '…' : fileLines[i]}`);
+    }
+    if (fileHits) {
+      filesWithHits++;
+      if (flags.l) lines.push(label);
+      else if (flags.c) lines.push(`${label}:${fileHits}`);
+    }
+  }
+  if (!matches) return ok('(no matches)', { hits: 0 });
+  let text = lines.join('\n');
+  if (text.length > GREP_RESULT_CAP) text = text.slice(0, GREP_RESULT_CAP) + '\n… [truncated — narrow the pattern or page with --offset=N]';
+  const shown = flags.l || flags.c ? filesWithHits : Math.min(lines.length, GREP_MAX_MATCHES);
+  text += `\n(${matches} match${matches === 1 ? '' : 'es'} in ${filesWithHits} file${filesWithHits === 1 ? '' : 's'}${!flags.l && !flags.c && matches - offset > shown ? `, showing ${offset + 1}-${offset + shown}, page on with --offset=${offset + shown}` : ''})`;
+  return ok(text, { hits: matches });
+}
+
+// ---- Explorer + session copy (server-side mirror of what the AI touched) ----
+// `ls` feeds the browser's live tree of the shared folders; `fetchfile` hands the
+// server ONE small text file so it can keep a copy in the chat. Nothing walks the
+// whole tree here — the user's folders may hold terabytes.
+const LS_MAX_ENTRIES = 2000;
+const FETCH_MAX_BYTES_DEFAULT = 2 * 1024 * 1024;
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp']);
+
+function ls(roots, p) {
+  const okRoots = roots.okRoots();
+  const raw = String(p == null ? '' : p).trim();
+  if (!raw) {
+    return ok('', { entries: okRoots.map((r) => ({ name: r.label ? r.label.split('/').pop() : (path.basename(r.real) || r.real), path: r.real, dir: true, size: null, mtime: null })) });
+  }
+  const r = roots.resolve(raw);
+  if (r.error) return err(`(cannot list "${raw}" — ${r.error})`);
+  let names = [];
+  try { names = fs.readdirSync(r.abs, { withFileTypes: true }); } catch (e) {
+    return err(`(cannot list ${roots.display(r.abs)} — ${e.code === 'ENOENT' ? 'no such folder' : e.code === 'ENOTDIR' ? 'not a folder' : e.message})`);
+  }
+  const entries = [];
+  let truncated = false;
+  for (const d of names) {
+    if (entries.length >= LS_MAX_ENTRIES) { truncated = true; break; }
+    const abs = path.join(r.abs, d.name);
+    let st = null;
+    try { st = fs.statSync(abs); } catch (_) { continue; }
+    if (!st.isDirectory() && !st.isFile()) continue;
+    entries.push({ name: d.name, path: abs, dir: st.isDirectory(), size: st.isFile() ? st.size : null, mtime: Math.round(st.mtimeMs) });
+  }
+  entries.sort((a, b) => (a.dir === b.dir ? a.name.localeCompare(b.name) : a.dir ? -1 : 1));
+  return ok('', { entries, truncated });
+}
+
+function fetchfile(roots, p, { maxBytes } = {}) {
+  const cap = Number(maxBytes) > 0 ? Number(maxBytes) : FETCH_MAX_BYTES_DEFAULT;
+  const r = roots.resolve(p);
+  if (r.error) return err(`(cannot fetch "${p}" — ${r.error})`);
+  let st = null;
+  try { st = fs.statSync(r.abs); } catch (_) {}
+  if (!st || !st.isFile()) return err(`(no such file: ${roots.display(r.abs)})`);
+  if (st.size > cap) return err(`(file too large to copy: ${st.size} bytes, limit ${cap})`, { bytes: st.size, tooLarge: true });
+  if (IMAGE_EXT.has(path.extname(r.abs).toLowerCase())) {
+    return ok('', { base64: fs.readFileSync(r.abs).toString('base64'), bytes: st.size, mtime: Math.round(st.mtimeMs), binary: true });
+  }
+  if (!isTextName(r.abs)) return err(`(binary file, ${st.size} bytes — not copied)`, { bytes: st.size, binary: true });
+  const content = fs.readFileSync(r.abs, 'utf8');
+  if (content.includes('\u0000')) return err(`(binary file, ${st.size} bytes — not copied)`, { bytes: st.size, binary: true });
+  return ok('', { content, bytes: st.size, mtime: Math.round(st.mtimeMs) });
+}
+
+module.exports = { read, write, edit, glob, grep, ls, fetchfile, isTextName, parseLineRange, globToRegex, READ_CHAR_CAP, WRITE_CHAR_CAP, LS_MAX_ENTRIES, FETCH_MAX_BYTES_DEFAULT };

package/src/tools/jobs.js

@@ -0,0 +1,138 @@
+'use strict';
+// Shell commands as jobs. Every command starts as a job; a foreground call just waits
+// for it. A command that outlives its wait is NOT killed — it keeps running and the
+// caller gets its id, so a dev server or a long build survives the tool's time limit.
+// Output is kept in one ordered log (stdout and stderr interleaved) with a cursor per
+// job, so "what is new since I last looked" is a slice, never a re-read.
+
+const { spawn } = require('child_process');
+const EventEmitter = require('events');
+const { shellFor, killTree, formatResult, OUTPUT_CAP } = require('./bash');
+
+const LOG_CAP = 256 * 1024;   // per job, oldest output falls off the front
+const TAIL_CHARS = 4000;      // what an exit report carries along
+const MAX_JOBS = 32;          // finished jobs are forgotten first, running ones never
+
+class Jobs extends EventEmitter {
+  constructor() {
+    super();
+    this.jobs = new Map();
+    this.nextId = 1;
+  }
+
+  start(command, { cwd, shell } = {}) {
+    const sh = shellFor(shell);
+    const id = this.nextId++;
+    const job = {
+      id, command: String(command), startedAt: Date.now(), endedAt: null,
+      status: 'running', exitCode: null, killed: false,
+      stdout: '', stderr: '', log: '', dropped: 0, cursor: 0, truncated: false,
+      child: null, waiters: [],
+    };
+    this.forgetOld();
+    this.jobs.set(id, job);
+    try {
+      job.child = spawn(sh.cmd, [...sh.args, job.command], {
+        cwd: cwd || undefined,
+        detached: process.platform !== 'win32',
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: process.env,
+      });
+    } catch (e) {
+      this.finish(job, null, `(could not start the shell "${sh.cmd}": ${e.message})`);
+      return job;
+    }
+    const collect = (key) => (chunk) => {
+      const s = chunk.toString('utf8');
+      if (job[key].length < OUTPUT_CAP) {
+        job[key] += s.slice(0, OUTPUT_CAP - job[key].length);
+        if (job[key].length >= OUTPUT_CAP) job.truncated = true;
+      }
+      job.log += s;
+      if (job.log.length > LOG_CAP) {
+        const cut = job.log.length - LOG_CAP;
+        job.log = job.log.slice(cut);
+        job.dropped += cut;
+      }
+    };
+    job.child.stdout.on('data', collect('stdout'));
+    job.child.stderr.on('data', collect('stderr'));
+    job.child.on('error', (e) => this.finish(job, null, `(shell error: ${e.message})`));
+    job.child.on('close', (code, sig) => this.finish(job, code == null ? (sig ? 137 : null) : code));
+    return job;
+  }
+
+  finish(job, exitCode, errText) {
+    if (job.status !== 'running') return;
+    if (errText) { job.stderr += (job.stderr ? '\n' : '') + errText; job.log += (job.log ? '\n' : '') + errText; }
+    job.status = job.killed ? 'killed' : 'exited';
+    job.exitCode = exitCode;
+    job.endedAt = Date.now();
+    for (const w of job.waiters.splice(0)) w();
+    this.emit('exit', this.report(job));
+  }
+
+  // Resolves true when the job ended, false when the wait ran out first.
+  wait(job, ms) {
+    if (job.status !== 'running') return Promise.resolve(true);
+    return new Promise((resolve) => {
+      const timer = setTimeout(() => { job.waiters = job.waiters.filter((w) => w !== done); resolve(false); }, Math.max(0, ms));
+      const done = () => { clearTimeout(timer); resolve(true); };
+      job.waiters.push(done);
+    });
+  }
+
+  kill(id) {
+    const job = this.jobs.get(Number(id));
+    if (!job) return null;
+    if (job.status === 'running') {
+      job.killed = true;
+      killTree(job.child);
+    }
+    return job;
+  }
+
+  get(id) { return this.jobs.get(Number(id)) || null; }
+
+  // New output since the last look, plus the job's state. Advances the cursor.
+  poll(id) {
+    const job = this.get(id);
+    if (!job) return null;
+    const from = Math.max(0, job.cursor - job.dropped);
+    const text = job.log.slice(from);
+    const skipped = job.cursor < job.dropped ? job.dropped - job.cursor : 0;
+    job.cursor = job.dropped + job.log.length;
+    return { ...this.report(job), text, skipped };
+  }
+
+  report(job) {
+    return {
+      jobId: job.id, command: job.command, status: job.status, exitCode: job.exitCode,
+      ms: (job.endedAt || Date.now()) - job.startedAt,
+      tail: job.log.slice(-TAIL_CHARS),
+    };
+  }
+
+  // The one-shot result of a finished job, for a command that ran in the foreground.
+  result(job) {
+    const timedOut = false;
+    const r = { stdout: job.stdout, stderr: job.stderr, exitCode: job.exitCode, truncated: job.truncated, timedOut };
+    return { ok: job.status === 'exited' && job.exitCode === 0, text: formatResult(r), exitCode: job.exitCode, truncated: job.truncated, timedOut, stdout: job.stdout, stderr: job.stderr };
+  }
+
+  list() { return [...this.jobs.values()].map((j) => this.report(j)); }
+
+  running() { return [...this.jobs.values()].filter((j) => j.status === 'running'); }
+
+  forgetOld() {
+    if (this.jobs.size < MAX_JOBS) return;
+    for (const [id, j] of this.jobs) {
+      if (j.status !== 'running') { this.jobs.delete(id); if (this.jobs.size < MAX_JOBS) return; }
+    }
+  }
+
+  killAll() { for (const j of this.running()) this.kill(j.id); }
+}
+
+module.exports = { Jobs, LOG_CAP, TAIL_CHARS, MAX_JOBS };

package/src/tools/touched.js

@@ -0,0 +1,36 @@
+'use strict';
+// Which files did a shell command touch? Every path-looking token in the command and
+// its output that resolves to an existing file inside a shared folder counts. Not
+// every model uses the file tools, so `cat notes.md` must register the file too.
+
+const fs = require('fs');
+
+const MAX = 50;
+const TOKEN_RE = /(?:[A-Za-z]:\\[^\s"'<>|*?]+|\/[^\s"'<>|:*?]+|(?:\.{1,2}\/)?[\w.\-]+(?:[\\/][\w.\-]+)*\.[A-Za-z0-9]{1,8})/g;
+
+function extractTouched(roots, ...texts) {
+  const seen = new Set();
+  const out = [];
+  for (const text of texts) {
+    const s = String(text == null ? '' : text);
+    if (!s) continue;
+    let m;
+    TOKEN_RE.lastIndex = 0;
+    let scanned = 0;
+    while ((m = TOKEN_RE.exec(s)) && scanned++ < 2000) {
+      const tok = m[0].replace(/[.,;:)\]]+$/, '');
+      if (!tok || tok.length > 1024) continue;
+      const r = roots.resolve(tok);
+      if (r.error || seen.has(r.abs)) continue;
+      seen.add(r.abs);
+      let st = null;
+      try { st = fs.statSync(r.abs); } catch (_) { continue; }
+      if (!st.isFile()) continue;
+      out.push(r.abs);
+      if (out.length >= MAX) return out;
+    }
+  }
+  return out;
+}
+
+module.exports = { extractTouched, MAX };