@trillboards/edge-sdk 0.2.154 → 0.2.157

package/deploy/litertlm/test_trillboards_litertlm_shim.py

@@ -6,6 +6,7 @@ the recorded kwargs prove WHICH configs are dropped and which survive.
 """
 
 import importlib
+import base64
 import hashlib
 import os
 import sys
@@ -208,6 +209,111 @@ class ShimTest(unittest.TestCase):
         self.assertEqual(captured["response"]["choices"], [{"text": "unchanged"}])
         self.assertNotIn("runtimeModel", captured["response"])
 
+    def test_native_images_are_hashed_at_the_ffi_boundary_not_copied_from_headers(self):
+        shim = self._load(TRILLBOARDS_LITERTLM_SHIM="1")
+        seen = []
+        class Conversation:
+            def send_message_async(self, message):
+                seen.append(message)
+                return "native result"
+        shim._apply_native_images(SimpleNamespace(Conversation=Conversation))
+        payloads = [b"whole marked area", b"person one", b"person two"]
+        expected = [hashlib.sha256(b).hexdigest() for b in payloads]
+        state = {"expected": expected, "consumed": None}
+        token = shim._image_request.set(state)
+        self.addCleanup(lambda: shim._image_request.reset(token))
+        message = {"content": [{"type": "image", "blob": base64.b64encode(b).decode()} for b in payloads]}
+        self.assertEqual(Conversation().send_message_async(message), "native result")
+        self.assertEqual(state["consumed"], expected)
+        self.assertEqual(len(seen), 1)
+        with self.assertRaisesRegex(ValueError, "native image"):
+            Conversation().send_message_async({"content": message["content"][:1]})
+        self.assertEqual(len(seen), 1)
+
+    def test_image_capacity_is_lazy_and_only_added_for_explicit_native_requests(self):
+        shim = self._load(TRILLBOARDS_LITERTLM_SHIM="1")
+        calls = []
+        class Engine:
+            def __init__(self, **kwargs):
+                calls.append(kwargs)
+        shim._apply_model_snapshot(Engine)
+        Engine()
+        self.assertEqual(calls, [{}])
+        token = shim._image_request.set({"expected": ["a" * 64, "b" * 64], "consumed": None})
+        try:
+            engine = Engine()
+            self.assertEqual(calls[1], {"max_num_images": 5})
+            self.assertEqual(engine._trillboards_image_capacity, 5)
+        finally:
+            shim._image_request.reset(token)
+        Engine()
+        self.assertEqual(calls[2], {})
+
+    def _native_http(self, low_memory=False):
+        shim = self._load(TRILLBOARDS_LITERTLM_SHIM="1")
+        events = []
+        images = [b"area", b"person"]
+        hashes = [hashlib.sha256(b).hexdigest() for b in images]
+        class Engine:
+            def __init__(self, **kwargs):
+                events.append(("allocate", kwargs.get("max_num_images", 1)))
+                if low_memory and kwargs.get("max_num_images") == 5:
+                    raise MemoryError("test image capacity allocation")
+                self.backend = SimpleNamespace(get_name=lambda: "cpu")
+                self._trillboards_artifact_sha256 = "a" * 64
+            def __exit__(self, *args):
+                events.append(("release", self._trillboards_image_capacity))
+        class Conversation:
+            def send_message_async(self, message):
+                events.append(("native", len(message["content"])))
+        shim._apply_model_snapshot(Engine)
+        shim._apply_native_images(SimpleNamespace(Conversation=Conversation))
+        server = SimpleNamespace(litert_lm_engine=Engine())
+        class Handler:
+            headers = {"X-Trillboards-Model-Sha256": "a" * 64, "X-Trillboards-Image-Sha256": ",".join(hashes)}
+            def __init__(self):
+                self.server = server
+            def send_error(self, code, message):
+                events.append(("error", code))
+            def _get_engine(self, model_id, *, backend):
+                if self.server.litert_lm_engine is None:
+                    try:
+                        self.server.litert_lm_engine = Engine()
+                    except MemoryError:
+                        self.send_error(500, "allocation failed")
+                        return None
+                return self.server.litert_lm_engine
+            def do_POST(self):
+                if self._get_engine("gemma", backend="cpu") is not None:
+                    Conversation().send_message_async({"content": [
+                        {"type": "image", "blob": base64.b64encode(b).decode()} for b in images]})
+                    module._dump_json({"object": "chat.completion"})
+        output = []
+        module = SimpleNamespace(OpenAIHandler=Handler, _dump_json=lambda data, **kwargs: output.append(data))
+        shim.apply_runtime_handler(module)
+        handler = Handler()
+        handler.do_POST()
+        return handler, events, output, hashes
+
+    def test_native_http_receipt_is_outside_model_text_and_capacity_reuses_one_engine(self):
+        handler, events, output, hashes = self._native_http()
+        self.assertEqual(events[:3], [("allocate", 1), ("release", 1), ("allocate", 5)])
+        self.assertEqual(output[0]["nativeImageInputs"], {"version": 1, "sha256": hashes})
+        handler.do_POST()
+        self.assertEqual(sum(e[0] == "allocate" for e in events), 2)
+        handler.headers = {"X-Trillboards-Model-Sha256": "a" * 64}
+        handler.do_POST()
+        self.assertNotIn("nativeImageInputs", output[-1])
+
+    def test_capacity_allocation_failure_leaves_single_image_recovery_available(self):
+        handler, events, output, _ = self._native_http(low_memory=True)
+        self.assertEqual(events[:4], [("allocate", 1), ("release", 1), ("allocate", 5), ("error", 500)])
+        self.assertEqual(output, [])
+        handler.headers = {"X-Trillboards-Model-Sha256": "a" * 64}
+        handler.do_POST()
+        self.assertEqual(events[-2:], [("allocate", 1), ("native", 2)])
+        self.assertNotIn("nativeImageInputs", output[-1])
+
 
 if __name__ == "__main__":
     unittest.main()

package/deploy/litertlm/trillboards_litertlm_shim.py

@@ -82,6 +82,9 @@ from __future__ import annotations
 
 import os
 import sys
+import contextvars
+
+_image_request = contextvars.ContextVar('trillboards_native_images', default=None)
 
 __all__ = ["install", "apply_to", "should_drop", "TAG"]
 
@@ -129,6 +132,7 @@ def apply_to(litert_lm_module: object) -> bool:
     Returns True when the wrap is in place (including when it already was).
     """
     engine_cls = getattr(litert_lm_module, "Engine", None)
