bridgerator 1.0.7 → 1.1.0

package/src/screen.ps1

@@ -0,0 +1,285 @@
+# LOGIC: see critical-logic/bridge.md ("Extra tools", screen). Screenshot / window list / OCR for the
+# `screen` tool (screen-tool.mjs). Windows PowerShell 5.1, no extra programs: user32 + System.Drawing for
+# the picture, the built-in Windows.Media.Ocr engine for text. Input only through BRX_* environment
+# variables; output = ONE JSON line. Never shows a window, never moves or restores the person's windows.
+#   BRX_ACTION  windows | capture | ocr | langs
+#   BRX_HWND    window id (capture / ocr of one window; BRX_PID = its process then, must still match), BRX_MONITOR 1-based monitor (0 = all)
+#   BRX_FILE    image file to recognize (ocr), BRX_LANG OCR language tag (empty = the user's languages)
+#   BRX_IMAGE   1 = return the compressed picture, BRX_MAXSIDE / BRX_MAXBYTES its limits, BRX_SAVE full-size copy path
+
+function Out-Json($o) { [Console]::Out.WriteLine((ConvertTo-Json -InputObject $o -Depth 6 -Compress)) }
+# taken = a picture was already made: the bridge shows the screenshot notice even when a later step fails.
+$script:taken = $false
+function Fail([string]$code, [string]$message, $extra = @{}) { $o = @{ ok = $false; code = $code; message = $message }; if ($script:taken) { $o.taken = $true }; foreach ($k in $extra.Keys) { $o[$k] = $extra[$k] }; Out-Json $o; exit 0 }
+
+# Compiled helpers are cached like the tray helper's (%LOCALAPPDATA%\Bridgerator\cache, br-<hash>.dll).
+function Add-CachedType([string]$code, [string[]]$refs = @()) {
+  try {
+    $dir = Join-Path $env:LOCALAPPDATA 'Bridgerator\cache'
+    $bytes = [Text.Encoding]::UTF8.GetBytes("$code|$($refs -join ',')|$($PSVersionTable.CLRVersion)")
+    $key = -join ([Security.Cryptography.SHA256]::Create().ComputeHash($bytes)[0..11] | ForEach-Object { $_.ToString('x2') })
+    $dll = Join-Path $dir "br-$key.dll"
+    if (-not [IO.File]::Exists($dll)) {
+      [void][IO.Directory]::CreateDirectory($dir)
+      $tmp = Join-Path $dir "br-$key.$PID.dll"
+      Add-Type -TypeDefinition $code -ReferencedAssemblies $refs -OutputAssembly $tmp -OutputType Library
+      try { [IO.File]::Move($tmp, $dll) } catch {
+        # Another run compiled the same helper at the same moment: use its file, drop ours.
+        if ([IO.File]::Exists($dll)) { try { [IO.File]::Delete($tmp) } catch { } } else { $dll = $tmp }
+      }
+    }
+    Add-Type -Path $dll
+  } catch {
+    Add-Type -TypeDefinition $code -ReferencedAssemblies $refs
+  }
+}
+
+Add-CachedType -refs System.Drawing @'
+using System; using System.Text; using System.Collections.Generic; using System.Runtime.InteropServices;
+using System.Drawing; using System.Drawing.Imaging; using System.Drawing.Drawing2D; using System.IO;
+public static class BrShot {
+  delegate bool EnumProc(IntPtr h, IntPtr l);
+  delegate bool MonProc(IntPtr m, IntPtr dc, ref RECT r, IntPtr l);
+  [StructLayout(LayoutKind.Sequential)] public struct RECT { public int L, T, R, B; }
+  [DllImport("user32.dll")] static extern bool EnumWindows(EnumProc f, IntPtr l);
+  [DllImport("user32.dll")] static extern bool EnumDisplayMonitors(IntPtr dc, IntPtr clip, MonProc f, IntPtr l);
+  [DllImport("user32.dll")] static extern bool IsWindowVisible(IntPtr h);
+  [DllImport("user32.dll")] static extern bool IsWindow(IntPtr h);
+  [DllImport("user32.dll")] static extern bool IsIconic(IntPtr h);
+  [DllImport("user32.dll", CharSet = CharSet.Unicode)] static extern int GetWindowText(IntPtr h, StringBuilder s, int n);
+  [DllImport("user32.dll")] static extern int GetWindowTextLength(IntPtr h);
+  [DllImport("user32.dll")] static extern uint GetWindowThreadProcessId(IntPtr h, out uint pid);
+  [DllImport("user32.dll")] static extern int GetWindowLong(IntPtr h, int idx);
+  [DllImport("user32.dll")] static extern bool GetWindowRect(IntPtr h, out RECT r);
+  [DllImport("user32.dll")] static extern bool PrintWindow(IntPtr h, IntPtr hdc, uint flags);
+  [DllImport("dwmapi.dll")] static extern int DwmGetWindowAttribute(IntPtr h, int a, out int v, int size);
+  [DllImport("dwmapi.dll")] static extern int DwmGetWindowAttribute(IntPtr h, int a, out RECT r, int size);
+  [DllImport("user32.dll")] static extern IntPtr OpenInputDesktop(uint flags, bool inherit, uint access);
+  [DllImport("user32.dll")] static extern bool CloseDesktop(IntPtr h);
+  [DllImport("user32.dll", CharSet = CharSet.Unicode)] static extern bool GetUserObjectInformation(IntPtr h, int idx, StringBuilder buf, int len, out int needed);
+  [DllImport("user32.dll")] static extern IntPtr SetThreadDpiAwarenessContext(IntPtr c);
+  [DllImport("user32.dll")] static extern bool SetProcessDPIAware();
+
+  // Physical pixels on every monitor (per-monitor v2; older Windows: system aware).
+  public static void Dpi() {
+    try { if (SetThreadDpiAwarenessContext(new IntPtr(-4)) != IntPtr.Zero) return; } catch (Exception) { }
+    try { SetProcessDPIAware(); } catch (Exception) { }
+  }
+  // The desktop that gets the keyboard: "Default" when the person is working; locked screen, sign-in
+  // screen and UAC prompts are on the secure desktop (not readable from here) -> null.
+  public static string InputDesktop() {
+    IntPtr d = OpenInputDesktop(0, false, 0x0001);
+    if (d == IntPtr.Zero) return null;
+    try { StringBuilder b = new StringBuilder(256); int n; return GetUserObjectInformation(d, 2, b, b.Capacity * 2, out n) ? b.ToString() : null; }
+    finally { CloseDesktop(d); }
+  }
+  public class Win { public long Id; public string Title; public uint Pid; public bool Minimized; public int W, H; }
+  public static List<Win> Windows() {
+    List<Win> list = new List<Win>();
+    EnumWindows(delegate(IntPtr h, IntPtr l) {
+      if (!IsWindowVisible(h)) return true;
+      int len = GetWindowTextLength(h);
+      if (len <= 0) return true;
+      if ((GetWindowLong(h, -20) & 0x80) != 0) return true;              // WS_EX_TOOLWINDOW
+      int cloaked = 0;
+      if (DwmGetWindowAttribute(h, 14, out cloaked, 4) == 0 && cloaked != 0) return true; // hidden store apps
+      StringBuilder sb = new StringBuilder(len + 1); GetWindowText(h, sb, sb.Capacity);
+      RECT r; GetWindowRect(h, out r);
+      uint pid; GetWindowThreadProcessId(h, out pid);
+      Win w = new Win(); w.Id = h.ToInt64(); w.Title = sb.ToString(); w.Pid = pid; w.Minimized = IsIconic(h); w.W = r.R - r.L; w.H = r.B - r.T;
+      if (!w.Minimized && (w.W <= 1 || w.H <= 1)) return true;
+      list.Add(w);
+      return true;
+    }, IntPtr.Zero);
+    return list;
+  }
+  public static Rectangle[] Monitors() {
+    List<Rectangle> m = new List<Rectangle>();
+    EnumDisplayMonitors(IntPtr.Zero, IntPtr.Zero, delegate(IntPtr hm, IntPtr dc, ref RECT r, IntPtr l) { m.Add(Rectangle.FromLTRB(r.L, r.T, r.R, r.B)); return true; }, IntPtr.Zero);
+    return m.ToArray();
+  }
+  public static Bitmap Screen(int monitor) {
+    Rectangle[] mons = Monitors();
+    Rectangle b;
+    if (monitor > 0) { if (monitor > mons.Length) return null; b = mons[monitor - 1]; }
+    else { b = mons.Length > 0 ? mons[0] : Rectangle.Empty; foreach (Rectangle x in mons) b = Rectangle.Union(b, x); }
+    if (b.Width <= 0 || b.Height <= 0) return null;
+    Bitmap bmp = new Bitmap(b.Width, b.Height, PixelFormat.Format32bppArgb);
+    using (Graphics g = Graphics.FromImage(bmp)) { g.Clear(Color.Black); g.CopyFromScreen(b.Left, b.Top, 0, 0, b.Size, CopyPixelOperation.SourceCopy); }
+    return bmp;
+  }
+  public static bool IsMinimized(long id) { return IsIconic(new IntPtr(id)); }
+  public static uint Owner(long id) { uint pid; GetWindowThreadProcessId(new IntPtr(id), out pid); return pid; }
+  public static bool Exists(long id) { IntPtr h = new IntPtr(id); return IsWindow(h) && IsWindowVisible(h); }
+  // PrintWindow with PW_RENDERFULLCONTENT: the window's own picture, also when other windows cover it.
+  // Cropped to the visible frame (without the invisible resize borders).
+  public static Bitmap Window(long id) {
+    IntPtr h = new IntPtr(id);
+    RECT r; if (!GetWindowRect(h, out r)) return null;
+    int w = r.R - r.L, ht = r.B - r.T;
+    if (w <= 1 || ht <= 1) return null;
+    Bitmap full = new Bitmap(w, ht, PixelFormat.Format32bppArgb);
+    using (Graphics g = Graphics.FromImage(full)) {
+      IntPtr hdc = g.GetHdc();
+      bool ok;
+      try { ok = PrintWindow(h, hdc, 2); } finally { g.ReleaseHdc(hdc); }
+      if (!ok) { full.Dispose(); return null; }
+    }
+    RECT f;
+    if (DwmGetWindowAttribute(h, 9, out f, Marshal.SizeOf(typeof(RECT))) == 0) {
+      Rectangle c = Rectangle.Intersect(new Rectangle(f.L - r.L, f.T - r.T, f.R - f.L, f.B - f.T), new Rectangle(0, 0, w, ht));
+      if (c.Width > 1 && c.Height > 1 && (c.Width < w || c.Height < ht)) { Bitmap crop = full.Clone(c, full.PixelFormat); full.Dispose(); return crop; }
+    }
+    return full;
+  }
+  public static Bitmap Scale(Bitmap src, double k) {
+    int w = Math.Max(1, (int)Math.Round(src.Width * k)), h = Math.Max(1, (int)Math.Round(src.Height * k));
+    Bitmap dst = new Bitmap(w, h, PixelFormat.Format24bppRgb);
+    using (Graphics g = Graphics.FromImage(dst)) { g.InterpolationMode = InterpolationMode.HighQualityBicubic; g.PixelOffsetMode = PixelOffsetMode.HighQuality; g.DrawImage(src, 0, 0, w, h); }
+    return dst;
+  }
+  static ImageCodecInfo Jpeg() { foreach (ImageCodecInfo c in ImageCodecInfo.GetImageEncoders()) if (c.MimeType == "image/jpeg") return c; return null; }
+  public static byte[] ToJpeg(Bitmap b, long quality) {
+    using (MemoryStream ms = new MemoryStream()) {
+      EncoderParameters p = new EncoderParameters(1); p.Param[0] = new EncoderParameter(System.Drawing.Imaging.Encoder.Quality, quality);
+      b.Save(ms, Jpeg(), p); return ms.ToArray();
+    }
+  }
+  // Long side <= maxSide, then lower quality / size until it fits maxBytes.
+  public class Packed { public byte[] Data; public int W, H; public long Quality; }
+  public static Packed Pack(Bitmap src, int maxSide, int maxBytes) {
+    double k = Math.Min(1.0, (double)maxSide / Math.Max(src.Width, src.Height));
+    long[] qs = new long[] { 80, 65, 50 };
+    for (int round = 0; round < 6; round++) {
+      using (Bitmap s = Scale(src, k)) {
+        foreach (long q in qs) {
+          byte[] d = ToJpeg(s, q);
+          if (d.Length <= maxBytes) { Packed p = new Packed(); p.Data = d; p.W = s.Width; p.H = s.Height; p.Quality = q; return p; }
+        }
+      }
+      k *= 0.75;
+    }
+    return null;
+  }
+  // A NEW file only (CreateNew): never overwrites, also when the name was taken a moment ago.
+  public static void Save(Bitmap b, string path) {
+    string ext = Path.GetExtension(path).ToLowerInvariant();
+    byte[] data = ext == ".png" ? ToPng(b) : ToJpeg(b, 90);
+    FileStream f = new FileStream(path, FileMode.CreateNew, FileAccess.Write, FileShare.None);
+    try { f.Write(data, 0, data.Length); f.Dispose(); }
+    catch (Exception) { f.Dispose(); try { File.Delete(path); } catch (Exception) { } throw; }
+  }
+  public static byte[] ToPng(Bitmap b) { using (MemoryStream ms = new MemoryStream()) { b.Save(ms, ImageFormat.Png); return ms.ToArray(); } }
+}
+'@
+
+# --- OCR (Windows.Media.Ocr, WinRT from PowerShell 5.1) ---------------------------------------
+function Get-Await {
+  Add-Type -AssemblyName System.Runtime.WindowsRuntime
+  $script:AsTaskOp = [System.WindowsRuntimeSystemExtensions].GetMethods() | Where-Object { $_.Name -eq 'AsTask' -and $_.GetParameters().Count -eq 1 -and $_.GetParameters()[0].ParameterType.Name -eq 'IAsyncOperation`1' } | Select-Object -First 1
+}
+function Await($op, [Type]$type) {
+  $task = $script:AsTaskOp.MakeGenericMethod($type).Invoke($null, @($op))
+  [void]$task.Wait(-1)
+  $task.Result
+}
+function Get-OcrLanguages {
+  [void][Windows.Media.Ocr.OcrEngine, Windows.Foundation, ContentType = WindowsRuntime]
+  @([Windows.Media.Ocr.OcrEngine]::AvailableRecognizerLanguages | ForEach-Object { $_.LanguageTag })
+}
+function Invoke-Ocr([byte[]]$bytes, [string]$lang) {
+  Get-Await
+  [void][Windows.Media.Ocr.OcrEngine, Windows.Foundation, ContentType = WindowsRuntime]
+  [void][Windows.Graphics.Imaging.BitmapDecoder, Windows.Foundation, ContentType = WindowsRuntime]
+  [void][Windows.Graphics.Imaging.SoftwareBitmap, Windows.Foundation, ContentType = WindowsRuntime]
+  [void][Windows.Storage.Streams.IRandomAccessStream, Windows.Foundation, ContentType = WindowsRuntime]
+  $langs = @(Get-OcrLanguages)                     # @(): one language must stay a list, not a string
+  if (-not $langs.Count) { Fail 'NO_OCR_LANG' 'No text recognition language is installed in Windows.' }
+  if ($lang) {
+    $hit = $langs | Where-Object { $_ -ieq $lang -or $_ -ilike "$lang-*" } | Select-Object -First 1
+    if (-not $hit) { Fail 'BAD_LANG' "Text recognition for ""$lang"" is not installed." @{ languages = $langs } }
+    $engine = [Windows.Media.Ocr.OcrEngine]::TryCreateFromLanguage([Windows.Globalization.Language]::new($hit))
+  } else {
+    $engine = [Windows.Media.Ocr.OcrEngine]::TryCreateFromUserProfileLanguages()
+    if (-not $engine) { $engine = [Windows.Media.Ocr.OcrEngine]::TryCreateFromLanguage([Windows.Globalization.Language]::new($langs[0])) }
+  }
+  if (-not $engine) { Fail 'NO_OCR_LANG' 'Text recognition could not start for the installed languages.' @{ languages = $langs } }
+  $ms = New-Object IO.MemoryStream (, $bytes)
+  $stream = [System.IO.WindowsRuntimeStreamExtensions]::AsRandomAccessStream($ms)
+  try {
+    $decoder = Await ([Windows.Graphics.Imaging.BitmapDecoder]::CreateAsync($stream)) ([Windows.Graphics.Imaging.BitmapDecoder])
+  } catch { Fail 'BAD_IMAGE' 'This file is not an image Windows can read (PNG, JPEG, BMP, GIF or TIFF).' }
+  $max = [Windows.Media.Ocr.OcrEngine]::MaxImageDimension
+  if ($decoder.PixelWidth -gt $max -or $decoder.PixelHeight -gt $max) { Fail 'IMAGE_TOO_LARGE' "The image is larger than $max pixels on a side." }
+  $bitmap = Await ($decoder.GetSoftwareBitmapAsync()) ([Windows.Graphics.Imaging.SoftwareBitmap])
+  $res = Await ($engine.RecognizeAsync($bitmap)) ([Windows.Media.Ocr.OcrResult])
+  @{ language = $engine.RecognizerLanguage.LanguageTag; lines = @($res.Lines | ForEach-Object { $_.Text }); width = [int]$decoder.PixelWidth; height = [int]$decoder.PixelHeight }
+}
+# Text recognition works best on the full-size picture; above the engine's limit it is scaled down.
+function Get-OcrBytes($bmp) {
+  [void][Windows.Media.Ocr.OcrEngine, Windows.Foundation, ContentType = WindowsRuntime]
+  $max = [Windows.Media.Ocr.OcrEngine]::MaxImageDimension
+  $side = [Math]::Max($bmp.Width, $bmp.Height)
+  if ($side -gt $max) { $s = [BrShot]::Scale($bmp, ($max - 1) / $side); try { return , [BrShot]::ToPng($s) } finally { $s.Dispose() } }
+  , [BrShot]::ToPng($bmp)
+}
+
+try {
+  [BrShot]::Dpi()
+  $action = $env:BRX_ACTION
+  if ($action -eq 'langs') { Out-Json @{ ok = $true; languages = @(Get-OcrLanguages) }; exit 0 }
+  if ($action -eq 'ocr' -and $env:BRX_FILE) {
+    $r = Invoke-Ocr ([IO.File]::ReadAllBytes($env:BRX_FILE)) $env:BRX_LANG
+    Out-Json (@{ ok = $true; kind = 'file' } + $r); exit 0
+  }
+  if (([BrShot]::InputDesktop()) -ne 'Default') { Fail 'SCREEN_LOCKED' 'The screen is locked, signed out or showing a Windows security prompt.' }
+  if ($action -eq 'windows') {
+    $wins = @([BrShot]::Windows() | ForEach-Object {
+      $p = ''; try { $p = (Get-Process -Id $_.Pid -ErrorAction Stop).ProcessName } catch { }
+      @{ id = $_.Id; pid = [int64]$_.Pid; title = $_.Title; process = $p; minimized = $_.Minimized; width = $_.W; height = $_.H } })
+    Out-Json @{ ok = $true; windows = $wins }; exit 0
+  }
+  if ($action -ne 'capture' -and $action -ne 'ocr') { Fail 'BAD_ACTION' "Unknown action $action." }
+  $hwnd = [long]('0' + $env:BRX_HWND)
+  $monitor = [int]('0' + $env:BRX_MONITOR)
+  $minimized = $false
+  if ($hwnd) {
+    if (-not [BrShot]::Exists($hwnd)) { Fail 'NO_WINDOW' 'That window is not open any more.' }
+    # The id was looked up in an earlier run: it must still belong to the same program (ids are reused).
+    if ($env:BRX_PID -and [string][BrShot]::Owner($hwnd) -ne $env:BRX_PID) { Fail 'NO_WINDOW' 'That window closed meanwhile.' }
+    $minimized = [BrShot]::IsMinimized($hwnd)
+    $bmp = [BrShot]::Window($hwnd)
+    $kind = 'window'
+  } else {
+    $count = ([BrShot]::Monitors()).Count
+    if ($monitor -gt $count) { Fail 'NO_MONITOR' "There is no monitor $monitor (this PC has $count)." @{ monitors = $count } }
+    try { $bmp = [BrShot]::Screen($monitor) } catch { Fail 'SCREEN_LOCKED' 'Windows gave no picture of the screen (locked, or a remote session without a display).' }
+    $kind = $(if ($monitor) { 'monitor' } else { 'screen' })
+  }
+  if (-not $bmp) { Fail 'CAPTURE_FAILED' 'Windows could not take the picture.' }
+  $script:taken = $true
+  try {
+    $out = @{ ok = $true; kind = $kind; width = $bmp.Width; height = $bmp.Height; minimized = $minimized }
+    if ($action -eq 'ocr') {
+      $r = Invoke-Ocr (Get-OcrBytes $bmp) $env:BRX_LANG
+      $out.language = $r.language; $out.lines = $r.lines
+    }
+    if ($env:BRX_IMAGE -eq '1') {
+      $p = [BrShot]::Pack($bmp, [int]$env:BRX_MAXSIDE, [int]$env:BRX_MAXBYTES)
+      if (-not $p) { Fail 'IMAGE_TOO_LARGE' 'The picture could not be made small enough.' }
+      $out.mime = 'image/jpeg'; $out.data = [Convert]::ToBase64String($p.Data); $out.outWidth = $p.W; $out.outHeight = $p.H; $out.bytes = $p.Data.Length
+    }
+    # The full-size copy last: no file is left on disk when an earlier step failed.
+    if ($env:BRX_SAVE) {
+      try { [BrShot]::Save($bmp, $env:BRX_SAVE) } catch {
+        $h = $_.Exception.HResult; if ($_.Exception.InnerException) { $h = $_.Exception.InnerException.HResult }
+        if ($h -eq -2147024816 -or $h -eq -2147024713) { Fail 'EXISTS' 'A file with this name appeared meanwhile; nothing was overwritten.' }
+        throw
+      }
+      $out.saved = $env:BRX_SAVE
+    }
+    Out-Json $out
+  } finally { $bmp.Dispose() }
+} catch {
+  Out-Json @{ ok = $false; code = 'PS_ERROR'; message = [string]$_.Exception.Message; taken = [bool]$script:taken }
+}

