@tensor.chat/companion 0.1.0 → 0.2.0

package/README.md

@@ -25,11 +25,15 @@ 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
+- **Shared folders** must be approved locally on the computer first with
+  `tensor-companion approve-folder <full-path>`. The website can request and display
+  folders, but it cannot grant itself access. Read, Write, Edit, Glob and Grep only
+  work inside locally approved folders. Paths outside, including symlinks that point
+  outside, are refused on this machine even if the server asks for them.
+- **Shell commands** stay in tensor.chat's server sandbox by default. Approve shell locally
+  for seven days with `tensor-companion approve-shell` (or supply another number of days);
+  the website cannot grant or extend shell access.
+  A chat must additionally have **Shell on the device** switched on. Commands then run
   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.

package/bin/tensor-companion.js

@@ -5,7 +5,9 @@
 
 const os = require('os');
 const config = require('../src/config');
+const pairing = require('../src/pairing');
 const { createDaemon, VERSION } = require('../src/daemon');
+const readline = require('readline/promises');
 
 const args = process.argv.slice(2);
 const cmd = args[0] || 'help';
@@ -17,22 +19,10 @@ function opt(name, 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 start = await pairing.start(server);
   const pretty = start.code.slice(0, 4) + '-' + start.code.slice(4);
   out('');
   out(`  Pairing code:  ${pretty}`);
@@ -40,27 +30,17 @@ async function pair() {
   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');
+  const cfg = await pairing.waitAndSave(server, start, { name });
+  if (!cfg) throw new Error('the pairing code expired — run "npx @tensor.chat/companion pair" again');
+  out(`  Paired as "${cfg.name}". Config saved to ${config.configPath()}`);
+  out('  Start the daemon with: npx @tensor.chat/companion run');
 }
 
 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}`) });
+  const daemon = createDaemon({ serverUrl: cfg.serverUrl, token: cfg.token, shell: cfg.shell, approvedRoots: () => config.approvedRoots(), approvedShell: () => config.shellApproved(), 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);
@@ -71,6 +51,7 @@ function run() {
   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.events.on('local_approval_request', (a) => out(`[${stamp()}] local approval requested: run npx @tensor.chat/companion allow ${a.code}`));
   daemon.start();
   const stop = () => { daemon.stop(); setTimeout(() => process.exit(0), 200); };
   process.on('SIGINT', stop);
@@ -102,13 +83,63 @@ function shell() {
 }
 
 function unpair() {
-  const cfg = config.load();
-  delete cfg.token;
-  delete cfg.deviceId;
-  config.save(cfg);
+  pairing.forget();
   out('local pairing removed — also remove the device in the account settings');
 }
 
+function approveFolder() {
+  const folder = args.slice(1).join(' ');
+  if (!folder) throw new Error('usage: tensor-companion approve-folder <full-path>');
+  const real = config.approveRoot(folder);
+  out(`Approved locally: ${real}`);
+}
+
+function revokeFolder() {
+  const folder = args.slice(1).join(' ');
+  if (!folder) throw new Error('usage: tensor-companion revoke-folder <full-path>');
+  out(config.revokeRoot(folder) ? `Local approval removed: ${folder}` : `No local approval matched: ${folder}`);
+}
+
+function folders() {
+  const roots = config.approvedRoots();
+  out(roots.length ? roots.map((r) => `  ${r}`).join('\n') : '  (no folders approved locally)');
+}
+
+function approveShell() {
+  const days = args[1] == null ? 7 : Number(args[1]);
+  const until = config.approveShell(days);
+  out(`Shell access approved locally until ${until}.`);
+}
+
+function revokeShell() {
+  config.revokeShell();
+  out('Local shell approval removed.');
+}
+
+async function deviceRequest(route, method = 'GET') {
+  const cfg = config.load();
+  if (!cfg.token || !cfg.serverUrl) throw new Error('not paired yet');
+  const res = await fetch(cfg.serverUrl.replace(/\/+$/, '') + route, { method, headers: { authorization: `Bearer ${cfg.token}`, 'content-type': 'application/json' } });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
+  return data;
+}
+
+async function allowRequest() {
+  const code = String(args[1] || '').replace(/[^A-Fa-f0-9]/g, '').toUpperCase();
+  if (!code) throw new Error('usage: tensor-companion allow <code>');
+  const { approval: a } = await deviceRequest(`/api/companion/local-approvals/${encodeURIComponent(code)}`);
+  const description = a.kind === 'folder' ? `folder "${a.path}"` : `shell access for ${a.days} day(s)`;
+  out(`Request: allow ${description} on this computer.`);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await rl.question('Approve locally? [y/N] ');
+  rl.close();
+  if (!/^y(?:es)?$/i.test(answer.trim())) { out('Not approved.'); return; }
+  if (a.kind === 'folder') config.approveRoot(a.path); else config.approveShell(a.days);
+  await deviceRequest(`/api/companion/local-approvals/${encodeURIComponent(code)}/complete`, 'POST');
+  out(`Approved locally: ${description}`);
+}
+
 function help() {
   out(`tensor-companion ${VERSION}
 
