bridgerator 1.0.7 → 1.1.0

package/src/settings-tool.mjs

@@ -0,0 +1,186 @@
+// bridgerator_settings: ChatGPT can read every setting of the Bridgerator window and change them.
+// Changes apply at once (owner 21.10). With "Ask before AI changes settings" (askSettings, off by default)
+// anything that lowers protection or widens access needs Apply on the PC.
+// LOGIC: see critical-logic/bridge.md ("Settings", "Access presets").
+import { CATEGORIES, LABEL, readSettings } from './confirm.mjs';
+import { validateSetup } from './setup-tool.mjs';
+import { SNAP_DEFAULTS } from './undo.mjs';
+import { FUSE_DEFAULTS } from './guard.mjs';
+import { extraRegistry } from './extra-tools.mjs';
+
+// Settings of the extra tools (screen capture…): declared by their modules (extra-tools.mjs).
+const EXTRA = extraRegistry();
+
+const BOOL = { type: 'boolean' };
+const b = (description) => ({ type: 'boolean', description });
+const int = (minimum, maximum, description) => ({ type: 'integer', minimum, maximum, description });
+export const PRESETS = ['read_only', 'files', 'full'];
+export const TIMEOUTS = [60, 120, 300];
+/** What a fresh install has (owner 21.10: nothing restricted, like the engine on its own). */
+export const DEFAULTS = {
+  preset: 'full', terminal: true, allowedDirectories: [], readOnlyDirectories: [], protectSensitive: false,
+  confirm: { enabled: false, ...readSettings('').ask, timeoutSeconds: 120 },   // no confirm.ini = the defaults per category
+  recycleBin: true, snapshots: { ...SNAP_DEFAULTS }, fuse: { ...FUSE_DEFAULTS }, keepAwake: true, askSettings: false,
+  theme: 'system', language: 'en', popupStyle: 'toast', notify: { sound: true, offline: true, queueDone: true, limit: true },
+  deviceName: '', autostart: true, localHistory: false, telemetryEnabled: true,
+  ...EXTRA.defaults(),
+};
+const NOTIFY = ['sound', 'offline', 'queueDone', 'limit'];
+const dirs = { type: 'array', maxItems: 20, items: { type: 'string' } };
+export const SETTINGS_TOOL_DEF = {
+  name: 'bridgerator_settings',
+  description: 'Reads ("get": current values and defaults) or changes ("set") every Bridgerator setting of this PC, the same as its window. Changes apply at once (the PC asks first only if the person turned on askSettings). Bridgerator\'s own folders and blocked commands are not settings.',
+  inputSchema: {
+    type: 'object', additionalProperties: false, required: ['action'],
+    properties: {
+      action: { type: 'string', enum: ['get', 'set'] },
+      settings: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          preset: { type: 'string', enum: PRESETS, description: 'Access level: read_only = terminal off and every folder read-only; files = terminal off; full = files and terminal (default).' },
+          terminal: b('Running commands and programs (start_process, interact_with_process, kill_process).'),
+          allowedDirectories: { ...dirs, description: 'Folders ChatGPT may use; empty = all folders (default).' },
+          readOnlyDirectories: { ...dirs, description: 'Folders that can be read but not changed by the file tools. Terminal commands are only checked as a courtesy (a script can still write there): for a hard limit turn the terminal off.' },
+          protectSensitive: b('Block startup programs, PowerShell profiles, .ssh/.aws/cloud logins and AppData (default off).'),
+          confirm: { type: 'object', additionalProperties: false, description: 'Ask the person on this PC before risky actions (default off).', properties: { ...Object.fromEntries(['enabled', ...CATEGORIES].map((k) => [k, BOOL])), timeoutSeconds: { type: 'integer', enum: TIMEOUTS, description: 'No answer in this time = Deny.' } } },
+          recycleBin: b('Simple delete commands move files to the Recycle Bin instead of deleting them (default on).'),
+          snapshots: { type: 'object', additionalProperties: false, description: 'Copies of files before ChatGPT changes them, for bridgerator_undo (default on, 7 days, 500 MB, files up to 50 MB).', properties: { enabled: BOOL, days: int(1, 30), maxMb: int(50, 5000), maxFileMb: int(1, 500) } },
+          fuse: { type: 'object', additionalProperties: false, description: 'Pause Bridgerator and ask the person when more than limit files are deleted or moved within a minute (default off, 20).', properties: { enabled: BOOL, limit: int(3, 1000) } },
+          keepAwake: b('Keep the PC from sleeping while ChatGPT works or the queue has tasks, on AC power only (default on).'),
+          askSettings: b('Ask the person on the PC before an AI change to these settings that lowers protection (default off: every change applies at once).'),
+          theme: { type: 'string', enum: ['system', 'light', 'dark'] }, language: { type: 'string', enum: ['en', 'ru'] },
+          popupStyle: { type: 'string', enum: ['toast', 'popup'] },
+          notify: { type: 'object', additionalProperties: false, properties: Object.fromEntries(NOTIFY.map((k) => [k, BOOL])) },
+          deviceName: { type: 'string', maxLength: 40 }, autostart: BOOL, localHistory: b('Keep the Recent list on disk for 7 days.'), telemetryEnabled: b('Anonymous usage counts.'),
+          ...EXTRA.schema(),
+        },
+      },
+    },
+  },
+};
+
+const TOP = ['theme', 'language', 'popupStyle', 'notify', 'deviceName', 'autostart', 'localHistory', 'telemetryEnabled', 'confirm', 'allowedDirectories', 'readOnlyDirectories',
+  'preset', 'terminal', 'protectSensitive', 'recycleBin', 'snapshots', 'fuse', 'keepAwake', 'askSettings', ...EXTRA.groups()];
+const RANGES = { 'snapshots.days': [1, 30], 'snapshots.maxMb': [50, 5000], 'snapshots.maxFileMb': [1, 500], 'fuse.limit': [3, 1000] };
+const ENUM = { theme: ['system', 'light', 'dark'], language: ['en', 'ru'], popupStyle: ['toast', 'popup'] };
+
+/** → { changes: [{key, value}] } (setSetting keys of the window) or { error }. */
+export function validateSettings(input, opts) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return { error: 'settings must be an object' };
+  const bad = Object.keys(input).filter((k) => !TOP.includes(k));
+  if (bad.length) return { error: `unknown setting(s): ${bad.join(', ')}` };
+  const changes = [];
+  for (const k of ['theme', 'language', 'popupStyle']) if (input[k] !== undefined) { if (!ENUM[k].includes(input[k])) return { error: `${k} must be one of ${ENUM[k].join(', ')}` }; changes.push({ key: k, value: input[k] }); }
+  if (input.preset !== undefined) { if (!PRESETS.includes(input.preset)) return { error: `preset must be one of ${PRESETS.join(', ')}` }; changes.push({ key: 'preset', value: input.preset }); }
+  for (const k of ['autostart', 'localHistory', 'telemetryEnabled', 'terminal', 'protectSensitive', 'recycleBin', 'keepAwake', 'askSettings']) if (input[k] !== undefined) { if (typeof input[k] !== 'boolean') return { error: `${k} must be true or false` }; changes.push({ key: k, value: input[k] }); }
+  if (input.deviceName !== undefined) { if (typeof input.deviceName !== 'string' || input.deviceName.trim().length > 40 || /[\u0000-\u001f]/.test(input.deviceName)) return { error: 'deviceName must be text, up to 40 characters' }; changes.push({ key: 'deviceName', value: input.deviceName.trim() }); }
+  for (const [group, keys] of [['notify', NOTIFY], ['confirm', ['enabled', ...CATEGORIES, 'timeoutSeconds']], ['snapshots', ['enabled', 'days', 'maxMb', 'maxFileMb']], ['fuse', ['enabled', 'limit']]]) {
+    const g = input[group];
+    if (g === undefined) continue;
+    if (!g || typeof g !== 'object' || Array.isArray(g)) return { error: `${group} must be an object` };
+    for (const [k, v] of Object.entries(g)) {
+      const key = `${group}.${k}`;
+      if (key === 'confirm.timeoutSeconds') { if (!TIMEOUTS.includes(v)) return { error: `confirm.timeoutSeconds must be one of ${TIMEOUTS.join(', ')}` }; changes.push({ key: 'confirm.timeout', value: v }); continue; }
+      if (RANGES[key]) { const [lo, hi] = RANGES[key]; if (!Number.isInteger(v) || v < lo || v > hi) return { error: `${key} must be a whole number from ${lo} to ${hi}` }; changes.push({ key, value: v }); continue; }
+      if (!keys.includes(k) || typeof v !== 'boolean') return { error: `${key}: unknown or not true/false` };
+      changes.push({ key, value: v });
+    }
+  }
+  const ex = EXTRA.parse(input);
+  if (ex.error) return { error: ex.error };
+  changes.push(...ex.changes);
+  for (const k of ['allowedDirectories', 'readOnlyDirectories']) if (input[k] !== undefined) {
+    const v = validateSetup({ [k]: input[k] }, opts);
+    if (v.error) return { error: v.error };
+    changes.push({ key: k, value: v.value[k] });
+  }
+  if (!changes.length) return { error: 'nothing to change' };
+  return { changes };
+}
+
+const low = (a) => a.map((x) => x.toLowerCase());
+/** Does this change lower protection or widen access (→ the person's OK on the PC)? */
+export function widens(cur, { key, value }) {
+  if (EXTRA.owns(key)) return EXTRA.widens(cur, { key, value });
+  if (key === 'confirm.enabled') return cur.confirm.enabled && !value;
+  if (key === 'confirm.timeout') return false;
+  if (key.startsWith('confirm.')) return cur.confirm.ask[key.slice(8)] && !value;
+  const was = (k, d) => (cur[k] === undefined ? d : cur[k]);
+  if (key === 'terminal') return value && !was('terminal', DEFAULTS.terminal);
+  if (key === 'protectSensitive' || key === 'recycleBin') return !value && was(key, DEFAULTS[key]);
+  const snap = { ...SNAP_DEFAULTS, ...(cur.snapshots || {}) }, fuse = { ...FUSE_DEFAULTS, ...(cur.fuse || {}) };
+  if (key === 'snapshots.enabled') return !value && snap.enabled;
+  if (key.startsWith('snapshots.')) return value < snap[key.slice(10)];          // less undo history
+  if (key === 'fuse.enabled') return !value && fuse.enabled;
+  if (key === 'fuse.limit') return fuse.enabled && value > fuse.limit;
+  if (key === 'askSettings') return !value && cur.askSettings === true;
+  if (key === 'keepAwake' || key === 'preset') return false;                     // preset: judged by its parts (presetChanges)
+  if (key === 'autostart') return value !== cur.autostart;
+  if (key === 'telemetryEnabled') return value && !cur.telemetry;
+  if (key === 'localHistory') return value && !cur.localHistory;
+  if (key === 'readOnlyDirectories') { const now = low(value); return low(cur.readOnlyDirectories).some((x) => !now.includes(x)); }
+  if (key === 'allowedDirectories') {
+    const before = low(cur.allowedDirectories), after = low(value);
+    if (!after.length) return before.length > 0;            // a list → all folders
+    if (!before.length) return false;                        // all folders → a list: narrower
+    return after.some((x) => !before.includes(x));           // a folder added to the list
+  }
+  return false;                                              // theme, language, notifications, name…
+}
+
+/** One human line per change, for the notification / the window. */
+export function describe(cur, { key, value }) {
+  const onoff = (v) => (v ? 'on' : 'off');
+  if (EXTRA.owns(key)) return EXTRA.describe({ key, value });
+  if (key === 'confirm.enabled') return `Confirmations: ${onoff(value)}`;
+  if (key === 'confirm.timeout') return `No answer = Deny after: ${value} s`;
+  if (key.startsWith('confirm.')) return `Confirm ${LABEL[key.slice(8)]}: ${onoff(value)}`;
+  if (key === 'allowedDirectories') {
+    if (!value.length) return 'Folders: all (except always-blocked)';
+    const before = low(cur.allowedDirectories);
+    const add = value.filter((x) => !before.includes(x.toLowerCase())), rem = cur.allowedDirectories.filter((x) => !low(value).includes(x.toLowerCase()));
+    return `Folders: ${[...add.map((x) => `+${x}`), ...rem.map((x) => `−${x}`)].join(', ') || 'unchanged'}`;
+  }
+  if (key === 'readOnlyDirectories') {
+    const before = low(cur.readOnlyDirectories);
+    const add = value.filter((x) => !before.includes(x.toLowerCase())), rem = cur.readOnlyDirectories.filter((x) => !low(value).includes(x.toLowerCase()));
+    return `Read-only: ${[...add.map((x) => `+${x}`), ...rem.map((x) => `−${x}`)].join(', ') || 'unchanged'}`;
+  }
+  const names = { autostart: 'Start with Windows', telemetryEnabled: 'Usage stats', localHistory: 'Local history', theme: 'Theme', language: 'Language', popupStyle: 'Pop-up style', deviceName: 'Computer name',
+    terminal: 'Terminal (commands)', protectSensitive: 'Protect sensitive folders', recycleBin: 'Recycle Bin instead of deleting', keepAwake: 'Keep the PC awake while ChatGPT works', askSettings: 'Ask before AI changes settings', preset: 'Access',
+    'snapshots.enabled': 'Snapshots and Undo', 'snapshots.days': 'Keep snapshots (days)', 'snapshots.maxMb': 'Snapshots up to (MB)', 'snapshots.maxFileMb': 'Snapshot files up to (MB)',
+    'fuse.enabled': 'Pause on mass deletes / moves', 'fuse.limit': 'Mass-action limit per minute' };
+  return `${names[key] || key}: ${typeof value === 'boolean' ? onoff(value) : value}`;
+}
+
+const covered = (dirs, ro) => { const r = low(ro).map((x) => x.replace(/[\\/]+$/, '')); return dirs.length > 0 && dirs.every((d) => { const n = d.toLowerCase().replace(/[\\/]+$/, ''); return r.some((x) => n === x || n.startsWith(`${x}\\`)); }); };
+/** Folders the Read only preset makes read-only: the folder list, or every drive when there is none. */
+const presetTargets = (s, drives) => (s.allowedDirectories.length ? s.allowedDirectories : drives);
+/** The access preset the settings amount to: full (terminal on), read_only (terminal off, all read-only), files. */
+export function presetOf(s, drives = []) {
+  if (s.terminal !== false) return 'full';
+  return covered(presetTargets(s, drives), s.readOnlyDirectories || []) ? 'read_only' : 'files';
+}
+/** A preset → the setting changes it stands for (terminal, readOnlyDirectories). */
+export function presetChanges(name, s, drives = []) {
+  const t = presetTargets(s, drives), ro = s.readOnlyDirectories || [];
+  const out = [{ key: 'terminal', value: name === 'full' }];
+  if (name === 'read_only') {
+    const add = t.filter((d) => !low(ro).includes(d.toLowerCase()));
+    if (add.length) out.push({ key: 'readOnlyDirectories', value: [...ro, ...add] });
+  } else if (presetOf(s, drives) === 'read_only') {
+    // Leaving Read only: the folders it made read-only go back to writable.
+    const keep = ro.filter((d) => !low(t).includes(d.toLowerCase()));
+    if (keep.length !== ro.length) out.push({ key: 'readOnlyDirectories', value: keep });
+  }
+  return out;
+}
+/** Change list with every preset replaced by what it stands for (the widen check looks at the parts). */
+// The preset is judged on the folder lists of the SAME request (they are applied first, the preset after).
+export function expandPresets(changes, s, drives) {
+  const rest = changes.filter((c) => c.key !== 'preset'), presets = changes.filter((c) => c.key === 'preset');
+  if (!presets.length) return changes;
+  const s2 = { ...s };
+  for (const c of rest) if (c.key === 'allowedDirectories' || c.key === 'readOnlyDirectories' || c.key === 'terminal') s2[c.key] = c.value;
+  return [...rest, ...presets.flatMap((c) => presetChanges(c.value, s2, drives))];
+}

