@vortex-os/computer-use 0.7.0 → 0.7.2

package/scripts/noise-filter.mjs

@@ -1,135 +1,135 @@
-// @vortex-os/computer-use — noise filter for the watch layer (design §22.1).
-//
-// Problem: video / games / scrolling change every frame, so a raw per-frame change threshold
-// floods the agent with one event per ripple of the SAME activity (each event costs a capture
-// + an LLM look). Measured calibration: a playing video jitters ~2.5–4% frame-to-frame, a real
-// scene cut jumps ~16.8%. We want to ignore the steady jitter and report only meaningful,
-// settled changes — without ever going completely silent on a screen that keeps moving.
-//
-// Design: debounce + cooldown COMBINED, with hysteresis. Neither alone works:
-//   - debounce alone ("report once it goes quiet") starves on video/games that never go quiet.
-//   - cooldown alone ("report at most once per N s") fires on a half-drawn transition frame (bad quality).
-// So they split roles:
-//   - debounce  = QUALITY  — emit the frame AFTER motion settles (a clean, stable shot).
-//   - cooldown  = FREQUENCY — never emit more than once per cooldownMs (suppress the ripples).
-//   - maxWait   = ANTI-STARVATION — once WOKEN, if motion never settles, emit anyway every maxWaitMs, so a
-//                 screen with sustained ABOVE-threshold motion still yields periodic snapshots (not silence).
-//   - hysteresis = two thresholds so ambient jitter never even wakes the filter (no flapping).
-// Note on the silence boundary: a screen that changes only BELOW activityThreshold (e.g. steady video jitter
-// at 2.5-4%) is intentionally treated as "nothing happening" and produces no events — that IS the goal of
-// ignoring the ripple, and it means maxWait only applies once a real (above-threshold) change has woken the
-// filter. Lower activityThreshold if you want fainter sustained motion to count as activity.
-//
-// This module is pure (no I/O, no timers of its own — the caller feeds it samples with an explicit
-// `now`), so the state machine is deterministically unit-testable from a synthetic change sequence.
-
-// Calibrated against the measured numbers above. All tunable per start_watch.
-export const FILTER_DEFAULTS = {
-  // % frame-to-frame change to WAKE the filter (enter an "active" episode). Set well above the
-  // measured video jitter ceiling (~4%) so steady playback never registers as a new event, yet
-  // below a scene cut (~16.8%) so real transitions do. The whole-frame metric dilutes tiny local
-  // changes (a clock, a cursor), so target a meaningful region/window for small UI events.
-  activityThreshold: 8,
-  // % below which a frame counts as "still". Hysteresis: must be < activityThreshold so a woken
-  // episode keeps tracking motion down to a lower floor before it's declared settled.
-  quietThreshold: 5,
-  // Motion must stay below quietThreshold this long before we emit a "settled" event (quality gate).
-  // Keep it a small multiple of the poll interval so a couple of quiet polls confirm the settle.
-  debounceQuietMs: 900,
-  // Minimum gap between emitted events (frequency cap). Suppresses the ripples of one activity.
-  cooldownMs: 6000,
-  // If an episode never settles (sustained motion: video, ongoing battle), emit anyway this often
-  // so a continuously-moving screen still produces periodic snapshots instead of going silent.
-  maxWaitMs: 8000,
-};
-
-const clampNum = (v, lo, hi, dflt) => {
-  const n = Number(v);
-  if (!Number.isFinite(n)) return dflt;
-  return Math.min(hi, Math.max(lo, n));
-};
-
-// Sanitize caller-supplied options into a coherent, safe config. Enforces the hysteresis invariant
-// (quietThreshold < activityThreshold) so a misconfiguration can't make the filter flap or never wake.
-export function resolveFilterConfig(opts = {}) {
-  const d = FILTER_DEFAULTS;
-  let activityThreshold = clampNum(opts.activityThreshold, 0.1, 100, d.activityThreshold);
-  let quietThreshold = clampNum(opts.quietThreshold, 0, 100, d.quietThreshold);
-  // Keep the quiet floor strictly below the wake threshold (hysteresis). If a caller inverts them,
-  // pull the quiet floor down to just under the wake threshold rather than silently swapping intent.
-  if (quietThreshold >= activityThreshold) quietThreshold = Math.max(0, activityThreshold - 1);
-  return {
-    activityThreshold,
-    quietThreshold,
-    debounceQuietMs: clampNum(opts.debounceQuietMs, 0, 60000, d.debounceQuietMs),
-    cooldownMs: clampNum(opts.cooldownMs, 0, 600000, d.cooldownMs),
-    maxWaitMs: clampNum(opts.maxWaitMs, 100, 600000, d.maxWaitMs),
-  };
-}
-
-export class NoiseFilter {
-  constructor(opts = {}) {
-    this.cfg = resolveFilterConfig(opts);
-    this.phase = 'idle';        // idle | active | cooldown
-    this.activeStart = 0;       // ts the current episode woke
-    this.lastMotionTs = 0;      // last ts change was >= quietThreshold (i.e. "still moving")
-    this.lastEmitTs = -Infinity; // ts of the last emitted event
-    this.peakPct = 0;           // strongest change seen during the current episode
-    this.samples = 0;           // total samples fed (diagnostics)
-  }
-
-  // Feed one polled sample. Returns an emit descriptor { reason, peakPct, activeMs } when this sample
-  // triggers an event, otherwise null. `now` is the caller's clock (ms); `baseline` true means the
-  // change metric is not meaningful for this sample (fresh baseline / lost watch state) — reset the episode.
-  push({ changePct, now, baseline = false }) {
-    this.samples++;
-    const c = Number.isFinite(Number(changePct)) ? Number(changePct) : 0;
-    const cfg = this.cfg;
-
-    if (baseline) {
-      // A (re)baseline carries no comparable diff — abandon any in-progress episode, stay armed.
-      this.phase = 'idle';
-      this.peakPct = 0;
-      return null;
-    }
-
-    // Re-arm after cooldown expires, then evaluate this same sample as idle (so a sample that arrives
-    // already above the wake threshold starts the next episode immediately, no wasted poll).
-    if (this.phase === 'cooldown') {
-      if (now - this.lastEmitTs >= cfg.cooldownMs) this.phase = 'idle';
-      else return null;
-    }
-
-    if (this.phase === 'idle') {
-      if (c >= cfg.activityThreshold) {
-        this.phase = 'active';
-        this.activeStart = now;
-        this.lastMotionTs = now;
-        this.peakPct = c;
-      }
-      return null;
-    }
-
-    // phase === 'active'
-    if (c > this.peakPct) this.peakPct = c;
-    if (c >= cfg.quietThreshold) this.lastMotionTs = now;   // still moving — push the settle clock back
-    const quietFor = now - this.lastMotionTs;
-    const activeFor = now - this.activeStart;
-    if (quietFor >= cfg.debounceQuietMs) return this._emit('settled', now, activeFor);
-    if (activeFor >= cfg.maxWaitMs) return this._emit('maxwait', now, activeFor);
-    return null;
-  }
-
-  _emit(reason, now, activeMs) {
-    const peakPct = this.peakPct;
-    this.lastEmitTs = now;
-    this.phase = 'cooldown';
-    this.peakPct = 0;
-    return { reason, peakPct, activeMs };
-  }
-
-  // Snapshot for status reporting / tests.
-  get status() {
-    return { phase: this.phase, samples: this.samples, peakPct: this.peakPct };
-  }
-}
+// @vortex-os/computer-use — noise filter for the watch layer (design §22.1).
+//
+// Problem: video / games / scrolling change every frame, so a raw per-frame change threshold
+// floods the agent with one event per ripple of the SAME activity (each event costs a capture
+// + an LLM look). Measured calibration: a playing video jitters ~2.5–4% frame-to-frame, a real
+// scene cut jumps ~16.8%. We want to ignore the steady jitter and report only meaningful,
+// settled changes — without ever going completely silent on a screen that keeps moving.
+//
+// Design: debounce + cooldown COMBINED, with hysteresis. Neither alone works:
+//   - debounce alone ("report once it goes quiet") starves on video/games that never go quiet.
+//   - cooldown alone ("report at most once per N s") fires on a half-drawn transition frame (bad quality).
+// So they split roles:
+//   - debounce  = QUALITY  — emit the frame AFTER motion settles (a clean, stable shot).
+//   - cooldown  = FREQUENCY — never emit more than once per cooldownMs (suppress the ripples).
+//   - maxWait   = ANTI-STARVATION — once WOKEN, if motion never settles, emit anyway every maxWaitMs, so a
+//                 screen with sustained ABOVE-threshold motion still yields periodic snapshots (not silence).
+//   - hysteresis = two thresholds so ambient jitter never even wakes the filter (no flapping).
+// Note on the silence boundary: a screen that changes only BELOW activityThreshold (e.g. steady video jitter
+// at 2.5-4%) is intentionally treated as "nothing happening" and produces no events — that IS the goal of
+// ignoring the ripple, and it means maxWait only applies once a real (above-threshold) change has woken the
+// filter. Lower activityThreshold if you want fainter sustained motion to count as activity.
+//
+// This module is pure (no I/O, no timers of its own — the caller feeds it samples with an explicit
+// `now`), so the state machine is deterministically unit-testable from a synthetic change sequence.
+
+// Calibrated against the measured numbers above. All tunable per start_watch.
+export const FILTER_DEFAULTS = {
+  // % frame-to-frame change to WAKE the filter (enter an "active" episode). Set well above the
+  // measured video jitter ceiling (~4%) so steady playback never registers as a new event, yet
+  // below a scene cut (~16.8%) so real transitions do. The whole-frame metric dilutes tiny local
+  // changes (a clock, a cursor), so target a meaningful region/window for small UI events.
+  activityThreshold: 8,
+  // % below which a frame counts as "still". Hysteresis: must be < activityThreshold so a woken
+  // episode keeps tracking motion down to a lower floor before it's declared settled.
+  quietThreshold: 5,
+  // Motion must stay below quietThreshold this long before we emit a "settled" event (quality gate).
+  // Keep it a small multiple of the poll interval so a couple of quiet polls confirm the settle.
+  debounceQuietMs: 900,
+  // Minimum gap between emitted events (frequency cap). Suppresses the ripples of one activity.
+  cooldownMs: 6000,
+  // If an episode never settles (sustained motion: video, ongoing battle), emit anyway this often
+  // so a continuously-moving screen still produces periodic snapshots instead of going silent.
+  maxWaitMs: 8000,
+};
+
+const clampNum = (v, lo, hi, dflt) => {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return dflt;
+  return Math.min(hi, Math.max(lo, n));
+};
+
+// Sanitize caller-supplied options into a coherent, safe config. Enforces the hysteresis invariant
+// (quietThreshold < activityThreshold) so a misconfiguration can't make the filter flap or never wake.
+export function resolveFilterConfig(opts = {}) {
+  const d = FILTER_DEFAULTS;
+  let activityThreshold = clampNum(opts.activityThreshold, 0.1, 100, d.activityThreshold);
+  let quietThreshold = clampNum(opts.quietThreshold, 0, 100, d.quietThreshold);
+  // Keep the quiet floor strictly below the wake threshold (hysteresis). If a caller inverts them,
+  // pull the quiet floor down to just under the wake threshold rather than silently swapping intent.
+  if (quietThreshold >= activityThreshold) quietThreshold = Math.max(0, activityThreshold - 1);
+  return {
+    activityThreshold,
+    quietThreshold,
+    debounceQuietMs: clampNum(opts.debounceQuietMs, 0, 60000, d.debounceQuietMs),
+    cooldownMs: clampNum(opts.cooldownMs, 0, 600000, d.cooldownMs),
+    maxWaitMs: clampNum(opts.maxWaitMs, 100, 600000, d.maxWaitMs),
+  };
+}
+
+export class NoiseFilter {
+  constructor(opts = {}) {
+    this.cfg = resolveFilterConfig(opts);
+    this.phase = 'idle';        // idle | active | cooldown
+    this.activeStart = 0;       // ts the current episode woke
+    this.lastMotionTs = 0;      // last ts change was >= quietThreshold (i.e. "still moving")
+    this.lastEmitTs = -Infinity; // ts of the last emitted event
+    this.peakPct = 0;           // strongest change seen during the current episode
+    this.samples = 0;           // total samples fed (diagnostics)
+  }
+
+  // Feed one polled sample. Returns an emit descriptor { reason, peakPct, activeMs } when this sample
+  // triggers an event, otherwise null. `now` is the caller's clock (ms); `baseline` true means the
+  // change metric is not meaningful for this sample (fresh baseline / lost watch state) — reset the episode.
+  push({ changePct, now, baseline = false }) {
+    this.samples++;
+    const c = Number.isFinite(Number(changePct)) ? Number(changePct) : 0;
+    const cfg = this.cfg;
+
+    if (baseline) {
+      // A (re)baseline carries no comparable diff — abandon any in-progress episode, stay armed.
+      this.phase = 'idle';
+      this.peakPct = 0;
+      return null;
+    }
+
+    // Re-arm after cooldown expires, then evaluate this same sample as idle (so a sample that arrives
+    // already above the wake threshold starts the next episode immediately, no wasted poll).
+    if (this.phase === 'cooldown') {
+      if (now - this.lastEmitTs >= cfg.cooldownMs) this.phase = 'idle';
+      else return null;
+    }
+
+    if (this.phase === 'idle') {
+      if (c >= cfg.activityThreshold) {
+        this.phase = 'active';
+        this.activeStart = now;
+        this.lastMotionTs = now;
+        this.peakPct = c;
+      }
+      return null;
+    }
+
+    // phase === 'active'
+    if (c > this.peakPct) this.peakPct = c;
+    if (c >= cfg.quietThreshold) this.lastMotionTs = now;   // still moving — push the settle clock back
+    const quietFor = now - this.lastMotionTs;
+    const activeFor = now - this.activeStart;
+    if (quietFor >= cfg.debounceQuietMs) return this._emit('settled', now, activeFor);
+    if (activeFor >= cfg.maxWaitMs) return this._emit('maxwait', now, activeFor);
+    return null;
+  }
+
+  _emit(reason, now, activeMs) {
+    const peakPct = this.peakPct;
+    this.lastEmitTs = now;
+    this.phase = 'cooldown';
+    this.peakPct = 0;
+    return { reason, peakPct, activeMs };
+  }
+
+  // Snapshot for status reporting / tests.
+  get status() {
+    return { phase: this.phase, samples: this.samples, peakPct: this.peakPct };
+  }
+}

