@abot-ai/runtime 1.4.0 → 1.5.0

package/dist/src/computer-access/companion/observation-windows.js

@@ -0,0 +1,173 @@
+/** A single native event loop. Timers only settle observed changes; they never poll the desktop. */
+import { OBSERVATION_CAPTURE_POLICY as policy } from "./observation-capture-policy.js";
+export const WINDOWS_OBSERVATION_SCRIPT = String.raw `
+$ErrorActionPreference = 'Stop'
+[Console]::OutputEncoding = New-Object System.Text.UTF8Encoding($false)
+try {
+Add-Type -ReferencedAssemblies @('UIAutomationClient','UIAutomationTypes','WindowsBase','System.Windows.Forms','System.Web.Extensions') -TypeDefinition @'
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Runtime.InteropServices;
+using System.Windows.Automation;
+using System.Windows.Forms;
+using System.Web.Script.Serialization;
+public static class PassiveDesktop {
+  delegate void WinEvent(IntPtr h,uint e,IntPtr w,int obj,int child,uint thread,uint time);
+  [DllImport("user32.dll")] static extern IntPtr SetWinEventHook(uint min,uint max,IntPtr module,WinEvent callback,uint pid,uint thread,uint flags);
+  [DllImport("user32.dll")] static extern bool UnhookWinEvent(IntPtr h);
+  [DllImport("user32.dll")] static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] static extern IntPtr OpenInputDesktop(uint flags,bool inherit,uint access);
+  [DllImport("user32.dll")] static extern bool CloseDesktop(IntPtr desktop);
+  [DllImport("user32.dll",CharSet=CharSet.Unicode)] static extern bool GetUserObjectInformation(IntPtr h,int index,System.Text.StringBuilder text,int size,out int required);
+  static JavaScriptSerializer json = new JavaScriptSerializer();
+  static HashSet<string> excluded = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+  static Timer quiet = new Timer { Interval=1200 };
+  static Timer maximum = new Timer { Interval=5000 };
+  static readonly Stopwatch cadence = Stopwatch.StartNew();
+  static long lastCapture=-${policy.minimumIntervalMs}, burstStarted;
+  static int burstCaptures, queuedChange;
+  static bool noisePaused;
+  static Form dispatch;
+  static bool edited;
+  static string editKey;
+  static WinEvent callback;
+  static IntPtr hook;
+  static AutomationFocusChangedEventHandler focus;
+  static AutomationPropertyChangedEventHandler properties;
+  static StructureChangedEventHandler structure;
+  static AutomationEventHandler text;
+  static IntPtr currentWindow;
+  static void Emit(object value) { Console.WriteLine(json.Serialize(value)); }
+  static void Status(string state,string reason) { Emit(new {type="status",state=state,reason=reason}); }
+  static bool AccessibleDesktop() {
+    IntPtr desktop=OpenInputDesktop(0,false,0x0001);
+    if(desktop==IntPtr.Zero) return false;
+    try { int needed; var name=new System.Text.StringBuilder(128); return GetUserObjectInformation(desktop,2,name,256,out needed) && name.ToString()=="Default"; }
+    finally { CloseDesktop(desktop); }
+  }
+  static bool Editable(object sender) {
+    try { var element=sender as AutomationElement; object pattern; if(element==null || element.Current.IsPassword) return false;
+      var ancestor=element; bool foreground=false;
+      for(int i=0;i<32 && ancestor!=null;i++) { if((IntPtr)ancestor.Current.NativeWindowHandle==GetForegroundWindow()) {foreground=true;break;} ancestor=TreeWalker.ControlViewWalker.GetParent(ancestor); }
+      if(!foreground) return false;
+      return element.TryGetCurrentPattern(ValuePattern.Pattern,out pattern) && !((ValuePattern)pattern).Current.IsReadOnly;
+    } catch { return false; }
+  }
+  static void Changed(bool edit, bool switched=false) {
+    if(dispatch==null || dispatch.IsDisposed) return;
+    if(!edit && !switched && System.Threading.Interlocked.Exchange(ref queuedChange,1)==1) return;
+    string source=null;
+    if(edit) { try {source=Key(AutomationElement.FromHandle(GetForegroundWindow()));} catch {} }
+    dispatch.BeginInvoke((Action)(()=> {
+      System.Threading.Interlocked.Exchange(ref queuedChange,0);
+      if(edit && source!=null) {edited=true;editKey=source;}
+      if(edit || switched) {noisePaused=false;burstCaptures=0;burstStarted=cadence.ElapsedMilliseconds;}
+      quiet.Stop(); quiet.Interval=noisePaused?${policy.resumeQuietMs}:1200; quiet.Start();
+      if(!noisePaused && !maximum.Enabled) maximum.Start();
+    }));
+  }
+  static AutomationElement Document(AutomationElement root) {
+    try { var item=AutomationElement.FocusedElement;
+      if(item.Current.ProcessId!=root.Current.ProcessId) return null;
+      for(int depth=0;depth<32 && item!=null;depth++) {
+        if(item.Current.ControlType==ControlType.Document) return item;
+        if(item.Equals(root)) return null;
+        item=TreeWalker.ControlViewWalker.GetParent(item);
+      }
+    } catch {}
+    return null;
+  }
+  static string DocumentId(AutomationElement root) { var document=Document(root); return document==null?"":String.Join("-",document.GetRuntimeId()); }
+  static bool VisibleLeaf(AutomationElement item, System.Windows.Rect window) {
+    var bounds=item.Current.BoundingRectangle;
+    return !bounds.IsEmpty && bounds.Width>0 && bounds.Height>0 && bounds.IntersectsWith(window);
+  }
+  static string Key(AutomationElement root) { return root.Current.NativeWindowHandle.ToString()+":"+root.Current.ProcessId.ToString()+":"+root.Current.Name+":"+DocumentId(root); }
+  static void Bind(AutomationElement root) {
+    IntPtr window=(IntPtr)root.Current.NativeWindowHandle;
+    if(window==currentWindow) return;
+    Automation.RemoveAllEventHandlers(); currentWindow=window;
+    Automation.AddAutomationFocusChangedEventHandler(focus);
+    Automation.AddAutomationPropertyChangedEventHandler(root,TreeScope.Subtree,properties,ValuePattern.ValueProperty,AutomationElement.NameProperty,AutomationElement.IsOffscreenProperty);
+    Automation.AddStructureChangedEventHandler(root,TreeScope.Subtree,structure);
+    Automation.AddAutomationEventHandler(TextPattern.TextChangedEvent,root,TreeScope.Subtree,text);
+  }
+  static void Capture() {
+    quiet.Stop(); maximum.Stop();
+    long now=cadence.ElapsedMilliseconds;
+    if(noisePaused) {noisePaused=false;burstCaptures=0;}
+    if(now-lastCapture<${policy.minimumIntervalMs}) {quiet.Interval=(int)(${policy.minimumIntervalMs}-(now-lastCapture));quiet.Start();return;}
+    if(now-burstStarted>${policy.burstWindowMs}) {burstStarted=now;burstCaptures=0;}
+    if(!edited && ++burstCaptures>${policy.burstLimit}) {
+      noisePaused=true;Status("paused","continuous_activity");quiet.Interval=${policy.resumeQuietMs};quiet.Start();return;
+    }
+    lastCapture=now; bool edit=edited; edited=false;
+    try {
+      if(!AccessibleDesktop()) { Status("paused","screen_locked_or_secure_desktop"); return; }
+      IntPtr window=GetForegroundWindow(); if(window==IntPtr.Zero) return;
+      var root=AutomationElement.FromHandle(window); int pid=root.Current.ProcessId;
+      string app=Process.GetProcessById(pid).ProcessName;
+      if(excluded.Contains(app)) { Status("paused","application_excluded"); return; }
+      Bind(root);
+      string before=Key(root); string title=root.Current.Name; edit=edit && editKey==before;
+      string documentId=DocumentId(root);
+      var document=Document(root); var windowBounds=root.Current.BoundingRectangle;
+      var queue=new Queue<AutomationElement>(); queue.Enqueue(document ?? root);
+      var parts=new List<string>(); var seen=new HashSet<string>(); int length=0; int count=0;
+      var watch=Stopwatch.StartNew(); var walker=TreeWalker.ControlViewWalker;
+      while(queue.Count>0 && count++<600 && length<24000 && watch.ElapsedMilliseconds<400) {
+        var item=queue.Dequeue();
+        try {
+          if(item.Current.IsPassword || item.Current.IsOffscreen) continue;
+          // A root fallback must not read background browser document trees.
+          if(document==null && item.Current.ControlType==ControlType.Document) continue;
+          var child=walker.GetFirstChild(item);
+          // Parent TextPattern may include protected descendants. Extract only visible leaf controls.
+          if(child==null && VisibleLeaf(item,windowBounds)) {
+            string value=null; object pattern;
+            if(item.TryGetCurrentPattern(ValuePattern.Pattern,out pattern)) value=((ValuePattern)pattern).Current.Value;
+            else if(item.TryGetCurrentPattern(TextPattern.Pattern,out pattern)) {
+              var visibleParts=new List<string>(); int remaining=24000-length;
+              foreach(var range in ((TextPattern)pattern).GetVisibleRanges()) {
+                if(remaining<=0 || watch.ElapsedMilliseconds>=400) break;
+                string visible=range.GetText(remaining);
+                if(!String.IsNullOrEmpty(visible)) { visibleParts.Add(visible); remaining-=visible.Length; }
+              }
+              value=String.Join("\n",visibleParts.ToArray());
+            }
+            else if(item.Current.ControlType==ControlType.Text) value=item.Current.Name;
+            if(!String.IsNullOrWhiteSpace(value) && seen.Add(value)) { parts.Add(value); length+=value.Length; }
+          }
+          int siblings=0;
+          while(child!=null && siblings++<600 && queue.Count<600) { queue.Enqueue(child); child=walker.GetNextSibling(child); }
+        } catch(ElementNotAvailableException) {}
+      }
+      if(GetForegroundWindow()!=window || !AccessibleDesktop()) return;
+      string after=Key(AutomationElement.FromHandle(window)); if(before!=after) return;
+      string content=String.Join("\n",parts.ToArray());
+      if(content.Length>24000) content=content.Substring(0,24000);
+      Emit(new {type="snapshot",source=new {app=app,processId=pid,windowId=window.ToString(),documentId=documentId,title=title},content=content,kind=edit?"edit":"view",extraction="uia",coverage=content.Length>0?"partial":"metadata_only",coverageReason="visible_accessibility_subset",beforeKey=before,afterKey=after});
+      Status("partial","uia_application_coverage");
+    } catch(Exception) { Status("partial","accessibility_read_unavailable"); }
+  }
+  public static void Run(string exclusions) {
+    foreach(string app in json.Deserialize<string[]>(exclusions)) excluded.Add(app);
+    dispatch=new Form { ShowInTaskbar=false,WindowState=FormWindowState.Minimized };
+    var handle=dispatch.Handle;
+    quiet.Tick+=(s,e)=>Capture(); maximum.Tick+=(s,e)=>Capture();
+    focus=(s,e)=>Changed(false); properties=(s,e)=>Changed(e.Property==ValuePattern.ValueProperty && Editable(s));
+    structure=(s,e)=>Changed(false); text=(s,e)=>Changed(Editable(s));
+    callback=(h,e,w,obj,child,thread,time)=>Changed(false,true);
+    hook=SetWinEventHook(3,3,IntPtr.Zero,callback,0,0,0);
+    if(hook==IntPtr.Zero) { Status("unavailable","foreground_events_unavailable"); return; }
+    Automation.AddAutomationFocusChangedEventHandler(focus);
+    Status("partial","uia_application_coverage"); Changed(false);
+    try { Application.Run(); }
+    finally { UnhookWinEvent(hook); Automation.RemoveAllEventHandlers(); dispatch.Dispose(); }
+  }
+}
+'@
+[PassiveDesktop]::Run($env:ABOT_OBSERVATION_EXCLUSIONS)
+} catch { [Console]::WriteLine('{"type":"status","state":"unavailable","reason":"windows_uia_helper_unavailable"}') }
+`;

