bridgerator 1.0.7 → 1.1.0

package/src/recent.mjs

@@ -0,0 +1,48 @@
+// "Recent on this PC": the last 100 tool calls WITH their command / path, for the person at the PC.
+// In memory; with "Keep a local history" on also in %APPDATA%\Bridgerator\recent.jsonl (inside the
+// always-excluded folder), entries older than 7 days dropped. Never sent to the server.
+import fs from 'node:fs';
+
+export const KEEP = 100;
+export const DAYS = 7;
+const short = (s, n = 300) => { s = String(s ?? ''); return s.length > n ? `${s.slice(0, n - 1)}…` : s; };
+
+export function target(a = {}) {
+  if (!a || typeof a !== 'object') return '';
+  if (a.source && a.destination) return short(`${a.source} → ${a.destination}`);
+  const t = a.command ?? a.input ?? a.path ?? a.file_path ?? (Array.isArray(a.paths) ? a.paths.join(', ') : undefined) ?? a.pattern ?? a.title ?? a.id;
+  return t === undefined ? '' : short(typeof t === 'string' ? t : JSON.stringify(t));
+}
+
+export function createRecent(file, { keepFile = false, now = Date.now } = {}) {
+  let list = [], keep = keepFile;
+  const fresh = (e) => now() - e.t < DAYS * 86400000;
+  const prune = () => {
+    if (!keep) return;
+    try {
+      const lines = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean);
+      const ok = lines.filter((l) => { try { return fresh(JSON.parse(l)); } catch { return false; } });
+      if (ok.length !== lines.length || ok.length > KEEP * 10) fs.writeFileSync(file, ok.slice(-KEEP * 10).join('\n') + (ok.length ? '\n' : ''));
+    } catch { /* no file */ }
+  };
+  if (keep) { prune(); try { list = fs.readFileSync(file, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l)).filter(fresh).slice(-KEEP); } catch { /* none */ } }
+  let lastPrune = now();
+  return {
+    record(name, args, outcome, extra) {
+      const e = { t: now(), tool: String(name), target: target(args), outcome, ...(extra && typeof extra === 'object' ? extra : {}) };
+      list.push(e); if (list.length > KEEP) list.shift();
+      if (keep) {
+        try { fs.appendFileSync(file, JSON.stringify(e) + '\n'); } catch { /* read-only */ }
+        if (now() - lastPrune > 86400000) { lastPrune = now(); prune(); }
+      }
+      return e;
+    },
+    list: () => [...list].reverse(),
+    clear() { list = []; try { fs.rmSync(file, { force: true }); } catch { /* none */ } },
+    setKeep(v) { keep = !!v; if (!keep) { try { fs.rmSync(file, { force: true }); } catch { /* none */ } } else for (const e of list) try { fs.appendFileSync(file, JSON.stringify(e) + '\n'); } catch { /* */ } },
+    get keep() { return keep; },
+  };
+}
+
+/** Result of a call → ok | error | refused | not confirmed | paused. */
+export const outcomeOf = (r) => (r?.paused ? 'paused' : r?.notConfirmed ? 'not confirmed' : r?.refused ? 'refused' : r?.isError ? 'error' : 'ok');

package/src/recipes.mjs

