bridgerator 1.0.8 → 1.1.0

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,
+  };
+}

package/src/tool-lib.mjs

@@ -0,0 +1,177 @@
+// LOGIC: see critical-logic/bridge.md ("Extra tools"). Shared helpers of the extra tools:
+// plain-words errors (stable code + what to do, never a stack), the folder guard (same rules as the
+// engine's file tools: allowed list, excluded, read-only, UNC) and the PowerShell runner.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { POWERSHELL, TASKKILL, psArgs } from './win.mjs';
+import { runFilesPs, stripOurs } from './ask.mjs';
+import { norm, realish } from './policy.mjs';
+
+export class ToolError extends Error {
+  /** code: stable UPPER_CASE id; hint: what the person / AI can do about it. */
+  constructor(code, message, hint = '') { super(message); this.code = code; this.hint = hint; }
+}
+
+// Node / Windows error codes → plain words (the AI shows them to the person).
+const NODE_ERRORS = {
+  ENOENT: ['File or folder not found.', 'Check the path (list the folder first).'],
+  EACCES: ['Windows denied access to this file or folder.', 'The file may belong to another user or need administrator rights.'],
+  EPERM: ['Windows did not allow this change.', 'The file may be read-only, open in another program, or protected.'],
+  EBUSY: ['The file is open in another program.', 'Close it there and try again.'],
+  EEXIST: ['A file with this name already exists.', 'Choose another name or allow overwriting.'],
+  ENOSPC: ['The disk is full.', 'Free some space and try again.'],
+  EISDIR: ['This is a folder, not a file.', ''],
+  ENOTDIR: ['A part of the path is a file, not a folder.', ''],
+  ETIMEDOUT: ['The operation took too long and was stopped.', 'Try a smaller task or try again later.'],
+};
+const clean = (s) => fromClixml(String(s ?? '')).replace(/\r?\n\s+at\s.*$/s, '').replace(/[\u0000-\u0008\u000b-\u001f]/g, ' ').trim().slice(0, 400);
+
+// PowerShell writes errors of a non-interactive run as CLIXML: keep only the error text.
+export function fromClixml(s) {
+  if (!s.startsWith('#< CLIXML')) return s;
+  const parts = [...s.matchAll(/<S S="Error">([\s\S]*?)<\/S>/g)].map((m) => m[1]);
+  return parts.join('').replace(/_x000D__x000A_/g, '\n').replace(/_x([0-9A-F]{4})_/g, (m, h) => String.fromCharCode(parseInt(h, 16)))
+    .replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&apos;/g, "'").replace(/&amp;/g, '&');
+}
+/** Any error → one short paragraph for the AI: what happened, what to do, (code). No stack, no internals. */
+export function errorText(e) {
+  if (e instanceof ToolError) return `${e.message}${e.hint ? ` What to do: ${e.hint}` : ''} (code ${e.code})`;
+  const m = NODE_ERRORS[e?.code];
+  if (m) return `${m[0]}${m[1] ? ` What to do: ${m[1]}` : ''} (code ${e.code})`;
+  const msg = clean(e?.message || e) || 'Something went wrong.';
+  return `${msg} (code INTERNAL)`;
+}
+
+/** An engine call that threw (not a tool error result) → plain words; MCP error codes, no stack. */
+export function engineErrorText(e) {
+  const code = e?.code, msg = clean(e?.message || e).split('\n')[0].replace(/^MCP error -?\d+:\s*/, '');
+  if (code === -32001 || /timed? ?out/i.test(msg)) return 'The PC did not finish this in time — it may still be running. Check the result, or do it in smaller steps. (code ENGINE_TIMEOUT)';
+  if (code === -32000 || /connection closed/i.test(msg)) return 'Bridgerator\'s file and terminal service on the PC restarted. Try again in a few seconds. (code ENGINE_RESTARTED)';
+  if (code === -32602) return `These arguments don't fit the tool: ${msg.slice(0, 200)} (code BAD_ARGS)`;
+  return `The PC could not do this: ${msg.slice(0, 300) || 'unknown error'}. If it repeats, the person can run "bridgerator doctor" on the PC. (code ENGINE_ERROR)`;
+}
+export const text = (t) => ({ content: [{ type: 'text', text: t }] });
+export const json = (o) => ({ content: [{ type: 'text', text: JSON.stringify(o, null, 2) }] });
+export const fail = (code, message, hint) => { throw new ToolError(code, message, hint); };
+
+export function needAction(args, actions) {
+  if (!actions.includes(args.action)) fail('BAD_ACTION', `action must be one of: ${actions.join(', ')}.`);
+  return args.action;
+}
+export function str(args, key, { required = false, max = 2000 } = {}) {
+  const v = args[key];
+  if (v === undefined || v === null || v === '') { if (required) fail('BAD_ARGS', `${key} is required.`); return undefined; }
+  if (typeof v !== 'string') fail('BAD_ARGS', `${key} must be text.`);
+  if (v.length > max) fail('BAD_ARGS', `${key} is longer than ${max} characters.`);
+  return v;
+}
+export function int(args, key, { min, max, def }) {
+  const v = args[key];
+  if (v === undefined || v === null) return def;
+  if (!Number.isInteger(v) || v < min || v > max) fail('BAD_ARGS', `${key} must be a whole number from ${min} to ${max}.`);
+  return v;
+}
+
+const inside = (p, d) => p === d || p.startsWith(d + path.sep);
+/**
+ * The folder rules for a path an extra tool reads (write=false) or writes (write=true) — the same the
+ * engine's file tools get: absolute local path only, inside the allowed list (when there is one),
+ * not in an excluded folder, not in a read-only folder for writes. → the absolute path, or throws.
+ */
+export function guard(ctx, p, { write = false, tree = false } = {}) {
+  if (typeof p !== 'string' || !p.trim()) fail('BAD_PATH', 'A file or folder path is required.');
+  const s = p.trim();
+  if (/^[\\/]{2}/.test(s)) fail('BAD_PATH', `Network and device paths ("${s}") are not allowed.`);
+  if (!/^[a-z]:[\\/]/i.test(s) && !(process.platform !== 'win32' && s.startsWith('/'))) fail('BAD_PATH', `"${s}" is not a full path.`, 'Use a full path like C:\\Users\\Name\\Documents\\file.docx.');
+  const abs = path.resolve(s);
+  const refusal = ctx.policy?.check(write ? 'write_file' : 'read_file', { path: abs });
+  if (refusal) fail('ACCESS_DENIED', refusal.replace(/^Access denied by Bridgerator: /, ''), 'Choose another folder, or ask the person to change Bridgerator → Safety.');
+  const allowed = ctx.cfg?.allowedDirectories || [];
+  if (allowed.length) {
+    const n = norm(realish(abs));
+    if (!allowed.some((d) => inside(n, norm(realish(d))))) fail('ACCESS_DENIED', `"${s}" is outside the folders allowed on this PC.`, 'Use a path inside an allowed folder (bridgerator_settings get shows them).');
+  }
+  // tree: the tool works on the whole folder (copies, walks, recycles below it) → it must not CONTAIN an
+  // excluded folder (Bridgerator's own ones included), nor a read-only one for writes.
+  if (tree && excludedInside(ctx, abs, { write }).length) fail('FOLDER_HAS_EXCLUDED', `"${s}" contains a folder that is excluded on this PC${write ? ' or read-only' : ''} (or belongs to Bridgerator), so it can't be used as a whole.`, 'Choose a subfolder that holds only the files of this task.');
+  return abs;
+}
+/**
+ * Excluded (and, for writes, read-only) folders strictly INSIDE folder `abs` → their paths relative to
+ * it (lower case, "\"-joined on Windows), [] when none. Same normalisation as policy (realish + norm).
+ */
+export function excludedInside(ctx, abs, { write = false } = {}) {
+  const nf = norm(realish(abs)), pre = nf.endsWith(path.sep) ? nf : nf + path.sep;
+  const list = [...(ctx.policy?.denied || []), ...(write ? (ctx.cfg?.readOnlyDirectories || []).map((d) => norm(realish(d))) : [])];
+  return [...new Set(list.filter((d) => d.startsWith(pre)).map((d) => d.slice(pre.length)))];
+}
+/** Paths of search results / listings that the person excluded → dropped (same as policy.filter). */
+export function visiblePath(ctx, p) {
+  try { guard(ctx, p); return true; } catch { return false; }
+}
+
+/** A new file never overwrites: "name.ext" → "name (2).ext" … when it exists. */
+export function freeName(p) {
+  if (!fs.existsSync(p)) return p;
+  const { dir, name, ext } = path.parse(p);
+  for (let i = 2; i < 1000; i++) { const c = path.join(dir, `${name} (${i})${ext}`); if (!fs.existsSync(c)) return c; }
+  fail('EXISTS', `Too many files named like "${name}${ext}".`);
+}
+
+// PowerShell: UTF-8 out, errors as text, no profile. Script text inline (-EncodedCommand, small
+// scripts) or read from package files (long scripts). Input data only through env (BRX_*) / stdin,
+// never interpolated into the script.
+const PRELUDE = "$ErrorActionPreference='Stop';$ProgressPreference='SilentlyContinue';[Console]::OutputEncoding=[Text.Encoding]::UTF8;$OutputEncoding=[Text.Encoding]::UTF8\n";
+// A script may start programs of its own: a timeout or the bridge exiting ends the whole process tree
+// (taskkill /T), not only powershell.exe.
+const live = new Set();
+export function killTree(child, { sync = false } = {}) {
+  if (!child?.pid) return;
+  if (process.platform === 'win32') {
+    const a = ['/PID', String(child.pid), '/T', '/F'];
+    try {
+      if (sync) spawnSync(TASKKILL, a, { windowsHide: true, stdio: 'ignore', timeout: 5000 });
+      else { const k = spawn(TASKKILL, a, { windowsHide: true, stdio: 'ignore' }); k.on('error', () => { try { child.kill(); } catch { /* gone */ } }); return; }
+    } catch { /* fall back to kill */ }
+  }
+  try { child.kill(); } catch { /* gone */ }
+}
+process.once('exit', () => { for (const c of live) killTree(c, { sync: true }); });
+/**
+ * → { code, stdout, stderr }. opts: { files: [abs .ps1 paths] } or { script }, env: {}, timeout ms, input.
+ * Not Windows → ToolError NOT_WINDOWS.
+ */
+export function runPs({ script, files, env = {}, timeout = 60000, input } = {}) {
+  if (process.platform !== 'win32') return Promise.reject(new ToolError('NOT_WINDOWS', 'This works only on Windows.'));
+  const cmd = files ? PRELUDE + runFilesPs(...files) : PRELUDE + script;
+  return new Promise((resolve, reject) => {
+    // PSModulePath of a PowerShell 7 parent would make 5.1 load the wrong modules: let 5.1 use its own.
+    const base = stripOurs(process.env);
+    for (const k of Object.keys(base)) if (k.toLowerCase() === 'psmodulepath') delete base[k];
+    const child = spawn(POWERSHELL, psArgs(cmd), { windowsHide: true, env: { ...base, ...env }, stdio: ['pipe', 'pipe', 'pipe'] });
+    const out = [], err = [];
+    let size = 0, done = false;
+    live.add(child);
+    const timer = setTimeout(() => { if (!done) { killTree(child); finish(new ToolError('TIMEOUT', 'Windows took too long to answer.', 'Try again, or ask for less at once.')); } }, timeout);
+    const finish = (e, r) => { if (done) return; done = true; clearTimeout(timer); live.delete(child); e ? reject(e) : resolve(r); };
+    child.stdout.on('data', (b) => { size += b.length; if (size < 64 * 1024 * 1024) out.push(b); });
+    child.stderr.on('data', (b) => { if (err.length < 200) err.push(b); });
+    child.on('error', (e) => finish(new ToolError('PS_START', `PowerShell did not start: ${e.code || e.message}.`, 'Check that Windows PowerShell is not blocked on this PC.')));
+    child.on('close', (code) => finish(null, { code, stdout: Buffer.concat(out).toString('utf8'), stderr: Buffer.concat(err).toString('utf8') }));
+    child.stdin.on('error', () => { /* child exited early: close reports it */ });
+    child.stdin.end(input ?? '');
+  });
+}
+/** Runs a script that prints ONE JSON object as its last line → that object. ps = ctx.runPs (tests) or runPs. */
+export async function psJson(ctx, opts) {
+  const r = await (ctx?.runPs || runPs)(opts);
+  const lines = String(r.stdout || '').trim().split(/\r?\n/).filter(Boolean);
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const l = lines[i].trim();
+    if (l.startsWith('{') || l.startsWith('[')) { try { return JSON.parse(l); } catch { /* not this line */ } }
+  }
+  const why = clean(r.stderr).split(/\r?\n/)[0] || `exit code ${r.code}`;
+  throw new ToolError('PS_FAILED', `Windows could not do it: ${why}`, 'Try again; if it repeats, run "bridgerator doctor" on the PC.');
+}
+export const pkgFile = (rel) => new URL(rel, import.meta.url);

