@abot-ai/runtime 1.3.1 → 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/src/computer-access/companion/pairing-store.d.ts

@@ -0,0 +1,28 @@
+import { type HostIdentity } from "./protocol.js";
+export declare class HostPairingStore {
+    private readonly now;
+    private readonly path;
+    constructor(rootDir: string, now?: () => number);
+    private read;
+    host(): {
+        hostId: string;
+        identity: HostIdentity;
+        credentialDigest: string;
+    } | undefined;
+    begin(lifetimeMs?: number): {
+        code: string;
+        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;
+    };
+    revoke(): void;
+}

package/dist/src/computer-access/companion/pairing-store.js

@@ -0,0 +1,146 @@
+import { createHash, randomBytes, randomUUID, timingSafeEqual, } from "node:crypto";
+import { join } from "node:path";
+import { isHostIdentifier, isHostIdentity, isHostRecord, } from "./protocol.js";
+import { hostStateDirectory, readHostPrivateJson, writeHostPrivateJson, } from "./private-store.js";
+function tokenDigest(token) {
+    return createHash("sha256").update(token).digest("hex");
+}
+function matchesToken(token, digest) {
+    if (!/^[a-f0-9]{64}$/u.test(digest))
+        return false;
+    return timingSafeEqual(Buffer.from(tokenDigest(token), "hex"), Buffer.from(digest, "hex"));
+}
+function isBoundedPairingLifetime(lifetimeMs) {
+    if (!Number.isSafeInteger(lifetimeMs))
+        return false;
+    if (lifetimeMs < 1)
+        return false;
+    return lifetimeMs <= 15 * 60_000;
+}
+function isStoredPairing(value) {
+    if (!isHostRecord(value))
+        return false;
+    if (value.version !== 1)
+        return false;
+    if (value.pending !== undefined) {
+        if (!isHostRecord(value.pending))
+            return false;
+        if (typeof value.pending.digest !== "string")
+            return false;
+        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))
+        return false;
+    if (!isHostIdentifier(value.host.hostId))
+        return false;
+    if (!isHostIdentity(value.host.identity))
+        return false;
+    return typeof value.host.credentialDigest === "string";
+}
+export class HostPairingStore {
+    now;
+    path;
+    constructor(rootDir, now = Date.now) {
+        this.now = now;
+        this.path = join(hostStateDirectory(rootDir), "pairing.json");
+    }
+    read() {
+        const value = readHostPrivateJson(this.path);
+        if (value === undefined)
+            return { version: 1 };
+        if (!isStoredPairing(value))
+            throw new Error("host_pairing_state_invalid");
+        return value;
+    }
+    host() {
+        return this.read().host;
+    }
+    begin(lifetimeMs = 5 * 60_000) {
+        if (!isBoundedPairingLifetime(lifetimeMs))
+            throw new Error("host_pairing_lifetime_invalid");
+        if (this.host())
+            throw new Error("host_already_paired");
+        const code = randomBytes(32).toString("base64url");
+        const expiresAt = this.now() + lifetimeMs;
+        writeHostPrivateJson(this.path, {
+            version: 1,
+            pending: { digest: tokenDigest(code), expiresAt },
+        });
+        return { code, expiresAt: new Date(expiresAt).toISOString() };
+    }
+    authenticate(token) {
+        if (!/^[A-Za-z0-9_-]{43}$/u.test(token))
+            return undefined;
+        const record = this.read();
+        if (record.host && matchesToken(token, record.host.credentialDigest))
+            return "credential";
+        if (!record.pending)
+            return undefined;
+        if (record.pending.expiresAt <= this.now())
+            return undefined;
+        if (matchesToken(token, record.pending.digest))
+            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");
+        const hostId = randomUUID();
+        const credential = randomBytes(32).toString("base64url");
+        writeHostPrivateJson(this.path, {
+            version: 1,
+            host: { hostId, identity, credentialDigest: tokenDigest(credential) },
+        });
+        return { hostId, credential };
+    }
+    revoke() {
+        writeHostPrivateJson(this.path, { version: 1 });
+    }
+}

package/dist/src/computer-access/companion/private-store.d.ts

@@ -0,0 +1,4 @@
+export declare function hostStateDirectory(rootDir: string): string;
+export declare function ensureHostStateDirectory(directory: string): void;
+export declare function readHostPrivateJson(path: string): unknown | undefined;
+export declare function writeHostPrivateJson(path: string, value: unknown): void;

