@whyvix/remote 0.3.5 → 0.3.6

package/native/gui-helper-manifest.json

@@ -0,0 +1,8 @@
+{
+  "artifacts": {
+    "win32-x64": {
+      "path": "native/win32-x64/whyvix-gui-helper.exe",
+      "sha256": "c9532bc51695d8d1afa93f56425b0142da78fbadc8719008d0b66f7e585669a5"
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@whyvix/remote",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "private": false,
   "type": "module",
   "files": [
@@ -8,6 +8,8 @@
     "packages/cli/index.js",
     "packages/cli/browser.js",
     "packages/protocol/src",
+    "native/gui-helper-manifest.json",
+    "native/win32-x64/whyvix-gui-helper.exe",
     "README.md"
   ],
   "scripts": {

package/packages/agent/src/agent.js

@@ -6,15 +6,18 @@ import { createSecurity } from "./security.js";
 import { ProcessManager } from "./process-manager.js";
 import { RemoteExecutionManager } from "./remote-execution-manager.js";
 import { DeploymentManager } from "./deployment-manager.js";
+import { GuiManager } from "./gui-manager.js";
 import { createToolExecutor } from "./tools.js";
 
-export function createAgent({gatewayUrl="ws://127.0.0.1:8787",deviceId=randomUUID(),deviceName=os.hostname(),token="",workspaces=[process.cwd()],remoteTargets=[],deploymentProfiles=[],agentVersion="unknown",capabilities=[],reconnectMs=1000,reconnect=true,heartbeatMs=30000,audit=()=>{},log=console.log,errorLog=console.error,onRegistered=()=>{}}={}) {
+export function createAgent({gatewayUrl="ws://127.0.0.1:8787",deviceId=randomUUID(),deviceName=os.hostname(),token="",workspaces=[process.cwd()],remoteTargets=[],deploymentProfiles=[],guiBackend=null,agentVersion="unknown",capabilities=[],reconnectMs=1000,reconnect=true,heartbeatMs=30000,audit=()=>{},log=console.log,errorLog=console.error,onRegistered=()=>{}}={}) {
   let ws=null,reconnectTimer=null,stopped=false,generation=0;
   const security=createSecurity({token,workspaces,audit});
   const processManager=new ProcessManager({audit});
   const remoteExecutionManager=new RemoteExecutionManager({targets:remoteTargets,audit});
   const deploymentManager=new DeploymentManager({profiles:deploymentProfiles,security,audit});
-  const executeTool=createToolExecutor({security,processManager,remoteExecutionManager,deploymentManager});
+  const guiManager=new GuiManager({backend:guiBackend,audit});
+  const advertisedCapabilities=[...new Set([...capabilities,...(guiManager.capabilities().available?["gui.observe"]:[])])].sort();
+  const executeTool=createToolExecutor({security,processManager,remoteExecutionManager,deploymentManager,guiManager});
   function scheduleReconnect(reason){
     if(stopped||!reconnect||reconnectTimer)return;
     log("[agent:reconnect-scheduled]",reason,reconnectMs);
@@ -37,7 +40,7 @@ export function createAgent({gatewayUrl="ws://127.0.0.1:8787",deviceId=randomUUI
       heartbeatTimer.unref?.();
     }
     log("[agent:connecting]",gatewayUrl,"generation="+current);
-    socket.on("open",()=>{if(ws!==socket)return;log("[agent:connected]",gatewayUrl);socket.send(JSON.stringify(envelope(TYPES.REGISTER,{auth:{token},device:{id:deviceId,name:deviceName,platform:process.platform,agentVersion,capabilities:[...new Set(capabilities.map(String))].sort()}})));});
+    socket.on("open",()=>{if(ws!==socket)return;log("[agent:connected]",gatewayUrl);socket.send(JSON.stringify(envelope(TYPES.REGISTER,{auth:{token},device:{id:deviceId,name:deviceName,platform:process.platform,agentVersion,capabilities:advertisedCapabilities}})));});
     socket.on("message",async(raw)=>{if(ws!==socket)return;try{const m=parseMessage(raw);if(m.type===TYPES.REGISTERED){log("[agent:registered]",m.deviceId);onRegistered({deviceId:m.deviceId,authorizedAccount:m.authorizedAccount||""});return;}if(m.type!==TYPES.REQUEST)return;log("[tool:request]",m.tool,{path:m.arguments?.path,cwd:m.arguments?.cwd});try{const result=await executeTool(m.tool,m.arguments);if(m.tool==="device.ping")Object.assign(result,{deviceId,deviceName});log("[tool:success]",m.tool);if(socket.readyState===WebSocket.OPEN)socket.send(JSON.stringify(envelope(TYPES.RESPONSE,{requestId:m.requestId,result})));}catch(error){errorLog("[tool:rejected]",m.tool,error.code||"TOOL_ERROR",error.message);if(socket.readyState===WebSocket.OPEN)socket.send(JSON.stringify(envelope(TYPES.ERROR,{requestId:m.requestId,error:{code:error.code||"TOOL_ERROR",message:error.message}})));}}catch(error){errorLog("[agent:protocol-error]",error.message);}});
     socket.on("close",(code)=>{stopHeartbeat();log("[agent:disconnected]","generation="+current,"code="+code);if(ws===socket)ws=null;if(code===1008){errorLog("[agent:authorization-required] device credential rejected");return;}if(code===4001){errorLog("[agent:replaced] newer WHYVIX Remote connection is active");return;}scheduleReconnect("close");});
     socket.on("error",(e)=>{errorLog("[agent:socket-error]",e.message);scheduleReconnect("error");});

package/packages/agent/src/binary-transfer-manager.js

@@ -0,0 +1,224 @@
+import fs from "node:fs/promises";
+import crypto from "node:crypto";
+
+const MAX_CHUNK = 32768;
+
+function fail(message, code) {
+  throw Object.assign(new Error(message), { code });
+}
+
+function decodeChunk(encoded) {
+  const value = String(encoded ?? "");
+
+  if (
+    value.length > 43692 ||
+    value.length % 4 !== 0 ||
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value)
+  ) {
+    fail("Invalid binary chunk", "INVALID_ARGUMENT");
+  }
+
+  const data = Buffer.from(value, "base64");
+
+  if (data.length > MAX_CHUNK) {
+    fail("Binary chunk exceeds 32768 bytes", "CONTENT_TOO_LARGE");
+  }
+
+  return data;
+}
+
+export class BinaryTransferManager {
+  constructor({ security, audit = () => {} } = {}) {
+    if (!security) throw new TypeError("security is required");
+
+    this.security = security;
+    this.audit = audit;
+    this.sessions = new Map();
+  }
+
+  async begin({ path, ownerId } = {}) {
+    const target = this.security.resolveFilesystemPath(path);
+
+    if (!ownerId) {
+      fail("ownerId is required", "INVALID_ARGUMENT");
+    }
+
+    try {
+      await fs.stat(target);
+      fail("Target already exists", "FILE_EXISTS");
+    } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+
+    const sessionId = crypto.randomUUID();
+    const temp = `${target}.whyvix-${sessionId}.part`;
+    const handle = await fs.open(temp, "wx");
+
+    const session = {
+      sessionId,
+      target,
+      temp,
+      ownerId,
+      handle,
+      size: 0,
+      hash: crypto.createHash("sha256"),
+    };
+
+    this.sessions.set(sessionId, session);
+
+    this.audit({
+      event: "binary.transfer.begin",
+      sessionId,
+      path: target,
+      ownerId,
+    });
+
+    return {
+      sessionId,
+      size: 0,
+      sha256: session.hash.copy().digest("hex"),
+    };
+  }
+
+  get(sessionId, ownerId) {
+    const session = this.sessions.get(String(sessionId));
+
+    if (!session) {
+      fail(
+        "Binary transfer session not found",
+        "TRANSFER_NOT_FOUND",
+      );
+    }
+
+    if (session.ownerId !== ownerId) {
+      fail(
+        "Binary transfer session belongs to another authorization",
+        "TRANSFER_OWNER_MISMATCH",
+      );
+    }
+
+    return session;
+  }
+
+  async write({
+    sessionId,
+    ownerId,
+    offset,
+    dataBase64,
+  } = {}) {
+    const session = this.get(sessionId, ownerId);
+    const data = decodeChunk(dataBase64);
+    const numericOffset = Number(offset);
+
+    if (
+      !Number.isSafeInteger(numericOffset) ||
+      numericOffset !== session.size
+    ) {
+      fail(
+        "Binary session requires sequential offset",
+        "INVALID_ARGUMENT",
+      );
+    }
+
+    await session.handle.write(
+      data,
+      0,
+      data.length,
+      session.size,
+    );
+
+    session.hash.update(data);
+    session.size += data.length;
+
+    return {
+      sessionId: session.sessionId,
+      size: session.size,
+      sha256: session.hash.copy().digest("hex"),
+    };
+  }
+
+  async finalize({
+    sessionId,
+    ownerId,
+    expectedSha256,
+  } = {}) {
+    const session = this.get(sessionId, ownerId);
+    const expected = String(expectedSha256 || "").toLowerCase();
+
+    if (!/^[a-f0-9]{64}$/.test(expected)) {
+      fail(
+        "expectedSha256 is required",
+        "INVALID_ARGUMENT",
+      );
+    }
+
+    const actual = session.hash.copy().digest("hex");
+
+    if (actual !== expected) {
+      fail(
+        "Final SHA-256 does not match transfer",
+        "FILE_CHANGED",
+      );
+    }
+
+    await session.handle.sync();
+    await session.handle.close();
+    session.handle = null;
+
+    try {
+      await fs.link(session.temp, session.target);
+      await fs.unlink(session.temp);
+    } catch (error) {
+      await fs.rm(session.temp, { force: true });
+      this.sessions.delete(session.sessionId);
+
+      if (error?.code === "EEXIST") {
+        fail(
+          "Target already exists",
+          "FILE_EXISTS",
+        );
+      }
+
+      throw error;
+    }
+
+    this.sessions.delete(session.sessionId);
+
+    this.audit({
+      event: "binary.transfer.finalize",
+      sessionId: session.sessionId,
+      path: session.target,
+      size: session.size,
+      ownerId,
+    });
+
+    return {
+      sessionId: session.sessionId,
+      path: session.target,
+      size: session.size,
+      sha256: actual,
+    };
+  }
+
+  async abort({ sessionId, ownerId } = {}) {
+    const session = this.get(sessionId, ownerId);
+
+    if (session.handle) {
+      await session.handle.close();
+    }
+
+    await fs.rm(session.temp, { force: true });
+    this.sessions.delete(session.sessionId);
+
+    this.audit({
+      event: "binary.transfer.abort",
+      sessionId: session.sessionId,
+      ownerId,
+    });
+
+    return {
+      sessionId: session.sessionId,
+      aborted: true,
+    };
+  }
+}

package/packages/agent/src/gui-backend-loader.js

@@ -0,0 +1,29 @@
+import path from "node:path";
+import { access, readFile } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import { WindowsGuiBackend } from "./windows-gui-backend.js";
+
+async function sha256(file){
+  const hash=createHash("sha256");
+  for await(const chunk of createReadStream(file))hash.update(chunk);
+  return hash.digest("hex");
+}
+
+export async function loadGuiBackend({platform=process.platform,arch=process.arch,runHelper,packageRoot}={}){
+  if(platform!=="win32")return null;
+  const root=packageRoot??path.resolve(path.dirname(fileURLToPath(import.meta.url)),"..","..","..");
+  const key=`${platform}-${arch}`;
+  const manifestPath=path.join(root,"native","gui-helper-manifest.json");
+  let manifest;
+  try{manifest=JSON.parse(await readFile(manifestPath,"utf8"));}catch{return null;}
+  const entry=manifest?.artifacts?.[key];
+  if(!entry||typeof entry.path!=="string"||!/^[a-f0-9]{64}$/.test(entry.sha256??""))return null;
+  const helperPath=path.resolve(root,entry.path);
+  if(!helperPath.startsWith(path.resolve(root)+path.sep))return null;
+  try{await access(helperPath);}catch{return null;}
+  if(await sha256(helperPath)!==entry.sha256)return null;
+  if(typeof runHelper!=="function")return null;
+  return new WindowsGuiBackend({helperPath,runHelper});
+}

package/packages/agent/src/gui-manager.js

@@ -0,0 +1,52 @@
+function fail(message,code){throw Object.assign(new Error(message),{code});}
+
+export class GuiManager {
+  constructor({backend=null,audit=()=>{}}={}){this.backend=backend;this.audit=audit;}
+
+  capabilities(){
+    const backend=this.backend;
+    return {
+      available:Boolean(backend),
+      backend:backend?.name||null,
+      observation:{
+        displays:Boolean(backend?.displays),
+        windows:Boolean(backend?.windows),
+        foreground:Boolean(backend?.foreground),
+        capture:Boolean(backend?.capture)
+      },
+      interaction:false,
+      accessibility:false
+    };
+  }
+
+  #require(operation){
+    if(!this.backend)fail("GUI backend is not available on this device","GUI_NOT_AVAILABLE");
+    const fn=this.backend[operation];
+    if(typeof fn!=="function")fail(`GUI operation is not supported: ${operation}`,"GUI_OPERATION_NOT_AVAILABLE");
+    return fn.bind(this.backend);
+  }
+
+  async displays(){
+    const result=await this.#require("displays")();
+    this.audit({event:"gui.displays"});
+    return result;
+  }
+
+  async windows(){
+    const result=await this.#require("windows")();
+    this.audit({event:"gui.windows"});
+    return result;
+  }
+
+  async foreground(){
+    const result=await this.#require("foreground")();
+    this.audit({event:"gui.foreground"});
+    return result;
+  }
+
+  async capture(args={}){
+    const result=await this.#require("capture")(args);
+    this.audit({event:"gui.capture",displayId:args.displayId??null,windowId:args.windowId??null});
+    return result;
+  }
+}

package/packages/agent/src/process-manager.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import fs from "node:fs";
 import path from "node:path";
 
 const DEFAULT_EXECUTABLES = null;
@@ -55,6 +56,15 @@ export class ProcessManager {
     while(completed.length>this.maxRetainedJobs){const oldest=completed.shift();this.processes.delete(oldest.id);}
   }
 
+  discover({command,pathValue=process.env.PATH||"",pathExtValue=process.env.PATHEXT||".COM;.EXE;.BAT;.CMD"}={}) {
+    const executable=resolveExecutable(this.executableRegistry,command);
+    const dirs=String(pathValue).split(path.delimiter).filter(Boolean);
+    const extensions=this.platform==="win32"?(path.extname(executable.command)?[""]:String(pathExtValue).split(";").filter(Boolean)):[""];
+    const matches=[];
+    for(const dir of dirs)for(const ext of extensions){const candidate=path.resolve(dir,executable.command+ext);try{const stat=fs.statSync(candidate);if(stat.isFile()&&!matches.includes(candidate))matches.push(candidate);}catch{}}
+    return{command:executable.name,available:matches.length>0,matches:matches.slice(0,16)};
+  }
+
   start({command,args=[],cwd,timeoutMs=30000,ownerId}={}) {
     this.#cleanup();
     const executable=resolveExecutable(this.executableRegistry,command);
@@ -83,5 +93,6 @@ export class ProcessManager {
 
   #owned(id,ownerId){this.#cleanup();const s=this.processes.get(String(id));if(!s)fail("LOCAL_JOB_NOT_FOUND","Local job not found");if(s.ownerId!=null&&String(ownerId||"")!==s.ownerId)fail("LOCAL_JOB_NOT_FOUND","Local job not found");return s;}
   output({id,ownerId}={}){const s=this.#owned(id,ownerId);return{id:s.id,stdout:s.stdout,stderr:s.stderr,running:s.running,exitCode:s.exitCode,errorCode:s.errorCode,truncated:s.truncated,timedOut:s.timedOut};}
+  input({id,ownerId,data,end=false}={}){const s=this.#owned(id,ownerId);if(!s.running)fail("LOCAL_JOB_NOT_RUNNING","Local job is not running");if(typeof data!=="string")fail("INVALID_ARGUMENT","data must be a string");if(Buffer.byteLength(data,"utf8")>65536)fail("CONTENT_TOO_LARGE","stdin data exceeds 65536 UTF-8 bytes");if(!s.child.stdin||typeof s.child.stdin.write!=="function")fail("LOCAL_STDIN_UNAVAILABLE","Local process stdin is unavailable");if(data.length)s.child.stdin.write(data);if(end){if(typeof s.child.stdin.end!=="function")fail("LOCAL_STDIN_UNAVAILABLE","Local process stdin cannot be closed");s.child.stdin.end();}this.audit({event:"process.input",id,bytes:Buffer.byteLength(data,"utf8"),end:Boolean(end)});return{id:s.id,writtenBytes:Buffer.byteLength(data,"utf8"),ended:Boolean(end)};}
   stop({id,ownerId}={}){const s=this.#owned(id,ownerId);if(s.running)s.child.kill();return{id:s.id,stopping:s.running};}
 }

package/packages/agent/src/tools.js

@@ -1,14 +1,26 @@
 import fs from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { BinaryTransferManager } from "./binary-transfer-manager.js";
 import path from "node:path";
 import crypto from "node:crypto";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
 const execFileAsync=promisify(execFile);
 
-export function createToolExecutor({ security, processManager, remoteExecutionManager, deploymentManager }) {
+export function createToolExecutor({ security, processManager, remoteExecutionManager, deploymentManager, guiManager }) {
+  const binaryTransferManager=new BinaryTransferManager({security,audit:(entry)=>security.audit(entry)});
   return async function executeTool(tool,args={}) {
     security.audit({event:"tool.request",tool});
     if(tool==="device.ping") return {pong:true,timestamp:new Date().toISOString()};
+    if(tool==="gui.capabilities")return guiManager?.capabilities()??{available:false,backend:null,observation:{displays:false,windows:false,foreground:false,capture:false},interaction:false,accessibility:false};
+    if(tool==="gui.displays")return guiManager.displays();
+    if(tool==="gui.windows")return guiManager.windows();
+    if(tool==="gui.foreground")return guiManager.foreground();
+    if(tool==="gui.capture")return guiManager.capture(args);
+    if(tool==="fs.begin_binary_write")return binaryTransferManager.begin(args);
+    if(tool==="fs.write_binary_session")return binaryTransferManager.write(args);
+    if(tool==="fs.finalize_binary_write")return binaryTransferManager.finalize(args);
+    if(tool==="fs.abort_binary_write")return binaryTransferManager.abort(args);
     if(tool==="fs.list"){const target=security.resolveFilesystemPath(args.path);const entries=await fs.readdir(target,{withFileTypes:true});return{path:target,entries:entries.map(e=>({name:e.name,type:e.isDirectory()?"directory":e.isFile()?"file":"other"}))};}
     if(tool==="fs.read"){const target=security.resolveFilesystemPath(args.path);const max=Math.min(Number(args.maxBytes||65536),262144);const h=await fs.open(target,"r");try{const stat=await h.stat();if(!stat.isFile())throw Object.assign(new Error("Target must be a regular file"),{code:"INVALID_TARGET"});const readBytes=Math.min(stat.size,262144);const snapshot=Buffer.alloc(readBytes);const {bytesRead}=await h.read(snapshot,0,readBytes,0);const data=snapshot.subarray(0,bytesRead);return{path:target,content:data.subarray(0,max).toString("utf8"),truncated:stat.size>max,size:stat.size,...(stat.size<=262144&&bytesRead===stat.size?{sha256:crypto.createHash("sha256").update(data).digest("hex")}:{})};}finally{await h.close();}}
     if(tool==="fs.search"){
@@ -32,6 +44,11 @@ export function createToolExecutor({ security, processManager, remoteExecutionMa
       await walk(root,0);return{path:root,query:q,mode,matches,truncated:matches.length>=maxResults};
     }
     if(tool==="fs.info"){const target=security.resolveFilesystemPath(args.path);const stat=await fs.stat(target);return{path:target,type:stat.isDirectory()?"directory":stat.isFile()?"file":"other",size:stat.size,createdAt:stat.birthtime.toISOString(),modifiedAt:stat.mtime.toISOString()};}
+    if(tool==="fs.hash"){const target=security.resolveFilesystemPath(args.path);const stat=await fs.stat(target);if(!stat.isFile())throw Object.assign(new Error("Target must be a regular file"),{code:"INVALID_TARGET"});const hash=crypto.createHash("sha256");await new Promise((resolve,reject)=>{const stream=createReadStream(target);stream.on("data",(chunk)=>hash.update(chunk));stream.on("error",reject);stream.on("end",resolve);});return{path:target,size:stat.size,sha256:hash.digest("hex")};}
+    if(tool==="fs.read_binary"){const target=security.resolveFilesystemPath(args.path);const stat=await fs.stat(target);if(!stat.isFile())throw Object.assign(new Error("Target must be a regular file"),{code:"INVALID_TARGET"});const offset=Number(args.offset||0),maxBytes=Number(args.maxBytes||32768);if(!Number.isSafeInteger(offset)||offset<0||!Number.isSafeInteger(maxBytes)||maxBytes<1||maxBytes>32768||offset>stat.size)throw Object.assign(new Error("Invalid binary range"),{code:"INVALID_ARGUMENT"});const bytesToRead=Math.min(maxBytes,stat.size-offset),handle=await fs.open(target,"r");try{const buffer=Buffer.alloc(bytesToRead),{bytesRead}=await handle.read(buffer,0,bytesToRead,offset);return{path:target,offset,bytesRead,size:stat.size,dataBase64:buffer.subarray(0,bytesRead).toString("base64"),eof:offset+bytesRead>=stat.size};}finally{await handle.close();}}
+    if(tool==="fs.create_binary"){const target=security.resolveFilesystemPath(args.path),encoded=String(args.dataBase64??"");if(encoded.length>43692||encoded.length%4!==0||!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded))throw Object.assign(new Error("Invalid or oversized binary chunk"),{code:"INVALID_ARGUMENT"});const data=Buffer.from(encoded,"base64");if(data.length>32768)throw Object.assign(new Error("Binary chunk exceeds 32768 bytes"),{code:"CONTENT_TOO_LARGE"});try{await fs.writeFile(target,data,{flag:"wx"});}catch(error){if(error?.code==="EEXIST")throw Object.assign(new Error("Target already exists"),{code:"FILE_EXISTS"});throw error;}return{path:target,size:data.length,sha256:crypto.createHash("sha256").update(data).digest("hex")};}
+    if(tool==="fs.write_binary"){const target=security.resolveFilesystemPath(args.path),offset=Number(args.offset),expectedSize=Number(args.expectedSize),expectedSha256=String(args.expectedSha256||"").toLowerCase(),encoded=String(args.dataBase64??"");if(!Number.isSafeInteger(offset)||offset<0||!Number.isSafeInteger(expectedSize)||expectedSize<0||offset!==expectedSize||!/^[a-f0-9]{64}$/.test(expectedSha256))throw Object.assign(new Error("Invalid guarded binary write"),{code:"INVALID_ARGUMENT"});if(encoded.length>43692||encoded.length%4!==0||!/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(encoded))throw Object.assign(new Error("Invalid or oversized binary chunk"),{code:"INVALID_ARGUMENT"});const data=Buffer.from(encoded,"base64");if(data.length>32768)throw Object.assign(new Error("Binary chunk exceeds 32768 bytes"),{code:"CONTENT_TOO_LARGE"});const stat=await fs.stat(target);if(!stat.isFile())throw Object.assign(new Error("Target must be a regular file"),{code:"INVALID_TARGET"});if(stat.size!==expectedSize)throw Object.assign(new Error("File changed since previous chunk"),{code:"FILE_CHANGED"});const hash=crypto.createHash("sha256");await new Promise((resolve,reject)=>{const stream=createReadStream(target);stream.on("data",(chunk)=>hash.update(chunk));stream.on("error",reject);stream.on("end",resolve);});if(hash.digest("hex")!==expectedSha256)throw Object.assign(new Error("File changed since previous chunk"),{code:"FILE_CHANGED"});await fs.appendFile(target,data);const updatedHash=crypto.createHash("sha256");await new Promise((resolve,reject)=>{const stream=createReadStream(target);stream.on("data",(chunk)=>updatedHash.update(chunk));stream.on("error",reject);stream.on("end",resolve);});return{path:target,size:expectedSize+data.length,sha256:updatedHash.digest("hex")};}
+    if(tool==="fs.copy"){const source=security.resolveFilesystemPath(args.source),destination=security.resolveFilesystemPath(args.destination),stat=await fs.stat(source);if(!stat.isFile())throw Object.assign(new Error("Source must be a regular file"),{code:"INVALID_TARGET"});try{await fs.copyFile(source,destination,fs.constants?.COPYFILE_EXCL??1);}catch(error){if(error?.code==="EEXIST")throw Object.assign(new Error("Destination already exists"),{code:"FILE_EXISTS"});throw error;}const copied=await fs.stat(destination),hash=crypto.createHash("sha256");await new Promise((resolve,reject)=>{const stream=createReadStream(destination);stream.on("data",(chunk)=>hash.update(chunk));stream.on("error",reject);stream.on("end",resolve);});return{source,destination,size:copied.size,sha256:hash.digest("hex")};}
     if(tool==="fs.mkdir"){const target=security.resolveFilesystemPath(args.path);try{const stat=await fs.stat(target);if(!stat.isDirectory())throw Object.assign(new Error("Target exists and is not a directory"),{code:"FILE_EXISTS"});return{path:target,created:false};}catch(error){if(error?.code!=="ENOENT")throw error;}await fs.mkdir(target,{recursive:Boolean(args.recursive)});return{path:target,created:true};}
     if(tool==="fs.move"){const source=security.resolveFilesystemPath(args.source);const destination=security.resolveFilesystemPath(args.destination);try{await fs.lstat(destination);throw Object.assign(new Error("Destination already exists"),{code:"FILE_EXISTS"});}catch(error){if(error?.code!=="ENOENT")throw error;}await fs.rename(source,destination);return{source,destination};}
     if(tool==="fs.delete_file"){const requested=path.resolve(String(args.path||""));const target=security.resolveFilesystemPath(requested);const linkStat=await fs.lstat(requested);if(linkStat.isSymbolicLink())throw Object.assign(new Error("Symbolic links cannot be deleted through delete_file"),{code:"INVALID_TARGET"});if(!linkStat.isFile())throw Object.assign(new Error("Target must be a regular file"),{code:"INVALID_TARGET"});await fs.unlink(requested);return{path:requested,deleted:true};}
@@ -76,8 +93,10 @@ export function createToolExecutor({ security, processManager, remoteExecutionMa
     if(tool==="remote.deploy_status"){if(!remoteExecutionManager)throw Object.assign(new Error("Remote execution is not configured"),{code:"REMOTE_TARGET_DENIED"});return remoteExecutionManager.startDeployHelper({alias:args.alias,input:{operation:"status",commit:args.commit},timeoutMs:args.timeoutMs,ownerId:args.ownerId});}
     if(tool==="remote.output"){if(!remoteExecutionManager)throw Object.assign(new Error("Remote execution is not configured"),{code:"REMOTE_JOB_NOT_FOUND"});return remoteExecutionManager.output(args);}
     if(tool==="remote.stop"){if(!remoteExecutionManager)throw Object.assign(new Error("Remote execution is not configured"),{code:"REMOTE_JOB_NOT_FOUND"});return remoteExecutionManager.stop(args);}
+    if(tool==="process.discover")return processManager.discover(args);
     if(tool==="process.start"){const cwd=security.resolveFilesystemPath(args.cwd);return processManager.start({...args,cwd});}
     if(tool==="process.output")return processManager.output(args);
+    if(tool==="process.input")return processManager.input(args);
     if(tool==="process.stop")return processManager.stop(args);
     if(tool==="git.status"||tool==="git.diff"||tool==="git.log"){const cwd=security.resolveFilesystemPath(args.cwd);const gitArgs=tool==="git.status"?["status","--porcelain=v1","--branch"]:tool==="git.diff"?["diff","--",...(args.paths||[])]:["log","--oneline","-n",String(Math.min(Number(args.limit||10),50))];const {stdout,stderr}=await execFileAsync("git",gitArgs,{cwd,windowsHide:true,maxBuffer:1024*1024});return{stdout,stderr};}
     if(tool==="git.stage_paths"||tool==="git.commit"||tool==="git.push"){

package/packages/agent/src/windows-gui-backend.js

@@ -0,0 +1,30 @@
+import path from "node:path";
+
+const OPERATIONS=new Set(["displays","windows","foreground","capture"]);
+function fail(message,code){throw Object.assign(new Error(message),{code});}
+
+export class WindowsGuiBackend {
+  constructor({helperPath,runHelper,maxOutputBytes=8*1024*1024}={}){
+    if(typeof runHelper!=="function")fail("Windows GUI helper runner is required","GUI_HELPER_NOT_CONFIGURED");
+    if(typeof helperPath!=="string"||!helperPath.trim())fail("Windows GUI helper path is required","GUI_HELPER_NOT_CONFIGURED");
+    this.name="windows-native";
+    this.helperPath=path.resolve(helperPath);
+    this.runHelper=runHelper;
+    this.maxOutputBytes=Math.max(65536,Math.min(Number(maxOutputBytes)||8*1024*1024,16*1024*1024));
+  }
+
+  async call(operation,args={}){
+    if(!OPERATIONS.has(operation))fail("GUI helper operation is not allowed","GUI_OPERATION_NOT_AVAILABLE");
+    let response;
+    try{response=await this.runHelper({helperPath:this.helperPath,operation,args,maxOutputBytes:this.maxOutputBytes});}
+    catch(error){if(error?.code==="GUI_NOT_AVAILABLE")throw error;fail("Windows GUI helper failed","GUI_BACKEND_FAILED");}
+    if(!response||typeof response!=="object"||Array.isArray(response))fail("Windows GUI helper returned invalid payload","GUI_BACKEND_PROTOCOL_ERROR");
+    if(response.error)fail(String(response.error.message||"Windows GUI helper rejected operation"),String(response.error.code||"GUI_BACKEND_FAILED"));
+    return response;
+  }
+
+  displays(){return this.call("displays");}
+  windows(){return this.call("windows");}
+  foreground(){return this.call("foreground");}
+  capture(args={}){return this.call("capture",args);}
+}

package/packages/agent/src/windows-gui-helper-runner.js

@@ -0,0 +1,13 @@
+import { execFile } from "node:child_process";
+
+const OPERATIONS=new Set(["displays","windows","foreground","capture"]);
+
+export function runWindowsGuiHelper({helperPath,operation,maxOutputBytes=8*1024*1024}){
+  if(!OPERATIONS.has(operation))return Promise.reject(Object.assign(new Error("GUI operation is not available"),{code:"GUI_OPERATION_NOT_AVAILABLE"}));
+  return new Promise((resolve,reject)=>{
+    execFile(helperPath,[operation],{windowsHide:true,timeout:15000,maxBuffer:maxOutputBytes,encoding:"utf8"},(error,stdout)=>{
+      if(error)return reject(Object.assign(new Error("Windows GUI helper failed"),{code:error.killed?"GUI_BACKEND_TIMEOUT":"GUI_BACKEND_FAILED"}));
+      try{resolve(JSON.parse(stdout));}catch{reject(Object.assign(new Error("Windows GUI helper returned invalid JSON"),{code:"GUI_BACKEND_PROTOCOL_ERROR"}));}
+    });
+  });
+}

package/packages/cli/index.js

@@ -5,7 +5,9 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createAgent } from "../agent/src/agent.js";
-import { loadDeploymentProfiles } from "../agent/src/deployment-profile-loader.js";
+import { loadDeploymentProfiles } from "../agent/src/deployment-profile-loader.js";
+import { loadGuiBackend } from "../agent/src/gui-backend-loader.js";
+import { runWindowsGuiHelper } from "../agent/src/windows-gui-helper-runner.js";
 import { openBrowser } from "./browser.js";
 
 const packageRoot=join(dirname(fileURLToPath(import.meta.url)),"..","..");
@@ -19,6 +21,7 @@ const remoteTargets=(process.env.WHYVIX_REMOTE_TARGETS||"").split(";").map(alias
 const configuredDeploymentProfiles=String(process.env.WHYVIX_DEPLOY_PROFILES_FILE||"").trim();
 const defaultDeploymentProfiles=join(os.homedir(),".whyvix-remote","deployment-profiles.json");
 const deploymentProfiles=await loadDeploymentProfiles(configuredDeploymentProfiles||defaultDeploymentProfiles,{optional:!configuredDeploymentProfiles});
+const guiBackend=await loadGuiBackend({packageRoot,runHelper:runWindowsGuiHelper});
 const capabilities=["filesystem.crud","process.bounded","git.read","git.mutate",...(remoteTargets.length?["remote.bounded"]:[]),...(deploymentProfiles.length?["deployment.profiled"]:[])];
 const deviceId=process.env.WHYVIX_DEVICE_ID||crypto.createHash("sha256").update(os.hostname()+"|"+os.userInfo().username).digest("hex").slice(0,24);
 const credentialDir=join(os.homedir(),".whyvix-remote");
@@ -65,6 +68,7 @@ const agent=createAgent({
   workspaces,
   remoteTargets,
   deploymentProfiles,
+  guiBackend,
   agentVersion:String(packageMeta.version||"unknown"),
   capabilities,
   audit:(event)=>{