package/dist/{plugins/system/source → src/computer-access}/companion/pairing-store.d.ts

@@ -14,6 +14,12 @@ export declare class HostPairingStore {
         expiresAt: string;
     };
     authenticate(token: string): "pairing" | "credential" | undefined;
+    /** Download-only grant; it cannot replace or authenticate as the paired host. */
+    beginBundleUpgrade(lifetimeMs?: number): {
+        code: string;
+        expiresAt: string;
+    };
+    authenticateBundleUpgrade(token: string): boolean;
     consume(code: string, identity: HostIdentity): {
         hostId: string;
         credential: string;

package/dist/{plugins/system/source → src/computer-access}/companion/pairing-store.js

@@ -30,6 +30,16 @@ function isStoredPairing(value) {
         if (typeof value.pending.expiresAt !== "number")
             return false;
     }
+    if (value.bundleUpgrade !== undefined) {
+        if (!isHostRecord(value.bundleUpgrade))
+            return false;
+        if (typeof value.bundleUpgrade.digest !== "string")
+            return false;
+        if (typeof value.bundleUpgrade.expiresAt !== "number")
+            return false;
+        if (!isHostIdentifier(value.bundleUpgrade.hostId))
+            return false;
+    }
     if (value.host === undefined)
         return true;
     if (!isHostRecord(value.host))
@@ -85,6 +95,40 @@ export class HostPairingStore {
             return "pairing";
         return undefined;
     }
+    /** Download-only grant; it cannot replace or authenticate as the paired host. */
+    beginBundleUpgrade(lifetimeMs = 15 * 60_000) {
+        if (!isBoundedPairingLifetime(lifetimeMs))
+            throw new Error("host_pairing_lifetime_invalid");
+        const record = this.read();
+        if (!record.host)
+            throw new Error("host_not_paired");
+        const code = randomBytes(32).toString("base64url");
+        const expiresAt = this.now() + lifetimeMs;
+        writeHostPrivateJson(this.path, {
+            ...record,
+            bundleUpgrade: {
+                digest: tokenDigest(code),
+                expiresAt,
+                hostId: record.host.hostId,
+            },
+        });
+        return { code, expiresAt: new Date(expiresAt).toISOString() };
+    }
+    authenticateBundleUpgrade(token) {
+        if (!/^[A-Za-z0-9_-]{43}$/u.test(token))
+            return false;
+        const record = this.read();
+        if (!record.host)
+            return false;
+        const grant = record.bundleUpgrade;
+        if (!grant)
+            return false;
+        if (grant.hostId !== record.host.hostId)
+            return false;
+        if (grant.expiresAt <= this.now())
+            return false;
+        return matchesToken(token, grant.digest);
+    }
     consume(code, identity) {
         if (this.authenticate(code) !== "pairing")
             throw new Error("host_pairing_expired");

package/dist/{plugins/system/source → src/computer-access}/companion/process-owner-identity.d.ts

@@ -11,6 +11,7 @@ export type ProcessOwnerIdentityDependencies = Readonly<{
     execute(file: string, args: readonly string[], options: IdentityCommandOptions): Promise<string>;
     processIsAlive(pid: number): boolean;
 }>;
+export declare function hasSameProcessOwnerIdentity(recorded: string, observed: string): boolean;
 export declare function createProcessOwnerIdentityProbe(dependencies: ProcessOwnerIdentityDependencies): {
     readProcessOwnerIdentity: (pid: number) => Promise<string | undefined>;
     isProcessOwnerAlive: (pid: number, ownerIdentity?: string) => Promise<boolean>;

package/dist/{plugins/system/source → src/computer-access}/companion/process-owner-identity.js

@@ -7,9 +7,19 @@ $ErrorActionPreference = 'Stop'
 $targetPid = [int]$env:ABOT_HOST_OWNER_PID
 $target = Get-Process -Id $targetPid -ErrorAction Stop
 $started = $target.StartTime.ToUniversalTime().Ticks
-$booted = (Get-CimInstance Win32_OperatingSystem -ErrorAction Stop).LastBootUpTime.ToUniversalTime().Ticks
-[Console]::Out.Write([string]$booted + '|' + [string]$started)
+[Console]::Out.Write([string]$started)
 `;
+export function hasSameProcessOwnerIdentity(recorded, observed) {
+    if (recorded === observed)
+        return true;
+    // Legacy Windows records also included a WMI boot time that can drift while
+    // the same process runs. Keep its exact creation ticks; never round them.
+    const windowsCreation = /^windows:(?:\d{10,20}\|)?(\d{10,20})$/u;
+    const recordedStart = windowsCreation.exec(recorded)?.[1];
+    if (!recordedStart)
+        return false;
+    return recordedStart === windowsCreation.exec(observed)?.[1];
+}
 function isProcessId(pid) {
     if (!Number.isSafeInteger(pid))
         return false;
@@ -74,7 +84,7 @@ async function windowsIdentity(pid, dependencies) {
         Buffer.from(WINDOWS_OWNER_SCRIPT, "utf16le").toString("base64"),
     ], commandOptions(pid));
     const value = text.trim();
-    if (!/^\d{10,20}\|\d{10,20}$/u.test(value))
+    if (!/^\d{10,20}$/u.test(value))
         return undefined;
     return `windows:${value}`;
 }
@@ -118,7 +128,7 @@ export function createProcessOwnerIdentityProbe(dependencies) {
         const observed = await readProcessOwnerIdentity(pid);
         if (!observed)
             return true;
-        return ownerIdentity === observed;
+        return hasSameProcessOwnerIdentity(ownerIdentity, observed);
     }
     async function requireCurrentProcessOwnerIdentity() {
         const identity = await readProcessOwnerIdentity(dependencies.currentPid);

package/dist/{plugins/system/source → src/computer-access}/companion/protocol.d.ts

@@ -1,9 +1,14 @@
-import type { ToolImplementationOutput } from "../../../../src/plugin-sdk/index.js";
+import type { ToolImplementationOutput } from "../../plugin-sdk/index.js";
+import type { ObservationControl } from "./observation-protocol.js";
+import type { PassiveCollectorEvent } from "../../shared/passive-observation.js";
+import type { companionReleaseStatus } from "./release-version.js";
+export declare const DESKTOP_NOTIFICATION_OPERATION = "desktop_notification";
 export declare const HOST_PROTOCOL_VERSION = 1;
 export declare const HOST_SOCKET_PATH = "/system-host/connect";
 export declare const HOST_WIRE_MAX_BYTES: number;
 export declare const HOST_OPERATIONS: readonly ["system_targets", "system_command", "system_applications", "system_launch"];
-export type HostOperation = (typeof HOST_OPERATIONS)[number];
+export declare const COMPUTER_HOST_OPERATIONS: readonly ["computer_execute", "computer_frame", "computer_close"];
+export type HostOperation = (typeof HOST_OPERATIONS)[number] | (typeof COMPUTER_HOST_OPERATIONS)[number] | typeof DESKTOP_NOTIFICATION_OPERATION;
 export type HostIdentity = Readonly<{
     name: string;
     os: "windows" | "macos" | "linux";
@@ -14,6 +19,8 @@ export type HostStatus = Readonly<{
     paired: boolean;
     hostId?: string;
     identity?: HostIdentity;
+    companion?: ReturnType<typeof companionReleaseStatus>;
+    capabilities?: readonly string[];
 } & ({
     connected: true;
     connectionId: string;
@@ -26,13 +33,20 @@ export type HostAgentHello = Readonly<{
     version: 1;
     identity: HostIdentity;
     hostId?: string;
+    capabilities?: readonly string[];
+    companionVersion?: number;
 }>;
 export type HostAgentMessage = HostAgentHello | Readonly<{
+    type: "observation_event";
+    ownerId: string;
+    leaseId: string;
+    event: PassiveCollectorEvent;
+}> | Readonly<{
     type: "result";
     id: string;
     result: ToolImplementationOutput;
 }>;
-export type HostServerMessage = Readonly<{
+export type HostServerMessage = ObservationControl | Readonly<{
     type: "paired";
     hostId: string;
     credential: string;
@@ -50,6 +64,7 @@ export type HostServerMessage = Readonly<{
     id: string;
 }>;
 export declare function isHostOperation(value: unknown): value is HostOperation;
+export declare function isHostWireOperation(value: unknown): value is HostOperation;
 export declare function isHostRecord(value: unknown): value is Record<string, unknown>;
 export declare function isHostIdentifier(value: unknown): value is string;
 export declare function isHostIdentity(value: unknown): value is HostIdentity;

package/dist/{plugins/system/source → src/computer-access}/companion/protocol.js

@@ -1,3 +1,4 @@
+export const DESKTOP_NOTIFICATION_OPERATION = "desktop_notification";
 export const HOST_PROTOCOL_VERSION = 1;
 export const HOST_SOCKET_PATH = "/system-host/connect";
 export const HOST_WIRE_MAX_BYTES = 256 * 1024;
@@ -7,9 +8,21 @@ export const HOST_OPERATIONS = [
     "system_applications",
     "system_launch",
 ];
+export const COMPUTER_HOST_OPERATIONS = [
+    "computer_execute",
+    "computer_frame",
+    "computer_close",
+];
 export function isHostOperation(value) {
     return HOST_OPERATIONS.some((operation) => operation === value);
 }
+export function isHostWireOperation(value) {
+    if (isHostOperation(value))
+        return true;
+    if (value === DESKTOP_NOTIFICATION_OPERATION)
+        return true;
+    return COMPUTER_HOST_OPERATIONS.some((operation) => operation === value);
+}
 export function isHostRecord(value) {
     if (value === null)
         return false;

package/dist/src/computer-access/companion/release-version.d.ts

@@ -0,0 +1,7 @@
+/** Increment when installed companions should be offered an update. Independent of the wire protocol. */
+export declare const COMPANION_RELEASE_VERSION = 6;
+export declare function companionReleaseStatus(version: unknown): {
+    installedVersion: number | null;
+    availableVersion: number;
+    updateAvailable: boolean;
+};

package/dist/src/computer-access/companion/release-version.js

@@ -0,0 +1,12 @@
+/** Increment when installed companions should be offered an update. Independent of the wire protocol. */
+export const COMPANION_RELEASE_VERSION = 6;
+export function companionReleaseStatus(version) {
+    const installedVersion = typeof version === "number" && Number.isSafeInteger(version) && version > 0
+        ? version
+        : null;
+    return {
+        installedVersion,
+        availableVersion: COMPANION_RELEASE_VERSION,
+        updateAvailable: installedVersion === null || installedVersion < COMPANION_RELEASE_VERSION,
+    };
+}

package/dist/src/computer-access/computer/action-input.d.ts

@@ -0,0 +1,8 @@
+import type { NativeComputerAction, PhysicalRectangle } from "./native-protocol.js";
+export declare function computerInputError(message: string): never;
+export declare function computerRecord(value: unknown): Record<string, unknown>;
+export declare function computerFields(value: Record<string, unknown>, fields: readonly string[]): void;
+export declare function computerText(value: unknown, maximum?: number): string;
+export declare function computerNumber(value: unknown, minimum: number, maximum: number): number;
+export declare function readPhysicalRectangle(value: unknown): PhysicalRectangle;
+export declare function readNativeComputerAction(value: unknown): NativeComputerAction;

package/dist/src/computer-access/computer/action-input.js

@@ -0,0 +1,107 @@
+import { SystemOperationError } from "../contracts.js";
+export function computerInputError(message) {
+    throw new SystemOperationError("computer_input_invalid", message);
+}
+export function computerRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return computerInputError("An object is required.");
+    return value;
+}
+export function computerFields(value, fields) {
+    if (Object.keys(value).some((key) => !fields.includes(key)))
+        computerInputError("Unexpected computer operation fields.");
+}
+export function computerText(value, maximum = 4096) {
+    if (typeof value !== "string")
+        return computerInputError("A string is required.");
+    if (value.length > maximum)
+        return computerInputError("Computer text exceeds its limit.");
+    return value;
+}
+export function computerNumber(value, minimum, maximum) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return computerInputError("A finite number is required.");
+    if (value < minimum || value > maximum)
+        return computerInputError("Computer coordinate or duration is out of range.");
+    return value;
+}
+export function readPhysicalRectangle(value) {
+    const rect = computerRecord(value);
+    computerFields(rect, ["x", "y", "width", "height"]);
+    return {
+        x: computerNumber(rect.x, -131072, 131072),
+        y: computerNumber(rect.y, -131072, 131072),
+        width: computerNumber(rect.width, 1, 65536),
+        height: computerNumber(rect.height, 1, 65536),
+    };
+}
+function readPoint(value) {
+    const point = computerRecord(value);
+    computerFields(point, ["x", "y"]);
+    return {
+        x: computerNumber(point.x, -131072, 131072),
+        y: computerNumber(point.y, -131072, 131072),
+    };
+}
+function readButton(value) {
+    if (value === "left" || value === "middle" || value === "right")
+        return value;
+    return computerInputError("Select left, middle or right button.");
+}
+export function readNativeComputerAction(value) {
+    const action = computerRecord(value);
+    switch (action.kind) {
+        case "click": {
+            computerFields(action, ["kind", "point", "button", "count"]);
+            if (action.count !== 1 && action.count !== 2)
+                return computerInputError("Click count must be one or two.");
+            return {
+                kind: action.kind,
+                point: readPoint(action.point),
+                button: readButton(action.button),
+                count: action.count,
+            };
+        }
+        case "move":
+            computerFields(action, ["kind", "point"]);
+            return { kind: action.kind, point: readPoint(action.point) };
+        case "drag":
+            computerFields(action, ["kind", "from", "to", "button", "durationMs"]);
+            return {
+                kind: action.kind,
+                from: readPoint(action.from),
+                to: readPoint(action.to),
+                button: readButton(action.button),
+                durationMs: computerNumber(action.durationMs, 0, 5000),
+            };
+        case "scroll":
+            computerFields(action, ["kind", "deltaX", "deltaY"]);
+            return {
+                kind: action.kind,
+                deltaX: computerNumber(action.deltaX, -5000, 5000),
+                deltaY: computerNumber(action.deltaY, -5000, 5000),
+            };
+        case "type_text":
+            computerFields(action, ["kind", "text"]);
+            return { kind: action.kind, text: computerText(action.text, 4096) };
+        case "press_keys": {
+            computerFields(action, ["kind", "keys"]);
+            if (!Array.isArray(action.keys))
+                return computerInputError("Keys must be an array.");
+            if (action.keys.length < 1 || action.keys.length > 8)
+                return computerInputError("Use one to eight explicit keys.");
+            return {
+                kind: action.kind,
+                keys: action.keys.map((key) => computerText(key, 32)),
+            };
+        }
+        case "focus_window":
+            computerFields(action, ["kind", "windowBinding"]);
+            return {
+                kind: action.kind,
+                windowBinding: computerText(action.windowBinding),
+            };
+        default:
+            return computerInputError("Unknown computer action.");
+    }
+}

package/dist/src/computer-access/computer/companion-backend.d.ts

@@ -0,0 +1,3 @@
+import type { ComputerAccessConnection, CompanionTarget } from "../client.js";
+import type { NativeComputerBackend } from "./native-protocol.js";
+export declare function createCompanionComputerBackend(rootDir: string, route: CompanionTarget, connection: ComputerAccessConnection): NativeComputerBackend;

package/dist/src/computer-access/computer/companion-backend.js

@@ -0,0 +1,73 @@
+import { createHash, randomUUID } from "node:crypto";
+import { SystemOperationError } from "../contracts.js";
+import { computerNumber, computerRecord, computerText, } from "./action-input.js";
+import { COMPUTER_FRAME_CHUNK_BYTES, COMPUTER_IMAGE_MAX_BYTES, readNativeComputerResult, } from "./native-validation.js";
+export function createCompanionComputerBackend(rootDir, route, connection) {
+    const sessionId = randomUUID();
+    let closed = false;
+    const call = async (operation, params, signal) => {
+        const result = await connection.executeHostOperation(rootDir, {
+            hostId: route.hostId,
+            connectionId: route.connectionId,
+            operation,
+            params: { ...params, sessionId, target: route.target },
+            ...(signal ? { abortSignal: signal } : {}),
+        });
+        if (!result.ok)
+            throw new SystemOperationError(result.errorCode ?? "computer_host_failed", result.output);
+        return computerRecord(result.data);
+    };
+    return {
+        async execute(request, signal) {
+            if (closed)
+                throw new SystemOperationError("computer_session_closed", "The desktop session has closed.");
+            const response = await call("computer_execute", { request }, signal);
+            const result = readNativeComputerResult(response.result);
+            if (response.frame === undefined)
+                return result;
+            let bytes;
+            try {
+                const frame = computerRecord(response.frame);
+                const id = computerText(frame.id, 128);
+                const size = computerNumber(frame.size, 1, COMPUTER_IMAGE_MAX_BYTES);
+                if (!Number.isInteger(size))
+                    throw new Error("computer_frame_size_invalid");
+                const hash = computerText(frame.sha256, 64);
+                bytes = Buffer.alloc(size);
+                for (let offset = 0; offset < size; offset += COMPUTER_FRAME_CHUNK_BYTES) {
+                    const chunk = await call("computer_frame", { frameId: id, offset }, signal);
+                    const encoded = computerText(chunk.bytes, COMPUTER_FRAME_CHUNK_BYTES * 2);
+                    const decoded = Buffer.from(encoded, "base64");
+                    if (decoded.length !==
+                        Math.min(COMPUTER_FRAME_CHUNK_BYTES, size - offset))
+                        throw new Error("computer_frame_chunk_invalid");
+                    decoded.copy(bytes, offset);
+                    decoded.fill(0);
+                }
+                if (createHash("sha256").update(bytes).digest("hex") !== hash)
+                    throw new Error("computer_frame_digest_invalid");
+                return { ...result, image: { mimeType: "image/png", bytes } };
+            }
+            catch (error) {
+                bytes?.fill(0);
+                // Retain a completed injection receipt even when image transfer fails.
+                if (result.dispatch)
+                    return {
+                        ...result,
+                        error: {
+                            code: "computer_frame_transfer_failed",
+                            message: "Input receipt is preserved; the resulting image could not be transferred. Observe again before another action.",
+                        },
+                    };
+                throw error;
+            }
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            const deadline = AbortSignal.timeout(3000);
+            await call("computer_close", {}, deadline).catch(() => undefined);
+        },
+    };
+}

package/dist/src/computer-access/computer/companion-sessions.d.ts

@@ -0,0 +1,25 @@
+import { type ToolImplementation } from "../../plugin-sdk/index.js";
+import { resolveSystemTarget } from "../targets.js";
+import type { SystemTargetId } from "../contracts.js";
+import { createNativeComputerBackend } from "./native-backend.js";
+/** Connection-owned, bounded private sessions. No image is written to disk. */
+export declare class CompanionComputerSessions {
+    private readonly platform;
+    private readonly createBackend;
+    private readonly resolveTarget;
+    private readonly sessions;
+    private readonly closedSessions;
+    private stopped;
+    constructor(platform: SystemTargetId, createBackend?: typeof createNativeComputerBackend, resolveTarget?: typeof resolveSystemTarget);
+    hasActiveSessions(): boolean;
+    handlers(): Record<string, ToolImplementation>;
+    close(): Promise<void>;
+    private sessionId;
+    private acquire;
+    private renew;
+    private execute;
+    private imageAdmissionError;
+    private frame;
+    private eraseFrame;
+    private release;
+}