package/src/tool-text.mjs

@@ -0,0 +1,45 @@
+// LOGIC: see critical-logic/bridge.md ("Tool descriptions"). The engine's own tool descriptions are long
+// and imperative (IMPORTANT / ALWAYS / MUST, caps): they cost tokens on every request and make ChatGPT's
+// safety layer flag the app ("suspicious instruction"). The bridge sends these short, plain ones
+// instead; names, schemas and annotations stay the engine's. A tool missing here keeps its debranded
+// engine text (a new engine version still works).
+const SHARED = ' Other chats may use this PC at the same time: re-read a file right before changing it.';
+export const SHORT = {
+  get_config: 'Shows this PC\'s engine settings: allowed folders, blocked commands, default shell, line limits and system info.',
+  read_file: 'Reads a local file. Text: offset/length in lines (negative offset = last lines). Excel: sheet and range like "A1:D100". PDF: text by pages. DOCX: an outline by default; offset ≥ 1 gives the raw XML for edit_block. Images come back viewable. Use absolute paths.',
+  read_multiple_files: 'Reads several files at once (text and images); a failed file does not stop the others. Use absolute paths.',
+  write_file: `Writes a file: mode "rewrite" (default) or "append". Long files are best written in parts of about 30 lines (first rewrite, then append). Excel: a JSON 2D array or {"Sheet": [[...]]}. A new .docx can be written from markdown-style text; edit existing .docx with edit_block. Previous content is kept for Undo.${SHARED}`,
+  create_directory: 'Creates a folder, including missing parent folders.',
+  list_directory: 'Lists a folder with [FILE] / [DIR] marks; depth sets how many levels (default 2, nested folders show up to 100 items).',
+  move_file: `Moves or renames a file or folder. It can be undone (bridgerator_undo).${SHARED}`,
+  start_search: 'Starts a background search and returns a session id. searchType "files" matches names, "content" searches inside files; literalSearch for exact text with special characters; filePattern like "*.js". Read results with get_more_search_results.',
+  get_more_search_results: 'Returns results of a search started with start_search; offset/length page through them (negative offset = last results).',
+  stop_search: 'Stops a running search; its results stay readable for a few minutes.',
+  list_searches: 'Lists running searches with their ids and status.',
+  get_file_info: 'File or folder details: size, dates, type; line counts for text files, sheets for Excel files.',
+  edit_block: `Edits a file in place. Text and DOCX: replaces old_string with new_string (one match unless expected_replacements says more; include a few lines of context). Excel: range like "Sheet1!A1:C10" with content as a 2D array. Previous content is kept for Undo.${SHARED}`,
+  start_process: 'Runs a command or program in a terminal session on this PC (PowerShell by default; shell can be "cmd"). Returns the output, or the session pid when it keeps running. Follow up with read_process_output or interact_with_process. Simple delete commands move files to the Recycle Bin.',
+  read_process_output: 'Reads new output from a running session (offset/length in lines; negative offset = last lines) and shows whether it waits for input or has finished.',
+  interact_with_process: 'Sends input to a running session or REPL (pid from start_process) and returns the new output.',
+  force_terminate: 'Stops a terminal session started with start_process.',
+  list_sessions: 'Lists terminal sessions: pid, whether one waits for input, how long it runs.',
+  list_processes: 'Lists running programs with pid, CPU and memory.',
+  kill_process: 'Ends a running program by pid.',
+  get_prompts: 'Returns a ready-made task prompt by id (action "get_prompt").',
+};
+
+// Our own tools: hints for the client (the relay passes them as they are).
+const RO = { readOnlyHint: true, destructiveHint: false, openWorldHint: false };
+const RW = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, openWorldHint: false };
+export const OWN_ANNOTATIONS = {
+  queue_list: RO, queue_next: RW, queue_update: RW, queue_add: RW, queue_edit: RW, queue_reorder: RW, queue_clear: DESTRUCTIVE,
+  bridgerator_setup: RW, bridgerator_settings: RW, request_confirm_off: RW, confirm_on: RW, bridgerator_undo: DESTRUCTIVE,
+};
+
+/** Tool (debranded) → the short description; annotations kept, ours added. */
+export function shorten(t) {
+  const d = SHORT[t.name];
+  const ann = t.annotations || OWN_ANNOTATIONS[t.name];
+  return { ...t, ...(d ? { description: d } : {}), ...(ann ? { annotations: ann } : {}) };
+}