package/src/setup-tool.mjs

@@ -0,0 +1,129 @@
+// bridgerator_setup: the assistant SUGGESTS folders / read-only folders / confirmation checks after
+// a conversation with the person; nothing changes until the person clicks Apply in a window on the
+// PC (no answer = Cancel). It can't touch the built-in exclusions, blockedCommands, telemetry or
+// anything else.
+import fs from 'node:fs';
+import path from 'node:path';
+import { CATEGORIES, readSettings, setIni, restoreIni, writeAtomic, LABEL } from './confirm.mjs';
+import { TERMINAL_TOOLS } from './policy.mjs';
+
+const MAX = 20;
+const CONFIRM_KEYS = ['enabled', ...CATEGORIES];
+const dirList = { type: 'array', maxItems: MAX, items: { type: 'string' } };
+export const SETUP_TOOL_DEF = {
+  name: 'bridgerator_setup',
+  description: 'Limits access on this PC, and only when the person explicitly asks for limits ("only this folder", "read only", "ask me before deleting"). A folder named for a task is not a request to limit: just work there. "Set up Bridgerator" needs no call: the defaults (every folder, terminal on, no confirmations, deletions to the Recycle Bin, Undo on) are the setup. Fields: preset (read_only | files | full), allowedDirectories (empty = every folder), readOnlyDirectories, confirm. Applied at once (the PC asks first only if the person turned on "Ask before AI changes settings"). Absolute local paths only.',
+  inputSchema: {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+      preset: { type: 'string', enum: ['read_only', 'files', 'full'], description: 'read_only = look only (terminal off, everything read-only); files = files but no terminal; full = files and terminal (default).' },
+      allowedDirectories: dirList,
+      readOnlyDirectories: dirList,
+      confirm: { type: 'object', additionalProperties: false, properties: Object.fromEntries(CONFIRM_KEYS.map((k) => [k, { type: 'boolean' }])) },
+    },
+  },
+};
+
+/** → { value } (normalized) or { error } (text for the assistant). */
+export function validateSetup(input, { isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } } } = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return { error: 'expected an object' };
+  const extra = Object.keys(input).filter((k) => !['preset', 'allowedDirectories', 'readOnlyDirectories', 'confirm'].includes(k));
+  if (extra.length) return { error: `unknown setting(s): ${extra.join(', ')} — only preset, allowedDirectories, readOnlyDirectories and confirm can be suggested` };
+  const value = {};
+  if (input.preset !== undefined) {
+    if (!['read_only', 'files', 'full'].includes(input.preset)) return { error: 'preset must be read_only, files or full' };
+    value.preset = input.preset;
+  }
+  for (const k of ['allowedDirectories', 'readOnlyDirectories']) {
+    if (input[k] === undefined) continue;
+    const list = input[k];
+    if (!Array.isArray(list) || list.length > MAX) return { error: `${k} must be a list of at most ${MAX} folders` };
+    const out = [];
+    for (const p of list) {
+      if (typeof p !== 'string' || !p.trim()) return { error: `${k}: every entry must be a folder path` };
+      const s = p.trim();
+      if (/^[\\/]{2}/.test(s) || /^[a-z][a-z0-9+.-]*:\/\//i.test(s)) return { error: `${k}: "${s}" — network paths and URLs are not allowed` };
+      if (!/^[a-z]:[\\/]/i.test(s)) return { error: `${k}: "${s}" is not an absolute local path like C:\\Users\\Name\\Documents` };
+      if (!isDir(s)) return { error: `${k}: "${s}" is not an existing folder` };
+      const n = path.resolve(s);
+      if (!out.some((x) => x.toLowerCase() === n.toLowerCase())) out.push(n);
+    }
+    value[k] = out;
+  }
+  if (input.confirm !== undefined) {
+    const c = input.confirm;
+    if (!c || typeof c !== 'object' || Array.isArray(c)) return { error: 'confirm must be an object' };
+    const bad = Object.keys(c).filter((k) => !CONFIRM_KEYS.includes(k) || typeof c[k] !== 'boolean');
+    if (bad.length) return { error: `confirm: unknown or non-boolean key(s): ${bad.join(', ')} (allowed: ${CONFIRM_KEYS.join(', ')})` };
+    value.confirm = { ...c };
+  }
+  if (!Object.keys(value).length) return { error: 'nothing to change' };
+  return { value };
+}
+
+/** One line for the notification, e.g. "Folders: D:\\Work, D:\\Photos (read-only) · confirm deletions: on". */
+export function summarizeSetup(cfg, ini, v) {
+  const parts = [];
+  const ro = v.readOnlyDirectories || cfg.readOnlyDirectories || [];
+  const folders = [...(v.allowedDirectories || []).map((d) => (ro.some((r) => r.toLowerCase() === d.toLowerCase()) ? `${d} (read-only)` : d)),
+    ...(v.readOnlyDirectories || []).filter((r) => !(v.allowedDirectories || []).some((d) => d.toLowerCase() === r.toLowerCase())).map((r) => `${r} (read-only)`)];
+  if (folders.length) parts.push(`Folders: ${folders.join(', ')}`);
+  else if (v.readOnlyDirectories) parts.push('Read-only folders: none');
+  if (v.confirm) {
+    const s = readSettings(ini);
+    const on = v.confirm.enabled ?? s.enabled;
+    if (!on) parts.push('confirmations: off');
+    else parts.push(`confirm ${CATEGORIES.filter((k) => (k in v.confirm ? v.confirm[k] : s.ask[k])).map((k) => LABEL[k]).join(', ') || 'nothing'}: on`);
+  }
+  const line = parts.join(' · ');
+  return line.length > 180 ? `${line.slice(0, 179)}…` : line;
+}
+
+/** Before → after as a diff: lines for the window, one short line for the notification. */
+export function diffSetup(cfg, ini, v) {
+  const lines = [], parts = [];
+  const same = (a, b) => a.toLowerCase() === b.toLowerCase();
+  const d = (label, before, after) => {
+    const add = after.filter((x) => !before.some((b) => same(b, x))), rem = before.filter((x) => !after.some((a) => same(a, x)));
+    if (!add.length && !rem.length) return;
+    lines.push(`${label}: ${before.length} → ${after.length}`, ...add.map((x) => `  + ${x}`), ...rem.map((x) => `  − ${x}`));
+    parts.push(`${label}: ${[...add.map((x) => `+${x}`), ...rem.map((x) => `−${x}`)].join(', ')}`);
+  };
+  if (v.allowedDirectories) {
+    const before = cfg.allowedDirectories || [], after = v.allowedDirectories;
+    if (!after.length && before.length) { lines.push('Folders: all folders (except always-blocked)'); parts.push('Folders: all (except always-blocked)'); }
+    else if (after.length && !before.length) { lines.push(`Folders: only these ${after.length}`, ...after.map((x) => `  + ${x}`)); parts.push(`Folders: only ${after.join(', ')}`); }
+    else d('Folders', before, after);
+  }
+  if (v.readOnlyDirectories) d('Read-only', cfg.readOnlyDirectories || [], v.readOnlyDirectories);
+  if (typeof v.terminal === 'boolean' && v.terminal !== !(cfg.disabledTools || []).includes('start_process')) { const t = `Terminal: ${v.terminal ? 'on' : 'off'}`; lines.push(t); parts.push(t); }
+  if (v.confirm) {
+    const s = readSettings(ini);
+    const cur = { enabled: s.enabled, ...s.ask };
+    for (const [k, x] of Object.entries(v.confirm)) if (cur[k] !== x) {
+      const t = `${k === 'enabled' ? 'Confirmations' : `Confirm ${LABEL[k]}`}: ${x ? 'on' : 'off'}`;
+      lines.push(t); parts.push(t);
+    }
+  }
+  return { lines: lines.length ? lines : ['No changes'], short: parts.join(' · ') || 'No changes' };
+}
+
+/** Writes the approved settings: config.json (folders, setupDone) and confirm.ini. → the new cfg. */
+export function applySetup(configFile, ini, v) {
+  const cfg = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+  const next = { ...cfg, ...(v.allowedDirectories ? { allowedDirectories: v.allowedDirectories } : {}), ...(v.readOnlyDirectories ? { readOnlyDirectories: v.readOnlyDirectories } : {}), setupDone: true };
+  if (typeof v.terminal === 'boolean') next.disabledTools = terminalTools(cfg.disabledTools, v.terminal);
+  writeAtomic(configFile, JSON.stringify(next, null, 2));
+  if (v.confirm) {
+    restoreIni(ini);
+    for (const [k, x] of Object.entries(v.confirm)) setIni(ini, k === 'enabled' ? 'confirm' : 'ask', k, x ? 'true' : 'false');
+  }
+  return next;
+}
+
+/** disabledTools with the terminal tools switched on (removed) or off (added). */
+export function terminalTools(list = [], on) {
+  const rest = (list || []).filter((x) => !TERMINAL_TOOLS.includes(x));
+  return on ? rest : [...rest, ...TERMINAL_TOOLS];
+}