@@ -0,0 +1,108 @@
+// LOGIC: see critical-logic/bridge.md ("Automations and recipes"). Ready-made PowerShell scripts
+// (recipes/*.json in the package): the AI runs one with parameters or saves it as an automation.
+// A recipe becomes ONE plain script: a `$P = @{…}` block with the checked parameters (single-quoted
+// literals, every quote character doubled), then the recipe's own lines. Paths go through the same
+// folder rules as the file tools (tool-lib guard); the whole script then through policy.check like a
+// terminal command (bridge.mjs / automations.mjs), so an excluded folder can't hide in a parameter.
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { expandVars, norm } from './policy.mjs';
+import { ToolError, fail, guard, excludedInside } from './tool-lib.mjs';
+
+export const RECIPE_IDS = ['backup-folder', 'clean-downloads', 'sort-folder', 'disk-report', 'update-apps'];
+const DIR = new URL('../recipes/', import.meta.url);
+let cache = null;
+export function loadRecipes() {
+  cache ||= RECIPE_IDS.map((id) => JSON.parse(fs.readFileSync(new URL(`${id}.json`, DIR), 'utf8')));
+  return cache;
+}
+const byId = (id) => loadRecipes().find((r) => r.id === id) || fail('NO_RECIPE', `There is no recipe "${id}".`, `Use one of: ${RECIPE_IDS.join(', ')} (action "recipes" lists them).`);
+
+/** What the AI gets from action "recipes" (English, parameters with types and defaults). */
+export function recipeList(lang = 'en') {
+  const l = (o) => (o && (o[lang] || o.en)) || '';
+  return loadRecipes().map((r) => ({
+    id: r.id, title: l(r.title), description: l(r.description), suggestedSchedule: r.schedule,
+    params: r.params.map((p) => ({ name: p.name, type: p.type, ...(p.required ? { required: true } : {}), ...(p.default !== undefined ? { default: p.default } : {}), ...(p.values ? { values: p.values } : {}), ...(p.min !== undefined ? { min: p.min, max: p.max } : {}), description: l(p.description) })),
+  }));
+}
+export const recipeTitle = (id) => { const r = loadRecipes().find((x) => x.id === id); return r ? r.title : null; };
+
+// PowerShell single-quoted literal. PowerShell treats ' ‘ ’ ‚ ‛ all as single quotes; doubling each
+// one keeps it literal. Control characters are refused before this (no line breaks in a value).
+export const psQuote = (s) => `'${String(s).replace(/['‘’‚‛]/g, (c) => c + c)}'`;
+const CTRL = /[\u0000-\u001f\u007f\u2028\u2029]/;
+
+// The Recycle Bin helper of the bridge itself (recycle.ps1, IFileOperation without UI; an item that
+// would be deleted for good is left alone). Copied into the script: a scheduled run needs no package.
+export function recycleLib() {
+  const t = fs.readFileSync(fileURLToPath(new URL('./recycle.ps1', import.meta.url)), 'utf8');
+  const m = /Add-CachedType @'\r?\n([\s\S]*?)\r?\n'@/.exec(t);
+  if (!m || !/class BrRecycle\b/.test(m[1])) throw new ToolError('INTERNAL', 'The Recycle Bin helper of this Bridgerator version could not be read.', 'Update Bridgerator.');
+  // Plain Add-Type (not ask-lib's Add-CachedType): its cache is in Bridgerator's own folder, which a
+  // recipe / scheduled script may never name (policy.check refuses such a script).
+  return `Add-Type -TypeDefinition @'\n${m[1]}\n'@`;
+}
+
+/** Relative folder path → "<depth>:<first 16 hex of SHA-256 of it in lower case>" (the recipe's walk computes the same). */
+export const skipId = (rel) => `${rel.split(/[\\/]/).length}:${crypto.createHash('sha256').update(rel.toLowerCase(), 'utf8').digest('hex').slice(0, 16)}`;
+
+function readParam(ctx, spec, v, all, skips = {}) {
+  const bad = (why) => fail('BAD_ARGS', `${spec.name}: ${why}.`);
+  if (spec.type === 'bool') { if (typeof v !== 'boolean') bad('must be true or false'); return v; }
+  if (spec.type === 'int') { if (!Number.isInteger(v) || v < spec.min || v > spec.max) bad(`must be a whole number from ${spec.min} to ${spec.max}`); return v; }
+  if (spec.type === 'enum') { if (!spec.values.includes(v)) bad(`must be one of ${spec.values.join(', ')}`); return v; }
+  if (spec.type === 'path') {
+    if (typeof v !== 'string' || !v.trim() || v.length > 1000 || CTRL.test(v)) bad('must be a full folder or file path on one line');
+    // A folder parameter is used as a whole tree (copied, walked, recycled below it): it must not contain an
+    // excluded / Bridgerator folder (FOLDER_HAS_EXCLUDED), except tree "skip": the script skips them itself.
+    const write = spec.access === 'write', folder = !spec.ext;
+    const abs = guard(ctx, expandVars(v.trim()), { write, tree: folder && spec.tree !== 'skip' });
+    if (folder && spec.tree === 'skip') skips[spec.name] = excludedInside(ctx, abs, { write }).map(skipId);
+    if (spec.mustExist) { let ok = false; try { ok = fs.statSync(abs).isDirectory(); } catch { /* missing */ } if (!ok) fail('NOT_FOUND', `${spec.name}: the folder "${abs}" does not exist.`, 'Check the path (list the folder first).'); }
+    if (spec.ext && path.extname(abs).toLowerCase() !== spec.ext) bad(`must end with ${spec.ext}`);
+    if (spec.notInside && all[spec.notInside]) {
+      const a = norm(abs), b = norm(all[spec.notInside]);
+      if (a === b || a.startsWith(b + path.sep) || b.startsWith(a + path.sep)) bad(`must not be inside ${spec.notInside} (or contain it)`);
+    }
+    return abs;
+  }
+  bad('unknown type');
+}
+
+/**
+ * → { recipe: id, params: {checked values}, script }. ctx: { cfg, policy } (folder rules).
+ * Throws ToolError on a wrong / missing parameter or a path the folder rules refuse.
+ */
+export function buildRecipe(ctx, id, input = {}) {
+  const r = byId(id);
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) fail('BAD_ARGS', 'params must be an object.');
+  const unknown = Object.keys(input).filter((k) => !r.params.some((p) => p.name === k));
+  if (unknown.length) fail('BAD_ARGS', `Unknown parameter(s) for ${id}: ${unknown.join(', ')}.`, `Parameters: ${r.params.map((p) => p.name).join(', ')}.`);
+  const out = {}, skips = {};
+  for (const spec of r.params) {
+    let v = input[spec.name];
+    if (v === undefined || v === null || v === '') {
+      if (spec.required) fail('BAD_ARGS', `${spec.name} is required for ${id}.`);
+      if (spec.default === undefined) { out[spec.name] = null; continue; }
+      v = spec.default;
+    }
+    out[spec.name] = readParam(ctx, spec, v, out, skips);
+  }
+  const lit = (v) => (v === null ? '$null' : typeof v === 'boolean' ? (v ? '$true' : '$false') : typeof v === 'number' ? String(v) : psQuote(v));
+  const body = r.script.join('\n').replace('#RECYCLE#', () => recycleLib());
+  const script = [
+    `# Recipe "${r.id}" (${r.title.en}). Parameters:`,
+    "$ErrorActionPreference = 'Continue'",
+    '$P = @{',
+    ...r.params.map((p) => `  ${p.name} = ${lit(out[p.name])}`),
+    // Excluded folders below a tree "skip" folder as "<depth>:<hash of the relative path>" (skipId): the
+    // script never names them (it may not mention an excluded folder or Bridgerator).
+    ...Object.entries(skips).map(([k, l]) => `  ${k}Skip = @(${l.map(psQuote).join(', ')})`),
+    '}',
+    body,
+  ].join('\n');
+  return { recipe: r.id, params: out, script };
+}

package/src/recycle.mjs