package/dist/src/computer-access/companion/private-store.js

@@ -0,0 +1,59 @@
+import { randomUUID } from "node:crypto";
+import { lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
+import { dirname, join } from "node:path";
+export function hostStateDirectory(rootDir) {
+    return join(rootDir, ".runtime", "system-host");
+}
+export function ensureHostStateDirectory(directory) {
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const stat = lstatSync(directory);
+    if (!stat.isDirectory())
+        throw new Error("host_state_directory_invalid");
+    if (process.platform === "win32")
+        return;
+    if (stat.uid !== process.getuid?.())
+        throw new Error("host_state_owner_invalid");
+    if ((stat.mode & 0o077) !== 0)
+        throw new Error("host_state_directory_not_private");
+}
+export function readHostPrivateJson(path) {
+    try {
+        const stat = lstatSync(path);
+        if (!stat.isFile())
+            throw new Error("host_state_file_invalid");
+        if (process.platform !== "win32") {
+            if (stat.uid !== process.getuid?.())
+                throw new Error("host_state_owner_invalid");
+            if ((stat.mode & 0o077) !== 0)
+                throw new Error("host_state_file_not_private");
+        }
+        if (stat.size > 16_384)
+            throw new Error("host_state_file_too_large");
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+}
+export function writeHostPrivateJson(path, value) {
+    ensureHostStateDirectory(dirname(path));
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, JSON.stringify(value), {
+            flag: "wx",
+            mode: 0o600,
+        });
+        renameSync(temporary, path);
+    }
+    finally {
+        try {
+            unlinkSync(temporary);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+}

package/dist/src/computer-access/companion/process-owner-identity.d.ts

@@ -0,0 +1,23 @@
+type IdentityCommandOptions = Readonly<{
+    env: NodeJS.ProcessEnv;
+    windowsHide: true;
+    timeout: number;
+    maxBuffer: number;
+}>;
+export type ProcessOwnerIdentityDependencies = Readonly<{
+    platform: NodeJS.Platform;
+    currentPid: number;
+    readText(path: string): Promise<string>;
+    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>;
+    requireCurrentProcessOwnerIdentity: () => Promise<string>;
+};
+export declare const readProcessOwnerIdentity: (pid: number) => Promise<string | undefined>;
+export declare const isProcessOwnerAlive: (pid: number, ownerIdentity?: string) => Promise<boolean>;
+export declare const requireCurrentProcessOwnerIdentity: () => Promise<string>;
+export {};

package/dist/src/computer-access/companion/process-owner-identity.js

@@ -0,0 +1,154 @@
+import { execFile } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { promisify } from "node:util";
+const executeFile = promisify(execFile);
+const WINDOWS_OWNER_SCRIPT = `
+$ErrorActionPreference = 'Stop'
+$targetPid = [int]$env:ABOT_HOST_OWNER_PID
+$target = Get-Process -Id $targetPid -ErrorAction Stop
+$started = $target.StartTime.ToUniversalTime().Ticks
+[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;
+    return pid > 0;
+}
+function isUuid(value) {
+    return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu.test(value);
+}
+function observePidLiveness(pid) {
+    if (!isProcessId(pid))
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        if (!error || typeof error !== "object" || !("code" in error))
+            return true;
+        return error.code !== "ESRCH";
+    }
+}
+async function linuxIdentity(pid, dependencies) {
+    const [bootText, processText] = await Promise.all([
+        dependencies.readText("/proc/sys/kernel/random/boot_id"),
+        dependencies.readText(`/proc/${pid}/stat`),
+    ]);
+    const boot = bootText.trim();
+    if (!isUuid(boot))
+        return undefined;
+    if (!processText.startsWith(`${pid} (`))
+        return undefined;
+    const commandEnd = processText.lastIndexOf(") ");
+    if (commandEnd < 0)
+        return undefined;
+    // After the final command-name parenthesis, index zero is stat field 3.
+    const startTicks = processText
+        .slice(commandEnd + 2)
+        .trim()
+        .split(/\s+/u)[19];
+    if (!startTicks || !/^\d+$/u.test(startTicks))
+        return undefined;
+    return `linux:${boot.toLowerCase()}:${startTicks}`;
+}
+function commandOptions(pid) {
+    return {
+        env: {
+            ...process.env,
+            ABOT_HOST_OWNER_PID: String(pid),
+            LC_ALL: "C",
+            TZ: "UTC",
+        },
+        windowsHide: true,
+        timeout: 5_000,
+        maxBuffer: 4_096,
+    };
+}
+async function windowsIdentity(pid, dependencies) {
+    const text = await dependencies.execute("powershell.exe", [
+        "-NoProfile",
+        "-NonInteractive",
+        "-EncodedCommand",
+        Buffer.from(WINDOWS_OWNER_SCRIPT, "utf16le").toString("base64"),
+    ], commandOptions(pid));
+    const value = text.trim();
+    if (!/^\d{10,20}$/u.test(value))
+        return undefined;
+    return `windows:${value}`;
+}
+async function macIdentity(pid, dependencies) {
+    const [bootText, startedText] = await Promise.all([
+        dependencies.execute("/usr/sbin/sysctl", ["-n", "kern.bootsessionuuid"], commandOptions(pid)),
+        dependencies.execute("/bin/ps", ["-p", String(pid), "-o", "lstart="], commandOptions(pid)),
+    ]);
+    const boot = bootText.trim();
+    const started = startedText.trim().replace(/\s+/gu, " ");
+    if (!isUuid(boot))
+        return undefined;
+    if (!/^[A-Za-z]{3} [A-Za-z]{3} \d{1,2} \d{2}:\d{2}:\d{2} \d{4}$/u.test(started))
+        return undefined;
+    return `macos:${boot.toLowerCase()}:${started}`;
+}
+export function createProcessOwnerIdentityProbe(dependencies) {
+    async function readProcessOwnerIdentity(pid) {
+        if (!isProcessId(pid))
+            return undefined;
+        try {
+            if (dependencies.platform === "linux")
+                return await linuxIdentity(pid, dependencies);
+            if (dependencies.platform === "win32")
+                return await windowsIdentity(pid, dependencies);
+            if (dependencies.platform === "darwin")
+                return await macIdentity(pid, dependencies);
+            return undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async function isProcessOwnerAlive(pid, ownerIdentity) {
+        if (!isProcessId(pid))
+            return false;
+        if (!dependencies.processIsAlive(pid))
+            return false;
+        if (!ownerIdentity)
+            return true;
+        const observed = await readProcessOwnerIdentity(pid);
+        if (!observed)
+            return true;
+        return hasSameProcessOwnerIdentity(ownerIdentity, observed);
+    }
+    async function requireCurrentProcessOwnerIdentity() {
+        const identity = await readProcessOwnerIdentity(dependencies.currentPid);
+        if (!identity)
+            throw new Error("The host companion could not establish this process's OS identity; its ownership lock was not acquired.");
+        return identity;
+    }
+    return {
+        readProcessOwnerIdentity,
+        isProcessOwnerAlive,
+        requireCurrentProcessOwnerIdentity,
+    };
+}
+const nativeProbe = createProcessOwnerIdentityProbe({
+    platform: process.platform,
+    currentPid: process.pid,
+    readText: (path) => readFile(path, "utf8"),
+    execute: async (file, args, options) => (await executeFile(file, [...args], options)).stdout,
+    processIsAlive: observePidLiveness,
+});
+export const readProcessOwnerIdentity = nativeProbe.readProcessOwnerIdentity;
+export const isProcessOwnerAlive = nativeProbe.isProcessOwnerAlive;
+export const requireCurrentProcessOwnerIdentity = nativeProbe.requireCurrentProcessOwnerIdentity;

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

@@ -0,0 +1,72 @@
+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 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";
+    user: string;
+    homeDir: string;
+}>;
+export type HostStatus = Readonly<{
+    paired: boolean;
+    hostId?: string;
+    identity?: HostIdentity;
+    companion?: ReturnType<typeof companionReleaseStatus>;
+    capabilities?: readonly string[];
+} & ({
+    connected: true;
+    connectionId: string;
+} | {
+    connected: false;
+    connectionId?: never;
+})>;
+export type HostAgentHello = Readonly<{
+    type: "hello";
+    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 = ObservationControl | Readonly<{
+    type: "paired";
+    hostId: string;
+    credential: string;
+}> | Readonly<{
+    type: "ready";
+    hostId: string;
+}> | Readonly<{
+    type: "execute";
+    id: string;
+    hostId: string;
+    operation: HostOperation;
+    params: Record<string, unknown>;
+}> | Readonly<{
+    type: "cancel";
+    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;
+export declare function hasMatchingHostIdentity(a: HostIdentity, b: HostIdentity): boolean;
+export declare function isHostToolResult(value: unknown): value is ToolImplementationOutput;