+    _apply_native_images(litert_lm_module)
     if engine_cls is not None:
         _apply_model_snapshot(engine_cls)
     original = getattr(engine_cls, "create_conversation", None)
@@ -261,9 +265,16 @@ def _apply_model_snapshot(engine_cls):
         return
 
     def initialize(self, *args, **kwargs):
+        images = _image_request.get()
+        if images is not None:
+            # The public option used by the saved-frame comparison. No larger
+            # engine is allocated on ordinary single-image/off-switch starts.
+            kwargs['max_num_images'] = 5
         path = kwargs.get('model_path', args[0] if args else None)
         if path is None:  # lightweight contract-test engines have no artifact
-            return original(self, *args, **kwargs)
+            result = original(self, *args, **kwargs)
+            self._trillboards_image_capacity = kwargs.get('max_num_images', 1)
+            return result
         snapshot, sha = _verified_snapshot(path)
         if 'model_path' in kwargs:
             kwargs['model_path'] = snapshot
@@ -271,11 +282,41 @@ def _apply_model_snapshot(engine_cls):
             args = (snapshot, *args[1:])
         original(self, *args, **kwargs)
         self._trillboards_artifact_sha256 = sha
+        self._trillboards_image_capacity = kwargs.get('max_num_images', 1)
 
     initialize._trillboards_model_snapshot = True
     engine_cls.__init__ = initialize
 
 
+def _apply_native_images(module):
+    """Prove the exact JPEGs consumed immediately before native serialization."""
+    import base64
+    import hashlib
+    conversation = getattr(module, 'Conversation', None)
+    original = getattr(conversation, 'send_message_async', None)
+    if original is None or getattr(original, '_trillboards_native_images', False):
+        return
+
+    def send(self, message, *args, **kwargs):
+        state = _image_request.get()
+        if state is not None:
+            parts = message.get('content', []) if isinstance(message, dict) else []
+            hashes = []
+            for part in parts:
+                if isinstance(part, dict) and part.get('type') == 'image':
+                    blob = part.get('blob')
+                    if not isinstance(blob, str):
+                        raise ValueError('native image must be an inline JPEG')
+                    hashes.append(hashlib.sha256(base64.b64decode(blob, validate=True)).hexdigest())
+            if hashes != state['expected']:
+                raise ValueError('native image input count, order or bytes do not match')
+            state['consumed'] = hashes
+        return original(self, message, *args, **kwargs)
+
+    send._trillboards_native_images = True
+    conversation.send_message_async = send
+
+
 def apply_runtime_handler(module):
     """Bind proof to the engine used by this HTTP request, outside model text."""
     import contextvars
@@ -291,13 +332,31 @@ def apply_runtime_handler(module):
         if expected is not None and not re.fullmatch(r'[a-f0-9]{64}', expected):
             self.send_error(400, 'invalid selected artifact hash')
             return
+        raw_images = self.headers.get('X-Trillboards-Image-Sha256')
+        images = raw_images.split(',') if raw_images is not None else None
+        if images is not None and (expected is None or not 2 <= len(images) <= 5
+                or any(not re.fullmatch(r'[a-f0-9]{64}', value) for value in images)):
+            self.send_error(400, 'invalid pinned native image request')
+            return
+        image_token = _image_request.set({'expected': images, 'consumed': None} if images is not None else None)
         token = active.set({'expected': expected, 'proof': None})
         try:
             return original_post(self)
         finally:
             active.reset(token)