package/src/software-tool.mjs

@@ -0,0 +1,185 @@
+// LOGIC: see critical-logic/bridge.md ("Software (winget)"). Programs through the Windows Package
+// Manager (winget, part of Windows 10/11 "App Installer"): search, installed list, available updates,
+// install, upgrade. winget is started by its absolute path (a planted winget.exe on the PATH never
+// runs), never through a shell, with --disable-interactivity; install / upgrade run --silent.
+// Agreements are accepted ONLY when the call says accept_agreements: true (the AI asks the person
+// first). Install / upgrade = confirmation category "install" (asks only when the person turned
+// confirmations on) and are refused while the terminal is off (access presets Read only / Files).
+// Tables are read by column positions from the dashes line under the header (any language), the
+// result by winget's exit code (HRESULT), never by message text.
+import fs from 'node:fs';
+import { spawn } from 'node:child_process';
+import { stripOurs } from './ask.mjs';
+import { WINGET } from './win.mjs';
+import { ToolError, fail, json, needAction, str } from './tool-lib.mjs';
+
+const ID_RE = /^[A-Za-z0-9][A-Za-z0-9.+_-]{0,127}$/;          // winget ids: Vendor.App, 9NBLGGH4NNS1 (Store)
+const SOURCES = ['winget', 'msstore'];
+const MAX_ROWS = 200;
+
+// winget runs in the background, so Windows often shows its administrator prompt only as a flashing
+// taskbar button (a background program can't bring it to the front): the person must be told to look.
+export const UAC_NOTE = 'Windows may show its administrator prompt only as a flashing button in the taskbar — ask the person to click it and choose Yes.';
+// HRESULT exit codes (winget returnCodes.md) → plain words + what to do.
+const CODES = {
+  0x8A150014: ['No program matches.', 'Search with other words (action "search").'],
+  0x8A150016: ['Several programs match.', 'Use the exact id from action "search".'],
+  0x8A150010: ['No installer of this program fits this PC.', ''],
+  0x8A150011: ['The downloaded installer does not match its published checksum, so it was not run.', 'Try again later.'],
+  0x8A150008: ['The download failed.', 'Check the internet connection and try again.'],
+  0x8A150019: ['This needs administrator rights.', 'Ask the person to run it from an administrator terminal.'],
+  0x8A15002B: ['No update is available for it.', ''],
+  0x8A15002C: ['Some updates failed.', 'Check the list with action "updates" and update them one by one.'],
+  0x8A15003A: ['A company policy blocks winget on this PC.', 'Ask the PC administrator.'],
+  0x8A150041: ['The program\'s license terms were not accepted.', 'Ask the person; if they agree, call again with accept_agreements: true.'],
+  0x8A150046: ['The program source\'s terms were not accepted yet.', 'Ask the person; if they agree, call again with accept_agreements: true.'],
+  0x8A15004F: ['The available version is not newer than the installed one.', ''],
+  0x8A150101: ['The program is running.', 'Close it and try again.'],
+  0x8A150102: ['Another installation is in progress.', 'Try again in a few minutes.'],
+  0x8A150103: ['A file of the program is in use.', 'Close the program and try again.'],
+  0x8A150105: ['The disk is full.', 'Free some space and try again.'],
+  0x8A150107: ['The installer needs the internet.', 'Check the connection.'],
+  0x8A150109: ['Installed — restart the PC to finish.', ''],
+  0x8A15010A: ['Installation failed: restart the PC, then try again.', ''],
+  0x8A15010B: ['The PC will restart to finish the installation.', ''],
+  0x8A15010C: ['The installation was cancelled (for example "No" in the Windows administrator prompt).', `Ask the person to allow it when Windows asks. ${UAC_NOTE}`],
+  0x8A15010D: ['It is already installed.', 'Use action "upgrade" to update it.'],
+  0x8A15010E: ['A newer version is already installed.', ''],
+  // Seen on a lab PC after "No" in the administrator prompt (installer exit 1625): said as not approved.
+  0x8A15010F: ['The installation was cancelled or not approved (for example "No" in the Windows administrator prompt, or a policy of this PC).', `Ask the person to try again and allow it when Windows asks. ${UAC_NOTE}`],
+  0x8A150113: ['This program does not support this Windows version.', ''],
+  0x8A150115: ['The program\'s installer reported an error.', 'Try again, or install it from the vendor\'s site.'],
+};
+const OK_CODES = new Set([0, 0x8A150109]);
+
+/** Runs winget (win.WINGET) → { code (unsigned HRESULT), out }. ctx.runWinget (tests) replaces it. */
+// winget.exe in WindowsApps is an App Execution Alias: stat() fails (EACCES) so fs.existsSync says false; lstat sees it.
+export const aliasExists = (p) => { try { fs.lstatSync(p); return true; } catch { return false; } };
+export function runWinget(args, { timeout = 120000, exists = aliasExists } = {}) {
+  if (process.platform !== 'win32') return Promise.reject(new ToolError('NOT_WINDOWS', 'This works only on Windows.'));
+  if (!exists(WINGET)) return Promise.reject(new ToolError('NO_WINGET', 'winget (Windows Package Manager) is not available on this PC.', 'It comes with "App Installer" from the Microsoft Store; Windows 10 1809+ and Windows 11 have it after updates.'));
+  return new Promise((resolve, reject) => {
+    const child = spawn(WINGET, args, { windowsHide: true, env: stripOurs(process.env), stdio: ['ignore', 'pipe', 'pipe'] });
+    const chunks = [];
+    let size = 0;
+    const timer = setTimeout(() => { child.kill(); reject(new ToolError('TIMEOUT', 'winget did not finish in time.', `An installer may be waiting for an answer on the PC screen; ask the person to look. ${UAC_NOTE}`)); }, timeout);
+    const take = (b) => { size += b.length; if (size < 8 * 1024 * 1024) chunks.push(b); };
+    child.stdout.on('data', take);
+    child.stderr.on('data', take);
+    child.on('error', (e) => { clearTimeout(timer); reject(new ToolError('NO_WINGET', `winget did not start (${e.code || e.message}).`, 'Update "App Installer" from the Microsoft Store.')); });
+    child.on('close', (code) => { clearTimeout(timer); resolve({ code: code >>> 0, out: Buffer.concat(chunks).toString('utf8') }); });
+  });
+}
+
+/** Output lines without progress spinners / bars (text after the last bare \r of a line). */
+export function cleanLines(out, { blank = false } = {}) {
+  return String(out).replace(/\r\n/g, '\n').split('\n')
+    .map((l) => l.slice(l.lastIndexOf('\r') + 1).replace(/[▀-▟]+/g, '').replace(/\s+$/, ''))
+    .filter((l) => (blank && !l) || (l && !/^\s*[-\\|/]\s*$/.test(l)));
+}
+
+/**
+ * The first table of winget output → rows of cells. Columns start where the header words start;
+ * the dashes line marks the header. Header labels are localized and only give positions.
+ * → { cols: number, rows: [[cell…]] }
+ */
+export function parseTable(out) {
+  const lines = cleanLines(out, { blank: true });
+  const dash = lines.findIndex((l) => /^-{10,}$/.test(l.trim()));
+  if (dash < 1) return { cols: 0, rows: [] };
+  const header = lines[dash - 1];
+  const starts = [];
+  for (const m of header.matchAll(/\S+/g)) starts.push(m.index);
+  const rows = [];
+  for (let i = dash + 1; i < lines.length && rows.length < MAX_ROWS; i++) {
+    const l = lines[i];
+    // The table ends at a blank line, a dashes line, or the header of a second table (its dashes follow).
+    if (!l.trim() || /^-{10,}$/.test(l.trim()) || /^-{10,}$/.test((lines[i + 1] || '').trim())) break;
+    rows.push(starts.map((s, j) => l.slice(s, starts[j + 1] ?? undefined).trim()));
+  }
+  return { cols: starts.length, rows };
+}
+
+// Column order is fixed by winget: search Name Id Version [Match] Source; list Name Id Version
+// [Available] Source; upgrade Name Id Version Available Source.
+function rowsOf(kind, { cols, rows }) {
+  return rows.map((r) => {
+    const o = { name: r[0], id: r[1], version: r[2] };
+    if (cols >= 5) { if (kind === 'search') { if (r[3]) o.match = r[3]; } else if (r[3]) o.available = r[3]; o.source = r[4] || undefined; }
+    else if (cols === 4) { if (kind === 'updates') o.available = r[3]; else o.source = r[3] || undefined; }
+    return o;
+  }).filter((o) => /^\S+$/.test(o.id || '') && o.version);            // footer lines ("2 upgrades available.") have no id
+}
+
+function explain(code, out) {
+  if (OK_CODES.has(code)) return null;
+  const known = CODES[code];
+  const hex = `0x${code.toString(16).toUpperCase()}`;
+  const tail = cleanLines(out).filter((l) => !/^-{3,}/.test(l)).slice(-3).join(' | ').slice(0, 300);
+  return known ? new ToolError(`WINGET_${hex}`, known[0], known[1]) : new ToolError(`WINGET_${hex}`, `winget stopped with code ${hex}.${tail ? ` Last output: ${tail}` : ''}`, 'Try again; if it repeats, the person can run the same winget command in a terminal to see more.');
+}
+
+const base = (args) => ['--disable-interactivity', ...(args.accept_agreements === true ? ['--accept-source-agreements'] : [])];
+const sourceArg = (args) => { const s = str(args, 'source', { max: 20 }); if (s && !SOURCES.includes(s)) fail('BAD_ARGS', `source must be ${SOURCES.join(' or ')}.`); return s ? ['--source', s] : []; };
+const idArg = (args, required) => {
+  const id = str(args, 'id', { required, max: 128 });
+  if (id && !ID_RE.test(id)) fail('BAD_ARGS', 'id must be a winget package id like "7zip.7zip" (from action "search").');
+  return id;
+};
+
+export const defs = [{
+  name: 'software',
+  title: 'Programs (winget)',
+  description: 'Programs on this PC through the Windows Package Manager (winget). search: find programs by name; list: installed programs; updates: programs with a newer version; install / upgrade: install or update one program by its id (silent; upgrade with all: true updates everything). Windows may still show its administrator prompt on the PC for some installers (often only as a flashing taskbar button). Program and source license terms are accepted only with accept_agreements: true, after the person agreed.',
+  inputSchema: {
+    type: 'object', additionalProperties: false, required: ['action'],
+    properties: {
+      action: { type: 'string', enum: ['search', 'list', 'updates', 'install', 'upgrade'] },
+      query: { type: 'string', maxLength: 100, description: 'search / list: words to look for' },
+      id: { type: 'string', maxLength: 128, description: 'install / upgrade: exact package id, e.g. "7zip.7zip"' },
+      all: { type: 'boolean', description: 'upgrade: update every program that has an update' },
+      version: { type: 'string', maxLength: 40, description: 'install: a specific version' },
+      scope: { type: 'string', enum: ['user', 'machine'], description: 'install: for this user only, or for all users (needs administrator rights)' },
+      source: { type: 'string', enum: SOURCES },
+      accept_agreements: { type: 'boolean', description: 'Accept the program\'s and the source\'s license terms (only after the person agreed). Default false.' },
+    },
+  },
+  annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+}];
+
+export async function handle(name, args, ctx) {
+  const action = needAction(args, defs[0].inputSchema.properties.action.enum);
+  const run = ctx.runWinget || runWinget;
+  if (action === 'search' || action === 'list' || action === 'updates') {
+    const q = str(args, 'query', { required: action === 'search', max: 100 });
+    if (q && /[\u0000-\u001f"]/.test(q)) fail('BAD_ARGS', 'query must be plain text.');
+    const argv = action === 'search' ? ['search', '--query', q, '--count', '50']
+      : action === 'list' ? ['list', ...(q ? ['--query', q] : [])]
+        : ['upgrade'];
+    const r = await run([...argv, ...sourceArg(args), ...base(args)], { timeout: 120000 });
+    if (r.code === 0x8A150014) return json({ action, found: 0, programs: [] });
+    const err = explain(r.code, r.out);
+    if (err) throw err;
+    const programs = rowsOf(action, parseTable(r.out));
+    return json({ action, found: programs.length, programs, ...(programs.length >= MAX_ROWS ? { note: `first ${MAX_ROWS} shown` } : {}) });
+  }
+  // install / upgrade: like a terminal command — off with the terminal; asks when confirmations are on.
+  if ((ctx.cfg?.disabledTools || []).includes('start_process')) fail('TERMINAL_OFF', 'Installing programs is off on this PC (access preset Read only or Files).', 'The person can switch to Full in Bridgerator → Safety, or you can ask with bridgerator_settings.');
+  const id = idArg(args, !(action === 'upgrade' && args.all === true));
+  if (action === 'upgrade' && args.all === true && id) fail('BAD_ARGS', 'Give either id or all: true, not both.');
+  const version = str(args, 'version', { max: 40 });
+  if (version && !/^[A-Za-z0-9.+_-]+$/.test(version)) fail('BAD_ARGS', 'version must look like 1.2.3.');
+  // Fails closed: without the confirmation gate nothing is installed.
+  if (typeof ctx.gate?.gate !== 'function') fail('NO_GATE', 'Installing programs is not available here.');
+  const stop = await ctx.gate.gate('software', { ...args, action });
+  if (stop) return stop;
+  const argv = [action, ...(id ? ['--id', id, '--exact'] : ['--all']),
+    ...(version && action === 'install' ? ['--version', version] : []),
+    ...(args.scope && action === 'install' ? ['--scope', args.scope === 'machine' ? 'machine' : 'user'] : []),
+    '--silent', ...sourceArg(args), ...base(args), ...(args.accept_agreements === true ? ['--accept-package-agreements'] : [])];
+  ctx.log?.(`[bridgerator] software ${action} ${id || '--all'}`);
+  const r = await run(argv, { timeout: 30 * 60000 });
+  const err = explain(r.code, r.out);
+  if (err) throw err;
+  return json({ action, id: id || 'all', done: true, ...(r.code === 0x8A150109 ? { restartNeeded: true } : {}), output: cleanLines(r.out).filter((l) => !/^-{3,}/.test(l)).slice(-6) });
+}

package/src/telemetry.mjs

@@ -0,0 +1,86 @@
+// Anonymous usage counts to Bridgerator (disclosed on the privacy page; off with
+// `bridgerator.cmd telemetry off`, "telemetryEnabled": false in config.json, or install -NoTelemetry).
+// Only these fields: random install id, bridge version, Windows version, OS language, Node.js
+// version, and in the daily heartbeat per-tool call / error counts. Never paths, file names,
+// commands, arguments, outputs, e-mail. HTTPS only; any failure is silent.
+import fs from 'node:fs';
+import os from 'node:os';
+import { createRequire } from 'node:module';
+import { writeAtomic } from './confirm.mjs';
+
+export const TELEMETRY_URL = 'https://bridgerator.recondeck.com/t';
+export const VERSION = createRequire(import.meta.url)('../package.json').version;
+const DAY = 24 * 3600 * 1000;
+const READ_FAILS_MAX = 3; // hourly ticks
+
+export const enabled = (cfg) => !!cfg?.installId && cfg.telemetryEnabled !== false;
+
+export function payload(cfg, event, extra = {}) {
+  let lang = '';
+  try { lang = Intl.DateTimeFormat().resolvedOptions().locale; } catch { /* none */ }
+  return { event, id: cfg.installId, version: VERSION, os: `${os.platform()} ${os.release()}`, lang, node: process.version, ...extra };
+}
+
+export async function send(cfg, event, extra, { fetch: f = globalThis.fetch } = {}) {
+  if (!enabled(cfg)) return;
+  try {
+    await f(TELEMETRY_URL, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(payload(cfg, event, extra)), signal: AbortSignal.timeout(10000) });
+  } catch { /* offline: nothing */ }
+}
+
+// Per-tool counters for the heartbeat. `known` = the engine's tool names: a name the relay made up
+// is never counted (only our own fixed tool names leave the PC). State survives restarts in `file`.
+export function usage(cfg, known, file, { now = Date.now, sendFn = send } = {}) {
+  const fresh = () => ({ since: now(), calls: {}, errors: {} });
+  // Only a missing file (ENOENT) or an unparsable / wrong-shape one = fresh (rewritten at the next save),
+  // so one bad usage.json never stops counting for good. Any other read error (a lock of antivirus /
+  // backup, EIO, EMFILE, EISDIR...) throws — the caller keeps its in-memory state and retries next tick;
+  // after READ_FAILS_MAX failed ticks in a row it goes on from memory (rewrites the file, the heartbeat
+  // goes), so a permanently unreadable file never stops telemetry. Only since / calls / errors are kept;
+  // a counter that is not a non-negative safe integer is dropped.
+  const load = () => {
+    let txt;
+    try { txt = fs.readFileSync(file, 'utf8'); } catch (e) { if (e?.code === 'ENOENT') return fresh(); throw e; }
+    let j; try { j = JSON.parse(txt); } catch { return fresh(); }
+    if (!j || typeof j !== 'object' || Array.isArray(j)) return fresh();
+    const obj = (o) => Object.fromEntries(Object.entries(o && typeof o === 'object' && !Array.isArray(o) ? o : {}).filter(([, n]) => Number.isSafeInteger(n) && n >= 0));
+    return { since: Number.isFinite(j.since) ? j.since : now(), calls: obj(j.calls), errors: obj(j.errors) };
+  };
+  let st; try { st = load(); } catch { st = fresh(); }
+  // Counted since the last save: added to what is in the file then (another bridge process may have
+  // saved meanwhile — no last-writer-wins), written atomically (temp + rename).
+  let delta = { calls: {}, errors: {} };
+  const add = (to, from) => { for (const [k, n] of Object.entries(from)) to[k] = (to[k] || 0) + n; };
+  const write = () => { try { writeAtomic(file, JSON.stringify(st)); } catch { /* read-only */ } };
+  let fails = 0;
+  const save = () => {
+    let disk;
+    try { disk = load(); fails = 0; } catch { // locked now: keep st + delta, retry next tick
+      if (++fails < READ_FAILS_MAX) return false;
+      fails = 0; delta = { calls: {}, errors: {} }; write(); return true; // still unreadable: go on from memory
+    }
+
+    add(disk.calls, delta.calls); add(disk.errors, delta.errors);
+    delta = { calls: {}, errors: {} };
+    st = disk;
+    write();
+    return true;
+  };
+  return {
+    count(name, isError) {
+      if (!known.has(name)) return;
+      st.calls[name] = (st.calls[name] || 0) + 1;
+      delta.calls[name] = (delta.calls[name] || 0) + 1;
+      if (isError) { st.errors[name] = (st.errors[name] || 0) + 1; delta.errors[name] = (delta.errors[name] || 0) + 1; }
+    },
+    async tick() {
+      if (!save()) return;
+      if (now() - st.since < DAY) return;
+      const { calls, errors } = st;
+      st = fresh();
+      write();
+      await sendFn(cfg, 'heartbeat', { calls, errors });
+    },
+    state: () => st,
+  };
+}