package/scripts/ocr.ps1

@@ -1,92 +1,92 @@
-# computer-use — OCR helper (Windows PowerShell 5.1 ONLY; invoked via powershell.exe).
-#
-# Why a separate helper: the resident worker runs under pwsh 7 (.NET Core), which dropped the WinRT
-# projection, so Windows.Media.Ocr (built-in, offline, NO install) cannot be loaded there. pwsh 7
-# delegates the OCR step to this script run via the in-box `powershell.exe` (Windows PowerShell 5.1),
-# where the WinRT types load. This powers the reflex path: read on-screen text WITHOUT a cloud LLM
-# round-trip, so an alert can be spoken in well under a second.
-#
-# Contract: input -ImagePath <png>; output exactly ONE JSON line on stdout — {ok, text, lang, ms} on
-# success, {ok:false, error} on failure (exit 1). Nothing else is written to stdout (clean to parse).
-# The PARENT must invoke this with an argument array (never a shell string): powershell.exe -NoProfile
-# -NonInteractive -ExecutionPolicy Bypass -File <abs ocr.ps1> -ImagePath <abs temp png>, and must impose
-# its OWN hard spawn timeout + temp-PNG cleanup + non-JSON-stdout handling (codex r1).
-#
-# SECURITY: the recognized text is UNTRUSTED input (it is screen content). It is for narration/alerting
-# ONLY — it must never be turned into an action or an instruction the agent follows, and a speaking
-# caller MUST add a provenance prefix + shape/cap it before TTS (design §14/§16/§24, codex r1 HIGH).
-# Defence-in-depth here: only OCR files under the allowed temp root, bound every WinRT await with a
-# timeout, and pre-shape/cap the emitted text so a hung or hostile crop can't stall or flood the caller.
-param(
-  [Parameter(Mandatory = $true)][string]$ImagePath,
-  [string]$Lang = '',                         # optional BCP-47 tag (e.g. 'ko', 'en-US'); else user-profile default
-  [int]$TimeoutMs = 4000,                     # per-await hard cap so a stuck WinRT call can't block forever
-  [string]$AllowRoot = '',                    # only OCR files under this root (default: the user TEMP dir)
-  [int]$MaxChars = 600                        # cap emitted text (a long spoken utterance is itself a risk)
-)
-$ErrorActionPreference = 'Stop'
-try { [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false) } catch {}
-function Emit($o) { [Console]::Out.WriteLine(($o | ConvertTo-Json -Compress)) }
-
-try {
-  # Path policy: resolve to a full path and require it under the allowed root (worker-owned temp crops only).
-  # The real guarantee is caller-side (it passes a denylist-gated, worker-created temp PNG); this is defence-in-depth.
-  $root = if ($AllowRoot) { $AllowRoot } else { $env:TEMP }
-  $rootFull = [System.IO.Path]::GetFullPath($root).TrimEnd('\') + '\'
-  $full = [System.IO.Path]::GetFullPath($ImagePath)
-  if (-not $full.StartsWith($rootFull, [System.StringComparison]::OrdinalIgnoreCase)) {
-    Emit @{ ok = $false; error = 'image path is outside the allowed temp root' }; exit 1
-  }
-  if (-not (Test-Path -LiteralPath $full -PathType Leaf)) { Emit @{ ok = $false; error = 'image not found' }; exit 1 }
-
-  $null = [Windows.Media.Ocr.OcrEngine, Windows.Foundation, ContentType = WindowsRuntime]
-  Add-Type -AssemblyName System.Runtime.WindowsRuntime
-  # The single-arg generic AsTask projection (IAsyncOperation<T> -> Task<T>) so we can synchronously await WinRT calls.
-  $asTask = ([System.WindowsRuntimeSystemExtensions].GetMethods() | Where-Object {
-      $_.Name -eq 'AsTask' -and $_.GetParameters().Count -eq 1 -and $_.GetParameters()[0].ParameterType.Name -eq 'IAsyncOperation`1'
-    })[0]
-  if (-not $asTask) { Emit @{ ok = $false; error = 'WinRT AsTask projection unavailable' }; exit 1 }
-  # Bound every await: if a WinRT call hangs, .Wait(timeout) returns false and we fail cleanly instead of blocking.
-  function Await($op, $t) {
-    $m = $asTask.MakeGenericMethod($t); $task = $m.Invoke($null, @($op))
-    if (-not $task.Wait($TimeoutMs)) { throw "OCR step timed out after ${TimeoutMs}ms" }
-    $task.Result
-  }
-
-  # Engine: a specific recognizer language if requested and installed, otherwise the user-profile default.
-  $eng = $null
-  if ($Lang) {
-    try {
-      $L = New-Object Windows.Globalization.Language $Lang
-      if ([Windows.Media.Ocr.OcrEngine]::IsLanguageSupported($L)) { $eng = [Windows.Media.Ocr.OcrEngine]::TryCreateFromLanguage($L) }
-    } catch {}
-  }
-  if (-not $eng) { $eng = [Windows.Media.Ocr.OcrEngine]::TryCreateFromUserProfileLanguages() }
-  if (-not $eng) { Emit @{ ok = $false; error = 'no OCR recognizer language installed on this machine' }; exit 1 }
-
-  $sw = [System.Diagnostics.Stopwatch]::StartNew()
-  $file = Await ([Windows.Storage.StorageFile, Windows.Storage, ContentType = WindowsRuntime]::GetFileFromPathAsync($full)) ([Windows.Storage.StorageFile])
-  $stream = Await ($file.OpenAsync([Windows.Storage.FileAccessMode]::Read)) ([Windows.Storage.Streams.IRandomAccessStream])
-  $decoder = Await ([Windows.Graphics.Imaging.BitmapDecoder, Windows.Graphics, ContentType = WindowsRuntime]::CreateAsync($stream)) ([Windows.Graphics.Imaging.BitmapDecoder])
-  $soft = Await ($decoder.GetSoftwareBitmapAsync()) ([Windows.Graphics.Imaging.SoftwareBitmap])
-  # Windows OCR is picky about pixel format on some decoders — normalize to Bgra8 for robustness (codex r1 low/med).
-  if ($soft.BitmapPixelFormat -ne [Windows.Graphics.Imaging.BitmapPixelFormat]::Bgra8) {
-    $soft = [Windows.Graphics.Imaging.SoftwareBitmap]::Convert($soft, [Windows.Graphics.Imaging.BitmapPixelFormat]::Bgra8, [Windows.Graphics.Imaging.BitmapAlphaMode]::Premultiplied)
-  }
-  $res = Await ($eng.RecognizeAsync($soft)) ([Windows.Media.Ocr.OcrResult])
-  $sw.Stop()
-
-  # Pre-shape the recognized text defensively: strip control/format chars (incl. bidi marks), collapse
-  # whitespace, cap length. The SPEAKING caller still adds a provenance prefix + full sanitization/budget.
-  $txt = [string]$res.Text
-  $txt = ($txt -replace '\p{C}', ' ') -replace '\s+', ' '
-  $txt = $txt.Trim()
-  $truncated = $false
-  if ($txt.Length -gt $MaxChars) { $txt = $txt.Substring(0, $MaxChars); $truncated = $true }
-
-  Emit @{ ok = $true; text = $txt; lang = $eng.RecognizerLanguage.LanguageTag; ms = [int]$sw.Elapsed.TotalMilliseconds; truncated = $truncated }
-} catch {
-  # Keep the reason generic: don't surface raw paths / exception internals into cloud-visible agent context (codex r1 low).
-  Emit @{ ok = $false; error = 'ocr failed' }
-  exit 1
-}
+# computer-use — OCR helper (Windows PowerShell 5.1 ONLY; invoked via powershell.exe).
+#
+# Why a separate helper: the resident worker runs under pwsh 7 (.NET Core), which dropped the WinRT
+# projection, so Windows.Media.Ocr (built-in, offline, NO install) cannot be loaded there. pwsh 7
+# delegates the OCR step to this script run via the in-box `powershell.exe` (Windows PowerShell 5.1),
+# where the WinRT types load. This powers the reflex path: read on-screen text WITHOUT a cloud LLM
+# round-trip, so an alert can be spoken in well under a second.
+#
+# Contract: input -ImagePath <png>; output exactly ONE JSON line on stdout — {ok, text, lang, ms} on
+# success, {ok:false, error} on failure (exit 1). Nothing else is written to stdout (clean to parse).
+# The PARENT must invoke this with an argument array (never a shell string): powershell.exe -NoProfile
+# -NonInteractive -ExecutionPolicy Bypass -File <abs ocr.ps1> -ImagePath <abs temp png>, and must impose
+# its OWN hard spawn timeout + temp-PNG cleanup + non-JSON-stdout handling (codex r1).
+#
+# SECURITY: the recognized text is UNTRUSTED input (it is screen content). It is for narration/alerting
+# ONLY — it must never be turned into an action or an instruction the agent follows, and a speaking
+# caller MUST add a provenance prefix + shape/cap it before TTS (design §14/§16/§24, codex r1 HIGH).
+# Defence-in-depth here: only OCR files under the allowed temp root, bound every WinRT await with a
+# timeout, and pre-shape/cap the emitted text so a hung or hostile crop can't stall or flood the caller.
+param(
+  [Parameter(Mandatory = $true)][string]$ImagePath,
+  [string]$Lang = '',                         # optional BCP-47 tag (e.g. 'ko', 'en-US'); else user-profile default
+  [int]$TimeoutMs = 4000,                     # per-await hard cap so a stuck WinRT call can't block forever
+  [string]$AllowRoot = '',                    # only OCR files under this root (default: the user TEMP dir)
+  [int]$MaxChars = 600                        # cap emitted text (a long spoken utterance is itself a risk)
+)
+$ErrorActionPreference = 'Stop'
+try { [Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false) } catch {}
+function Emit($o) { [Console]::Out.WriteLine(($o | ConvertTo-Json -Compress)) }
+
+try {
+  # Path policy: resolve to a full path and require it under the allowed root (worker-owned temp crops only).
+  # The real guarantee is caller-side (it passes a denylist-gated, worker-created temp PNG); this is defence-in-depth.
+  $root = if ($AllowRoot) { $AllowRoot } else { $env:TEMP }
+  $rootFull = [System.IO.Path]::GetFullPath($root).TrimEnd('\') + '\'
+  $full = [System.IO.Path]::GetFullPath($ImagePath)
+  if (-not $full.StartsWith($rootFull, [System.StringComparison]::OrdinalIgnoreCase)) {
+    Emit @{ ok = $false; error = 'image path is outside the allowed temp root' }; exit 1
+  }
+  if (-not (Test-Path -LiteralPath $full -PathType Leaf)) { Emit @{ ok = $false; error = 'image not found' }; exit 1 }
+
+  $null = [Windows.Media.Ocr.OcrEngine, Windows.Foundation, ContentType = WindowsRuntime]
+  Add-Type -AssemblyName System.Runtime.WindowsRuntime
+  # The single-arg generic AsTask projection (IAsyncOperation<T> -> Task<T>) so we can synchronously await WinRT calls.
+  $asTask = ([System.WindowsRuntimeSystemExtensions].GetMethods() | Where-Object {
+      $_.Name -eq 'AsTask' -and $_.GetParameters().Count -eq 1 -and $_.GetParameters()[0].ParameterType.Name -eq 'IAsyncOperation`1'
+    })[0]
+  if (-not $asTask) { Emit @{ ok = $false; error = 'WinRT AsTask projection unavailable' }; exit 1 }
+  # Bound every await: if a WinRT call hangs, .Wait(timeout) returns false and we fail cleanly instead of blocking.
+  function Await($op, $t) {
+    $m = $asTask.MakeGenericMethod($t); $task = $m.Invoke($null, @($op))
+    if (-not $task.Wait($TimeoutMs)) { throw "OCR step timed out after ${TimeoutMs}ms" }
+    $task.Result
+  }
+
+  # Engine: a specific recognizer language if requested and installed, otherwise the user-profile default.
+  $eng = $null
+  if ($Lang) {
+    try {
+      $L = New-Object Windows.Globalization.Language $Lang
+      if ([Windows.Media.Ocr.OcrEngine]::IsLanguageSupported($L)) { $eng = [Windows.Media.Ocr.OcrEngine]::TryCreateFromLanguage($L) }
+    } catch {}
+  }
+  if (-not $eng) { $eng = [Windows.Media.Ocr.OcrEngine]::TryCreateFromUserProfileLanguages() }
+  if (-not $eng) { Emit @{ ok = $false; error = 'no OCR recognizer language installed on this machine' }; exit 1 }
+
+  $sw = [System.Diagnostics.Stopwatch]::StartNew()
+  $file = Await ([Windows.Storage.StorageFile, Windows.Storage, ContentType = WindowsRuntime]::GetFileFromPathAsync($full)) ([Windows.Storage.StorageFile])
+  $stream = Await ($file.OpenAsync([Windows.Storage.FileAccessMode]::Read)) ([Windows.Storage.Streams.IRandomAccessStream])
+  $decoder = Await ([Windows.Graphics.Imaging.BitmapDecoder, Windows.Graphics, ContentType = WindowsRuntime]::CreateAsync($stream)) ([Windows.Graphics.Imaging.BitmapDecoder])
+  $soft = Await ($decoder.GetSoftwareBitmapAsync()) ([Windows.Graphics.Imaging.SoftwareBitmap])
+  # Windows OCR is picky about pixel format on some decoders — normalize to Bgra8 for robustness (codex r1 low/med).
+  if ($soft.BitmapPixelFormat -ne [Windows.Graphics.Imaging.BitmapPixelFormat]::Bgra8) {
+    $soft = [Windows.Graphics.Imaging.SoftwareBitmap]::Convert($soft, [Windows.Graphics.Imaging.BitmapPixelFormat]::Bgra8, [Windows.Graphics.Imaging.BitmapAlphaMode]::Premultiplied)
+  }
+  $res = Await ($eng.RecognizeAsync($soft)) ([Windows.Media.Ocr.OcrResult])
+  $sw.Stop()
+
+  # Pre-shape the recognized text defensively: strip control/format chars (incl. bidi marks), collapse
+  # whitespace, cap length. The SPEAKING caller still adds a provenance prefix + full sanitization/budget.
+  $txt = [string]$res.Text
+  $txt = ($txt -replace '\p{C}', ' ') -replace '\s+', ' '
+  $txt = $txt.Trim()
+  $truncated = $false
+  if ($txt.Length -gt $MaxChars) { $txt = $txt.Substring(0, $MaxChars); $truncated = $true }
+
+  Emit @{ ok = $true; text = $txt; lang = $eng.RecognizerLanguage.LanguageTag; ms = [int]$sw.Elapsed.TotalMilliseconds; truncated = $truncated }
+} catch {
+  # Keep the reason generic: don't surface raw paths / exception internals into cloud-visible agent context (codex r1 low).
+  Emit @{ ok = $false; error = 'ocr failed' }
+  exit 1
+}