package/src/tray.mjs

@@ -0,0 +1,97 @@
+// The tray helper (tray.ps1, one hidden PowerShell per bridge) and the JSON-lines link to it:
+// icon + menu (Pause / Resume / Quit), the questions on the PC (toast / fallback window, already
+// loaded → instant) and the requests of its window (rpc → handled in the bridge, rpc.mjs).
+import os from 'node:os';
+import readline from 'node:readline';
+import { spawn as nodeSpawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { POWERSHELL } from './win.mjs';
+import { runFilesPs, askOnPc, stripOurs } from './ask.mjs';
+import { localizeAsk, attrLine } from './pc-text.mjs';
+
+const LIB = fileURLToPath(new URL('./ask-lib.ps1', import.meta.url));
+const TRAY = fileURLToPath(new URL('./tray.ps1', import.meta.url));
+export const PKG_DIR = fileURLToPath(new URL('..', import.meta.url)).replace(/[\\/]+$/, '');
+
+/**
+ * The protocol, without the process: `write(line)` sends to the helper; feed helper lines to
+ * `onLine`. onMenu(action), onRpc(method, params, paths) → Promise<result>.
+ */
+export function createLink(write, { onMenu = () => {}, onRpc = async () => null, onLog = () => {}, onPower = () => {}, now = Date.now, setTimer = setTimeout } = {}) {
+  let ready = false, seq = 0;
+  const waiting = new Map(); // id → { resolve, keys, timer }
+  const send = (o) => write(`${JSON.stringify(o)}\n`);
+  const finish = (id, key) => { const w = waiting.get(id); if (!w) return; waiting.delete(id); clearTimeout(w.timer); w.resolve(w.keys.includes(key) ? key : 'deny'); };
+  return {
+    get ready() { return ready; },
+    onLine(line) {
+      let m; try { m = JSON.parse(line); } catch { return; }
+      if (m.t === 'ready') ready = true;
+      else if (m.t === 'log' && typeof m.msg === 'string') onLog(m.msg.slice(0, 2000));
+      // Keep-awake as the helper applied it: on = holding the PC awake, ac = on mains power.
+      else if (m.t === 'power') onPower({ on: m.on === true, ac: m.ac !== false });
+      else if (m.t === 'answer' && typeof m.id === 'string') finish(m.id, String(m.key));
+      else if (m.t === 'menu' && ['pause', 'resume', 'quit', 'confirm'].includes(m.action)) onMenu(m.action, { minutes: Number.isInteger(m.minutes) ? m.minutes : undefined, on: m.on === true });
+      else if (m.t === 'rpc' && typeof m.id === 'string' && typeof m.method === 'string') {
+        Promise.resolve().then(() => onRpc(m.method, m.params ?? {}, Array.isArray(m.paths) ? m.paths.filter((p) => typeof p === 'string') : []))
+          .then((result) => send({ t: 'rpc-result', id: m.id, result: result ?? null }), (e) => send({ t: 'rpc-result', id: m.id, error: String(e?.message || e) }));
+      }
+    },
+    state: (o) => send({ t: 'state', ...o }),
+    open: (page) => send({ t: 'open', page }),
+    /** Same contract as askOnPc → the chosen key, 'deny' on timeout / no helper. */
+    ask(q0) {
+      // The PC's language (V-3): fixed texts, buttons and the "auto-deny in 2 min" line.
+      const { head, text, buttons, secs = 120, host = os.hostname(), auto = 'auto-deny', theme = 'system', silent = false, style = 'toast', lang = 'en' } = localizeAsk({ ...q0, auto: q0.auto || 'auto-deny' }, q0.lang);
+      const id = `a${++seq}-${now().toString(36)}`;
+      const attr = attrLine(host, auto, secs, lang);
+      return new Promise((resolve) => {
+        const timer = setTimer(() => finish(id, 'deny'), (secs + 15) * 1000);
+        waiting.set(id, { resolve, keys: buttons.map((b) => b[0]), timer });
+        send({ t: 'ask', id, head, detail: text, attr, host, auto, secs, theme, silent, style, buttons, lang: lang === 'ru' ? 'ru' : 'en' });
+      });
+    },
+    lost() { ready = false; for (const id of [...waiting.keys()]) finish(id, 'deny'); },
+  };
+}
+
+/** Starts the helper (Windows only) and keeps it running while the bridge runs. → link-like object. */
+export function startTray({ log = console.log, onMenu, onRpc, onPower, spawn = nodeSpawn, stderr = 'ignore', testEnv = {}, account = '' } = {}) {
+  if (process.platform !== 'win32') return null;
+  let child = null, link = null, closing = false, restartTimer = null;
+  // Our own variables only: BR_* / BRIDGERATOR_* from the environment are ignored (a test harness
+  // passes its hooks explicitly as testEnv).
+  // BR_ACCOUNT: the account page of the site this PC is linked to (a staging install opens staging; V-5).
+  const env = { ...stripOurs(process.env), ...testEnv, BR_PARENT: String(process.pid), BR_PKG: PKG_DIR, ...(/^https:\/\/[a-z0-9.-]+(:\d+)?\/app$/i.test(account) ? { BR_ACCOUNT: account } : {}) };
+  const start = () => {
+    // Plain -Command (not encoded): its command line names the package folder, so the one process
+    // matcher (stop / update / uninstall) finds the helper too.
+    child = spawn(POWERSHELL, ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', runFilesPs(LIB, TRAY)], { env, stdio: ['pipe', 'pipe', stderr], windowsHide: true });
+    const c = child;
+    // An EPIPE after the helper died is an 'error' event on the stream: without a listener it would crash the bridge.
+    c.stdin?.on('error', () => {});
+    link = createLink((l) => { try { c.stdin.write(l); } catch { /* gone */ } }, { onMenu, onRpc, onPower, onLog: (msg) => log(`[bridgerator] ${msg}`) });
+    readline.createInterface({ input: child.stdout }).on('line', (l) => link.onLine(l));
+    child.on('error', (e) => log(`[bridgerator] tray: ${e.message}`));
+    child.on('exit', (code) => {
+      link.lost();
+      if (!closing) { log(`[bridgerator] tray helper stopped (${code}); restarting in 30 s`); restartTimer = setTimeout(() => { restartTimer = null; if (!closing) start(); }, 30000); restartTimer.unref(); }
+    });
+  };
+  start();
+  // Questions go through the helper when it is up, otherwise one PowerShell per question.
+  return {
+    get ready() { return !!link?.ready; },
+    get pid() { return child?.pid; },
+    ask: (q) => (link?.ready ? link.ask(q) : askOnPc(q)),
+    state: (o) => link?.state(o),
+    open: (page) => link?.open(page),
+    // 'exit' + closing stdin let the helper hide + dispose its tray icon itself (a kill leaves a ghost icon); the kill is the fallback.
+    close: () => {
+      closing = true; clearTimeout(restartTimer);
+      try { child?.stdin?.write('{"t":"exit"}\n'); } catch { /* gone */ }
+      try { child?.stdin?.end(); } catch { /* gone */ }
+      const c = child; const t = setTimeout(() => { try { c?.kill(); } catch { /* gone */ } }, 2000); t.unref();
+    },
+  };
+}