+            _image_request.reset(image_token)
 
     def get_engine(self, *args, **kwargs):
+        images = _image_request.get()
+        if images is not None:
+            server = getattr(self, 'server', None)
+            previous = getattr(server, 'litert_lm_engine', None)
+            if previous is not None and getattr(previous, '_trillboards_image_capacity', 1) < 5:
+                # The pinned CLI's HTTPServer is serial. Release its previous
+                # engine BEFORE allocating the larger one; no duplicate model.
+                previous.__exit__(None, None, None)
+                server.litert_lm_engine = None
+                _say('native image request: upgrading idle engine capacity to five')
         engine = original_engine(self, *args, **kwargs)
         state = active.get()
         if engine is None or state is None:
@@ -326,6 +385,11 @@ def apply_runtime_handler(module):
         state = active.get()
         if isinstance(data, dict) and data.get('object') == 'chat.completion' and state and state['proof']:
             data = {**data, 'runtimeModel': dict(state['proof'])}
+        images = _image_request.get()
+        if isinstance(data, dict) and data.get('object') == 'chat.completion' and images is not None:
+            if images['consumed'] != images['expected']:
+                raise ValueError('native image consumption was not verified')
+            data = {**data, 'nativeImageInputs': {'version': 1, 'sha256': images['consumed']}}
         return original_dump(data, **kwargs)
 
     handler.do_POST, handler._get_engine, module._dump_json = do_post, get_engine, dump_json

package/deploy/windows/apply-update.ps1

@@ -499,7 +499,7 @@ function Invoke-Commit {
     # failure and $ErrorActionPreference = 'Stop' turns that into ours.
     & $installUpdate -InstallDir $InstallDir -StagingDir $PayloadDir
   } catch {
-    Fail 'failed' "the swap failed and the previous version was restored: $($_.Exception.Message)"
+    Fail 'failed' "the update transaction failed: $($_.Exception.Message)"
   }
 
   # The measured half. The probe predicts; this observes.

package/deploy/windows/install-update.ps1