@@ -116,6 +147,12 @@ function help() {
   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 approve-folder <full-path>          allow this folder on this computer
+  tensor-companion revoke-folder <full-path>           remove a local folder approval
+  tensor-companion folders                             list locally approved folders
+  tensor-companion approve-shell [days]                allow remote shell locally (default: 7 days)
+  tensor-companion revoke-shell                        remove the local shell approval
+  tensor-companion allow <code>                        confirm a request shown by tensor.chat
   tensor-companion unpair                              forget the local pairing`);
 }
 
@@ -125,6 +162,12 @@ function help() {
     else if (cmd === 'run') run();
     else if (cmd === 'status') status();
     else if (cmd === 'shell') shell();
+    else if (cmd === 'approve-folder') approveFolder();
+    else if (cmd === 'revoke-folder') revokeFolder();
+    else if (cmd === 'folders') folders();
+    else if (cmd === 'approve-shell') approveShell();
+    else if (cmd === 'revoke-shell') revokeShell();
+    else if (cmd === 'allow') await allowRequest();
     else if (cmd === 'unpair') unpair();
     else help();
   } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tensor.chat/companion",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Lets your tensor.chat AI use this machine: files, shell and internet through your own connection.",
   "license": "MIT",
   "homepage": "https://tensor.chat",

package/src/config.js

@@ -33,4 +33,66 @@ function save(cfg) {
   fs.renameSync(tmp, configPath());
 }
 
-module.exports = { DEFAULT_SERVER, homeDir, configPath, load, save };
+function approvedRoots(cfg = load()) {
+  return Array.isArray(cfg.approvedRoots) ? cfg.approvedRoots.map(String) : [];
+}
+
+function shellApproved(cfg = load()) {
+  const until = Date.parse(String(cfg.shellApprovedUntil || ''));
+  return Number.isFinite(until) && until > Date.now();
+}
+
+function approveShell(days = 7) {
+  const n = Number(days);
+  if (!Number.isInteger(n) || n < 1 || n > 365) throw new Error('shell approval days must be an integer from 1 to 365');
+  const cfg = load();
+  cfg.shellApprovedUntil = new Date(Date.now() + n * 24 * 60 * 60 * 1000).toISOString();
+  save(cfg);
+  return cfg.shellApprovedUntil;
+}
+
+function revokeShell() {
+  const cfg = load();
+  delete cfg.shellApprovedUntil;
+  save(cfg);
+}
+
+function approveRoot(folder) {
+  const raw = expandHome(folder);
+  if (!raw) throw new Error('a folder path is required');
+  let real;
+  try {
+    real = fs.realpathSync.native(path.resolve(raw));
+    if (!fs.statSync(real).isDirectory()) throw new Error('not a folder');
+  } catch (e) {
+    throw new Error(`cannot approve "${raw}": ${e.message}`);
+  }
+  const cfg = load();
+  const roots = approvedRoots(cfg);
+  const key = process.platform === 'win32' ? real.toLowerCase() : real;
+  if (!roots.some((r) => (process.platform === 'win32' ? r.toLowerCase() : r) === key)) roots.push(real);
+  cfg.approvedRoots = roots;
+  save(cfg);
+  return real;
+}
+
+function revokeRoot(folder) {
+  const input = expandHome(folder);
+  let raw = path.resolve(input);
+  try { raw = fs.realpathSync.native(raw); } catch (_) {}
+  const cfg = load();
+  const key = process.platform === 'win32' ? raw.toLowerCase() : raw;
+  const before = approvedRoots(cfg);
+  cfg.approvedRoots = before.filter((r) => (process.platform === 'win32' ? path.resolve(r).toLowerCase() : path.resolve(r)) !== key);
+  save(cfg);
+  return before.length !== cfg.approvedRoots.length;
+}
+
+function expandHome(folder) {
+  const raw = String(folder || '').trim();
+  if (raw === '~') return os.homedir();
+  if (raw.startsWith('~/') || raw.startsWith('~\\')) return path.join(os.homedir(), raw.slice(2));
+  return raw;
+}
+
+module.exports = { DEFAULT_SERVER, homeDir, configPath, load, save, approvedRoots, approveRoot, revokeRoot, shellApproved, approveShell, revokeShell };

package/src/daemon.js

@@ -5,6 +5,7 @@
 
 const os = require('os');
 const path = require('path');
+const fs = require('fs');
 const EventEmitter = require('events');
 const WebSocket = require('ws');
 const { Roots } = require('./paths');
@@ -34,7 +35,7 @@ function isRoot() {
   try { return typeof process.getuid === 'function' && process.getuid() === 0; } catch (_) { return false; }
 }
 
-function systemInfo(shell) {
+function systemInfo(shell, localAuthority = false) {
   let username = null;
   try { username = os.userInfo().username; } catch (_) {}
   return {
@@ -50,14 +51,44 @@ function systemInfo(shell) {
     shell: bash.shellFor(shell).cmd,
     shellKind: bash.shellFor(shell).kind,
     cwd: process.cwd(),
+    localAuthority: localAuthority ? 1 : null,
   };
 }
 
-function createDaemon({ serverUrl, token, shell, log } = {}) {
+function authorizeRequestedRoots(requestedRoots, labels, approvedRoots) {
+  const requested = Array.isArray(requestedRoots) ? requestedRoots.map(String) : [];
+  const names = Array.isArray(labels) ? labels.map(String) : [];
+  const approved = (Array.isArray(approvedRoots) ? approvedRoots : []).map((r) => path.resolve(String(r)));
+  const norm = (p) => process.platform === 'win32' ? p.toLowerCase() : p;
+  const inside = (candidate, allowed) => {
+    const rel = path.relative(norm(allowed), norm(candidate));
+    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+  };
+  const roots = [];
+  const keptLabels = [];
+  const rejected = [];
+  requested.forEach((raw, i) => {
+    const abs = path.resolve(raw);
+    let real;
+    try { real = fs.realpathSync.native(abs); } catch (_) {
+      rejected.push({ path: abs, ok: false, error: 'folder does not exist on this computer' });
+      return;
+    }
+    if (approved.some((allow) => inside(real, allow))) {
+      roots.push(real);
+      keptLabels.push(names[i] || '');
+    } else rejected.push({ path: abs, ok: false, error: 'not approved on this computer' });
+  });
+  return { roots, labels: keptLabels, rejected };
+}
+
+function createDaemon({ serverUrl, token, shell, log, approvedRoots, approvedShell } = {}) {
   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 localApprovals = typeof approvedRoots === 'function' ? approvedRoots : null;
+  const localShellApproval = typeof approvedShell === 'function' ? approvedShell : null;
   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)
@@ -69,22 +100,26 @@ function createDaemon({ serverUrl, token, shell, log } = {}) {
   }
 
   function applyConfig(msg) {
-    state.roots = Array.isArray(msg.roots) ? msg.roots.map(String) : [];
-    state.labels = Array.isArray(msg.labels) ? msg.labels.map(String) : [];
+    const requested = Array.isArray(msg.roots) ? msg.roots.map(String) : [];
+    const labels = Array.isArray(msg.labels) ? msg.labels.map(String) : [];
+    const approved = localApprovals ? localApprovals() : [];
+    const authorized = authorizeRequestedRoots(requested, labels, approved);
+    state.roots = authorized.roots;
+    state.labels = authorized.labels;
     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 });
+    send({ t: 'roots_status', roots: [...roots.status(), ...authorized.rejected] });
+    emitter.emit('config', { roots: [...roots.status(), ...authorized.rejected], mode: state.mode, name: state.name });
   }
 
-  async function runTool(tool, args, signal, timeoutMs) {
+  async function runTool(tool, args, signal, timeoutMs, callRoots = roots) {
     const a = args && typeof args === 'object' ? args : {};
     switch (tool) {
       case 'bash': {
-        const cwdRes = a.cwd ? roots.resolve(a.cwd) : null;
+        const cwdRes = a.cwd ? callRoots.resolve(a.cwd) : null;
         if (cwdRes && cwdRes.error) return { ok: false, text: `(cannot run there — ${cwdRes.error})` };
-        const cwd = cwdRes ? cwdRes.abs : roots.primary();
+        const cwd = cwdRes ? cwdRes.abs : callRoots.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
@@ -99,7 +134,7 @@ function createDaemon({ serverUrl, token, shell, log } = {}) {
         if (signal) signal.removeEventListener('abort', onAbort);
         if (ended) {
           const r = jobs.result(job);
-          r.touched = extractTouched(roots, a.command, r.stdout, r.stderr);
+          r.touched = extractTouched(callRoots, a.command, r.stdout, r.stderr);
           delete r.stdout;
           delete r.stderr;
           jobs.poll(job.id); // the one-shot result already carried every line
@@ -119,13 +154,21 @@ function createDaemon({ serverUrl, token, shell, log } = {}) {
         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 'read': return files.read(callRoots, a.path, { lines: a.lines });
+      case 'write': return files.write(callRoots, a.path, a.content, { overwrite: a.overwrite === true });
+      case 'edit': return files.edit(callRoots, a.path, a.edits);
+      case 'glob': return files.glob(callRoots, a.pattern);
+      case 'grep': return files.grep(callRoots, a.command);
+      case 'ls': return files.ls(callRoots, a.path, { max: a.max });
+      case 'fetchfile': return files.fetchfile(callRoots, a.path, { maxBytes: a.maxBytes });
+      case 'fetchpart': return files.fetchpart(callRoots, a.path, { offset: a.offset, length: a.length });
+      // Das eingehaengte Laufwerk schreibt ueber diese vier zurueck. Sie stehen der KI
+      // NICHT offen - sie kommen nur aus dem Adapter, der das Laufwerk bedient.
+      case 'writepart': return files.writepart(callRoots, a.path, { offset: a.offset, base64: a.base64, truncate: a.truncate });
+      case 'mkdirpath': return files.mkdirpath(callRoots, a.path);
+      case 'removepath': return await files.removepath(callRoots, a.path, { endgueltig: a.endgueltig === true });
+      case 'renamepath': return files.renamepath(callRoots, a.from, a.to);
+      case 'statpath': return files.statpath(callRoots, a.path);
       case 'fetch': return fetchUrl(a.url, { signal });
       default: return { ok: false, text: `(unknown tool "${tool}" on the companion device)` };
     }
@@ -133,6 +176,13 @@ function createDaemon({ serverUrl, token, shell, log } = {}) {
 
   async function onCall(msg) {
     const id = String(msg.id);
+    const tool = String(msg.tool || '');
+    if ((tool === 'bash' || tool === 'job') && localShellApproval && !localShellApproval()) {
+      const r = { ok: false, text: '(shell access is not approved on this computer)' };
+      send({ t: 'result', id, ...r });
+      emitter.emit('result', { id, tool, ok: false });
+      return;
+    }
     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;
@@ -142,7 +192,13 @@ function createDaemon({ serverUrl, token, shell, log } = {}) {
     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);
+      let callRoots = roots;
+      if (Array.isArray(msg.roots)) {
+        const approved = localApprovals ? localApprovals() : [];
+        const scoped = authorizeRequestedRoots(msg.roots, msg.labels, approved);
+        callRoots = new Roots(scoped.roots, scoped.labels);
+      }
+      r = await runTool(tool, msg.args, ctrl.signal, Number(msg.timeoutMs) || undefined, callRoots);
     } catch (e) {
       r = { ok: false, text: `(tool error on the companion device: ${e && e.message ? e.message : e})` };
     }
@@ -180,6 +236,7 @@ function createDaemon({ serverUrl, token, shell, log } = {}) {
       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;
+      case 'local_approval_request': emitter.emit('local_approval_request', msg); break;
       default: break;
     }
   }
@@ -207,7 +264,7 @@ function createDaemon({ serverUrl, token, shell, log } = {}) {
     ws.on('open', () => {
       state.connected = true;
       state.reconnectMs = RECONNECT_MIN_MS;
-      send(systemInfo(shell));
+      send(systemInfo(shell, !!localApprovals && !!localShellApproval));
       flushExits();
       say(`connected to ${serverUrl}`);
       emitter.emit('connected');
@@ -246,4 +303,4 @@ function createDaemon({ serverUrl, token, shell, log } = {}) {
   };
 }
 
-module.exports = { createDaemon, wsUrlFor, systemInfo, VERSION };
+module.exports = { createDaemon, wsUrlFor, systemInfo, authorizeRequestedRoots, VERSION };

package/src/pairing.js

@@ -0,0 +1,65 @@
+'use strict';
+// Pairing this machine with an account: ask the server for a code, wait until a
+// signed-in user confirms it, keep the token. The command line shows the code to a
+// person; the desktop app hands it to its own signed-in page. Both walk these steps.
+
+const os = require('os');
+const config = require('./config');
+
+const POLL_MS = 3000;
+const REQUEST_TIMEOUT_MS = 30000;
+
+// `signal` has to reach fetch itself: a request that hangs in the network would
+// otherwise outlive the abort, and the pairing dialog would wait on it forever.
+async function postJson(base, route, body, signal, timeoutMs = REQUEST_TIMEOUT_MS) {
+  const limit = AbortSignal.timeout(timeoutMs);
+  const res = await fetch(base.replace(/\/+$/, '') + route, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body || {}),
+    signal: signal ? AbortSignal.any([signal, limit]) : limit,
+  });
+  let data = null;
+  try { data = await res.json(); } catch (_) {}
+  if (!res.ok) throw new Error((data && data.error) || `HTTP ${res.status}`);
+  return data;
+}
+
+function start(server) {
+  return postJson(server, '/api/companion/pair/start', { platform: process.platform, hostname: os.hostname() });
+}
+
+// Resolves with the saved config once the code is confirmed, or null when the code
+// expired or `signal` was aborted first.
+async function waitAndSave(server, started, { name, pollMs = POLL_MS, signal, timeoutMs = REQUEST_TIMEOUT_MS } = {}) {
+  const deadline = Date.now() + started.expiresInSec * 1000;
+  while (Date.now() < deadline && !(signal && signal.aborted)) {
+    await new Promise((r) => setTimeout(r, pollMs));
+    let poll;
+    try {
+      poll = await postJson(server, '/api/companion/pair/poll', { pollSecret: started.pollSecret }, signal, timeoutMs);
+    } catch (e) {
+      // A stop ends the wait. A request that ran out of time does not: the code is
+      // still good for as long as the server said, so the next turn asks again.
+      if (signal && signal.aborted) return null;
+      if (e && (e.name === 'AbortError' || e.name === 'TimeoutError')) continue;
+      throw e;
+    }
+    if (poll.status === 'confirmed') {
+      const cfg = { ...config.load(), serverUrl: server, token: poll.token, deviceId: poll.deviceId, name: poll.name || name || os.hostname() };
+      config.save(cfg);
+      return cfg;
+    }
+    if (poll.status === 'expired') return null;
+  }
+  return null;
+}
+
+function forget() {
+  const cfg = config.load();
+  delete cfg.token;
+  delete cfg.deviceId;
+  config.save(cfg);
+}
+
+module.exports = { start, waitAndSave, forget };

package/src/tools/files.js

@@ -300,10 +300,18 @@ function grep(roots, command) {
 // 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;
+// Der harte Deckel, den auch das Laufwerk nicht ueberschreitet: irgendwo muss die
+// Grenze liegen, sonst legt ein Ordner mit einer Million Eintraegen den Daemon
+// des Nutzers lahm.
+const LS_HARD_MAX = 100000;
 const FETCH_MAX_BYTES_DEFAULT = 2 * 1024 * 1024;
 const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp']);
 
-function ls(roots, p) {
+function ls(roots, p, { max } = {}) {
+  // Der Deckel ist fuer die KI da. Das eingehaengte Laufwerk fragt mit einem
+  // hoeheren, weil ein halb gelisteter Ordner dort schlimmer ist als ein langes
+  // Listing: ls` zeigt sonst weniger, als da ist, und niemand merkt es.
+  const deckel = Number(max) > 0 ? Math.min(Number(max), LS_HARD_MAX) : LS_MAX_ENTRIES;
   const okRoots = roots.okRoots();
   const raw = String(p == null ? '' : p).trim();
   if (!raw) {
@@ -318,7 +326,7 @@ function ls(roots, p) {
   const entries = [];
   let truncated = false;
   for (const d of names) {
-    if (entries.length >= LS_MAX_ENTRIES) { truncated = true; break; }
+    if (entries.length >= deckel) { truncated = true; break; }
     const abs = path.join(r.abs, d.name);
     let st = null;
     try { st = fs.statSync(abs); } catch (_) { continue; }
@@ -346,4 +354,154 @@ function fetchfile(roots, p, { maxBytes } = {}) {
   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 };
+// One slice of ANY file, for the server's on-demand materialisation. fetchfile above
+// answers "give me this small text file"; this one answers "give me bytes 0..N of
+// whatever this is", because a video the AI touched has to reach a classifier too and
+// no single WebSocket frame carries it. size+mtime come with every slice: the caller
+// notices a file that changed under it mid-transfer instead of writing a torn copy.
+const PART_MAX_BYTES = 1024 * 1024;
+
+function fetchpart(roots, p, { offset, length } = {}) {
+  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)})`);
+  const from = Math.max(0, Math.floor(Number(offset) || 0));
+  const want = Math.min(Number(length) > 0 ? Math.floor(Number(length)) : PART_MAX_BYTES, PART_MAX_BYTES);
+  const meta = { bytes: st.size, mtime: Math.round(st.mtimeMs), offset: from };
+  if (from >= st.size) return ok('', { ...meta, base64: '', read: 0, eof: true });
+  const buf = Buffer.alloc(Math.min(want, st.size - from));
+  let fd = null;
+  let read = 0;
+  try {
+    fd = fs.openSync(r.abs, 'r');
+    read = fs.readSync(fd, buf, 0, buf.length, from);
+  } catch (e) {
+    return err(`(cannot read ${roots.display(r.abs)} — ${e.message})`);
+  } finally {
+    if (fd != null) { try { fs.closeSync(fd); } catch (_) {} }
+  }
+  return ok('', { ...meta, base64: buf.subarray(0, read).toString('base64'), read, eof: from + read >= st.size });
+}
+
+// ---- Das Netzlaufwerk schreibt zurueck ------------------------------------
+//
+// fetchpart liest JEDE Datei in Scheiben; diese vier schreiben sie genauso. Sie
+// sind fuer das eingehaengte Laufwerk da, nicht fuer die KI: <Write> und <Edit>
+// bleiben auf Text beschraenkt, weil ein Modell, das eine Binaerdatei "bearbeitet",
+// sie kaputt macht. Ein Laufwerk dagegen muss alles koennen, was ein Laufwerk kann -
+// sonst laeuft ffmpeg ins Leere, sobald es seine Ausgabe schreiben will.
+
+// Eine Scheibe an ihren Platz. Zustandslos mit Absicht: jede Scheibe traegt ihren
+// eigenen Versatz, also kann eine verlorene Verbindung nichts halb Gemerktes
+// hinterlassen. offset 0 kuerzt die Datei - so faengt jedes Schreiben an.
+function writepart(roots, p, { offset, base64, truncate } = {}) {
+  const r = roots.resolve(p);
+  if (r.error) return err(`(cannot write "${p}" — ${r.error})`);
+  const from = Math.max(0, Math.floor(Number(offset) || 0));
+  const buf = Buffer.from(String(base64 || ''), 'base64');
+  if (buf.length > PART_MAX_BYTES) return err(`(slice too large: ${buf.length} bytes, limit ${PART_MAX_BYTES})`);
+  let fd = null;
+  try {
+    fs.mkdirSync(path.dirname(r.abs), { recursive: true });
+    // Erst oeffnen, dann entscheiden. Zwischen einem existsSync und dem Oeffnen
+    // passt ein fremder Schreibvorgang: legt jemand die Datei genau dort an,
+    // leerte sie das 'w' wieder. 'r+' scheitert sauber, wenn es sie nicht gibt.
+    try {
+      fd = fs.openSync(r.abs, 'r+');
+    } catch (e) {
+      if (e && e.code !== 'ENOENT') throw e;
+      fd = fs.openSync(r.abs, 'w');
+    }
+    if (truncate === true) fs.ftruncateSync(fd, from);
+    if (buf.length) fs.writeSync(fd, buf, 0, buf.length, from);
+  } catch (e) {
+    return err(`(cannot write ${roots.display(r.abs)} — ${e.message})`);
+  } finally {
+    if (fd != null) { try { fs.closeSync(fd); } catch (_) {} }
+  }
+  let st = null;
+  try { st = fs.statSync(r.abs); } catch (_) {}
+  return ok('', { bytes: st ? st.size : null, mtime: st ? Math.round(st.mtimeMs) : null, wrote: buf.length });
+}
+function mkdirpath(roots, p) {
+  const r = roots.resolve(p);
+  if (r.error) return err(`(cannot create "${p}" — ${r.error})`);
+  try { fs.mkdirSync(r.abs, { recursive: true }); }
+  catch (e) { return err(`(cannot create ${roots.display(r.abs)} — ${e.message})`); }
+  return ok('');
+}
+
+// Loeschen heisst loeschen - ein Laufwerk hat keinen Papierkorb. Ein Ordner geht nur
+// MIT Inhalt weg, sonst waere `rm -r` auf dem Laufwerk keine Loeschung, sondern ein
+// Fehler, und die Werkzeuge daran wuerden sich seltsam verhalten.
+// Loeschen heisst: in den Papierkorb des Rechners. Auf dem Server ist eine
+// geloeschte Datei ein Eintrag, den wir zurueckholen koennen; auf einer fremden
+// Platte gibt es das nicht - dort waere weg wirklich weg. Den Papierkorb kennt
+// der Nutzer, er weiss, wo er nachsieht, und er raeumt ihn selbst.
+//
+// `endgueltig` gibt es fuer den einen Fall, in dem ein Papierkorb keinen Sinn
+// ergibt: unsere eigenen Entwuerfe (.part), die beim Abbruch weggeraeumt werden.
+// Die sammelten sich dort sonst an, ohne dass sie je jemand vermisst haette.
+async function removepath(roots, p, { endgueltig = false } = {}) {
+  const r = roots.resolve(p);
+  if (r.error) return err(`(cannot delete "${p}" — ${r.error})`);
+  if (endgueltig) {
+    try { fs.rmSync(r.abs, { recursive: true, force: false }); }
+    catch (e) { return err(`(cannot delete ${roots.display(r.abs)} — ${e.code === 'ENOENT' ? 'no such file' : e.message})`); }
+    return ok('');
+  }
+  try { await require('./trash').inDenPapierkorb(r.abs); }
+  catch (e) {
+    // NICHT ersatzweise vernichten. Lieber eine Fehlermeldung als eine Datei,
+    // die der Nutzer nie wiedersieht.
+    const grund = e && e.code === 'ENOENT' ? 'no such file' : (e && e.message ? e.message : String(e));
+    return err(`(cannot move ${roots.display(r.abs)} to the recycle bin — ${grund})`);
+  }
+  return ok('', { inDenPapierkorb: true });
+}
+
+// Beide Seiten muessen im geteilten Ordner liegen: ein Verschieben ist sonst ein
+// Weg hinaus, an dem der Zaun nichts merkt.
+// Ein einzelnes Nachsehen. Das Laufwerk fragt danach fuer jede Datei, die es
+// anfasst; ueber ein Verzeichnislisting waere das je Frage ein Gang durch den
+// ganzen Ordner - und der Ordner koennte 20 000 Eintraege haben.
+function statpath(roots, p) {
+  const r = roots.resolve(p);
+  if (r.error) return err(`(cannot stat "${p}" — ${r.error})`);
+  let st = null;
+  try { st = fs.lstatSync(r.abs); } catch (_) { st = null; }
+  if (!st) return err(`(no such file: ${roots.display(r.abs)})`);
+  // Eine Verknuepfung wird als das gemeldet, worauf sie zeigt - so sieht sie jedes
+  // andere Werkzeug auf diesem Rechner auch. Zeigt sie ins Leere, bleibt sie, was
+  // sie ist: nichts Lesbares.
+  if (st.isSymbolicLink()) {
+    try { st = fs.statSync(r.abs); } catch (_) { return err(`(broken link: ${roots.display(r.abs)})`); }
+  }
+  return ok('', { dir: st.isDirectory(), bytes: st.size, mtime: Math.round(st.mtimeMs) });
+}
+
+function renamepath(roots, from, to) {
+  const a = roots.resolve(from);
+  if (a.error) return err(`(cannot move "${from}" — ${a.error})`);
+  const b = roots.resolve(to);
+  if (b.error) return err(`(cannot move to "${to}" — ${b.error})`);
+  try {
+    fs.mkdirSync(path.dirname(b.abs), { recursive: true });
+    fs.renameSync(a.abs, b.abs);
+  } catch (e) {
+    // Die Quelle ist weg und das Ziel ist da: dann ist genau das passiert, was
+    // erreicht werden sollte - nur die Antwort ging verloren, und der Aufruf kam
+    // ein zweites Mal. Das als Fehler zu melden, hiesse den Aufrufer anzuluegen
+    // ueber eine Datei, die laengst an ihrem Platz liegt.
+    if (e && e.code === 'ENOENT' && fs.existsSync(b.abs)) return ok('', { schonDa: true });
+    return err(`(cannot move ${roots.display(a.abs)} — ${e.message})`);
+  }
+  return ok('');
+}
+
+module.exports = {
+  statpath,
+  fetchpart, writepart, mkdirpath, removepath, renamepath,
+  PART_MAX_BYTES, 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/trash.js

@@ -0,0 +1,189 @@
+'use strict';
+// Loeschen heisst hier: in den Papierkorb des Rechners, nicht ins Nichts.
+//
+// Auf dem Server ist eine geloeschte Datei ein Eintrag in unserer Datenbank, den
+// wir zurueckholen koennen. Auf dem Rechner des Nutzers gibt es das nicht - dort
+// ist weg wirklich weg. Der Rechner hat aber seinen eigenen Papierkorb, und den
+// kennt der Nutzer: er weiss, wo er nachsehen muss, und er raeumt ihn selbst.
+//
+// Jedes System macht das anders, und zwar wirklich anders - nicht nur mit einem
+// anderen Ordnernamen:
+//   Windows  hat einen Papierkorb, in den nur die Shell einsortieren kann.
+//   macOS    hat ~/.Trash, ein gewoehnlicher Ordner.
+//   Linux    hat die freedesktop-Ablage: Datei nach files/, und daneben eine
+//            .trashinfo mit Herkunft und Zeit, sonst weiss der Dateimanager
+//            beim Zuruecklegen nicht, wohin.
+//
+// Geht das Einsortieren nicht, wird NICHT ersatzweise vernichtet. Lieber eine
+// Fehlermeldung als eine Datei, die der Nutzer nie wiedersieht.
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFile } = require('child_process');
+
+// Ein Name, den es im Zielordner noch nicht gibt. Zwei gleichnamige Dateien aus
+// zwei Ordnern landen sonst uebereinander, und die erste waere doch weg.
+const NUMMERN_BIS = 50;
+
+function freierName(ordner, name) {
+  let ziel = path.join(ordner, name);
+  if (!fs.existsSync(ziel)) return ziel;
+  const ext = path.extname(name);
+  const stamm = path.basename(name, ext);
+  // Erst durchnummerieren: "bericht.1.txt" liest sich im Papierkorb, ein Zufall
+  // nicht. Nach ein paar Dutzend ist die Lesbarkeit ohnehin dahin, und dann
+  // zaehlt nur noch, dass ein Name frei ist.
+  for (let i = 1; i <= NUMMERN_BIS; i++) {
+    ziel = path.join(ordner, `${stamm}.${i}${ext}`);
+    if (!fs.existsSync(ziel)) return ziel;
+  }
+  for (;;) {
+    ziel = path.join(ordner, `${stamm}.${require('crypto').randomBytes(4).toString('hex')}${ext}`);
+    if (!fs.existsSync(ziel)) return ziel;
+  }
+}
+
+// Ein Verschieben, das auch ueber Dateisystemgrenzen hinweg geht. rename schafft
+// das nicht - und der Papierkorb liegt oft auf einer anderen Platte als die Datei.
+// Kopieren und dann erst wegnehmen. Die Reihenfolge ist die ganze Vorsicht: ein
+// Abbruch dazwischen laesst eine Kopie zu viel zurueck, nie eine zu wenig.
+function kopiereUndLoesche(von, nach) {
+  fs.cpSync(von, nach, { recursive: true, errorOnExist: true, force: false });
+  fs.rmSync(von, { recursive: true, force: false });
+}
+
+function verschiebe(von, nach) {
+  try {
+    fs.renameSync(von, nach);
+    return;
+  } catch (e) {
+    // Der Papierkorb liegt oft auf einer anderen Platte als die Datei, und ueber
+    // Dateisystemgrenzen hinweg kann rename nichts ausrichten.
+    if (!e || (e.code !== 'EXDEV' && e.code !== 'EPERM')) throw e;
+  }
+  // coverage:host-only Hierhin kommt nur, wer wirklich ueber eine
+  // Dateisystemgrenze verschiebt. Auf einer Kiste mit einem einzigen Dateisystem
+  // kann KEIN Test das ausloesen - rename gelingt dort immer. Was hier passiert,
+  // ist einzeln geprueft: kopiereUndLoesche in tests/_trash.js.
+  kopiereUndLoesche(von, nach);
+  // coverage:host-only-end
+}
+
+// --- Linux: die freedesktop-Ablage -----------------------------------------
+//
+// Ohne die .trashinfo daneben zeigt der Dateimanager den Eintrag zwar an, kann
+// ihn aber nicht zuruecklegen - er weiss nicht, wo er herkam.
+function linuxPapierkorb(abs) {
+  const heim = process.env.XDG_DATA_HOME || path.join(os.homedir(), '.local', 'share');
+  const korb = path.join(heim, 'Trash');
+  const dateien = path.join(korb, 'files');
+  const infos = path.join(korb, 'info');
+  fs.mkdirSync(dateien, { recursive: true, mode: 0o700 });
+  fs.mkdirSync(infos, { recursive: true, mode: 0o700 });
+
+  const ziel = freierName(dateien, path.basename(abs));
+  const info = path.join(infos, path.basename(ziel) + '.trashinfo');
+  // Die Zeit in der Ortszeit des Rechners, ohne Zone - so will es die Spezifikation.
+  const jetzt = new Date();
+  const zz = (n) => String(n).padStart(2, '0');
+  const stempel = `${jetzt.getFullYear()}-${zz(jetzt.getMonth() + 1)}-${zz(jetzt.getDate())}T`
+    + `${zz(jetzt.getHours())}:${zz(jetzt.getMinutes())}:${zz(jetzt.getSeconds())}`;
+  // Der Pfad wird URL-kodiert, aber die Trenner bleiben Trenner.
+  const pfad = abs.split('/').map((s) => encodeURIComponent(s)).join('/');
+
+  // Erst die Notiz, dann die Datei: bricht es dazwischen ab, liegt eine Notiz
+  // ohne Datei herum (harmlos) statt einer Datei ohne Herkunft (nicht mehr
+  // zurueckzulegen).
+  fs.writeFileSync(info, `[Trash Info]\nPath=${pfad}\nDeletionDate=${stempel}\n`, { mode: 0o600 });
+  try {
+    verschiebe(abs, ziel);
+  } catch (e) {
+    try { fs.unlinkSync(info); } catch (_) {}
+    throw e;
+  }
+  return ziel;
+}
+
+// --- macOS: ein ganz gewoehnlicher Ordner ----------------------------------
+// coverage:host-only Jeder Weg hier laeuft nur auf SEINEM System, und ein Lauf
+// kann hoechstens einen davon nehmen. Der Windows-Weg WIRD auf einem
+// Windows-Rechner wirklich gefahren (tests/_trash.js legt dort zwei Dateien in
+// den echten Papierkorb, eine davon mit Leerzeichen und & im Namen) - genau dort
+// sass auch der Fehler, den ein Pruefer am 21.09.2026 vermutet und eine Messung
+// bestaetigt hat. Die beiden anderen sind ueber ihre Bestandteile geprueft:
+// freierName und verschiebe, und der eingestellte Ort, den ein Nutzer ohne
+// Arbeitsoberflaeche ohnehin braucht.
+function macPapierkorb(abs) {
+  const korb = path.join(os.homedir(), '.Trash');
+  fs.mkdirSync(korb, { recursive: true });
+  const ziel = freierName(korb, path.basename(abs));
+  verschiebe(abs, ziel);
+  return ziel;
+}
+
+// --- Windows: nur die Shell darf in den Papierkorb -------------------------
+//
+// Es gibt keinen Ordner, in den man schieben koennte: der Papierkorb ist eine
+// Sicht der Shell, und nur sie legt die Wiederherstellungsdaten an. Deshalb geht
+// es hier ueber PowerShell und die VisualBasic-Dateioperationen - das ist auf
+// jedem Windows vorhanden und braucht kein zusaetzliches Paket.
+function windowsPapierkorb(abs) {
+  return new Promise((fertig, scheitern) => {
+    if (!abs) return scheitern(new Error('the recycle bin needs a path'));
+    const skript = [
+      'Add-Type -AssemblyName Microsoft.VisualBasic;',
+      // Der Pfad kommt ueber die Umgebung, nicht ueber die Befehlszeile. Hinter
+      // -Command ist $args LEER (gemessen 21.09.2026): PowerShell liest alles
+      // nach dem Skripttext als WEITERE Befehle, ein Pfad mit einem Leerzeichen
+      // zerfaellt dabei in zwei davon. $p waere leer geblieben und jedes
+      // Loeschen auf einem Windows-Rechner gescheitert. Ueber die Umgebung gibt
+      // es die Frage nach Anfuehrungszeichen gar nicht erst.
+      '$p = $env:COMPANION_TRASH_TARGET;',
+      'if (Test-Path -LiteralPath $p -PathType Container) {',
+      '  [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteDirectory($p,',
+      "    'OnlyErrorDialogs', 'SendToRecycleBin');",
+      '} else {',
+      '  [Microsoft.VisualBasic.FileIO.FileSystem]::DeleteFile($p,',
+      "    'OnlyErrorDialogs', 'SendToRecycleBin');",
+      '}',
+    ].join(' ');
+    execFile('powershell.exe',
+      ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', skript],
+      { timeout: 30000, windowsHide: true, env: { ...process.env, COMPANION_TRASH_TARGET: abs } },
+      (e, _out, err) => {
+        if (e) return scheitern(new Error(String(err || e.message).trim().split('\n')[0] || 'the recycle bin refused'));
+        fertig(abs);
+      });
+  });
+}
+
+// coverage:host-only-end
+
+/**
+ * Legt `abs` in den Papierkorb des Rechners. Wirft, wenn das nicht geht -
+ * ersatzweise zu vernichten waere das Gegenteil dessen, wofuer das hier da ist.
+ */
+async function inDenPapierkorb(abs) {
+  // Ein eigener Ort, wenn der Nutzer einen nennt. Das braucht, wer den
+  // Papierkorb des Systems nicht benutzen will oder kann - eine Kiste ohne
+  // Arbeitsoberflaeche hat keinen -, und die Tests legen ihre Sachen damit in
+  // ihr eigenes Verzeichnis statt in den echten Papierkorb des Entwicklers.
+  const eigener = process.env.COMPANION_TRASH_DIR;
+  if (eigener) {
+    fs.mkdirSync(eigener, { recursive: true, mode: 0o700 });
+    const ziel = freierName(eigener, path.basename(abs));
+    verschiebe(abs, ziel);
+    return ziel;
+  }
+  // coverage:host-only Jede dieser drei Zeilen laeuft nur auf IHREM System - ein
+  // Lauf kann hoechstens eine davon nehmen. Geprueft sind sie einzeln: der
+  // Linux-Weg direkt (tests/_trash.js), die beiden anderen ueber freierName und
+  // kopiereUndLoesche, aus denen sie bestehen.
+  if (process.platform === 'win32') return await windowsPapierkorb(abs);
+  if (process.platform === 'darwin') return macPapierkorb(abs);
+  return linuxPapierkorb(abs);
+  // coverage:host-only-end
+}
+
+module.exports = { inDenPapierkorb, freierName, verschiebe, kopiereUndLoesche, linuxPapierkorb, macPapierkorb, windowsPapierkorb, NUMMERN_BIS };