@@ -0,0 +1,185 @@
+// LOGIC: see critical-logic/bridge.md ("Recycle Bin"). A delete command the AI runs in the terminal
+// goes to the Recycle Bin instead, when Bridgerator can read it for sure: ONE delete statement
+// (Remove-Item / ri / rm / del / erase / rd / rmdir, optionally inside `cmd /c`) with plain paths or a
+// wildcard in the last part. Anything else (pipes, ;, &&, variables, loops, scripts, other programs
+// that delete) runs as written — a safety net, not a guarantee (said so in the window and on the site).
+// The move itself: recycle.ps1 (IFileOperation; an item the shell would delete for good is left alone
+// and reported 'nobin' → the bridge asks on the PC before a permanent delete).
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { POWERSHELL, psArgs } from './win.mjs';
+import { runFilesPs, stripOurs } from './ask.mjs';
+
+const VERBS = new Set(['remove-item', 'ri', 'rm', 'del', 'erase', 'rd', 'rmdir']);
+const MAX_TARGETS = 1000;
+const RECURSE = new Set(['-recurse', '-r', '-rf', '-fr', '--recursive', '/s']);
+const QUIET = new Set(['-force', '-f', '--force', '-v', '-verbose', '/q', '/f', '/a', '-confirm:$false']);
+
+function tokenize(s) {
+  const out = [];
+  let cur = '', q = null, quoted = false;
+  const push = () => { if (cur || quoted) out.push({ v: cur, quoted }); cur = ''; quoted = false; };
+  for (const ch of s) {
+    if (q) { if (ch === q) q = null; else cur += ch; continue; }
+    if (ch === '"' || ch === "'") { q = ch; quoted = true; continue; }
+    if (/\s/.test(ch)) { push(); continue; }
+    if (ch === ',') { push(); out.push({ v: ',', sep: true }); continue; }
+    cur += ch;
+  }
+  if (q) return null;                       // unbalanced quote
+  push();
+  return out;
+}
+
+const hasWild = (s) => /[*?]/.test(s);
+const wildRe = (seg) => new RegExp(`^${seg.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.')}$`, 'i');
+const kindOf = (p) => { try { const s = fs.lstatSync(p); return s.isDirectory() ? 'dir' : 'file'; } catch { return null; } };
+const isEmptyDir = (p) => { try { return fs.readdirSync(p).length === 0; } catch { return false; } };
+
+/**
+ * One delete command → { verb, targets: [absolute paths], recurse } when Bridgerator can do exactly
+ * what it asks (each target exists, folders only with a recurse flag or empty), else null (the
+ * command then runs as written).
+ */
+export function parseDelete(command, cwd = os.homedir(), home = os.homedir()) {
+  let s = String(command ?? '').trim();
+  if (!s || s.length > 4000) return null;
+  const wrapped = /^cmd(?:\.exe)?\s+\/[ck]\s+(.+)$/i.exec(s);
+  if (wrapped) { s = wrapped[1].trim(); if (/^"[^"]*"$/.test(s)) s = s.slice(1, -1); }
+  s = s.replace(/\s-Confirm:\$false\b/gi, ' -confirm:$false');
+  // Only plain text: no statements, pipes, redirects, variables, sub-expressions, escapes, line breaks.
+  if (/[;&|<>`\r\n{}()@%]/.test(s) || /\$(?!false\b)/i.test(s)) return null;
+  const tok = tokenize(s);
+  if (!tok || !tok.length) return null;
+  const verb = tok[0].v.toLowerCase().replace(/\.exe$/, '');
+  if (tok[0].quoted || !VERBS.has(verb)) return null;
+  const cmdStyle = ['del', 'erase', 'rd', 'rmdir'].includes(verb);
+  let recurse = false, literal = false, force = false, allAttrs = false;
+  const raw = [];
+  for (let i = 1; i < tok.length; i++) {
+    const t = tok[i];
+    if (t.sep) continue;
+    const low = t.v.toLowerCase();
+    if (!t.quoted && /^(-|\/[a-z]|\/[a-z]:)/i.test(t.v) && !/^\/[a-z]:?[\\/]/i.test(t.v)) {
+      if (RECURSE.has(low)) { recurse = true; continue; }
+      if (low === '-force' || low === '/f') force = true;
+      if (low === '/a') allAttrs = true;
+      if (/^\/a:[a-z-]+$/.test(low)) { allAttrs = 'filter'; continue; }
+      if (QUIET.has(low)) continue;
+      if (low === '-path') continue;
+      if (low === '-literalpath' || low === '-lp') { literal = true; continue; }
+      if (low === '-erroraction' || low === '-ea') { i++; continue; }
+      return null;                          // a flag we don't know: run as written
+    }
+    raw.push(t.v);
+  }
+  if (!raw.length || (cmdStyle && (verb === 'del' || verb === 'erase') && recurse)) return null; // del /s *.tmp: every subfolder
+  const targets = [];
+  // Wildcard matches the command itself would skip: hidden / system items (del without /a,
+  // Remove-Item without -Force) and read-only files (without /f or -Force). Checked by recycle.ps1.
+  const skip = cmdStyle ? `${allAttrs === true ? '' : 'hs'}${force ? '' : 'r'}` : force ? '' : 'hsr';
+  const wild = [];
+  for (let p of raw) {
+    if (/^[\\/]{2}/.test(p) || /^[a-z][a-z0-9+.-]*:\/\//i.test(p)) return null;
+    if (!literal && /[[\]]/.test(p)) return null;
+    if (p === '~' || /^~[\\/]/.test(p)) p = path.join(home, p.slice(1));
+    const abs = path.resolve(cwd, p);
+    if (!literal && hasWild(abs)) {
+      const dir = path.dirname(abs), seg = path.basename(abs);
+      // rd / rmdir take no wildcards; /a:<attributes> filters we don't copy: run as written.
+      if (hasWild(dir) || verb === 'rd' || verb === 'rmdir' || allAttrs === 'filter') return null;
+      let names;
+      try { names = fs.readdirSync(dir); } catch { return null; }
+      const re = wildRe(seg);
+      const hits = names.filter((n) => re.test(n)).map((n) => path.join(dir, n));
+      if (!hits.length) return null;
+      for (const h of hits) {
+        const k = kindOf(h);
+        if (k === 'dir') { if (verb === 'del' || verb === 'erase') continue; if (!recurse && !isEmptyDir(h)) return null; }
+        targets.push(h);
+        wild.push(h);
+      }
+      continue;
+    }
+    const k = kindOf(abs);
+    if (!k) return null;
+    if (k === 'dir' && (verb === 'del' || verb === 'erase')) return null; // del <folder> deletes the files inside
+    if (k === 'dir' && !recurse && !isEmptyDir(abs)) return null;
+    if (k === 'file' && (verb === 'rd' || verb === 'rmdir')) return null;
+    targets.push(abs);
+  }
+  const uniq = [...new Set(targets)];
+  if (!uniq.length || uniq.length > MAX_TARGETS) return null;
+  return { verb, targets: uniq, recurse, ...(wild.length && skip ? { skip: Object.fromEntries(wild.map((h) => [h, skip])) } : {}) };
+}
+
+const LIB = fileURLToPath(new URL('./ask-lib.ps1', import.meta.url));
+const PS = fileURLToPath(new URL('./recycle.ps1', import.meta.url));
+
+/**
+ * Moves the paths to the Recycle Bin → [{ p, r: 'recycled' | 'nobin' | 'missing' | 'skipped' | 'error:…' }].
+ * skip: { path: 'hsr' } — leave that item alone ('skipped') when it is hidden (h) / system (s) / read-only (r).
+ */
+export function recycle(paths, { timeoutMs = 120000, skip = {} } = {}) {
+  if (process.platform !== 'win32') return Promise.resolve(paths.map((p) => ({ p, r: 'nobin' })));
+  return new Promise((resolve) => {
+    const fail = (why) => resolve(paths.map((p) => ({ p, r: `error:${why}` })));
+    const chunks = [];
+    let done = false;
+    const child = spawn(POWERSHELL, psArgs(runFilesPs(LIB, PS)), { windowsHide: true, env: stripOurs(process.env), stdio: ['pipe', 'pipe', 'pipe'] });
+    const timer = setTimeout(() => { try { child.kill(); } catch { /* gone */ } if (!done) { done = true; fail('timeout'); } }, timeoutMs);
+    child.stdout.on('data', (b) => { chunks.push(b); }); // decoded once at the end: a UTF-8 character may span chunks
+    child.stderr.on('data', () => {});
+    child.on('error', (e) => { clearTimeout(timer); if (!done) { done = true; fail(e.code || 'spawn'); } });
+    child.on('close', () => {
+      clearTimeout(timer);
+      if (done) return;
+      done = true;
+      try {
+        const r = JSON.parse(Buffer.concat(chunks).toString('utf8').trim().split(/\r?\n/).pop());
+        const list = Array.isArray(r) ? r : [r];
+        resolve(paths.map((p) => list.find((x) => x && x.p === p) || { p, r: 'error:no-answer' }));
+      } catch { fail('bad-answer'); }
+    });
+    // PowerShell gone early (EPIPE): the error is reported through 'close' / the timeout, never thrown.
+    child.stdin.on('error', () => {});
+    child.stdin.end(JSON.stringify(paths.map((p) => ({ p, skip: typeof skip[p] === 'string' ? skip[p] : '' }))));
+  });
+}
+
+// --- Undo of a delete: the restored item's copy leaves the Recycle Bin too ----------------------
+// Each recycled item is a pair in <drive>\$Recycle.Bin\<SID>\: $I<id> (original path + deletion time)
+// and $R<id> (the item itself). Only this user's folder is readable, so only their items match.
+const FILETIME_EPOCH_MS = 11644473600000;
+/** $I file → { path, t } (format 1: Vista–8, 2: Windows 10+), or null. */
+export function readBinInfo(buf) {
+  try {
+    const v = Number(buf.readBigInt64LE(0));
+    const t = Number(buf.readBigInt64LE(16) / 10000n) - FILETIME_EPOCH_MS;
+    const p = v === 2 ? buf.toString('utf16le', 28, 28 + (buf.readUInt32LE(24) - 1) * 2) : v === 1 ? buf.toString('utf16le', 24, 24 + 520) : null;
+    return p ? { path: p.replace(/\0.*$/s, ''), t } : null;
+  } catch { return null; }
+}
+/**
+ * Removes from the Recycle Bin exactly the copies this bridge made: items = [{ path, bin }], bin = the
+ * $R path recycle.ps1 reported when it recycled `path`. Removed only when that pair is still there and
+ * its $I names that same original path; an item without a recorded copy is left alone (never another
+ * bin entry — it may be the person's own later deletion). → the paths whose bin copy was removed. Never throws.
+ */
+export function purgeFromBin(items) {
+  const gone = [];
+  for (const it of Array.isArray(items) ? items : []) {
+    try {
+      const r = typeof it?.bin === 'string' ? path.resolve(it.bin) : '', n = path.basename(r);
+      if (!/^\$R/i.test(n) || path.basename(path.dirname(path.dirname(r))).toLowerCase() !== '$recycle.bin') continue;
+      const i = path.join(path.dirname(r), `$I${n.slice(2)}`);
+      const info = readBinInfo(fs.readFileSync(i));
+      if (!info || path.resolve(info.path).toLowerCase() !== path.resolve(String(it.path)).toLowerCase()) continue;
+      fs.rmSync(r, { recursive: true, force: true }); fs.rmSync(i, { force: true }); gone.push(it.path);
+    } catch { /* gone already / in use: stays in the bin */ }
+  }
+  return gone;
+}

package/src/recycle.ps1

@@ -0,0 +1,110 @@
+# Bridgerator: move files / folders to the Recycle Bin (never a permanent delete). Loaded after
+# ask-lib.ps1 (Add-CachedType). Reads a JSON list of absolute paths on stdin, prints one JSON line:
+# [{p, r}] with r = 'recycled' | 'nobin' (this drive has no Recycle Bin / the item is too big for it:
+# nothing was deleted) | 'missing' | 'error:<hresult>'; a recycled item also carries bin = the path of
+# its copy in the Recycle Bin ($R...), so Undo later removes exactly that copy and no other.
+# IFileOperation with FOFX_RECYCLEONDELETE and no UI; a progress sink checks PreDeleteItem: without
+# TSF_DELETE_RECYCLE_IF_POSSIBLE the shell would delete for good, so the item is aborted instead.
+$ErrorActionPreference = 'Stop'
+[Console]::InputEncoding = [Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)
+Add-CachedType @'
+using System; using System.IO; using System.Runtime.InteropServices;
+[ComImport, Guid("43826d1e-e718-42ee-bc55-a1e261c37bfe"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+public interface IBrShellItem { void BindToHandler(IntPtr pbc, ref Guid bhid, ref Guid riid, out IntPtr ppv); void GetParent(out IBrShellItem ppsi); void GetDisplayName(uint sigdn, out IntPtr name); void GetAttributes(uint mask, out uint attrs); void Compare(IBrShellItem psi, uint hint, out int order); }
+[ComImport, Guid("04b0f1a7-9490-44bc-96e1-4296a31252e2"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+public interface IBrSink {
+  [PreserveSig] int StartOperations();
+  [PreserveSig] int FinishOperations(int hr);
+  [PreserveSig] int PreRenameItem(uint f, IBrShellItem i, [MarshalAs(UnmanagedType.LPWStr)] string n);
+  [PreserveSig] int PostRenameItem(uint f, IBrShellItem i, [MarshalAs(UnmanagedType.LPWStr)] string n, int hr, IBrShellItem c);
+  [PreserveSig] int PreMoveItem(uint f, IBrShellItem i, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n);
+  [PreserveSig] int PostMoveItem(uint f, IBrShellItem i, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n, int hr, IBrShellItem c);
+  [PreserveSig] int PreCopyItem(uint f, IBrShellItem i, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n);
+  [PreserveSig] int PostCopyItem(uint f, IBrShellItem i, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n, int hr, IBrShellItem c);
+  [PreserveSig] int PreDeleteItem(uint f, IBrShellItem i);
+  [PreserveSig] int PostDeleteItem(uint f, IBrShellItem i, int hr, IBrShellItem c);
+  [PreserveSig] int PreNewItem(uint f, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n);
+  [PreserveSig] int PostNewItem(uint f, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n, [MarshalAs(UnmanagedType.LPWStr)] string t, uint a, int hr, IBrShellItem c);
+  [PreserveSig] int UpdateProgress(uint total, uint sofar);
+  [PreserveSig] int ResetTimer();
+  [PreserveSig] int PauseTimer();
+  [PreserveSig] int ResumeTimer();
+}
+[ComImport, Guid("947aab5f-0a5c-4c13-b4d6-4bf7836fc9f8"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+public interface IBrFileOperation {
+  uint Advise(IBrSink s); void Unadvise(uint c); void SetOperationFlags(uint f);
+  void SetProgressMessage([MarshalAs(UnmanagedType.LPWStr)] string m); void SetProgressDialog([MarshalAs(UnmanagedType.IUnknown)] object d);
+  void SetProperties([MarshalAs(UnmanagedType.IUnknown)] object p); void SetOwnerWindow(IntPtr h);
+  void ApplyPropertiesToItem(IBrShellItem i); void ApplyPropertiesToItems([MarshalAs(UnmanagedType.IUnknown)] object i);
+  void RenameItem(IBrShellItem i, [MarshalAs(UnmanagedType.LPWStr)] string n, IBrSink s); void RenameItems([MarshalAs(UnmanagedType.IUnknown)] object i, [MarshalAs(UnmanagedType.LPWStr)] string n);
+  void MoveItem(IBrShellItem i, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n, IBrSink s); void MoveItems([MarshalAs(UnmanagedType.IUnknown)] object i, IBrShellItem d);
+  void CopyItem(IBrShellItem i, IBrShellItem d, [MarshalAs(UnmanagedType.LPWStr)] string n, IBrSink s); void CopyItems([MarshalAs(UnmanagedType.IUnknown)] object i, IBrShellItem d);
+  void DeleteItem(IBrShellItem i, IBrSink s); void DeleteItems([MarshalAs(UnmanagedType.IUnknown)] object i);
+  void NewItem(IBrShellItem d, uint a, [MarshalAs(UnmanagedType.LPWStr)] string n, [MarshalAs(UnmanagedType.LPWStr)] string t, IBrSink s);
+  void PerformOperations(); [return: MarshalAs(UnmanagedType.Bool)] bool GetAnyOperationsAborted();
+}
+public class BrRecycleSink : IBrSink {
+  public bool Seen, ToBin; public int Hr; public string Bin;
+  public int PreDeleteItem(uint f, IBrShellItem i) { Seen = true; ToBin = (f & 0x80) != 0; return ToBin ? 0 : unchecked((int)0x80004004); }
+  public int PostDeleteItem(uint f, IBrShellItem i, int hr, IBrShellItem c) {
+    Hr = hr;
+    // c = the item now in the Recycle Bin (null when deleted for good): its file-system path (SIGDN_FILESYSPATH).
+    if (c != null) { try { IntPtr n; c.GetDisplayName(0x80058000, out n); Bin = Marshal.PtrToStringUni(n); Marshal.FreeCoTaskMem(n); } catch { Bin = null; } }
+    return 0;
+  }
+  public int StartOperations() { return 0; } public int FinishOperations(int hr) { return 0; }
+  public int PreRenameItem(uint f, IBrShellItem i, string n) { return 0; } public int PostRenameItem(uint f, IBrShellItem i, string n, int hr, IBrShellItem c) { return 0; }
+  public int PreMoveItem(uint f, IBrShellItem i, IBrShellItem d, string n) { return 0; } public int PostMoveItem(uint f, IBrShellItem i, IBrShellItem d, string n, int hr, IBrShellItem c) { return 0; }
+  public int PreCopyItem(uint f, IBrShellItem i, IBrShellItem d, string n) { return 0; } public int PostCopyItem(uint f, IBrShellItem i, IBrShellItem d, string n, int hr, IBrShellItem c) { return 0; }
+  public int PreNewItem(uint f, IBrShellItem d, string n) { return 0; } public int PostNewItem(uint f, IBrShellItem d, string n, string t, uint a, int hr, IBrShellItem c) { return 0; }
+  public int UpdateProgress(uint t, uint s) { return 0; } public int ResetTimer() { return 0; } public int PauseTimer() { return 0; } public int ResumeTimer() { return 0; }
+}
+public static class BrRecycle {
+  [DllImport("shell32.dll", CharSet = CharSet.Unicode, PreserveSig = false)]
+  static extern void SHCreateItemFromParsingName(string path, IntPtr pbc, [MarshalAs(UnmanagedType.LPStruct)] Guid riid, [MarshalAs(UnmanagedType.Interface)] out IBrShellItem item);
+  // FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOERRORUI | FOF_NOCONFIRMMKDIR | FOF_ALLOWUNDO | FOFX_RECYCLEONDELETE | FOFX_EARLYFAILURE
+  const uint FLAGS = 0x0004 | 0x0010 | 0x0400 | 0x0200 | 0x0040 | 0x00080000 | 0x00100000;
+  public static string LastBin;
+  public static string One(string path) {
+    LastBin = null;
+    if (!File.Exists(path) && !Directory.Exists(path)) return "missing";
+    try {
+      var root = Path.GetPathRoot(path);
+      if (string.IsNullOrEmpty(root) || root.StartsWith(@"\\")) return "nobin";
+      var dt = new DriveInfo(root).DriveType;
+      if (dt != DriveType.Fixed && dt != DriveType.Removable) return "nobin";
+    } catch { return "nobin"; }
+    var op = (IBrFileOperation)Activator.CreateInstance(Type.GetTypeFromCLSID(new Guid("3ad05575-8857-4850-9277-11b85bdb8e09")));
+    var sink = new BrRecycleSink();
+    try {
+      op.SetOperationFlags(FLAGS);
+      IBrShellItem item; SHCreateItemFromParsingName(path, IntPtr.Zero, typeof(IBrShellItem).GUID, out item);
+      op.DeleteItem(item, sink);
+      try { op.PerformOperations(); } catch (COMException e) { if (sink.Seen && !sink.ToBin) return "nobin"; return "error:" + e.ErrorCode.ToString("x8"); }
+      if (sink.Seen && !sink.ToBin) return "nobin";
+      if (sink.Hr < 0) return "error:" + sink.Hr.ToString("x8");
+      if (!sink.Seen || File.Exists(path) || Directory.Exists(path)) return op.GetAnyOperationsAborted() ? "nobin" : "error:not-deleted";
+      LastBin = sink.Bin;
+      return "recycled";
+    } catch (Exception e) { return "error:" + e.GetType().Name; }
+    finally { Marshal.ReleaseComObject(op); }
+  }
+}
+'@
+$list = [Console]::In.ReadToEnd() | ConvertFrom-Json
+# Each item: a path, or {p, skip}: skip = letters h / s / r - a hidden / system / read-only item is left
+# alone ('skipped'), as the command itself would (a wildcard without -Force / /a / /f).
+function Test-Skip([string]$path, [string]$skip) {
+  if (-not $skip) { return $false }
+  try { $a = [IO.File]::GetAttributes($path) } catch { return $false }
+  return (($skip.Contains('h') -and ($a -band [IO.FileAttributes]::Hidden)) -or ($skip.Contains('s') -and ($a -band [IO.FileAttributes]::System)) -or ($skip.Contains('r') -and ($a -band [IO.FileAttributes]::ReadOnly)))
+}
+$out = @(foreach ($x in @($list)) {
+  if ($x -is [string]) { $p = $x; $skip = '' } else { $p = [string]$x.p; $skip = [string]$x.skip }
+  if (Test-Skip $p $skip) { @{ p = $p; r = 'skipped' } } else {
+    $r = [BrRecycle]::One($p)
+    if ($r -eq 'recycled' -and [BrRecycle]::LastBin) { @{ p = $p; r = $r; bin = [BrRecycle]::LastBin } } else { @{ p = $p; r = $r } }
+  }
+})
+[Console]::Out.WriteLine((ConvertTo-Json -InputObject @($out) -Compress -Depth 3))

package/src/screen-tool.mjs

@@ -0,0 +1,185 @@
+// LOGIC: see critical-logic/bridge.md ("Extra tools", screen). `screen`: the list of open windows, a
+// screenshot of the whole screen / one monitor / one window, and text recognition (Windows' built-in
+// OCR, the languages installed on the PC) of the screen, a window or an image file. Everything runs in
+// screen.ps1 (user32 + System.Drawing + Windows.Media.Ocr); no extra programs, nothing downloaded.
+// Every screenshot shows a notification on the PC ("the AI took a screenshot") unless the person turned
+// that off (screen.notify). Screenshots can be switched off completely (screen.enabled).
+// A locked screen / sign-in screen / UAC prompt can't be captured: an honest error, never a black picture.
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { showNotice } from './notice.mjs';
+import { fail, guard, freeName, needAction, str, int, psJson, ToolError } from './tool-lib.mjs';
+
+const PS = fileURLToPath(new URL('./screen.ps1', import.meta.url));
+export const MAX_SIDE = 1600;                 // long side of the picture sent to the AI
+export const MAX_BYTES = 900 * 1024;          // JPEG bytes (base64 ≈ 1.2 MB)
+const MAX_B64 = Math.ceil(MAX_BYTES / 3) * 4 + 4;
+const MAX_TEXT = 60000;
+const IMAGE_EXT = new Set(['.png', '.jpg', '.jpeg', '.bmp', '.gif', '.tif', '.tiff']);
+const ACTIONS = ['windows', 'capture', 'ocr'];
+
+export const defs = [{
+  name: 'screen',
+  title: 'Screen and text recognition',
+  description: 'Screenshots and text recognition on this PC. action "windows": open windows (id, title, program). '
+    + '"capture": a picture of the whole screen, one monitor (monitor) or one window (window = part of its title, or window_id); save_to also keeps a full-size copy. '
+    + '"ocr": the text on the screen, a window or an image file (path), recognized by Windows (languages installed on the PC; language like "en-US"). '
+    + 'The person sees a notification on the PC for each screenshot. A locked screen can\'t be captured.',
+  inputSchema: {
+    type: 'object', additionalProperties: false, required: ['action'],
+    properties: {
+      action: { type: 'string', enum: ACTIONS },
+      window: { type: 'string', maxLength: 200, description: 'Part of the window title (any case)' },
+      window_id: { type: 'integer', minimum: 1, description: 'Window id from action "windows"' },
+      monitor: { type: 'integer', minimum: 1, maximum: 16, description: 'Monitor number; without it: all monitors' },
+      language: { type: 'string', maxLength: 20, description: 'OCR language tag, e.g. "en-US", "ru"' },
+      path: { type: 'string', maxLength: 1000, description: 'Image file for ocr instead of the screen' },
+      save_to: { type: 'string', maxLength: 1000, description: 'Full path of a .png or .jpg for a full-size copy (capture)' },
+    },
+  },
+  annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+}];
+
+export const settings = [
+  { key: 'screen.enabled', default: true, widensWhen: true, label: { en: 'Screenshots and screen text recognition', ru: 'Снимки экрана и распознавание текста' }, hint: { en: 'The AI can take a picture of the screen or a window.', ru: 'ИИ может сделать снимок экрана или окна.' } },
+  { key: 'screen.notify', default: true, widensWhen: false, label: { en: 'Notify me about every screenshot', ru: 'Уведомлять о каждом снимке экрана' }, hint: { en: 'A notification "the AI took a screenshot" appears on the PC.', ru: 'На ПК появляется уведомление «ИИ сделал снимок экрана».' } },
+];
+const DEFAULT = Object.fromEntries(settings.map((s) => [s.key, s.default]));
+function setting(ctx, key) {
+  if (ctx.extra?.value) return ctx.extra.value(ctx.cfg, key);
+  const [g, k] = key.split('.');
+  const v = ctx.cfg?.[g]?.[k];
+  return typeof v === 'boolean' ? v : DEFAULT[key];
+}
+
+const clean = (s, n = 200) => String(s ?? '').replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, ' ').trim().slice(0, n);
+const run = (ctx, env, timeout = 60000) => psJson(ctx, { files: [PS], env, timeout });
+const check = (r) => { if (!r || r.ok !== true) throw new ToolError(r?.code || 'PS_FAILED', MESSAGES[r?.code] || clean(r?.message, 300) || 'Windows could not do it.', HINTS[r?.code] || ''); return r; };
+const MESSAGES = {
+  SCREEN_LOCKED: 'The screen is locked (or the sign-in screen / a Windows security prompt is open), so no screenshot can be taken until the person unlocks the PC.',
+};
+const HINTS = {
+  SCREEN_LOCKED: 'Ask the person to unlock the PC and try again.',
+  NO_WINDOW: 'Call screen with action "windows" to see the open windows.',
+  NO_MONITOR: 'Leave monitor out to capture all monitors.',
+  NO_OCR_LANG: 'The person can add a language with text recognition in Windows Settings → Time & language → Language & region (Add a language).',
+  BAD_LANG: 'Use one of the installed languages, or leave language out.',
+  BAD_IMAGE: 'Use a PNG, JPEG, BMP, GIF or TIFF file.',
+  IMAGE_TOO_LARGE: 'Use a smaller image or capture one window instead of all monitors.',
+  EXISTS: 'Call again: a new free name is chosen.',
+};
+
+/** Part of a title → one window: exact title first, then the topmost window whose title contains it. */
+export function pickWindow(list, query) {
+  const q = clean(query).toLowerCase();
+  if (!q) fail('BAD_ARGS', 'window must name a part of a window title.');
+  const hits = list.filter((w) => String(w.title).toLowerCase().includes(q));
+  if (!hits.length) {
+    const titles = list.slice(0, 15).map((w) => `"${clean(w.title, 80)}"`).join(', ');
+    fail('NO_WINDOW', `No open window has "${clean(query, 80)}" in its title.${titles ? ` Open windows: ${titles}.` : ''}`, HINTS.NO_WINDOW);
+  }
+  const exact = hits.find((w) => String(w.title).toLowerCase() === q);
+  return { win: exact || hits[0], others: hits.length - 1 };
+}
+
+const kb = (n) => `${Math.max(1, Math.round(n / 1024))} KB`;
+
+// The capture runs in a second PowerShell: it checks the id still belongs to the same program.
+const winEnv = (win) => ({ BRX_HWND: String(win.id), ...(Number.isInteger(win.pid) && win.pid > 0 ? { BRX_PID: String(win.pid) } : {}) });
+async function target(ctx, args) {
+  const windowQuery = str(args, 'window', { max: 200 });
+  const windowId = args.window_id === undefined ? undefined : int(args, 'window_id', { min: 1, max: Number.MAX_SAFE_INTEGER });
+  const monitor = int(args, 'monitor', { min: 1, max: 16, def: 0 });
+  if ((windowQuery || windowId) && monitor) fail('BAD_ARGS', 'Use either window / window_id or monitor, not both.');
+  if (windowId || windowQuery) {
+    const r = check(await run(ctx, { BRX_ACTION: 'windows' }));
+    const list = Array.isArray(r.windows) ? r.windows : [];
+    if (windowId) {
+      const win = list.find((w) => w.id === windowId);
+      if (!win) fail('NO_WINDOW', 'That window is not open any more.', HINTS.NO_WINDOW);
+      return { env: winEnv(win), what: 'window', win, others: 0 };
+    }
+    const { win, others } = pickWindow(list, windowQuery);
+    return { env: winEnv(win), what: 'window', win, others };
+  }
+  return { env: monitor ? { BRX_MONITOR: String(monitor) } : {}, what: monitor ? 'monitor' : 'screen', monitor };
+}
+
+function saveTarget(ctx, p) {
+  if (p === undefined) return undefined;
+  const abs = guard(ctx, p, { write: true });
+  if (!['.png', '.jpg', '.jpeg'].includes(path.extname(abs).toLowerCase())) fail('BAD_PATH', 'save_to must end with .png or .jpg.');
+  if (!fs.existsSync(path.dirname(abs))) fail('BAD_PATH', `The folder "${path.dirname(abs)}" does not exist.`, 'Create the folder first or choose another one.');
+  return freeName(abs);
+}
+
+function indicate(ctx, t, ocr) {
+  if (!setting(ctx, 'screen.notify')) return;
+  try {
+    (ctx.notice ?? showNotice)({ kind: 'screenshot', what: t.what, monitor: t.monitor, title: t.win?.title, ocr }, ctx.log || (() => {}));
+  } catch (e) { ctx.log?.(`[bridgerator] screenshot notice failed: ${e?.message || e}`); }
+}
+
+const describeTarget = (t) => (t.what === 'window' ? `window "${clean(t.win.title, 120)}"` : t.what === 'monitor' ? `monitor ${t.monitor}` : 'the whole screen');
+
+function linesText(r) {
+  let s = (Array.isArray(r.lines) ? r.lines : []).map((l) => clean(l, 2000)).join('\n');
+  if (s.length > MAX_TEXT) s = `${s.slice(0, MAX_TEXT)}\n[… cut at ${MAX_TEXT} characters]`;
+  return s;
+}
+
+export async function handle(name, args, ctx) {
+  const action = needAction(args, ACTIONS);
+  const lang = str(args, 'language', { max: 20 });
+  if (lang && !/^[a-z]{2,3}(-[a-z0-9]{2,8})*$/i.test(lang)) fail('BAD_ARGS', 'language must be a tag like "en-US" or "ru".');
+
+  // OCR of an image file is not a screenshot: no screen setting, no notice — the folder rules apply.
+  if (action === 'ocr' && args.path !== undefined) {
+    const file = guard(ctx, str(args, 'path', { required: true, max: 1000 }));
+    if (!IMAGE_EXT.has(path.extname(file).toLowerCase())) fail('BAD_IMAGE', 'This is not an image file.', HINTS.BAD_IMAGE);
+    const st = fs.statSync(file);
+    if (!st.isFile()) fail('BAD_PATH', 'path must be an image file, not a folder.');
+    if (st.size > 50 * 1024 * 1024) fail('IMAGE_TOO_LARGE', 'The image is larger than 50 MB.', HINTS.IMAGE_TOO_LARGE);
+    const r = check(await run(ctx, { BRX_ACTION: 'ocr', BRX_FILE: file, ...(lang ? { BRX_LANG: lang } : {}) }, 120000));
+    const body = linesText(r);
+    return { content: [{ type: 'text', text: `Text recognized in ${path.basename(file)} (${r.width}×${r.height}, language ${clean(r.language, 20)}):\n${body || '[no text found]'}` }] };
+  }
+  if (args.path !== undefined) fail('BAD_ARGS', 'path is only for action "ocr".');
+
+  if (!setting(ctx, 'screen.enabled')) {
+    fail('SCREEN_OFF', 'Screenshots are turned off on this PC.', 'The person can turn them on in the Bridgerator window (Settings), or you can ask with bridgerator_settings (screen.enabled); the person confirms it on the PC.');
+  }
+
+  if (action === 'windows') {
+    const r = check(await run(ctx, { BRX_ACTION: 'windows' }));
+    const windows = (Array.isArray(r.windows) ? r.windows : []).slice(0, 100).map((w) => ({ id: w.id, title: clean(w.title), program: clean(w.process, 60), ...(w.minimized ? { minimized: true } : {}) }));
+    return { content: [{ type: 'text', text: JSON.stringify({ windows }, null, 2) }] };
+  }
+
+  if (action === 'ocr' && args.save_to !== undefined) fail('BAD_ARGS', 'save_to is only for action "capture".');
+  const t = await target(ctx, args);
+  const save = action === 'capture' ? saveTarget(ctx, args.save_to) : undefined;
+  const env = { BRX_ACTION: action, ...t.env, ...(lang ? { BRX_LANG: lang } : {}), ...(save ? { BRX_SAVE: save } : {}),
+    ...(action === 'capture' ? { BRX_IMAGE: '1', BRX_MAXSIDE: String(MAX_SIDE), BRX_MAXBYTES: String(MAX_BYTES) } : {}) };
+  // The person is told about every picture taken (after the capture, so the notice is not in it) — also
+  // when a later step failed (taken) or the run did not answer (it may have taken one).
+  let raw;
+  try { raw = await run(ctx, env, action === 'ocr' ? 120000 : 60000); } catch (e) { indicate(ctx, t, action === 'ocr'); throw e; }
+  if (raw?.ok === true || raw?.taken === true) indicate(ctx, t, action === 'ocr');
+  const r = check(raw);
+  const notes = [
+    ...(t.others ? [`${t.others} other window(s) also match "${clean(args.window, 80)}"; use window_id to pick another one.`] : []),
+    ...(r.minimized ? ['The window is minimized: Windows may give an empty or old picture of it.'] : []),
+  ];
+  if (action === 'ocr') {
+    const body = linesText(r);
+    return { content: [{ type: 'text', text: `Text on ${describeTarget(t)} (${r.width}×${r.height}, language ${clean(r.language, 20)}):\n${body || '[no text found]'}${notes.length ? `\n\n${notes.join(' ')}` : ''}` }] };
+  }
+  if (typeof r.data !== 'string' || !r.data || r.data.length > MAX_B64 || !/^[A-Za-z0-9+/]+=*$/.test(r.data.slice(-64))) {
+    fail('IMAGE_TOO_LARGE', 'The screenshot could not be made small enough to send.', HINTS.IMAGE_TOO_LARGE);
+  }
+  const head = `Screenshot of ${describeTarget(t)}: ${r.width}×${r.height}, sent as ${r.outWidth}×${r.outHeight} JPEG (${kb(r.bytes || r.data.length * 0.75)}).`;
+  const saved = r.saved ? ` Full-size copy saved: ${r.saved}` : '';
+  return { content: [{ type: 'text', text: `${head}${saved}${notes.length ? ` ${notes.join(' ')}` : ''}` }, { type: 'image', data: r.data, mimeType: 'image/jpeg' }] };
+}