@@ -10,9 +10,17 @@ param(
 
 $ErrorActionPreference = "Stop"
 $previousDir = Join-Path $InstallDir ".previous"
+$runtimeRepairMarker = Join-Path $previousDir 'model-runtime-rollback-failed.json'
 $parts = @("bin", "lib")
 $movedPrevious = New-Object System.Collections.Generic.List[string]
 $movedStaged = New-Object System.Collections.Generic.List[string]
+$script:modelRuntimeUpdate = $null
+
+# A failed external-runtime rollback owns this recovery tree. A later update
+# must not delete it in the normal .previous cleanup or restart sensing over it.
+if (Test-Path -LiteralPath $runtimeRepairMarker) {
+  throw 'The previous local AI rollback needs repair; saved connector/runtime backups were left untouched'
+}
 
 function Assert-ConnectorVersion([string]$Root) {
   $node = Join-Path $Root "bin\node.exe"
@@ -43,6 +51,109 @@ function Register-Connector([string]$Root) {
   if ($LASTEXITCODE -ne 0) { throw "Scheduled-task registration failed." }
 }
 
+function Get-OwnedLocalAiProcesses {
+  # Task Scheduler can stop the uv launcher while leaving its Python child
+  # alive. Match only this user's model server on the verified task's port;
+  # never kill all Python processes or a different user's listener.
+  $portPattern = '(?:^|\s)--port(?:\s+|=)' + $script:modelRuntimeUpdate.Port + '(?=\s|$)'
+  $processes = Get-CimInstance Win32_Process -Filter "Name = 'python.exe' OR Name = 'pythonw.exe' OR Name = 'litert-lm.exe'" -OperationTimeoutSec 5 -ErrorAction Stop
+  foreach ($process in $processes) {
+    if (-not $process.CommandLine -or $process.CommandLine -notmatch 'litert[-_]lm' -or
+        $process.CommandLine -notmatch '(?:^|\s)serve(?=\s|$)' -or $process.CommandLine -notmatch $portPattern) { continue }
+    $owner = Invoke-CimMethod -InputObject $process -MethodName GetOwnerSid -OperationTimeoutSec 5 -ErrorAction Stop
+    if ($owner.ReturnValue -ne 0 -or -not $owner.Sid) { throw 'Cannot verify the model process owner; no unverified process was stopped' }
+    if ($owner.Sid -eq $script:modelRuntimeUpdate.OwnerSid) { $process }
+  }
+}
+
+function Stop-LocalAiForUpdate {
+  Disable-ScheduledTask -TaskName 'TrillboardsLiteRtLm' -ErrorAction Stop | Out-Null
+  Stop-ScheduledTask -TaskName 'TrillboardsLiteRtLm' -ErrorAction Stop
+  for ($attempt = 0; $attempt -lt 15; $attempt++) {
+    $task = Get-ScheduledTask -TaskName 'TrillboardsLiteRtLm' -ErrorAction Stop
+    $remaining = @(Get-OwnedLocalAiProcesses)
+    foreach ($process in $remaining) { Stop-Process -Id $process.ProcessId -Force -ErrorAction Stop }
+    $listenerErrors = @()
+    $listeners = @(Get-NetTCPConnection -LocalPort $script:modelRuntimeUpdate.Port -State Listen -ErrorAction SilentlyContinue -ErrorVariable listenerErrors)
+    if (@($listenerErrors | Where-Object { $_.CategoryInfo.Category -ne 'ObjectNotFound' }).Count) { throw 'Cannot verify the local AI port is free' }
+    if ($task.State -notin @('Running', 'Queued') -and $remaining.Count -eq 0 -and $listeners.Count -eq 0) { return }
+    Start-Sleep -Seconds 1
+  }
+  throw 'The local AI task, server process or listening port did not stop; runtime files were not replaced'
+}
+
+function Restore-LocalAiTaskState {
+  if ($null -eq $script:modelRuntimeUpdate) { return }
+  if ($script:modelRuntimeUpdate.Enabled) {
+    Enable-ScheduledTask -TaskName 'TrillboardsLiteRtLm' -ErrorAction Stop | Out-Null
+    if ($script:modelRuntimeUpdate.Running) { Start-ScheduledTask -TaskName 'TrillboardsLiteRtLm' -ErrorAction Stop }
+  } else {
+    Disable-ScheduledTask -TaskName 'TrillboardsLiteRtLm' -ErrorAction Stop | Out-Null
+  }
+}
+
+function Update-LocalAiRuntime([string]$Root) {
+  $modelTaskErrors = @()
+  $task = Get-ScheduledTask -TaskName 'TrillboardsLiteRtLm' -ErrorAction SilentlyContinue -ErrorVariable modelTaskErrors
+  if (-not $task) {
+    # Only a genuine absence belongs to first-time setup. An inaccessible task
+    # must not be mistaken for "no model service" and silently keep old code.
+    if (@($modelTaskErrors | Where-Object { $_.CategoryInfo.Category -ne 'ObjectNotFound' }).Count) {
+      throw 'The local AI task is inaccessible; runtime refresh was not skipped'
+    }
+    return
+  }
+  $taskUser = [string]$task.Principal.UserId
+  $taskSid = if ($taskUser -match '^S-1-') { $taskUser } else {
+    (New-Object Security.Principal.NTAccount($taskUser)).Translate([Security.Principal.SecurityIdentifier]).Value
+  }
+  $currentSid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+  $action = @($task.Actions)
+  $ownTool = Join-Path $env:USERPROFILE '.local\bin\litert-lm.exe'
+  if ($taskSid -ne $currentSid -or $action.Count -ne 1 -or
+      [IO.Path]::GetFullPath([string]$action[0].Execute) -ine [IO.Path]::GetFullPath($ownTool)) {
+    throw 'Cannot verify ownership of the local AI task; no runtime was changed'
+  }
+  $serverArguments = [string]$action[0].Arguments
+  $ports = [regex]::Matches($serverArguments, '(?:^|\s)--port(?:\s+|=)([0-9]+)(?=\s|$)')
+  if ($serverArguments -notmatch '^serve\s' -or $ports.Count -ne 1 -or
+      [long]$ports[0].Groups[1].Value -lt 1 -or [long]$ports[0].Groups[1].Value -gt 65535) {
+    throw 'Cannot verify the local AI task port; no runtime was changed'
+  }
+  $setup = Join-Path $Root 'bin\setup-litertlm.ps1'
+  if (-not (Test-Path -LiteralPath $setup -PathType Leaf)) { throw 'The released local AI setup is missing' }
+  # Inspect first: an unchanged shim does NOT restart a healthy model server on
+  # every SDK update. /v1/models and the CLI version cannot detect stale code.
+  $state = (& $setup -RuntimeAction Inspect | Out-String).Trim() | ConvertFrom-Json
+  if ($LASTEXITCODE -ne 0 -or $state.version -ne 1) { throw 'Could not inspect the installed local AI runtime' }
+  if (-not $state.needsRefresh) { return }
+  $script:modelRuntimeUpdate = [pscustomobject]@{
+    Enabled = [bool]$task.Settings.Enabled
+    Running = ($task.State -eq 'Running')
+    OwnerSid = $currentSid
+    Port = [int]$ports[0].Groups[1].Value
+    Setup = $setup
+    Backup = (Join-Path $previousDir 'litertlm-runtime')
+  }
+  Stop-LocalAiForUpdate
+  # This mode is local file replacement only. It never downloads a CLI/model,
+  # imports weights, resets tuning, re-registers tasks or runs image inference.
+  & $setup -RuntimeAction Refresh -RuntimeBackupDir $script:modelRuntimeUpdate.Backup
+  if ($LASTEXITCODE -ne 0) { throw 'The local AI runtime refresh failed' }
+  Restore-LocalAiTaskState
+}
+
+function Restore-LocalAiRuntime {
+  if ($null -eq $script:modelRuntimeUpdate) { return }
+  Stop-LocalAiForUpdate
+  $receipt = Join-Path $script:modelRuntimeUpdate.Backup 'runtime-backup.json'
+  if (Test-Path -LiteralPath $receipt -PathType Leaf) {
+    & $script:modelRuntimeUpdate.Setup -RuntimeAction Restore -RuntimeBackupDir $script:modelRuntimeUpdate.Backup
+    if ($LASTEXITCODE -ne 0) { throw 'The previous local AI runtime could not be verified; rollback backup was preserved' }
+  }
+  Restore-LocalAiTaskState
+}
+
 <#
   Carry the detector's RAM ceiling onto an EXISTING install.
 
@@ -192,6 +303,9 @@ try {
   }
 
   Assert-ConnectorVersion $InstallDir
+  # The Python venv is OUTSIDE bin/lib. Refresh it transactionally before the
+  # connector can review a saved frame with the new native-image contract.
+  Update-LocalAiRuntime $InstallDir
   Register-Connector $InstallDir
   Assert-ConnectorScheduled
   if (Test-Path (Join-Path $InstallDir "trillboards.config.json")) {
@@ -206,11 +320,21 @@ try {
   Write-Host "Trillboards Edge update installed successfully."
 } catch {
   $failure = $_
+  $runtimeRollbackFailure = $null
   try {
     $stopScript = Join-Path $InstallDir "bin\stop-existing.ps1"
     if (Test-Path $stopScript) { & $stopScript -InstallDir $InstallDir }
   } catch {}
 
+  # Use the NEW setup while its bin tree still exists. Restore external runtime
+  # bytes before rolling bin/lib back; neither path touches pairings or spools.
+  try { Restore-LocalAiRuntime } catch { $runtimeRollbackFailure = $_.Exception.Message }
+  if ($runtimeRollbackFailure) {
+    [IO.File]::WriteAllText($runtimeRepairMarker,
+      (@{ version = 1; failedAtUtc = [DateTime]::UtcNow.ToString('o'); detail = $runtimeRollbackFailure } | ConvertTo-Json),
+      [Text.UTF8Encoding]::new($false))
+    throw "Update failed: $($failure.Exception.Message). Local AI rollback needs repair: $runtimeRollbackFailure. Preserved both connector trees, runtime backups, pairings and saved evidence."
+  }
   foreach ($part in $movedStaged) {
     Remove-Item -Recurse -Force (Join-Path $InstallDir $part) -ErrorAction SilentlyContinue
   }

package/deploy/windows/setup-litertlm.ps1

@@ -24,6 +24,10 @@ param(
   [switch]$RequireBundledModel,
   [switch]$AllowModelDownload,
   [string]$ProgressPath = "",
+  # Upgrades refresh only our shipped Python adapter, never the CLI, weights,
+  # model config or task registration. The caller owns stopping/restarting it.
+  [ValidateSet('Setup', 'Inspect', 'Refresh', 'Restore')][string]$RuntimeAction = 'Setup',
+  [string]$RuntimeBackupDir = "",
   [switch]$SmokeTest
 )
 
@@ -333,6 +337,128 @@ function Import-VerifiedModel([string]$SourcePath, [string]$ExecutablePath) {
   return (($LASTEXITCODE -eq 0) -and (Test-LitertLmModel $ExecutablePath))
 }
 
+# One owner for the shim on fresh installs AND upgrades. None of these helpers
+# import a model, rewrite model config, install dependencies or register tasks.
+function Get-LitertlmShimPaths([string]$UvPath) {
+  $shim = $null
+  foreach ($candidate in @(
+    (Join-Path $PSScriptRoot 'trillboards_litertlm_shim.py'),
+    (Join-Path $PSScriptRoot '..\litertlm\trillboards_litertlm_shim.py')
+  )) { if (Test-Path -LiteralPath $candidate -PathType Leaf) { $shim = $candidate; break } }
+  if (-not $shim) { throw 'The released litert-lm shim is missing' }
+  $toolDir = (& $UvPath tool dir 2>$null | Select-Object -First 1)
+  if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($toolDir)) { throw 'Cannot resolve uv tool dir' }
+  $venv = [IO.Path]::GetFullPath((Join-Path $toolDir.Trim() 'litert-lm'))
+  $py = Join-Path $venv 'Scripts\python.exe'
+  if (-not (Test-Path -LiteralPath $py -PathType Leaf)) { throw 'The installed litert-lm Python is missing' }
+  $site = (& $py -c "import sysconfig;print(sysconfig.get_paths()['purelib'])" 2>$null | Select-Object -First 1)
+  if ($LASTEXITCODE -ne 0 -or [string]::IsNullOrWhiteSpace($site)) { throw 'Cannot resolve litert-lm site-packages' }
+  $site = [IO.Path]::GetFullPath($site.Trim())
+  if (-not $site.StartsWith(($venv.TrimEnd('\') + '\'), [StringComparison]::OrdinalIgnoreCase) -or
+      -not (Test-Path -LiteralPath $site -PathType Container)) { throw 'The runtime site is outside its managed venv' }
+  return [pscustomobject]@{ Source = $shim; Python = $py; Site = $site }
+}
+
+function Get-LitertlmShimFiles($Paths) {
+  return @(
+    [pscustomobject]@{ Name = 'trillboards_litertlm_shim.py'; Bytes = [IO.File]::ReadAllBytes($Paths.Source) },
+    [pscustomobject]@{ Name = 'trillboards-litertlm-shim.pth'; Bytes = [Text.Encoding]::ASCII.GetBytes("import trillboards_litertlm_shim`r`n") }
+  )
+}
+
+function Get-ShimBytesHash([byte[]]$Bytes) {
+  $hasher = [Security.Cryptography.SHA256]::Create()
+  try { return ([BitConverter]::ToString($hasher.ComputeHash($Bytes))).Replace('-', '').ToLowerInvariant() }
+  finally { $hasher.Dispose() }
+}
+
+function Get-LitertlmShimState([string]$UvPath) {
+  $paths = Get-LitertlmShimPaths $UvPath
+  $needsRefresh = $false
+  foreach ($file in (Get-LitertlmShimFiles $paths)) {
+    $target = Join-Path $paths.Site $file.Name
+    if (-not (Test-Path -LiteralPath $target -PathType Leaf)) { $needsRefresh = $true; continue }
+    if ((Get-FileHash -LiteralPath $target -Algorithm SHA256).Hash.ToLowerInvariant() -ne (Get-ShimBytesHash $file.Bytes)) { $needsRefresh = $true }
+  }
+  return [pscustomobject]@{ version = 1; needsRefresh = $needsRefresh }
+}
+
+function Install-LitertlmShim {
+  param([string]$UvPath, [string]$BackupDirectory = '', [switch]$Restore)
+  $ErrorActionPreference = 'Stop'
+  try {
+    $paths = Get-LitertlmShimPaths $UvPath
+    $files = @(Get-LitertlmShimFiles $paths)
+    $receiptPath = if ($BackupDirectory) { Join-Path $BackupDirectory 'runtime-backup.json' } else { '' }
+    if ($Restore) {
+      if (-not $receiptPath) { throw 'Runtime rollback requires its backup directory' }
+      $receipt = Get-Content -LiteralPath $receiptPath -Raw | ConvertFrom-Json
+      if ($receipt.version -ne 1 -or $receipt.site -ine $paths.Site -or @($receipt.files).Count -ne $files.Count) { throw 'Runtime rollback scope mismatch' }
+      # Validate the COMPLETE restore before changing either file. Refuse an
+      # unexpected concurrent write rather than overwriting another repair.
+      foreach ($file in $files) {
+        $entry = @($receipt.files | Where-Object { $_.name -eq $file.Name })
+        if ($entry.Count -ne 1) { throw 'Runtime rollback file set mismatch' }
+        $target = Join-Path $paths.Site $file.Name
+        if (Test-Path -LiteralPath $target) {
+          $current = (Get-FileHash -LiteralPath $target -Algorithm SHA256).Hash.ToLowerInvariant()
+          if ($current -ne $entry[0].installedSha256 -and $current -ne $entry[0].previousSha256) { throw 'Runtime changed after the update; rollback refused' }
+        }
+        if ($entry[0].existed -and (Get-FileHash -LiteralPath (Join-Path $BackupDirectory $file.Name) -Algorithm SHA256).Hash.ToLowerInvariant() -ne $entry[0].previousSha256) { throw 'Runtime rollback backup hash mismatch' }
+      }
+      foreach ($entry in $receipt.files) {
+        $target = Join-Path $paths.Site $entry.name
+        if ($entry.existed) { Copy-Item -LiteralPath (Join-Path $BackupDirectory $entry.name) -Destination $target -Force }
+        elseif (Test-Path -LiteralPath $target) { Remove-Item -LiteralPath $target -Force }
+        if ($entry.existed) {
+          if ((Get-FileHash -LiteralPath $target -Algorithm SHA256).Hash.ToLowerInvariant() -ne $entry.previousSha256) { throw 'Restored runtime hash mismatch' }
+        } elseif (Test-Path -LiteralPath $target) { throw 'Runtime rollback left a newly introduced file' }
+      }
+      Log 'restored the previous litert-lm shim bytes'
+      return $true
+    }
+    if ($BackupDirectory) {
+      if (Test-Path -LiteralPath $receiptPath) { throw 'Preserve the existing runtime rollback receipt' }
+      New-Item -ItemType Directory -Force -Path $BackupDirectory | Out-Null
+      $backups = @(foreach ($file in $files) {
+        $target = Join-Path $paths.Site $file.Name
+        $existed = Test-Path -LiteralPath $target -PathType Leaf
+        $previousSha = $null
+        if ($existed) {
+          $previousSha = (Get-FileHash -LiteralPath $target -Algorithm SHA256).Hash.ToLowerInvariant()
+          $backup = Join-Path $BackupDirectory $file.Name
+          Copy-Item -LiteralPath $target -Destination $backup
+          if ((Get-FileHash -LiteralPath $backup -Algorithm SHA256).Hash.ToLowerInvariant() -ne $previousSha) { throw 'Runtime rollback copy did not verify' }
+        }
+        [pscustomobject]@{ name = $file.Name; existed = [bool]$existed; previousSha256 = $previousSha; installedSha256 = (Get-ShimBytesHash $file.Bytes) }
+      })
+      [IO.File]::WriteAllText($receiptPath, (@{ version = 1; site = $paths.Site; files = $backups } | ConvertTo-Json -Depth 5), [Text.UTF8Encoding]::new($false))
+    }
+    foreach ($file in $files) {
+      $target = Join-Path $paths.Site $file.Name
+      $temporary = "$target.$PID.update"
+      try {
+        [IO.File]::WriteAllBytes($temporary, $file.Bytes)
+        if ((Get-FileHash -LiteralPath $temporary -Algorithm SHA256).Hash.ToLowerInvariant() -ne (Get-ShimBytesHash $file.Bytes)) { throw 'Runtime refresh hash mismatch' }
+        # PS 5.1 binds an ordinary $null to an empty String here, which .NET
+        # treats as an invalid backup path. Pass an actual null String.
+        if (Test-Path -LiteralPath $target) { [IO.File]::Replace($temporary, $target, [NullString]::Value) }
+        else { [IO.File]::Move($temporary, $target) }
+        if ((Get-FileHash -LiteralPath $target -Algorithm SHA256).Hash.ToLowerInvariant() -ne (Get-ShimBytesHash $file.Bytes)) { throw 'Installed runtime refresh hash mismatch' }
+      } finally { if (Test-Path -LiteralPath $temporary) { Remove-Item -LiteralPath $temporary -Force } }
+    }
+    # A fresh interpreter proves the installed wrapper imports. No engine,
+    # weights, image inference, model config or camera credentials are loaded.
+    & $paths.Python -c "import litert_lm,sys; sys.exit(0 if getattr(litert_lm.Engine.create_conversation,'_trillboards_litertlm_shim',False) else 1)" *>> $LogPath
+    if ($LASTEXITCODE -ne 0) { throw 'The refreshed model-service shim did not import' }
+    Log "litert-lm fast-conversation shim active in $($paths.Site)"
+    return $true
+  } catch {
+    Log "WARN: litert-lm shim operation failed: $_"
+    return $false
+  }
+}
+
 if ($SmokeTest) {
   if ([string]::IsNullOrWhiteSpace($ProgressPath)) { throw "SmokeTest requires ProgressPath" }
   Write-SetupProgress -Stage "local_ai" -Title "Installing local AI" -Message "Smoke test" -Phase "installing_model" -Percent 62 -TotalBytes $ExpectedModelBytes
@@ -345,7 +471,10 @@ if ($SmokeTest) {
   exit 0
 }
 
-$setupMutex = New-Object System.Threading.Mutex($false, "Local\TrillboardsLiteRtLmSetup")
+# S4U/boot tasks and the interactive installer run in different sessions. A
+# Local mutex cannot serialize them; scope the Global name to this user's SID.
+$setupSid = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+$setupMutex = New-Object System.Threading.Mutex($false, ("Global\TrillboardsLiteRtLmSetup-" + $setupSid))
 $haveSetupMutex = $false
 try {
   $haveSetupMutex = $setupMutex.WaitOne(0)
@@ -354,6 +483,10 @@ try {
 }
 
 if (-not $haveSetupMutex) {
+  if ($RuntimeAction -ne 'Setup') {
+    $setupMutex.Dispose()
+    throw 'Local AI setup is busy; no concurrent runtime refresh was attempted'
+  }
   Log "LiteRT-LM provisioning is already running; attaching setup progress"
   if ([string]::IsNullOrWhiteSpace($ProgressPath) -and -not $RequireBundledModel) {
     $setupMutex.Dispose()
@@ -389,6 +522,24 @@ function Stop-SetupLock {
   $setupMutex.Dispose()
 }
 
+if ($RuntimeAction -ne 'Setup') {
+  try {
+    $refreshUvPath = Join-Path $LocalBin 'uv.exe'
+    if (-not (Test-Path -LiteralPath $refreshUvPath -PathType Leaf)) {
+      $refreshUv = Get-Command uv -ErrorAction Stop
+      $refreshUvPath = $refreshUv.Source
+    }
+    if ($RuntimeAction -eq 'Inspect') {
+      Get-LitertlmShimState $refreshUvPath | ConvertTo-Json -Compress
+    } else {
+      if ([string]::IsNullOrWhiteSpace($RuntimeBackupDir)) { throw 'A runtime rollback directory is required' }
+      $refreshArgs = @{ UvPath = $refreshUvPath; BackupDirectory = $RuntimeBackupDir; Restore = ($RuntimeAction -eq 'Restore') }
+      if (-not (Install-LitertlmShim @refreshArgs)) { throw 'The local AI runtime refresh/rollback did not verify' }
+    }
+  } finally { Stop-SetupLock }
+  exit 0
+}
+
 Log "starting LiteRT-LM provisioning (Windows x64, CPU backend)"
 Write-SetupProgress -Stage "local_ai" -Title "Installing local AI" -Message "Preparing the private on-device AI runtime. Cloud inference remains off." -Phase "installing_runtime" -Percent 0
 
@@ -585,41 +736,6 @@ if ((Test-LitertLmCli) -and ($installedLitertLmVersion -eq $LitertLmVersion)) {
 # short-circuits that branch on a healthy CLI -- gating this behind it is exactly
 # how a repaired-and-healthy machine would keep the slow serve and report fine.
 # Never throws: this is a speed fix, and it must not be able to fail an install.
-function Install-LitertlmShim {
-  param([string]$UvPath)
-  try {
-    $shim = $null
-    foreach ($c in @(
-      (Join-Path $PSScriptRoot "trillboards_litertlm_shim.py"),
-      (Join-Path $PSScriptRoot "..\litertlm\trillboards_litertlm_shim.py")
-    )) { if (Test-Path -LiteralPath $c -PathType Leaf) { $shim = $c; break } }
-    if (-not $shim) { Log "WARN: litert-lm shim source not found; serve keeps stock (slower) conversation setup"; return $false }
-
-    $toolDir = (& $UvPath tool dir 2>$null | Select-Object -First 1)
-    if ([string]::IsNullOrWhiteSpace($toolDir)) { Log "WARN: could not resolve 'uv tool dir'; skipping litert-lm shim"; return $false }
-    $py = Join-Path $toolDir.Trim() "litert-lm\Scripts\python.exe"
-    if (-not (Test-Path -LiteralPath $py -PathType Leaf)) { Log "WARN: litert-lm venv python missing at $py; skipping shim"; return $false }
-
-    $site = (& $py -c "import sysconfig;print(sysconfig.get_paths()['purelib'])" 2>$null | Select-Object -First 1)
-    if ([string]::IsNullOrWhiteSpace($site) -or -not (Test-Path -LiteralPath $site.Trim())) {
-      Log "WARN: could not resolve litert-lm site-packages; skipping shim"; return $false
-    }
-    $site = $site.Trim()
-    Copy-Item -LiteralPath $shim -Destination (Join-Path $site "trillboards_litertlm_shim.py") -Force
-    Set-Content -LiteralPath (Join-Path $site "trillboards-litertlm-shim.pth") -Value "import trillboards_litertlm_shim" -Encoding ASCII
-
-    # Capability is established by ATTEMPTING THE OPERATION. Importing litert_lm
-    # here is the only thing that proves the wrap landed on the class the serve
-    # will use; a file that merely exists proves nothing.
-    & $py -c "import litert_lm,sys; sys.exit(0 if getattr(litert_lm.Engine.create_conversation,'_trillboards_litertlm_shim',False) else 1)" *>> $LogPath
-    if ($LASTEXITCODE -eq 0) { Log "litert-lm fast-conversation shim active in $site"; return $true }
-    Log "WARN: litert-lm shim did not take effect; serve keeps stock (slower) conversation setup"
-    return $false
-  } catch {
-    Log "WARN: litert-lm shim install failed: $_"
-    return $false
-  }
-}
 Install-LitertlmShim -UvPath $uvCmd.Source | Out-Null
 
 $bundledModelVerified = $false

package/dist/EdgeAgent.js

@@ -44,7 +44,7 @@ const edge_ads_1 = require("@trillboards/edge-ads");
 const CommandRouter_1 = require("./CommandRouter");
 const config_1 = require("./config");
 const dataDir_1 = require("./dataDir");
-const SDK_VERSION = '0.2.154';
+const SDK_VERSION = '0.2.157';
 class EdgeAgent extends events_1.EventEmitter {
     constructor(config, deps) {
         super();

package/dist/LiteRtVlmProvider.d.ts

@@ -381,6 +381,8 @@ export interface LocalAnalyzeRequest {
     expectedModel?: ModelPin;
     /** Raw JPEG bytes for this frame. */
     jpeg: Buffer;
+    /** One moment: entire scoped area first, then separate person views. */
+    images?: Buffer[];
     /** The JSON Schema the output is validated against (the profile contract). */
     schema: Record<string, unknown>;
     /** The analysis prompt (same instruction the cloud VLM gets). */
@@ -416,6 +418,7 @@ export declare class LiteRtVlmProvider {
      * an observation or a request?" — see LiteRtAcceleratorHealth.delegateConfirmed.
      */
     private confirmedModel;
+    private static readonly unavailableMultiImageRuntimes;
     /** Did the serve list the `,gpu` id? null = never asked (the healthy path). */
     private gpuAdvertised;
     /** Set once the GPU variant failed a whole frame and we fell back to CPU. */