@whyvix/remote 0.2.1 → 0.3.0

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@whyvix/remote",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "private": false,
   "type": "module",
   "files": [
     "packages/agent/src",
     "packages/cli/index.js",
+    "packages/cli/browser.js",
     "packages/protocol/src",
     "README.md"
   ],

package/packages/agent/src/agent.js

@@ -4,13 +4,15 @@ import WebSocket from "ws";
 import { envelope, parseMessage, TYPES } from "../../protocol/src/index.js";
 import { createSecurity } from "./security.js";
 import { ProcessManager } from "./process-manager.js";
+import { RemoteExecutionManager } from "./remote-execution-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()],reconnectMs=1000,reconnect=true,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=[],reconnectMs=1000,reconnect=true,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 executeTool=createToolExecutor({security,processManager});
+  const remoteExecutionManager=new RemoteExecutionManager({targets:remoteTargets,audit});
+  const executeTool=createToolExecutor({security,processManager,remoteExecutionManager});
   function scheduleReconnect(reason){
     if(stopped||!reconnect||reconnectTimer)return;
     log("[agent:reconnect-scheduled]",reason,reconnectMs);

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

@@ -0,0 +1,51 @@
+import path from "node:path";
+import fs from "node:fs/promises";
+import crypto from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync=promisify(execFile);
+const PROFILE_RE=/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const SHA_RE=/^[a-f0-9]{40}$/;
+
+function fail(code,message){throw Object.assign(new Error(message),{code});}
+async function sha256(file){const hash=crypto.createHash("sha256");const data=await fs.readFile(file);hash.update(data);return hash.digest("hex");}
+
+export class DeploymentManager{
+ constructor({profiles=[],security,audit=()=>{},execFileFn=execFileAsync}={}){
+  if(!security?.resolveAllowed)fail("DEPLOY_PROFILE_DENIED","Deployment security authority is required");
+  this.profiles=new Map();
+  for(const profile of profiles){
+   if(!PROFILE_RE.test(String(profile?.alias||""))||!PROFILE_RE.test(String(profile?.remoteAlias||""))||typeof profile?.repository!=="string"||!profile.repository.trim())fail("DEPLOY_PROFILE_DENIED","Invalid deployment profile");
+   if(this.profiles.has(profile.alias))fail("DEPLOY_PROFILE_DENIED","Duplicate deployment profile");
+   this.profiles.set(profile.alias,profile);
+  }
+  this.security=security;this.audit=audit;this.execFileFn=execFileFn;
+ }
+ listProfiles(){return [...this.profiles.values()].map(({alias,label="",remoteAlias})=>({alias,label,remoteAlias}));}
+ #profile(alias){const value=String(alias||"");if(!PROFILE_RE.test(value)||!this.profiles.has(value))fail("DEPLOY_PROFILE_DENIED","Deployment profile is not registered");return this.profiles.get(value);}
+ async prepareLocal({profile:profileAlias,commit,baseCommit=null}){
+  const profile=this.#profile(profileAlias);
+  if(!SHA_RE.test(String(commit||"")))fail("DEPLOY_COMMIT_INVALID","Deployment commit must be an exact 40-character lowercase SHA");
+  if(baseCommit!==null&&!SHA_RE.test(String(baseCommit)))fail("DEPLOY_COMMIT_INVALID","Base commit must be an exact 40-character lowercase SHA");
+  const repo=this.security.resolveAllowed(profile.repository);
+  const {stdout:rootRaw}=await this.execFileFn("git",["rev-parse","--show-toplevel"],{cwd:repo,windowsHide:true,maxBuffer:1024*1024});
+  const root=this.security.resolveAllowed(rootRaw.trim());
+  if(path.resolve(root)!==path.resolve(repo))fail("DEPLOY_PROFILE_DENIED","Deployment repository root does not match profile");
+  const {stdout:status}=await this.execFileFn("git",["status","--porcelain"],{cwd:root,windowsHide:true,maxBuffer:1024*1024});
+  const dirty=status.split(/\r?\n/).filter(Boolean).filter(line=>!line.startsWith("?? .deploy/"));
+  if(dirty.length)fail("DEPLOY_REPOSITORY_DIRTY","Deployment repository must be clean");
+  try{await this.execFileFn("git",["cat-file","-e",commit+"^{commit}"],{cwd:root,windowsHide:true,maxBuffer:1024*1024});}catch{fail("DEPLOY_COMMIT_INVALID","Deployment commit does not exist locally");}
+  let dependencyChanged=false;
+  if(baseCommit){
+   try{const {stdout}=await this.execFileFn("git",["diff","--name-only",baseCommit,commit,"--","package-lock.json","npm-shrinkwrap.json","composer.lock"],{cwd:root,windowsHide:true,maxBuffer:1024*1024});dependencyChanged=Boolean(stdout.trim());}
+   catch{fail("DEPLOY_COMMIT_INVALID","Base commit does not exist locally");}
+  }
+  const deployDir=this.security.resolveAllowed(path.join(root,".deploy"));await fs.mkdir(deployDir,{recursive:true});
+  const shortSha=commit.slice(0,7),artifact=path.join(deployDir,`release-${shortSha}.tar`);
+  await this.execFileFn("git",["archive","--format=tar","-o",artifact,commit],{cwd:root,windowsHide:true,maxBuffer:1024*1024});
+  const artifactSha256=await sha256(artifact);
+  this.audit({event:"deploy.prepare_local",profile:profile.alias,commit,dependencyChanged});
+  return{profile:profile.alias,remoteAlias:profile.remoteAlias,commit,shortSha,artifact,artifactSha256,dependencyChanged};
+ }
+}

package/packages/agent/src/deployment-protocol.js

@@ -0,0 +1,45 @@
+import path from "node:path";
+
+const PROFILE_RE=/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const SHA_RE=/^[a-f0-9]{40}$/;
+const HASH_RE=/^[a-f0-9]{64}$/;
+const OPS=new Set(["stage","verify","prepare","status","activate"]);
+
+function fail(code,message){throw Object.assign(new Error(message),{code});}
+function absolutePosix(value){return typeof value==="string"&&value.startsWith("/")&&!value.includes("\0")&&!value.split("/").includes("..");}
+
+export function validateDeploymentProfile(profile){
+ if(!profile||!PROFILE_RE.test(String(profile.alias||""))||!PROFILE_RE.test(String(profile.remoteAlias||"")))fail("DEPLOY_PROFILE_DENIED","Invalid deployment profile");
+ if(!absolutePosix(profile.remoteReleaseRoot)||!absolutePosix(profile.remoteStagingRoot))fail("DEPLOY_PROFILE_DENIED","Invalid deployment profile paths");
+ if(typeof profile.serviceName!=="string"||!/^[-A-Za-z0-9_.@]+\.service$/.test(profile.serviceName))fail("DEPLOY_PROFILE_DENIED","Invalid deployment service");
+ return Object.freeze({...profile});
+}
+
+export function releaseIdFromCommit(commit){
+ if(!SHA_RE.test(String(commit||"")))fail("DEPLOY_COMMIT_INVALID","Deployment commit must be an exact 40-character lowercase SHA");
+ return "r10-"+commit.slice(0,12);
+}
+
+export function buildDeployHelperArgs(input){
+ const operation=String(input?.operation||""),commit=String(input?.commit||""),releaseId=releaseIdFromCommit(commit);
+ if(!["verify","prepare","status"].includes(operation))fail("DEPLOY_OPERATION_DENIED","Deployment helper operation is not allowed");
+ if(input?.releaseId!==undefined&&String(input.releaseId)!==releaseId)fail("DEPLOY_ARGUMENT_INVALID","Release identity does not match commit");
+ if(operation==="status"){if(input?.artifactSha256!==undefined)fail("DEPLOY_ARGUMENT_INVALID","Status does not accept artifact checksum");return Object.freeze([operation,releaseId,commit]);}
+ const artifactSha256=String(input?.artifactSha256||"");if(!HASH_RE.test(artifactSha256))fail("DEPLOY_CHECKSUM_INVALID","Artifact SHA-256 is required");
+ return Object.freeze([operation,releaseId,commit,artifactSha256]);
+}
+
+export function buildDeploymentOperation(profile,input){
+ const p=validateDeploymentProfile(profile),op=String(input?.operation||"");
+ if(!OPS.has(op))fail("DEPLOY_OPERATION_DENIED","Deployment operation is not allowed");
+ const commit=String(input?.commit||"");const releaseId=releaseIdFromCommit(commit);
+ const releasePath=path.posix.join(p.remoteReleaseRoot,releaseId);
+ const artifactPath=path.posix.join(p.remoteStagingRoot,releaseId+".tar");
+ const result={operation:op,profile:p.alias,remoteAlias:p.remoteAlias,commit,releaseId,releasePath,artifactPath,serviceName:p.serviceName};
+ if(["stage","verify","prepare"].includes(op)){
+  const artifactSha256=String(input?.artifactSha256||"");
+  if(!HASH_RE.test(artifactSha256))fail("DEPLOY_CHECKSUM_INVALID","Artifact SHA-256 is required");
+  result.artifactSha256=artifactSha256;
+ }
+ return Object.freeze(result);
+}

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

@@ -1,19 +1,78 @@
 import { spawn } from "node:child_process";
 
-export class ProcessManager {
-  constructor({ audit = () => {} } = {}) { this.audit=audit; this.processes=new Map(); this.nextId=1; }
-  start({ command, args = [], cwd, timeoutMs = 30000 }) {
-    if (!command) throw Object.assign(new Error("command is required"), { code:"INVALID_ARGUMENT" });
-    const id=String(this.nextId++);
-    const child=spawn(command,args,{cwd,windowsHide:true,shell:false});
-    const state={ id, command, args, cwd, stdout:"", stderr:"", exitCode:null, running:true, child };
-    this.processes.set(id,state); this.audit({event:"process.start",id,command,cwd});
-    child.stdout?.on("data",(x)=>state.stdout+=x.toString());
-    child.stderr?.on("data",(x)=>state.stderr+=x.toString());
-    child.on("close",(code)=>{state.exitCode=code;state.running=false;this.audit({event:"process.exit",id,code});});
-    if(timeoutMs>0) setTimeout(()=>{if(state.running) child.kill();},Math.min(timeoutMs,300000)).unref();
-    return {id,pid:child.pid};
+const DEFAULT_EXECUTABLES = Object.freeze({
+  node: process.execPath,
+  npm: "npm",
+  npx: "npx",
+  php: "php",
+  composer: "composer"
+});
+
+function fail(code, message) { throw Object.assign(new Error(message), { code }); }
+
+function appendBounded(state, key, chunk, maxBytes) {
+  const current = Buffer.from(state[key], "utf8");
+  const incoming = Buffer.from(chunk);
+  const remaining = Math.max(0, maxBytes - current.length);
+  if (incoming.length > remaining) state.truncated = true;
+  if (remaining > 0) state[key] += incoming.subarray(0, remaining).toString("utf8");
+}
+
+function normalizeRegistry(value) {
+  if (Array.isArray(value)) return new Map(value.map((x) => [String(x).toLowerCase(), String(x)]));
+  return new Map(Object.entries(value || {}).map(([name, command]) => [String(name).toLowerCase(), String(command)]));
+}
+
+function resolveExecutable(registry, requested) {
+  const raw = String(requested || "").trim();
+  if (!raw) fail("INVALID_ARGUMENT", "command is required");
+  const key = raw.toLowerCase().replace(/\.exe$/, "");
+  if (registry.has(key) && !raw.includes("/") && !raw.includes("\\") && !raw.includes(":")) return { name: key, command: registry.get(key) };
+  for (const [name, command] of registry) {
+    if (raw.toLowerCase() === command.toLowerCase()) return { name, command };
   }
-  output({id}) { const s=this.processes.get(String(id)); if(!s) throw Object.assign(new Error("Process not found"),{code:"PROCESS_NOT_FOUND"}); return {id:s.id,stdout:s.stdout,stderr:s.stderr,running:s.running,exitCode:s.exitCode}; }
-  stop({id}) { const s=this.processes.get(String(id)); if(!s) throw Object.assign(new Error("Process not found"),{code:"PROCESS_NOT_FOUND"}); if(s.running)s.child.kill(); return {id:s.id,stopping:s.running}; }
+  fail("LOCAL_EXEC_NOT_ALLOWED", "Local executable is not allowed");
 }
+
+export class ProcessManager {
+  constructor({ audit=()=>{}, spawnFn=spawn, allowedExecutables=DEFAULT_EXECUTABLES, maxOutputBytes=262144, maxRetainedJobs=100, maxRunningJobs=16, jobRetentionMs=300000, now=()=>Date.now() }={}) {
+    this.audit=audit; this.spawnFn=spawnFn; this.executableRegistry=normalizeRegistry(allowedExecutables);
+    this.maxOutputBytes=Math.max(1024,Math.min(Number(maxOutputBytes)||262144,1048576));
+    this.maxRetainedJobs=Math.max(1,Math.min(Number(maxRetainedJobs)||100,1000));
+    this.maxRunningJobs=Math.max(1,Math.min(Number(maxRunningJobs)||16,128));
+    this.jobRetentionMs=Math.max(1000,Math.min(Number(jobRetentionMs)||300000,86400000));
+    this.now=now; this.processes=new Map(); this.nextId=1;
+  }
+
+  #cleanup() {
+    const now=this.now();
+    for(const [id,state] of this.processes) if(!state.running&&state.completedAt!=null&&now-state.completedAt>=this.jobRetentionMs)this.processes.delete(id);
+    const completed=[...this.processes.values()].filter(x=>!x.running).sort((a,b)=>(a.completedAt||0)-(b.completedAt||0));
+    while(completed.length>this.maxRetainedJobs){const oldest=completed.shift();this.processes.delete(oldest.id);}
+  }
+
+  start({command,args=[],cwd,timeoutMs=30000,ownerId}={}) {
+    this.#cleanup();
+    const executable=resolveExecutable(this.executableRegistry,command);
+    if(!Array.isArray(args)||args.some(x=>typeof x!=="string"))fail("INVALID_ARGUMENT","args must be an array of strings");
+    if(executable.name==="npx") {
+      if(args.some(x=>/^--(?:yes|package|call|shell|install)/i.test(x))) fail("LOCAL_EXEC_NOT_ALLOWED","npx install or shell options are not allowed");
+      args=["--no-install",...args];
+    }
+    if([...this.processes.values()].filter(x=>x.running).length>=this.maxRunningJobs)fail("LOCAL_JOB_LIMIT","Local running job limit reached");
+    const id=String(this.nextId++);let child;
+    try{child=this.spawnFn(executable.command,args,{cwd,windowsHide:true,shell:false});}catch{fail("LOCAL_EXEC_FAILED","Local process failed to start");}
+    const state={id,ownerId:ownerId==null?null:String(ownerId),command:executable.name,cwd,stdout:"",stderr:"",truncated:false,exitCode:null,errorCode:null,timedOut:false,running:true,completedAt:null,child};
+    this.processes.set(id,state);this.audit({event:"process.start",id,command:executable.name,cwd});
+    child.stdout?.on("data",x=>appendBounded(state,"stdout",x,this.maxOutputBytes));child.stderr?.on("data",x=>appendBounded(state,"stderr",x,this.maxOutputBytes));
+    child.on("error",()=>{state.running=false;state.errorCode="LOCAL_EXEC_FAILED";state.completedAt=this.now();this.audit({event:"process.error",id,code:state.errorCode});this.#cleanup();});
+    child.on("close",code=>{state.exitCode=code;state.running=false;if(!state.errorCode&&state.timedOut)state.errorCode="LOCAL_EXEC_TIMEOUT";else if(!state.errorCode&&code!==0)state.errorCode="LOCAL_EXEC_FAILED";state.completedAt=this.now();this.audit({event:"process.exit",id,code,errorCode:state.errorCode,truncated:state.truncated,timedOut:state.timedOut});this.#cleanup();});
+    const boundedTimeout=Math.max(0,Math.min(Number(timeoutMs)||0,300000));
+    if(boundedTimeout>0)setTimeout(()=>{if(!state.running)return;state.timedOut=true;state.errorCode="LOCAL_EXEC_TIMEOUT";child.kill();},boundedTimeout).unref();
+    return{id,pid:child.pid};
+  }
+
+  #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};}
+  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/remote-execution-manager.js

@@ -0,0 +1,68 @@
+import { spawn } from "node:child_process";
+import { buildDeployHelperArgs } from "./deployment-protocol.js";
+
+const ALIAS_RE=/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const DEFAULT_EXECUTABLES=new Set(["uname","systemctl","journalctl","cat","ls","sha256sum","node","npm"]);
+
+function fail(code,message){throw Object.assign(new Error(message),{code});}
+function classifySshFailure(state,code){
+ if(state.timedOut)return "REMOTE_TIMEOUT";
+ if(code!==255)return state.errorCode||null;
+ const text=state.stderr.toLowerCase();
+ if(text.includes("host key verification failed")||text.includes("remote host identification has changed"))return "REMOTE_HOST_KEY_FAILED";
+ if(text.includes("permission denied")||text.includes("authentication failed")||text.includes("no supported authentication methods available"))return "REMOTE_AUTH_FAILED";
+ return state.errorCode||"REMOTE_EXEC_FAILED";
+}
+function appendBounded(state,key,chunk,maxBytes){
+ const current=Buffer.from(state[key],"utf8"),incoming=Buffer.from(chunk);
+ const room=Math.max(0,maxBytes-current.length);
+ if(incoming.length>room)state.truncated=true;
+ if(room>0)state[key]=Buffer.concat([current,incoming.subarray(0,room)]).toString("utf8");
+}
+export class RemoteExecutionManager {
+ constructor({targets=[],allowedExecutables=DEFAULT_EXECUTABLES,audit=()=>{},spawnFn=spawn,maxOutputBytes=262144,maxRetainedJobs=100,maxRunningJobs=16,jobRetentionMs=300000,now=()=>Date.now()}={}){
+  this.targets=new Map(targets.map(x=>[x.alias,x]));this.allowedExecutables=new Set(allowedExecutables);this.audit=audit;this.spawnFn=spawnFn;this.maxOutputBytes=maxOutputBytes;
+  this.maxRetainedJobs=Math.max(1,Math.min(Number(maxRetainedJobs)||100,1000));
+  this.maxRunningJobs=Math.max(1,Math.min(Number(maxRunningJobs)||16,128));
+  this.jobRetentionMs=Math.max(1000,Math.min(Number(jobRetentionMs)||300000,86400000));
+  this.now=now;this.jobs=new Map();this.nextId=1;
+ }
+ #cleanup(){
+  const now=this.now();
+  for(const [id,state] of this.jobs){
+   if(!state.running&&state.completedAt!=null&&now-state.completedAt>=this.jobRetentionMs)this.jobs.delete(id);
+  }
+  const completed=[...this.jobs.values()].filter(x=>!x.running).sort((a,b)=>(a.completedAt||0)-(b.completedAt||0));
+  while(completed.length>this.maxRetainedJobs){
+   const oldest=completed.shift();this.jobs.delete(oldest.id);
+  }
+ }
+ listTargets(){return [...this.targets.values()].map(({alias,label=""})=>({alias,label}));}
+ #target(alias){const value=String(alias||"");if(!ALIAS_RE.test(value)||!this.targets.has(value))fail("REMOTE_TARGET_DENIED","Remote target is not registered");return this.targets.get(value);}
+ #argv(executable,args=[]){if(!this.allowedExecutables.has(executable))fail("REMOTE_COMMAND_DENIED","Remote executable denied");if(!Array.isArray(args)||args.length>64)fail("INVALID_ARGUMENT","Invalid remote arguments");for(const arg of args){if(typeof arg!=="string"||Buffer.byteLength(arg,"utf8")>4096||arg.includes("\0"))fail("INVALID_ARGUMENT","Invalid remote argument");}return [executable,...args];}
+ start({alias,executable,args=[],timeoutMs=30000,ownerId}){
+  return this.#start({alias,executable,args,timeoutMs,ownerId,allowDeployHelper:false});
+ }
+ startDeployHelper({alias,input={},timeoutMs=30000,ownerId}){
+  const args=buildDeployHelperArgs(input);
+  return this.#start({alias,executable:"whyvix-deploy",args,timeoutMs,ownerId,allowDeployHelper:true});
+ }
+ #start({alias,executable,args=[],timeoutMs=30000,ownerId,allowDeployHelper=false}){
+  if(!ownerId)fail("REMOTE_OWNER_REQUIRED","Remote job owner is required");
+  this.#cleanup();
+  let runningJobs=0;
+  for(const state of this.jobs.values())if(state.running)runningJobs++;
+  if(runningJobs>=this.maxRunningJobs)fail("REMOTE_JOB_LIMIT","Remote running job limit reached");
+  const target=this.#target(alias),remoteArgv=allowDeployHelper?["whyvix-deploy",...args]:this.#argv(executable,args),timeout=Math.max(1,Math.min(Number(timeoutMs)||30000,300000)),id=String(this.nextId++);
+  const sshArgs=["--",target.alias,...remoteArgv],child=this.spawnFn("ssh",sshArgs,{windowsHide:true,shell:false});
+  const state={id,ownerId:String(ownerId),alias:target.alias,executable,stdout:"",stderr:"",truncated:false,running:true,exitCode:null,child};this.jobs.set(id,state);this.audit({event:"remote.start",id,alias:state.alias,executable});
+  child.stdout?.on("data",x=>appendBounded(state,"stdout",x,this.maxOutputBytes));child.stderr?.on("data",x=>appendBounded(state,"stderr",x,this.maxOutputBytes));
+  const finish=()=>{if(state.timer){clearTimeout(state.timer);state.timer=null;}};
+  child.on("error",()=>{state.running=false;state.spawnFailed=true;state.errorCode="REMOTE_EXEC_FAILED";state.completedAt=this.now();finish();this.audit({event:"remote.error",id,alias:state.alias,code:state.errorCode});this.#cleanup();});
+  child.on("close",code=>{state.exitCode=code;state.running=false;state.errorCode=classifySshFailure(state,code);state.completedAt=this.now();finish();this.audit({event:"remote.exit",id,alias:state.alias,code,errorCode:state.errorCode||null,truncated:state.truncated,timedOut:Boolean(state.timedOut)});this.#cleanup();});
+  state.timer=setTimeout(()=>{if(state.running){state.timedOut=true;state.errorCode="REMOTE_TIMEOUT";this.audit({event:"remote.timeout",id,alias:state.alias});child.kill();}},timeout);state.timer.unref?.();
+  return{id,pid:child.pid,alias:state.alias};
+ }
+ output({id,ownerId}){this.#cleanup();const s=this.jobs.get(String(id));if(!s||!ownerId||s.ownerId!==String(ownerId))fail("REMOTE_JOB_NOT_FOUND","Remote job not found");return{id:s.id,alias:s.alias,stdout:s.stdout,stderr:s.stderr,running:s.running,exitCode:s.exitCode,errorCode:s.errorCode||null,truncated:s.truncated,timedOut:Boolean(s.timedOut)};}
+ stop({id,ownerId}){this.#cleanup();const s=this.jobs.get(String(id));if(!s||!ownerId||s.ownerId!==String(ownerId))fail("REMOTE_JOB_NOT_FOUND","Remote job not found");if(s.running)s.child.kill();return{id:s.id,stopping:s.running};}
+}

package/packages/agent/src/security.js

@@ -27,6 +27,22 @@ export function createSecurity({ token, workspaces = [], audit = () => {} } = {}
     const b = Buffer.from(String(candidate));
     return a.length === b.length && crypto.timingSafeEqual(a, b);
   }
+  function resolveFilesystemPath(input) {
+    if (typeof input !== "string" || !input.trim()) throw Object.assign(new Error("path is required"), { code:"INVALID_ARGUMENT" });
+    const requested = path.resolve(input);
+    const target = canonicalExisting(requested);
+    if (target) return target;
+    let ancestor = path.dirname(requested);
+    while (ancestor !== path.dirname(ancestor)) {
+      const canonicalAncestor = canonicalExisting(ancestor);
+      if (canonicalAncestor) return path.resolve(canonicalAncestor, path.relative(ancestor, requested));
+      ancestor = path.dirname(ancestor);
+    }
+    const root = path.parse(requested).root;
+    const canonicalRoot = canonicalExisting(root);
+    if (canonicalRoot) return path.resolve(canonicalRoot, path.relative(root, requested));
+    throw denied();
+  }
   function resolveAllowed(input) {
     if (typeof input !== "string" || !input.trim()) throw Object.assign(new Error("path is required"), { code:"INVALID_ARGUMENT" });
     const requested = path.resolve(input);
@@ -48,5 +64,5 @@ export function createSecurity({ token, workspaces = [], audit = () => {} } = {}
     }
     throw denied();
   }
-  return { authenticate, resolveAllowed, audit, roots };
+  return { authenticate, resolveAllowed, resolveFilesystemPath, audit, roots };
 }

package/packages/agent/src/tools.js

@@ -1,18 +1,52 @@
 import fs from "node:fs/promises";
 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 }) {
+export function createToolExecutor({ security, processManager, remoteExecutionManager }) {
   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==="fs.list"){const target=security.resolveAllowed(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.resolveAllowed(args.path);const max=Math.min(Number(args.maxBytes||65536),262144);const h=await fs.open(target,"r");try{const stat=await h.stat();const b=Buffer.alloc(max);const {bytesRead}=await h.read(b,0,max,0);return{path:target,content:b.subarray(0,bytesRead).toString("utf8"),truncated:stat.size>bytesRead,size:stat.size};}finally{await h.close();}}
-    if(tool==="fs.search"){const root=security.resolveAllowed(args.path);const q=String(args.query||"").toLowerCase();if(!q)throw Object.assign(new Error("query is required"),{code:"INVALID_ARGUMENT"});const entries=await fs.readdir(root,{withFileTypes:true});return{path:root,query:args.query,matches:entries.filter(e=>e.name.toLowerCase().includes(q)).slice(0,Math.min(Number(args.maxResults||50),200)).map(e=>({name:e.name,path:path.join(root,e.name),type:e.isDirectory()?"directory":"file"}))};}
+    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"){
+      const root=security.resolveFilesystemPath(args.path);const q=String(args.query||"");if(!q)throw Object.assign(new Error("query is required"),{code:"INVALID_ARGUMENT"});
+      const mode=args.mode==="content"?"content":"name",maxResults=Math.min(Math.max(Number(args.maxResults||50),1),200),maxDepth=Math.min(Math.max(Number(args.maxDepth??8),0),20),maxFileBytes=Math.min(Math.max(Number(args.maxFileBytes||262144),1),1048576),matches=[];
+      const needle=q.toLowerCase();
+      async function walk(dir,depth){
+        if(matches.length>=maxResults||depth>maxDepth)return;
+        const entries=await fs.readdir(dir,{withFileTypes:true});
+        for(const entry of entries){
+          if(matches.length>=maxResults)break;
+          const candidate=path.join(dir,entry.name);let target;try{target=security.resolveFilesystemPath(candidate);}catch{continue;}
+          if(entry.isDirectory()){if(mode==="name"&&entry.name.toLowerCase().includes(needle))matches.push({name:entry.name,path:target,type:"directory"});await walk(target,depth+1);continue;}
+          if(!entry.isFile())continue;
+          if(mode==="name"){if(entry.name.toLowerCase().includes(needle))matches.push({name:entry.name,path:target,type:"file"});continue;}
+          const stat=await fs.stat(target);if(stat.size>maxFileBytes)continue;
+          const raw=await fs.readFile(target);if(raw.includes(0))continue;const content=raw.toString("utf8");const lines=content.split(/\r?\n/);
+          for(let i=0;i<lines.length&&matches.length<maxResults;i++){if(lines[i].toLowerCase().includes(needle))matches.push({name:entry.name,path:target,type:"file",line:i+1,preview:lines[i].slice(0,500)});}
+        }
+      }
+      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.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};}
+    if(tool==="fs.delete_empty_directory"){const requested=path.resolve(String(args.path||""));const target=security.resolveFilesystemPath(requested);security.resolveFilesystemPath(path.dirname(requested));const linkStat=await fs.lstat(requested);if(linkStat.isSymbolicLink())throw Object.assign(new Error("Symbolic links cannot be deleted through delete_empty_directory"),{code:"INVALID_TARGET"});if(!linkStat.isDirectory())throw Object.assign(new Error("Target must be a directory"),{code:"INVALID_TARGET"});const entries=await fs.readdir(requested);if(entries.length)throw Object.assign(new Error("Directory must be empty"),{code:"DIRECTORY_NOT_EMPTY"});await fs.rmdir(requested);return{path:target,deleted:true};}
+    if(tool==="fs.write_text"){
+      const target=security.resolveFilesystemPath(args.path),content=String(args.content??""),expectedSha256=String(args.expectedSha256||"").toLowerCase();
+      const bytes=Buffer.byteLength(content,"utf8");if(bytes>262144)throw Object.assign(new Error("content exceeds 262144 UTF-8 bytes"),{code:"CONTENT_TOO_LARGE"});
+      if(!/^[a-f0-9]{64}$/.test(expectedSha256))throw Object.assign(new Error("expectedSha256 is required"),{code:"INVALID_ARGUMENT"});
+      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>262144)throw Object.assign(new Error("Target exceeds 262144 bytes"),{code:"CONTENT_TOO_LARGE"});
+      const current=await fs.readFile(target);const actualSha256=crypto.createHash("sha256").update(current).digest("hex");if(actualSha256!==expectedSha256)throw Object.assign(new Error("File changed since it was read"),{code:"FILE_CHANGED"});
+      const beforeWrite=await fs.readFile(target);const beforeWriteSha256=crypto.createHash("sha256").update(beforeWrite).digest("hex");if(beforeWriteSha256!==expectedSha256)throw Object.assign(new Error("File changed before write"),{code:"FILE_CHANGED"});
+      await fs.writeFile(target,content,{encoding:"utf8",flag:"w"});return{path:target,bytes,sha256:crypto.createHash("sha256").update(content,"utf8").digest("hex")};
+    }
     if(tool==="fs.create_text"){
-      const target=security.resolveAllowed(args.path);
+      const target=security.resolveFilesystemPath(args.path);
       const content=String(args.content??"");
       const bytes=Buffer.byteLength(content,"utf8");
       if(bytes>262144)throw Object.assign(new Error("content exceeds 262144 UTF-8 bytes"),{code:"CONTENT_TOO_LARGE"});
@@ -20,10 +54,59 @@ export function createToolExecutor({ security, processManager }) {
       catch(error){if(error?.code==="EEXIST")throw Object.assign(new Error("Target already exists"),{code:"FILE_EXISTS"});throw error;}
       return{path:target,bytes};
     }
+    if(tool==="fs.replace_text"){
+      const target=security.resolveFilesystemPath(args.path);
+      const expected=String(args.expected??"");
+      const replacement=String(args.replacement??"");
+      if(!expected)throw Object.assign(new Error("expected text is required"),{code:"INVALID_ARGUMENT"});
+      if(Buffer.byteLength(expected,"utf8")>262144||Buffer.byteLength(replacement,"utf8")>262144)throw Object.assign(new Error("text exceeds 262144 UTF-8 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>262144)throw Object.assign(new Error("Target exceeds 262144 UTF-8 bytes"),{code:"CONTENT_TOO_LARGE"});
+      const content=await fs.readFile(target,"utf8");
+      const first=content.indexOf(expected);if(first<0)throw Object.assign(new Error("Expected text was not found"),{code:"TEXT_NOT_FOUND"});
+      if(content.indexOf(expected,first+expected.length)>=0)throw Object.assign(new Error("Expected text is not unique"),{code:"TEXT_NOT_UNIQUE"});
+      const updated=content.slice(0,first)+replacement+content.slice(first+expected.length);
+      const bytes=Buffer.byteLength(updated,"utf8");if(bytes>262144)throw Object.assign(new Error("Updated content exceeds 262144 UTF-8 bytes"),{code:"CONTENT_TOO_LARGE"});
+      await fs.writeFile(target,updated,{encoding:"utf8",flag:"w"});
+      return{path:target,bytes,replacements:1};
+    }
+    if(tool==="remote.targets"){if(!remoteExecutionManager)throw Object.assign(new Error("Remote execution is not configured"),{code:"REMOTE_TARGET_DENIED"});return{targets:remoteExecutionManager.listTargets()};}
+    if(tool==="remote.start"){if(!remoteExecutionManager)throw Object.assign(new Error("Remote execution is not configured"),{code:"REMOTE_TARGET_DENIED"});return remoteExecutionManager.start(args);}
+    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.start"){const cwd=security.resolveAllowed(args.cwd);return processManager.start({...args,cwd});}
     if(tool==="process.output")return processManager.output(args);
     if(tool==="process.stop")return processManager.stop(args);
     if(tool==="git.status"||tool==="git.diff"||tool==="git.log"){const cwd=security.resolveAllowed(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"){
+      const cwd=security.resolveAllowed(args.cwd);
+      const {stdout:rootRaw}=await execFileAsync("git",["rev-parse","--show-toplevel"],{cwd,windowsHide:true,maxBuffer:1024*1024});
+      const repoRoot=security.resolveAllowed(rootRaw.trim());
+      if(tool==="git.stage_paths"){
+        const {stdout:alreadyStaged}=await execFileAsync("git",["diff","--cached","--name-only"],{cwd:repoRoot,windowsHide:true,maxBuffer:1024*1024});
+        if(alreadyStaged.trim())throw Object.assign(new Error("Repository already has staged changes"),{code:"INDEX_NOT_EMPTY"});
+        const paths=Array.isArray(args.paths)?args.paths.map(String):[];
+        if(paths.length<1||paths.length>64)throw Object.assign(new Error("paths must contain 1 to 64 explicit paths"),{code:"INVALID_ARGUMENT"});
+        const relativePaths=paths.map((item)=>{
+          if(!item||item==="."||item==="*"||item.startsWith("-"))throw Object.assign(new Error("Only explicit repository paths may be staged"),{code:"INVALID_ARGUMENT"});
+          const absolute=security.resolveAllowed(path.resolve(repoRoot,item));
+          const relative=path.relative(repoRoot,absolute);
+          if(!relative||relative.startsWith(".."+path.sep)||path.isAbsolute(relative))throw Object.assign(new Error("Path outside repository"),{code:"PATH_DENIED"});
+          return relative.split(path.sep).join("/");
+        });
+        await execFileAsync("git",["add","--",...relativePaths],{cwd:repoRoot,windowsHide:true,maxBuffer:1024*1024});
+        const {stdout}=await execFileAsync("git",["diff","--cached","--name-only","--",...relativePaths],{cwd:repoRoot,windowsHide:true,maxBuffer:1024*1024});
+        return{staged:stdout.split(/\r?\n/).filter(Boolean)};
+      }
+      const message=String(args.message||"");
+      if(!message.trim()||message.length>500||/[\r\n]/.test(message))throw Object.assign(new Error("Commit message must be 1 to 500 characters on one line"),{code:"INVALID_ARGUMENT"});
+      const {stdout:before}=await execFileAsync("git",["diff","--cached","--name-only"],{cwd:repoRoot,windowsHide:true,maxBuffer:1024*1024});
+      const committedFiles=before.split(/\r?\n/).filter(Boolean);
+      if(!committedFiles.length)throw Object.assign(new Error("No staged changes to commit"),{code:"NOTHING_STAGED"});
+      await execFileAsync("git",["commit","-m",message],{cwd:repoRoot,windowsHide:true,maxBuffer:1024*1024});
+      const {stdout:sha}=await execFileAsync("git",["rev-parse","HEAD"],{cwd:repoRoot,windowsHide:true,maxBuffer:1024*1024});
+      return{sha:sha.trim(),committedFiles};
+    }
     throw Object.assign(new Error("Unsupported tool"),{code:"TOOL_NOT_FOUND"});
   };
 }

package/packages/cli/browser.js

@@ -0,0 +1,21 @@
+import { spawn } from "node:child_process";
+
+export function validateVerificationUri(value,expectedAuthUrl){
+  const uri=new URL(value);
+  const authority=new URL(expectedAuthUrl);
+  if(uri.protocol!=="https:"||uri.origin!==authority.origin||uri.pathname!=="/device/pair")throw new Error("Invalid device authorization URL");
+  return uri.href;
+}
+
+export async function openBrowser(url,expectedAuthUrl,{platform=process.platform,spawnProcess=spawn}={}){
+  const uri=validateVerificationUri(url,expectedAuthUrl);
+  const command=platform==="win32"?"rundll32.exe":platform==="darwin"?"open":"xdg-open";
+  const args=platform==="win32"?["url.dll,FileProtocolHandler",uri]:[uri];
+  try{
+    const child=spawnProcess(command,args,{detached:true,stdio:"ignore",windowsHide:true});
+    return await new Promise(resolve=>{
+      child.once("spawn",()=>{child.unref();resolve(true);});
+      child.once("error",()=>resolve(false));
+    });
+  }catch{return false;}
+}

package/packages/cli/index.js

@@ -1,80 +1,84 @@
-#!/usr/bin/env node
-import os from "node:os";
-import crypto from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import { createAgent } from "../agent/src/agent.js";
-
-const command=process.argv[2]||"remote";
-if(command!=="remote"){console.error("Usage: whyvix-remote remote");process.exit(2);}
-const gatewayUrl=process.env.WHYVIX_GATEWAY_URL||"wss://remote.whyvix.com";
-const authUrl=(process.env.WHYVIX_AUTH_URL||"https://auth.whyvix.com").replace(/\/$/,"");
-const workspaces=(process.env.WHYVIX_WORKSPACES||process.cwd()).split(";").filter(Boolean);
-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");
-const credentialPath=join(credentialDir,"device.json");
-
-async function loadCredential(){
-  if(process.env.WHYVIX_DEVICE_CREDENTIAL)return process.env.WHYVIX_DEVICE_CREDENTIAL;
-  try{const saved=JSON.parse(await readFile(credentialPath,"utf8"));return saved.deviceId===deviceId?saved.credential:"";}catch{return "";}
-}
-async function saveCredential(credential){
-  await mkdir(credentialDir,{recursive:true,mode:0o700});
-  await writeFile(credentialPath,JSON.stringify({deviceId,credential}),{encoding:"utf8",mode:0o600});
-}
-async function post(path,fields){
-  const response=await fetch(authUrl+path,{method:"POST",headers:{"content-type":"application/x-www-form-urlencoded"},body:new URLSearchParams(fields),redirect:"error"});
-  return{status:response.status,body:await response.json()};
-}
-async function pair(){
-  const started=await post("/device/pair/start",{device_id:deviceId,device_name:os.hostname()});
-  if(started.status!==201)throw new Error("Unable to start device pairing");
-  console.log("Open this URL to authorize the device:");
-  console.log(started.body.verification_uri);
-  while(Date.now()<started.body.expires_at){
-    await new Promise(r=>setTimeout(r,2000));
-    const result=await post("/device/pair/status",{pairing_id:started.body.pairing_id,pairing_secret:started.body.pairing_secret});
-    if(result.status===200&&result.body.status==="approved"){await saveCredential(result.body.device_credential);return result.body.device_credential;}
-  }
-  throw new Error("Device pairing expired");
-}
-let credential=await loadCredential();
-if(!credential){
-  console.log("WHYVIX Remote device authorization required.");
-  credential=await pair();
-  console.log("Device authorized.");
-}
-console.log("WHYVIX Remote");
-console.log("");
-const agent=createAgent({
-  gatewayUrl,
-  deviceId,
-  deviceName:os.hostname(),
-  token:credential,
-  workspaces,
-  audit:()=>{},
-  log:(event,tool)=>{
-    if(event==="[tool:request]") console.log("←",tool);
-    else if(event==="[tool:success]") console.log("✓",tool);
-  },
-  errorLog:(event,tool,code,message)=>{
-    if(event==="[tool:rejected]") console.error("✗",tool,"·",code,"·",message);
-  },
-  onRegistered:({authorizedAccount})=>{
-    console.log("Device     :",os.hostname());
-    console.log("Status     : Connected");
-    console.log("Authorized :",authorizedAccount||"-");
-    console.log("");
-    console.log("Keep this terminal open while using WHYVIX Remote.");
-    console.log("Press Ctrl+C to disconnect.");
-  }
-});
-let shuttingDown=false;
-async function shutdown(){
-  if(shuttingDown)return;
-  shuttingDown=true;
-  await agent.stop();
-  process.exit(0);
-}
-process.once("SIGINT",shutdown);
-process.once("SIGTERM",shutdown);
+#!/usr/bin/env node
+import os from "node:os";
+import crypto from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createAgent } from "../agent/src/agent.js";
+import { openBrowser } from "./browser.js";
+
+const command=process.argv[2]||"remote";
+if(command!=="remote"){console.error("Usage: whyvix-remote remote");process.exit(2);}
+const gatewayUrl=process.env.WHYVIX_GATEWAY_URL||"wss://remote.whyvix.com";
+const authUrl=(process.env.WHYVIX_AUTH_URL||"https://auth.whyvix.com").replace(/\/$/,"");
+const workspaces=(process.env.WHYVIX_WORKSPACES||process.cwd()).split(";").filter(Boolean);
+const remoteTargets=(process.env.WHYVIX_REMOTE_TARGETS||"").split(";").map(alias=>alias.trim()).filter(Boolean).map(alias=>({alias}));
+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");
+const credentialPath=join(credentialDir,"device.json");
+
+async function loadCredential(){
+  if(process.env.WHYVIX_DEVICE_CREDENTIAL)return process.env.WHYVIX_DEVICE_CREDENTIAL;
+  try{const saved=JSON.parse(await readFile(credentialPath,"utf8"));return saved.deviceId===deviceId?saved.credential:"";}catch{return "";}
+}
+async function saveCredential(credential){
+  await mkdir(credentialDir,{recursive:true,mode:0o700});
+  await writeFile(credentialPath,JSON.stringify({deviceId,credential}),{encoding:"utf8",mode:0o600});
+}
+async function post(path,fields){
+  const response=await fetch(authUrl+path,{method:"POST",headers:{"content-type":"application/x-www-form-urlencoded"},body:new URLSearchParams(fields),redirect:"error"});
+  return{status:response.status,body:await response.json()};
+}
+async function pair(){
+  const started=await post("/device/pair/start",{device_id:deviceId,device_name:os.hostname()});
+  if(started.status!==201)throw new Error("Unable to start device pairing");
+  const opened=await openBrowser(started.body.verification_uri,authUrl);
+  console.log(opened?"Authorization opened in your browser.":"Open this URL to authorize the device:");
+  console.log(started.body.verification_uri);
+  while(Date.now()<started.body.expires_at){
+    await new Promise(r=>setTimeout(r,2000));
+    const result=await post("/device/pair/status",{pairing_id:started.body.pairing_id,pairing_secret:started.body.pairing_secret});
+    if(result.status===200&&result.body.status==="approved"){await saveCredential(result.body.device_credential);return result.body.device_credential;}
+  }
+  throw new Error("Device pairing expired");
+}
+let credential=await loadCredential();
+if(!credential){
+  console.log("WHYVIX Remote device authorization required.");
+  credential=await pair();
+  console.log("Device authorized.");
+}
+console.log("WHYVIX Remote");
+console.log("");
+const agent=createAgent({
+  gatewayUrl,
+  deviceId,
+  deviceName:os.hostname(),
+  token:credential,
+  workspaces,
+  remoteTargets,
+  audit:()=>{},
+  log:(event,tool)=>{
+    if(event==="[tool:request]") console.log("←",tool);
+    else if(event==="[tool:success]") console.log("✓",tool);
+  },
+  errorLog:(event,tool,code,message)=>{
+    if(event==="[tool:rejected]") console.error("✗",tool,"·",code,"·",message);
+  },
+  onRegistered:({authorizedAccount})=>{
+    console.log("Device     :",os.hostname());
+    console.log("Status     : Connected");
+    console.log("Authorized :",authorizedAccount||"-");
+    console.log("");
+    console.log("Keep this terminal open while using WHYVIX Remote.");
+    console.log("Press Ctrl+C to disconnect.");
+  }
+});
+let shuttingDown=false;
+async function shutdown(){
+  if(shuttingDown)return;
+  shuttingDown=true;
+  await agent.stop();
+  process.exit(0);
+}
+process.once("SIGINT",shutdown);
+process.once("SIGTERM",shutdown);