package/src/search-tool.mjs

@@ -0,0 +1,189 @@
+// LOGIC: see critical-logic/bridge.md ("Extra tools" / fast_search). Instant search: Everything (if
+// installed and running) → the Windows Search index (SystemIndex over OLE DB) → the engine's own
+// search (start_search, already under the policy). Every hit goes through the same folder rules as the
+// file tools (visiblePath): excluded folders and folders outside the allowed list never show up.
+// Queries are built here (escaped); search.ps1 only runs them.
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { psJson, guard, visiblePath, fail, json, needAction, str, int, ToolError, errorText } from './tool-lib.mjs';
+
+const PS = fileURLToPath(new URL('./search.ps1', import.meta.url));
+const ACTIONS = ['files', 'text', 'status'];
+const MAX = 500;
+const POLL_MS = 400, BASIC_WAIT_MS = 20000;
+
+export const defs = [{
+  name: 'fast_search',
+  title: 'Fast search',
+  description: 'Fast file search on this PC. action "files": names or masks like *.pdf; "text": words inside documents (Windows Search index); "status": which search sources this PC has. Uses Everything when it is installed, then the Windows Search index, then a plain folder scan. Results follow the folder rules of this PC.',
+  inputSchema: {
+    type: 'object', additionalProperties: false, required: ['action'],
+    properties: {
+      action: { type: 'string', enum: ACTIONS },
+      query: { type: 'string', maxLength: 300, description: 'Name, mask (* ?) or words' },
+      folder: { type: 'string', description: 'Search only inside this folder (full path)' },
+      kind: { type: 'string', maxLength: 12, description: 'File extension, e.g. pdf or .docx' },
+      limit: { type: 'integer', minimum: 1, maximum: MAX, description: 'Default 100' },
+    },
+  },
+  annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+}];
+
+const b64 = (s) => Buffer.from(String(s), 'utf8').toString('base64');
+const sq = (s) => String(s).replace(/'/g, "''");                         // SQL string literal
+const ctl = (s) => String(s).replace(/[\u0000-\u001f\u007f]/g, ' ').trim();
+export function extOf(kind) {
+  if (kind === undefined) return undefined;
+  const k = String(kind).trim().replace(/^\*?\./, '');
+  if (!/^[\p{L}\p{N}_-]{1,10}$/u.test(k)) fail('BAD_ARGS', 'kind must be a file extension like pdf or .docx.');
+  return k.toLowerCase();
+}
+/** Name / mask → LIKE pattern: LIKE's own specials are literal, * ? are the wildcards. */
+export function likePattern(q) {
+  const lit = ctl(q).replace(/[[%_]/g, (c) => `[${c}]`);
+  const w = lit.replace(/\*/g, '%').replace(/\?/g, '_');
+  return /[*?]/.test(q) ? w : `%${w}%`;
+}
+const scopeUrl = (d) => `file:${d.replace(/\\/g, '/')}`;
+/** The SystemIndex query for files / text, scoped to folders (none = whole index). */
+export function indexSql({ action, query, folders = [], ext, limit }) {
+  const where = [];
+  if (folders.length) where.push(`(${folders.map((d) => `SCOPE='${sq(scopeUrl(d))}'`).join(' OR ')})`);
+  if (action === 'text') { where.push(`FREETEXT('${sq(ctl(query))}')`); where.push("System.ItemType <> 'Directory'"); }
+  else if (query) where.push(`System.FileName LIKE '${sq(likePattern(query))}'`);
+  if (ext) where.push(`System.FileExtension = '.${sq(ext)}'`);
+  return `SELECT TOP ${limit} System.ItemUrl, System.Size, System.DateModified FROM SystemIndex${where.length ? ` WHERE ${where.join(' AND ')}` : ''} ORDER BY System.DateModified DESC`;
+}
+export const coverSql = (folder) => `SELECT TOP 1 System.ItemUrl FROM SystemIndex WHERE SCOPE='${sq(scopeUrl(folder))}'`;
+/** es.exe arguments: words only — nothing that starts like an option (-export-…, /a) reaches it. Every
+ * double quote goes first (a quoted "-export-txt" or a"b must never turn into a switch), then a leading - or /. */
+export function esArgs({ query, folder, ext, limit }) {
+  const words = ctl(query || '').replace(/["\u201c\u201d]/g, '').split(/\s+/).map((w) => w.replace(/^[-/]+/, '')).filter(Boolean);
+  return ['-n', String(limit), ...(folder ? ['-path', folder] : []), ...(ext ? [`ext:${ext}`] : []), ...words];
+}
+export const urlToPath = (u) => String(u).replace(/^file:/i, '').replace(/\//g, '\\');
+
+const run = (ctx, env, timeout = 30000) => psJson(ctx, { files: [PS], env, timeout });
+async function status(ctx, folder) {
+  return run(ctx, { BRX_MODE: 'status', ...(folder ? { BRX_SCOPE_SQL: b64(coverSql(folder)) } : {}) }, 20000);
+}
+
+function keep(ctx, items, limit) {
+  const out = [];
+  let hidden = 0;
+  for (const it of items) {
+    if (!it?.path || typeof it.path !== 'string') continue;
+    if (!visiblePath(ctx, it.path)) { hidden++; continue; }
+    out.push({ path: it.path, ...(Number.isFinite(it.size) ? { size: it.size } : {}), ...(it.modified ? { modified: it.modified } : {}), ...(it.dir ? { folder: true } : {}) });
+    if (out.length >= limit) break;
+  }
+  return { items: out, hidden };
+}
+
+// The engine's own search: "📁 path" (files) / "📄 path:line - text" (content) lines.
+export function parseBasic(text) {
+  const items = [];
+  for (const line of String(text || '').split(/\r?\n/)) {
+    let m = /^📁 (.+)$/u.exec(line);
+    if (m) { items.push({ path: m[1].trim() }); continue; }
+    m = /^📄 (.+?):(\d+) - (.*)$/u.exec(line);
+    if (m && !items.some((x) => x.path === m[1])) items.push({ path: m[1], line: Number(m[2]), match: m[3].slice(0, 200) });
+  }
+  return items;
+}
+const textOf = (r) => (r?.content || []).filter((c) => c?.type === 'text').map((c) => c.text).join('\n');
+async function basic(ctx, { action, query, folder, ext, limit }, wait = BASIC_WAIT_MS) {
+  if (!ctx.engine) throw new ToolError('NO_BASIC', 'The plain folder search is not available here.');
+  const root = folder || ctx.cfg?.allowedDirectories?.[0] || process.env.USERPROFILE;
+  if (!root) throw new ToolError('NO_FOLDER', 'Say which folder to search.', 'Pass folder.');
+  // Names: the engine takes masks (* ?) as globs and plain text as "contains"; content: literal text.
+  const started = await ctx.engine('start_search', { path: root, pattern: query, searchType: action === 'text' ? 'content' : 'files', ...(ext ? { filePattern: `*.${ext}` } : {}), maxResults: limit, literalSearch: true });
+  const t0 = textOf(started);
+  if (started?.isError) throw new ToolError('BASIC_FAILED', t0.slice(0, 300) || 'The folder search did not start.');
+  const id = /session:\s*(\S+)/i.exec(t0)?.[1];
+  if (!id) return parseBasic(t0);
+  let all = [], done = /COMPLETED/.test(t0);
+  const until = Date.now() + wait;
+  try {
+    for (;;) {
+      const r = await ctx.engine('get_more_search_results', { sessionId: id, offset: 0, length: limit });
+      const t = textOf(r);
+      all = parseBasic(t);
+      done = /Status:\s*COMPLETED/i.test(t);
+      if (done || r?.isError || Date.now() > until) break;
+      await new Promise((res) => setTimeout(res, POLL_MS));
+    }
+  } finally {
+    // Also when a poll throws (engine timeout / restart): the search must not keep running.
+    if (!done) await Promise.resolve().then(() => ctx.engine('stop_search', { sessionId: id })).catch(() => null);
+  }
+  return all;
+}
+
+export async function handle(name, args, ctx) {
+  const action = needAction(args, ACTIONS);
+  const folder = args.folder !== undefined ? guard(ctx, str(args, 'folder', { max: 1000 })) : undefined;
+  if (action === 'status') {
+    const s = await status(ctx, folder);
+    return json({
+      everything: s.everything?.path ? (s.everything.running ? 'ready' : 'installed, not running') : s.everything?.untrusted ? 'not used (es.exe is outside Program Files and not signed by voidtools)' : 'not installed',
+      windows_index: s.index?.service === 'Running' ? 'ready' : `not available (service ${String(s.index?.service || 'unknown')})`,
+      ...(folder ? { folder, folder_indexed: s.index?.covered === true ? 'yes' : s.index?.covered === false ? 'no (not in the index — the plain scan is used)' : 'unknown' } : {}),
+      plain_scan: 'always available',
+    });
+  }
+  const query = str(args, 'query', { required: true, max: 300 });
+  const limit = int(args, 'limit', { min: 1, max: MAX, def: 100 });
+  const ext = extOf(args.kind);
+  const allowed = ctx.cfg?.allowedDirectories || [];
+  const folders = folder ? [folder] : allowed.map((d) => path.resolve(d));
+  const want = Math.min(MAX, limit * 2);       // room for hits the folder rules hide
+  const tried = [];
+  let firstError = null;
+  const note = (src, e) => { tried.push(`${src}: ${e instanceof ToolError ? e.code : e?.code || 'error'}`); firstError ||= e; };
+  // null = every hit was hidden by the folder rules → the next source is tried.
+  const answer = (source, items, extra = {}) => {
+    const k = keep(ctx, items, limit);
+    if (!k.items.length && k.hidden) { tried.push(`${source}: ${k.hidden} result(s) hidden by this PC's folder rules`); return null; }
+    return json({ source, count: k.items.length, results: k.items, ...(k.hidden ? { hidden: `${k.hidden} result(s) hidden by this PC's folder rules` } : {}), ...(tried.length ? { skipped_sources: tried } : {}), ...extra });
+  };
+
+  let st = null;
+  try { st = await status(ctx, folder); } catch (e) { note('status', e); }
+
+  if (action === 'files' && st?.everything?.path && st.everything.running) {
+    try {
+      // Scoped like the index: the folder, or the one allowed folder (several: hits are filtered below).
+      const esFolder = folder || (folders.length === 1 ? folders[0] : undefined);
+      const r = await run(ctx, { BRX_MODE: 'everything', BRX_ES: st.everything.path, BRX_ARGS: b64(JSON.stringify(esArgs({ query, folder: esFolder, ext, limit: want }))) });
+      if (r.error) throw new ToolError(r.error, r.error === 'ES_START_FAILED' ? 'Everything\'s es.exe could not start (an antivirus may block it).' : 'Everything did not answer.');
+      const a = r.items?.length ? answer('everything', r.items) : null;
+      if (a) return a;
+      if (!r.items?.length) tried.push('everything: nothing found');
+    } catch (e) { note('everything', e); }
+  } else if (action === 'files') tried.push(`everything: ${st?.everything?.path ? 'not running' : 'not installed'}`);
+
+  let indexNote;
+  if (st?.index?.service === 'Running') {
+    try {
+      const r = await run(ctx, { BRX_MODE: 'index', BRX_SQL: b64(indexSql({ action, query, folders, ext, limit: want })) });
+      if (r.error) throw new ToolError(r.error, 'The Windows Search index did not answer.');
+      const items = (r.items || []).map((x) => ({ ...x, path: urlToPath(x.url) }));
+      const a = items.length ? answer('windows_index', items, folder && st.index.covered === false ? { note: 'This folder is not in the Windows Search index; results may be incomplete.' } : {}) : null;
+      if (a) return a;
+      if (!items.length) {
+        indexNote = folder && st.index.covered === false ? 'This folder is not in the Windows Search index' : 'Nothing found in the Windows Search index';
+        tried.push(`windows_index: ${indexNote.toLowerCase()}`);
+      }
+    } catch (e) { note('windows_index', e); }
+  } else tried.push(`windows_index: service ${String(st?.index?.service || 'unknown')}`);
+
+  try {
+    const items = await basic(ctx, { action, query, folder, ext, limit: want });
+    return answer('basic', items, { note: `Plain folder scan${indexNote ? ` (${indexNote.toLowerCase()})` : ''}.` })
+      || json({ source: 'basic', count: 0, results: [], skipped_sources: tried });
+  } catch (e) {
+    note('basic', e);
+    throw new ToolError('SEARCH_FAILED', `Search did not work: ${errorText(firstError).replace(/\s*\(code [A-Z_0-9]+\)$/, '')}`, 'Pass a folder, or check the PC with bridgerator_doctor.');
+  }
+}

package/src/search.ps1

@@ -0,0 +1,129 @@
+# LOGIC: see critical-logic/bridge.md ("Extra tools" / fast_search). Instant search sources for the
+# bridge (search-tool.mjs builds every query; this script only runs it).
+# In (env): BRX_MODE = status | everything | index; BRX_ES (es.exe path), BRX_ARGS (base64 UTF-8 JSON
+# array of es.exe arguments), BRX_SQL (base64 UTF-8 SystemIndex query), BRX_SCOPE_SQL (status: the
+# coverage query, optional), BRX_ES_WAIT (ms es.exe may run, default 20000). Out: ONE JSON line. Errors are codes, never localized message text.
+function Out-Json($o) { [Console]::Out.WriteLine(($o | ConvertTo-Json -Compress -Depth 5)) }
+function From-B64($s) { if (-not $s) { return '' }; [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($s)) }
+
+# es.exe runs only from a place a standard user cannot write (Program Files, Windows) or when it is
+# signed by voidtools: a planted es.exe on the PATH / in a user folder never runs.
+function Test-TrustedEs([string]$p) {
+  if (-not $p -or -not (Test-Path -LiteralPath $p -PathType Leaf)) { return $false }
+  $full = [IO.Path]::GetFullPath($p)
+  foreach ($d in @($env:ProgramFiles, ${env:ProgramFiles(x86)})) {
+    if ($d -and $full.StartsWith(([IO.Path]::GetFullPath($d).TrimEnd('\') + '\'), [StringComparison]::OrdinalIgnoreCase)) { return $true }
+  }
+  # Windows itself: only the folder and System32 (subfolders like Temp are writable by users).
+  $parent = [IO.Path]::GetDirectoryName($full)
+  if ($env:SystemRoot -and @($env:SystemRoot, (Join-Path $env:SystemRoot 'System32')) -contains $parent) { return $true }
+  try {
+    $sig = Get-AuthenticodeSignature -LiteralPath $full
+    return ($sig.Status -eq 'Valid' -and [string]$sig.SignerCertificate.Subject -match '(^|,\s*)(CN|O)=voidtools(,|$)')
+  } catch { return $false }
+}
+function Find-Es {
+  $found = $null
+  $cands = @(Get-Command es.exe -CommandType Application -All -ErrorAction SilentlyContinue | ForEach-Object { $_.Source })
+  foreach ($d in @($env:ProgramFiles, ${env:ProgramFiles(x86)}, (Join-Path $env:LOCALAPPDATA 'Programs'))) { if ($d) { $cands += (Join-Path $d 'Everything\es.exe') } }
+  foreach ($p in $cands) {
+    if (-not $p -or -not (Test-Path -LiteralPath $p -PathType Leaf)) { continue }
+    if (Test-TrustedEs $p) { return @{ path = $p } }
+    if (-not $found) { $found = $p }
+  }
+  return @{ path = $null; untrusted = $found }
+}
+# One Windows command-line argument (words carry no quotes: search-tool.mjs strips them). Quoted, a
+# trailing \ is doubled: "C:\My Files\" would end in \" (a literal quote) and swallow the next arguments.
+function Quote-Arg([string]$a) { if ($a -match '[\s"]' -or -not $a) { return '"' + (($a -replace '"', '') -replace '(\\+)$', '$1$1') + '"' }; return $a }
+
+function Invoke-Index($sql) {
+  $conn = $null; $rs = $null
+  try {
+    $conn = New-Object -ComObject ADODB.Connection
+    $conn.Open("Provider=Search.CollatorDSO;Extended Properties='Application=Windows';")
+    $rs = New-Object -ComObject ADODB.Recordset
+    $rs.Open($sql, $conn)
+    $items = New-Object System.Collections.ArrayList
+    while (-not $rs.EOF) {
+      $url = [string]$rs.Fields.Item('System.ItemUrl').Value
+      $size = $rs.Fields.Item('System.Size').Value
+      $mod = $rs.Fields.Item('System.DateModified').Value
+      $o = @{ url = $url }
+      if ($size -ne $null -and $size -isnot [DBNull]) { $o.size = [int64]$size }
+      if ($mod -is [DateTime]) { $o.modified = $mod.ToUniversalTime().ToString('yyyy-MM-ddTHH:mm:ssZ') }
+      [void]$items.Add($o)
+      $rs.MoveNext()
+    }
+    return @{ items = @($items) }
+  } catch {
+    return @{ error = 'INDEX_UNAVAILABLE'; hresult = ('0x{0:X8}' -f $_.Exception.HResult) }
+  } finally {
+    if ($rs) { try { $rs.Close() } catch { } }
+    if ($conn) { try { $conn.Close() } catch { } }
+  }
+}
+
+$mode = $env:BRX_MODE
+if ($mode -eq 'status') {
+  $es = Find-Es
+  $running = [bool](Get-Process -Name 'Everything', 'Everything64' -ErrorAction SilentlyContinue)
+  $svc = Get-Service -Name WSearch -ErrorAction SilentlyContinue
+  $state = if ($svc) { [string]$svc.Status } else { 'Missing' }
+  $covered = $null
+  $scopeSql = From-B64 $env:BRX_SCOPE_SQL
+  if ($scopeSql -and $state -eq 'Running') {
+    $r = Invoke-Index $scopeSql
+    $covered = if ($r.error) { $null } else { $r.items.Count -gt 0 }
+  }
+  Out-Json @{ everything = @{ path = $es.path; untrusted = [bool]$es.untrusted; running = $running }; index = @{ service = $state; covered = $covered } }
+  exit 0
+}
+if ($mode -eq 'everything') {
+  $es = $env:BRX_ES
+  if (-not $es -or -not (Test-Path -LiteralPath $es)) { Out-Json @{ error = 'ES_MISSING' }; exit 0 }
+  # Held open (others may only read) from the trust check until it has started: it can't be swapped in between.
+  $hold = $null; try { $hold = [IO.File]::Open($es, 'Open', 'Read', 'Read') } catch { Out-Json @{ error = 'ES_START_FAILED' }; exit 0 }
+  if (-not (Test-TrustedEs $es)) { $hold.Dispose(); Out-Json @{ error = 'ES_UNTRUSTED' }; exit 0 }
+  # PowerShell 5.1 ConvertFrom-Json emits an array as ONE object: enumerate it into separate arguments.
+  $argv = @((From-B64 $env:BRX_ARGS) | ConvertFrom-Json | ForEach-Object { $_ })
+  # The export file lives in our own cache folder (not TEMP); es.exe is stopped when it takes too long.
+  $dir = Join-Path $env:LOCALAPPDATA 'Bridgerator\cache'
+  [void][IO.Directory]::CreateDirectory($dir)
+  $tmp = Join-Path $dir ('es-' + [guid]::NewGuid().ToString('N') + '.efu')
+  $wait = 20000; $w = 0; if ([int]::TryParse([string]$env:BRX_ES_WAIT, [ref]$w) -and $w -gt 0) { $wait = $w }
+  $proc = $null
+  try {
+    $psi = New-Object Diagnostics.ProcessStartInfo
+    $psi.FileName = $es
+    $psi.Arguments = ((@($argv) + @('-export-efu', $tmp)) | ForEach-Object { Quote-Arg ([string]$_) }) -join ' '
+    # Its own pipes (our stdout stays the one JSON line for the bridge), both drained at once: a full pipe
+    # (usage / error text) would block es.exe until the kill.
+    $psi.UseShellExecute = $false; $psi.CreateNoWindow = $true; $psi.RedirectStandardOutput = $true; $psi.RedirectStandardError = $true
+    try { $proc = [Diagnostics.Process]::Start($psi) } catch { Out-Json @{ error = 'ES_START_FAILED' }; exit 0 } finally { $hold.Dispose() }
+    [void]$proc.StandardOutput.ReadToEndAsync(); [void]$proc.StandardError.ReadToEndAsync()
+    if (-not $proc.WaitForExit($wait)) { try { $proc.Kill() } catch { }; [void]$proc.WaitForExit(5000); Out-Json @{ error = 'ES_TIMEOUT' }; exit 0 }
+    $code = $proc.ExitCode
+    if ($code -ne 0) { Out-Json @{ error = ('ES_EXIT_' + $code) }; exit 0 }
+    $items = New-Object System.Collections.ArrayList
+    if (Test-Path -LiteralPath $tmp) {
+      foreach ($row in (Import-Csv -LiteralPath $tmp -Encoding UTF8)) {
+        $o = @{ path = [string]$row.Filename }
+        $s = 0L; if ([int64]::TryParse([string]$row.Size, [ref]$s)) { $o.size = $s }
+        $ft = 0L; if ([int64]::TryParse([string]$row.'Date Modified', [ref]$ft) -and $ft -gt 0) { $o.modified = [DateTime]::FromFileTimeUtc($ft).ToString('yyyy-MM-ddTHH:mm:ssZ') }
+        $a = 0; if ([int]::TryParse([string]$row.Attributes, [ref]$a)) { $o.dir = [bool]($a -band 16) }
+        [void]$items.Add($o)
+      }
+    }
+    Out-Json @{ items = @($items) }
+  } finally {
+    if ($proc) { try { if (-not $proc.HasExited) { $proc.Kill() } } catch { }; $proc.Dispose() }
+    Remove-Item -LiteralPath $tmp -Force -ErrorAction SilentlyContinue
+  }
+  exit 0
+}
+if ($mode -eq 'index') {
+  Out-Json (Invoke-Index (From-B64 $env:BRX_SQL))
+  exit 0
+}
+Out-Json @{ error = 'BAD_MODE' }