grix-connector 3.1.13 → 3.1.15

package/dist/service/platform-adapter.js

@@ -1,12 +1,12 @@
-import{existsSync as R,readFileSync as j}from"node:fs";import{mkdir as P,readdir as C,readFile as f,rm as w,stat as V,writeFile as h}from"node:fs/promises";import p from"node:os";import u from"node:path";import{isProcessRunning as v,runCommand as d,spawnDetached as W,isWindowsElevated as G,killProcessesByCommandLine as T}from"./process-control.js";import{getServicePrefix as A,parseConfigDirFromPlistXML as Q,parseConfigDirFromSystemdUnit as z,resolveBareDaemonMarkerPath as g,resolveLinuxUserUnitPath as H,resolveMacOSLaunchAgentPath as J}from"./service-paths.js";function y(t){return String(t??"").replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;")}function F(t){return`'${String(t??"").replace(/'/g,"'\\''")}'`}function M(t){return[t.nodePath,t.cliPath,...t.configDir?["--config-dir",t.configDir]:[]]}function X(t){const r=M(t);return`<?xml version="1.0" encoding="UTF-8"?>
+import{existsSync as E,readFileSync as O}from"node:fs";import{mkdir as P,readdir as v,readFile as g,rm as h,stat as U,writeFile as w}from"node:fs/promises";import l from"node:os";import u from"node:path";import{isProcessRunning as C,runCommand as d,spawnDetached as F,isWindowsElevated as H,killProcessesByCommandLine as _}from"./process-control.js";import{getServicePrefix as A,parseConfigDirFromPlistXML as G,parseConfigDirFromSystemdUnit as V,resolveBareDaemonMarkerPath as y,resolveLinuxUserUnitPath as X,resolveMacOSLaunchAgentPath as Q}from"./service-paths.js";function p(t){return String(t??"").replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;")}function T(t){return`'${String(t??"").replace(/'/g,"'\\''")}'`}function j(t){return[t.nodePath,t.cliPath,...t.configDir?["--config-dir",t.configDir]:[]]}function z(t){const e=j(t);return`<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
   <key>Label</key>
-  <string>${y(t.serviceID)}</string>
+  <string>${p(t.serviceID)}</string>
   <key>ProgramArguments</key>
   <array>
-${r.map(e=>`    <string>${y(e)}</string>`).join(`
+${e.map(r=>`    <string>${p(r)}</string>`).join(`
 `)}
   </array>
   <key>RunAtLoad</key>
@@ -14,25 +14,25 @@ ${r.map(e=>`    <string>${y(e)}</string>`).join(`
   <key>KeepAlive</key>
   <true/>
   <key>WorkingDirectory</key>
-  <string>${y(u.dirname(t.cliPath))}</string>
+  <string>${p(u.dirname(t.cliPath))}</string>
 ${t.environmentPath?`  <key>EnvironmentVariables</key>
   <dict>
     <key>PATH</key>
-    <string>${y(t.environmentPath)}</string>
+    <string>${p(t.environmentPath)}</string>
   </dict>
 `:""}  <key>StandardOutPath</key>
-  <string>${y(t.stdoutPath)}</string>
+  <string>${p(t.stdoutPath)}</string>
   <key>StandardErrorPath</key>
-  <string>${y(t.stderrPath)}</string>
+  <string>${p(t.stderrPath)}</string>
 </dict>
 </plist>
-`}function Z(t){const r=M(t).map(e=>F(e)).join(" ");return`[Unit]
+`}function J(t){const e=j(t).map(r=>T(r)).join(" ");return`[Unit]
 Description=grix-connector daemon (${t.serviceID})
 After=network.target
 
 [Service]
 Type=simple
-ExecStart=${r}
+ExecStart=${e}
 WorkingDirectory=${u.dirname(t.cliPath)}
 Restart=always
 RestartSec=2
@@ -41,13 +41,56 @@ StandardError=append:${t.stderrPath}
 
 [Install]
 WantedBy=default.target
-`}function k(t,r){const e=t.replace(/[^a-zA-Z0-9._-]/g,"_");return u.join(r,".grix",`${e}-wrapper.vbs`)}function B(t,r){const e=t.replace(/[^a-zA-Z0-9._-]/g,"_"),n=u.join(r,"AppData","Roaming","Microsoft","Windows","Start Menu","Programs","Startup");return u.join(n,`${e}.lnk`)}function $(t){return String(t??"").replace(/"/g,'""')}function q(t,r){const e=u.join(u.dirname(t),u.basename(r).replace(/\.lnk$/,"-create.vbs")),n=["Option Explicit","Dim shell, shortcut",'Set shell = CreateObject("WScript.Shell")',`Set shortcut = shell.CreateShortcut("${$(r)}")`,'shortcut.TargetPath = "wscript.exe"',`shortcut.Arguments = "//B //NoLogo \\"${$(t)}\\""`,"shortcut.WindowStyle = 7","shortcut.Save",""].join(`\r
-`);return{path:e,content:n}}function K(t){const r=[`"${$(t.nodePath)}"`,`"${$(t.cliPath)}"`,...t.configDir?["--config-dir",`"${$(t.configDir)}"`]:[]].join(" ");return["Option Explicit","Dim shell, command, delayMs, rapidCount",`command = "${$(r)}"`,'Set shell = CreateObject("WScript.Shell")',"delayMs = 5000","rapidCount = 0","Do","  shell.Run command, 0, True","  rapidCount = rapidCount + 1","  If rapidCount >= 10 Then","    WScript.Sleep 300000","    rapidCount = 0","  Else","    WScript.Sleep delayMs","  End If","Loop",""].join(`\r
-`)}function b(t){return`gui/${t??0}`}function E(t){const r=String(t?.stdout??"").trim();return String(t?.stderr??"").trim()||r||`exit=${Number(t?.exitCode??-1)}`}function L(t,r){if(Number(t?.exitCode??0)!==0)throw new Error(`${r}: ${E(t)}`)}function Y(){return{platform:"darwin",kind:"launchd",async install({serviceID:t,nodePath:r,cliPath:e,configDir:n,stdoutPath:a,stderrPath:i,environmentPath:s="",homeDir:o=p.homedir()}){const c=J(t,o);return await P(u.dirname(c),{recursive:!0}),await h(c,X({serviceID:t,nodePath:r,cliPath:e,configDir:n,stdoutPath:a,stderrPath:i,environmentPath:s}),{encoding:"utf8",mode:384}),{definitionPath:c}},async start({serviceID:t,definitionPath:r,runCommand:e=d,uid:n=process.getuid?.()??0}){const a=b(n);let i=await e("launchctl",["bootstrap",a,r],{allowFailure:!0});Number(i?.exitCode??0)!==0&&(await e("launchctl",["bootout",`${a}/${t}`],{allowFailure:!0}),i=await e("launchctl",["bootstrap",a,r],{allowFailure:!0}),L(i,`launchctl bootstrap ${a}`));const s=await e("launchctl",["kickstart","-k",`${a}/${t}`],{allowFailure:!0});if(Number(s?.exitCode??0)!==0){const o=Number(i?.exitCode??0)===0?"":`, bootstrap=${E(i)}`;throw new Error(`launchctl start failed for ${a}/${t}: ${E(s)}${o}`)}},async stop({serviceID:t,runCommand:r=d,uid:e=process.getuid?.()??0}){const n=b(e);await r("launchctl",["bootout",`${n}/${t}`],{allowFailure:!0})},async restart({serviceID:t,definitionPath:r,runCommand:e=d,uid:n=process.getuid?.()??0}){const a=b(n);await e("launchctl",["bootout",`${a}/${t}`],{allowFailure:!0});for(let o=0;o<20&&(await e("launchctl",["print",`${a}/${t}`],{allowFailure:!0})).exitCode===0;o+=1)await new Promise(l=>setTimeout(l,250));try{await V(r)}catch{throw new Error(`launchd plist missing: ${r}`)}const i=await e("launchctl",["bootstrap",a,r],{allowFailure:!0});L(i,`launchctl bootstrap ${a}`);const s=await e("launchctl",["kickstart","-k",`${a}/${t}`],{allowFailure:!0});L(s,`launchctl kickstart ${a}/${t}`)},async uninstall({serviceID:t,definitionPath:r,runCommand:e=d,uid:n=process.getuid?.()??0}){const a=b(n);await e("launchctl",["bootout",`${a}/${t}`],{allowFailure:!0}),await w(r,{force:!0})},async discoverServices({homeDir:t=p.homedir()}={}){const r=u.join(t,"Library","LaunchAgents"),e=await C(r).catch(()=>[]),n=A("darwin"),a=[];for(const i of e){if(!i.startsWith(n)||!i.endsWith(".plist"))continue;const s=i.slice(0,-6),o=u.join(r,i);let c=null;try{const l=await f(o,"utf8");c=Q(l)}catch{}a.push({serviceID:s,definitionPath:o,configDir:c})}return a},async isServiceLoaded({serviceID:t,runCommand:r=d,uid:e=process.getuid?.()??0}){const n=b(e),a=await r("launchctl",["print",`${n}/${t}`],{allowFailure:!0});return Number(a?.exitCode??1)===0}}}function I(){return{platform:"win32",kind:"task-scheduler",async install({serviceID:t,nodePath:r,cliPath:e,configDir:n,runCommand:a=d,homeDir:i=p.homedir()}){const s=k(t,i);await P(u.dirname(s),{recursive:!0}),await h(s,K({nodePath:r,cliPath:e,configDir:n}),"utf8");let o=!1;if(G())try{await a("schtasks",["/Create","/TN",t,"/SC","ONCE","/ST","00:00","/SD","2099/12/31","/RL","LIMITED","/F","/TR",`wscript.exe //B //NoLogo "${s}"`]),o=!0}catch{}const c=B(t,i),l=q(s,c);return await h(l.path,l.content,"utf8"),await a("wscript.exe",[l.path,"//B","//NoLogo"]).catch(()=>{}),await w(l.path,{force:!0}),{definitionPath:o?`task:${t}`:`startup:${t}`}},async start({serviceID:t,definitionPath:r,runCommand:e=d,homeDir:n=p.homedir()}){const a=k(t,n);if(r.startsWith("task:"))try{await e("schtasks",["/Run","/TN",t]);return}catch{}W("wscript.exe",["//B","//NoLogo",a])},async stop({serviceID:t,runCommand:r=d,homeDir:e=p.homedir()}){await r("schtasks",["/End","/TN",t],{allowFailure:!0});const n=`${t}-wrapper.vbs`;await T(n,{platform:"win32"})},async restart({serviceID:t,definitionPath:r,runCommand:e=d,homeDir:n=p.homedir()}){await e("schtasks",["/End","/TN",t],{allowFailure:!0});const a=`${t}-wrapper.vbs`;await T(a,{platform:"win32"});const i=k(t,n);if(r?.startsWith("task:"))try{await e("schtasks",["/Run","/TN",t]);return}catch{}W("wscript.exe",["//B","//NoLogo",i])},async uninstall({serviceID:t,runCommand:r=d,homeDir:e=p.homedir()}){await r("schtasks",["/Delete","/TN",t,"/F"],{allowFailure:!0});const n=k(t,e);await w(n,{force:!0});const a=B(t,e);await w(a,{force:!0})},async discoverServices({homeDir:t=p.homedir(),runCommand:r=d}={}){const e=A("win32"),n=await r("schtasks",["/Query","/FO","CSV","/NH"],{allowFailure:!0}),a=[];if(Number(n?.exitCode??-1)===0){const o=String(n.stdout??"").split(/\r?\n/);for(const c of o){const l=c.match(/^"([^"]+)"/);if(!l)continue;const m=l[1];if(!m.startsWith(e))continue;let _=null;try{const x=k(m,t),D=(await f(x,"utf8")).match(/--config-dir\s+""([^""]+)""/);D&&(_=D[1])}catch{}a.push({serviceID:m,definitionPath:`task:${m}`,configDir:_})}}const i=u.join(t,"AppData","Roaming","Microsoft","Windows","Start Menu","Programs","Startup"),s=await C(i).catch(()=>[]);for(const o of s){if(!o.startsWith(e)||!o.endsWith(".lnk"))continue;const c=o.slice(0,-4);if(a.some(m=>m.serviceID===c))continue;let l=null;try{const m=k(c,t),x=(await f(m,"utf8")).match(/--config-dir\s+""([^""]+)""/);x&&(l=x[1])}catch{}a.push({serviceID:c,definitionPath:`startup:${c}`,configDir:l})}return a},async isServiceLoaded({serviceID:t,runCommand:r=d}){const e=await r("schtasks",["/Query","/TN",t,"/NH"],{allowFailure:!0});return Number(e?.exitCode??1)===0}}}function tt(){return{platform:"linux",kind:"systemd-user",async install({serviceID:t,nodePath:r,cliPath:e,configDir:n,stdoutPath:a,stderrPath:i,homeDir:s=p.homedir(),runCommand:o=d}){const c=H(t,s);return await P(u.dirname(c),{recursive:!0}),await h(c,Z({serviceID:t,nodePath:r,cliPath:e,configDir:n,stdoutPath:a,stderrPath:i}),{encoding:"utf8",mode:384}),await o("systemctl",["--user","daemon-reload"]),await o("systemctl",["--user","enable",`${t}.service`]),{definitionPath:c}},async start({serviceID:t,runCommand:r=d}){await r("systemctl",["--user","start",`${t}.service`])},async stop({serviceID:t,runCommand:r=d}){await r("systemctl",["--user","stop",`${t}.service`],{allowFailure:!0})},async restart({serviceID:t,runCommand:r=d}){await r("systemctl",["--user","restart",`${t}.service`])},async uninstall({serviceID:t,definitionPath:r,runCommand:e=d}){await e("systemctl",["--user","stop",`${t}.service`],{allowFailure:!0}),await e("systemctl",["--user","disable",`${t}.service`],{allowFailure:!0}),await w(r,{force:!0}),await e("systemctl",["--user","daemon-reload"])},async discoverServices({homeDir:t=p.homedir()}={}){const r=u.join(t,".config","systemd","user"),e=await C(r).catch(()=>[]),n=A("linux"),a=[];for(const i of e){if(!i.startsWith(n)||!i.endsWith(".service"))continue;const s=i.slice(0,-8),o=u.join(r,i);let c=null;try{const l=await f(o,"utf8");c=z(l)}catch{}a.push({serviceID:s,definitionPath:o,configDir:c})}return a},async isServiceLoaded({serviceID:t,runCommand:r=d}){const e=await r("systemctl",["--user","is-active",`${t}.service`],{allowFailure:!0});return String(e?.stdout??"").trim()==="active"}}}function S(t){try{const r=j(t,"utf8"),e=JSON.parse(r);if(e&&typeof e.service_id=="string"&&typeof e.node_path=="string"&&typeof e.cli_path=="string"&&typeof e.root_dir=="string")return e}catch{}return null}function rt(t){return u.join(t,"daemon.lock.json")}function N(t){const r=rt(t);try{const e=j(r,"utf8"),n=JSON.parse(e);if(typeof n?.pid=="number")return n.pid}catch{}return 0}function O(t){return u.join(t,".profile")}function et(t){return t.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}function nt(t){const r=[F(t.nodePath),F(t.cliPath)];t.configDir&&r.push("--config-dir",F(t.configDir));const e=r.join(" ");return`${e} status >/dev/null 2>&1 || (nohup ${e} start >/dev/null 2>&1 &)`}function at(t,r){return`# >>> grix-connector autostart [${t}] >>>
-${r}
+`}function k(t,e){const r=t.replace(/[^a-zA-Z0-9._-]/g,"_");return u.join(e,".grix",`${r}-wrapper.vbs`)}function I(t,e){const r=t.replace(/[^a-zA-Z0-9._-]/g,"_"),n=u.join(e,"AppData","Roaming","Microsoft","Windows","Start Menu","Programs","Startup");return u.join(n,`${r}.lnk`)}function S(t){return String(t??"").replace(/"/g,'""')}function Z(t,e){const r=u.join(u.dirname(t),u.basename(e).replace(/\.lnk$/,"-create.vbs")),n=["Option Explicit","Dim shell, shortcut",'Set shell = CreateObject("WScript.Shell")',`Set shortcut = shell.CreateShortcut("${S(e)}")`,'shortcut.TargetPath = "wscript.exe"',`shortcut.Arguments = "//B //NoLogo \\"${S(t)}\\""`,"shortcut.WindowStyle = 7","shortcut.Save",""].join(`\r
+`);return{path:r,content:n}}async function q(t){const{wrapperPath:e,shortcutPath:r,runCommand:n}=t,a=Z(e,r);for(let i=1;i<=3;i+=1){try{await w(a.path,a.content,"utf8"),await n("wscript.exe",[a.path,"//B","//NoLogo"])}catch{}finally{await h(a.path,{force:!0}).catch(()=>{})}if(E(r))return!0}return console.warn(`Warning: failed to create Windows logon-autostart shortcut at ${r}. The daemon will NOT start automatically after the next reboot/logon. Check Controlled Folder Access / antivirus blocking writes to the Startup folder, or create the shortcut manually.`),!1}async function K(t){try{const e=await t("whoami",["/user","/fo","csv","/nh"],{allowFailure:!0}),r=String(e?.stdout??"").match(/"(S-1-[0-9-]+)"/);if(r)return r[1]}catch{}return null}function Y(t){const e=`//B //NoLogo "${t.wrapperPath}"`;return`<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>grix-connector daemon autostart</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+      <UserId>${p(t.userId)}</UserId>
+    </LogonTrigger>
+  </Triggers>
+  <Principals>
+    <Principal id="Author">
+      <UserId>${p(t.userId)}</UserId>
+      <LogonType>InteractiveToken</LogonType>
+      <RunLevel>LeastPrivilege</RunLevel>
+    </Principal>
+  </Principals>
+  <Settings>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <AllowHardTerminate>true</AllowHardTerminate>
+    <StartWhenAvailable>true</StartWhenAvailable>
+    <RunOnlyIfNetworkAvailable>false</RunOnlyIfNetworkAvailable>
+    <IdleSettings>
+      <StopOnIdleEnd>false</StopOnIdleEnd>
+      <RestartOnIdle>false</RestartOnIdle>
+    </IdleSettings>
+    <AllowStartOnDemand>true</AllowStartOnDemand>
+    <Enabled>true</Enabled>
+    <Hidden>false</Hidden>
+    <RunOnlyIfIdle>false</RunOnlyIfIdle>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+    <Priority>7</Priority>
+  </Settings>
+  <Actions Context="Author">
+    <Exec>
+      <Command>wscript.exe</Command>
+      <Arguments>${p(e)}</Arguments>
+    </Exec>
+  </Actions>
+</Task>
+`}async function tt(t){const{serviceID:e,wrapperPath:r,runCommand:n}=t,a=await K(n)??l.userInfo().username,i=u.join(u.dirname(r),`${e}-task.xml`);try{const o=Y({userId:a,wrapperPath:r});return await w(i,"\uFEFF"+o,"utf16le"),await n("schtasks",["/Create","/TN",e,"/XML",i,"/F"]),!0}catch{return!1}finally{await h(i,{force:!0}).catch(()=>{})}}function et(t){const e=[`"${S(t.nodePath)}"`,`"${S(t.cliPath)}"`,...t.configDir?["--config-dir",`"${S(t.configDir)}"`]:[]].join(" ");return["Option Explicit","Dim shell, command, delayMs, rapidCount",`command = "${S(e)}"`,'Set shell = CreateObject("WScript.Shell")',"delayMs = 5000","rapidCount = 0","Do","  shell.Run command, 0, True","  rapidCount = rapidCount + 1","  If rapidCount >= 10 Then","    WScript.Sleep 300000","    rapidCount = 0","  Else","    WScript.Sleep delayMs","  End If","Loop",""].join(`\r
+`)}function b(t){return`gui/${t??0}`}function N(t){const e=String(t?.stdout??"").trim();return String(t?.stderr??"").trim()||e||`exit=${Number(t?.exitCode??-1)}`}function R(t,e){if(Number(t?.exitCode??0)!==0)throw new Error(`${e}: ${N(t)}`)}function rt(){return{platform:"darwin",kind:"launchd",async install({serviceID:t,nodePath:e,cliPath:r,configDir:n,stdoutPath:a,stderrPath:i,environmentPath:s="",homeDir:o=l.homedir()}){const c=Q(t,o);return await P(u.dirname(c),{recursive:!0}),await w(c,z({serviceID:t,nodePath:e,cliPath:r,configDir:n,stdoutPath:a,stderrPath:i,environmentPath:s}),{encoding:"utf8",mode:384}),{definitionPath:c}},async start({serviceID:t,definitionPath:e,runCommand:r=d,uid:n=process.getuid?.()??0}){const a=b(n);let i=await r("launchctl",["bootstrap",a,e],{allowFailure:!0});Number(i?.exitCode??0)!==0&&(await r("launchctl",["bootout",`${a}/${t}`],{allowFailure:!0}),i=await r("launchctl",["bootstrap",a,e],{allowFailure:!0}),R(i,`launchctl bootstrap ${a}`));const s=await r("launchctl",["kickstart","-k",`${a}/${t}`],{allowFailure:!0});if(Number(s?.exitCode??0)!==0){const o=Number(i?.exitCode??0)===0?"":`, bootstrap=${N(i)}`;throw new Error(`launchctl start failed for ${a}/${t}: ${N(s)}${o}`)}},async stop({serviceID:t,runCommand:e=d,uid:r=process.getuid?.()??0}){const n=b(r);await e("launchctl",["bootout",`${n}/${t}`],{allowFailure:!0})},async restart({serviceID:t,definitionPath:e,runCommand:r=d,uid:n=process.getuid?.()??0}){const a=b(n);await r("launchctl",["bootout",`${a}/${t}`],{allowFailure:!0});for(let o=0;o<20&&(await r("launchctl",["print",`${a}/${t}`],{allowFailure:!0})).exitCode===0;o+=1)await new Promise(m=>setTimeout(m,250));try{await U(e)}catch{throw new Error(`launchd plist missing: ${e}`)}const i=await r("launchctl",["bootstrap",a,e],{allowFailure:!0});R(i,`launchctl bootstrap ${a}`);const s=await r("launchctl",["kickstart","-k",`${a}/${t}`],{allowFailure:!0});R(s,`launchctl kickstart ${a}/${t}`)},async uninstall({serviceID:t,definitionPath:e,runCommand:r=d,uid:n=process.getuid?.()??0}){const a=b(n);await r("launchctl",["bootout",`${a}/${t}`],{allowFailure:!0}),await h(e,{force:!0})},async discoverServices({homeDir:t=l.homedir()}={}){const e=u.join(t,"Library","LaunchAgents"),r=await v(e).catch(()=>[]),n=A("darwin"),a=[];for(const i of r){if(!i.startsWith(n)||!i.endsWith(".plist"))continue;const s=i.slice(0,-6),o=u.join(e,i);let c=null;try{const m=await g(o,"utf8");c=G(m)}catch{}a.push({serviceID:s,definitionPath:o,configDir:c})}return a},async isServiceLoaded({serviceID:t,runCommand:e=d,uid:r=process.getuid?.()??0}){const n=b(r),a=await e("launchctl",["print",`${n}/${t}`],{allowFailure:!0});return Number(a?.exitCode??1)===0}}}function nt(){return{platform:"win32",kind:"task-scheduler",async install({serviceID:t,nodePath:e,cliPath:r,configDir:n,runCommand:a=d,homeDir:i=l.homedir()}){const s=k(t,i);await P(u.dirname(s),{recursive:!0}),await w(s,et({nodePath:e,cliPath:r,configDir:n}),"utf8");let o=!1;H()&&(o=await tt({serviceID:t,wrapperPath:s,runCommand:a}));const c=I(t,i);return o?await h(c,{force:!0}).catch(()=>{}):await q({wrapperPath:s,shortcutPath:c,runCommand:a}),{definitionPath:o?`task:${t}`:`startup:${t}`}},async start({serviceID:t,definitionPath:e,runCommand:r=d,homeDir:n=l.homedir()}){const a=k(t,n);if(e.startsWith("task:"))try{await r("schtasks",["/Run","/TN",t]);return}catch{}F("wscript.exe",["//B","//NoLogo",a])},async stop({serviceID:t,runCommand:e=d,homeDir:r=l.homedir()}){await e("schtasks",["/End","/TN",t],{allowFailure:!0});const n=`${t}-wrapper.vbs`;await _(n,{platform:"win32"})},async restart({serviceID:t,definitionPath:e,runCommand:r=d,homeDir:n=l.homedir()}){await r("schtasks",["/End","/TN",t],{allowFailure:!0});const a=`${t}-wrapper.vbs`;await _(a,{platform:"win32"});const i=k(t,n);if(e?.startsWith("task:"))try{await r("schtasks",["/Run","/TN",t]);return}catch{}F("wscript.exe",["//B","//NoLogo",i])},async uninstall({serviceID:t,runCommand:e=d,homeDir:r=l.homedir()}){await e("schtasks",["/Delete","/TN",t,"/F"],{allowFailure:!0});const n=k(t,r);await h(n,{force:!0});const a=I(t,r);await h(a,{force:!0})},async discoverServices({homeDir:t=l.homedir(),runCommand:e=d}={}){const r=A("win32"),n=await e("schtasks",["/Query","/FO","CSV","/NH"],{allowFailure:!0}),a=[];if(Number(n?.exitCode??-1)===0){const o=String(n.stdout??"").split(/\r?\n/);for(const c of o){const m=c.match(/^"([^"]+)"/);if(!m)continue;const f=m[1];if(!f.startsWith(r))continue;let W=null;try{const x=k(f,t),D=(await g(x,"utf8")).match(/--config-dir\s+""([^""]+)""/);D&&(W=D[1])}catch{}a.push({serviceID:f,definitionPath:`task:${f}`,configDir:W})}}const i=u.join(t,"AppData","Roaming","Microsoft","Windows","Start Menu","Programs","Startup"),s=await v(i).catch(()=>[]);for(const o of s){if(!o.startsWith(r)||!o.endsWith(".lnk"))continue;const c=o.slice(0,-4);if(a.some(f=>f.serviceID===c))continue;let m=null;try{const f=k(c,t),x=(await g(f,"utf8")).match(/--config-dir\s+""([^""]+)""/);x&&(m=x[1])}catch{}a.push({serviceID:c,definitionPath:`startup:${c}`,configDir:m})}return a},async isServiceLoaded({serviceID:t,runCommand:e=d}){const r=await e("schtasks",["/Query","/TN",t,"/NH"],{allowFailure:!0});return Number(r?.exitCode??1)===0}}}function at(){return{platform:"linux",kind:"systemd-user",async install({serviceID:t,nodePath:e,cliPath:r,configDir:n,stdoutPath:a,stderrPath:i,homeDir:s=l.homedir(),runCommand:o=d}){const c=X(t,s);return await P(u.dirname(c),{recursive:!0}),await w(c,J({serviceID:t,nodePath:e,cliPath:r,configDir:n,stdoutPath:a,stderrPath:i}),{encoding:"utf8",mode:384}),await o("systemctl",["--user","daemon-reload"]),await o("systemctl",["--user","enable",`${t}.service`]),{definitionPath:c}},async start({serviceID:t,runCommand:e=d}){await e("systemctl",["--user","start",`${t}.service`])},async stop({serviceID:t,runCommand:e=d}){await e("systemctl",["--user","stop",`${t}.service`],{allowFailure:!0})},async restart({serviceID:t,runCommand:e=d}){await e("systemctl",["--user","restart",`${t}.service`])},async uninstall({serviceID:t,definitionPath:e,runCommand:r=d}){await r("systemctl",["--user","stop",`${t}.service`],{allowFailure:!0}),await r("systemctl",["--user","disable",`${t}.service`],{allowFailure:!0}),await h(e,{force:!0}),await r("systemctl",["--user","daemon-reload"])},async discoverServices({homeDir:t=l.homedir()}={}){const e=u.join(t,".config","systemd","user"),r=await v(e).catch(()=>[]),n=A("linux"),a=[];for(const i of r){if(!i.startsWith(n)||!i.endsWith(".service"))continue;const s=i.slice(0,-8),o=u.join(e,i);let c=null;try{const m=await g(o,"utf8");c=V(m)}catch{}a.push({serviceID:s,definitionPath:o,configDir:c})}return a},async isServiceLoaded({serviceID:t,runCommand:e=d}){const r=await e("systemctl",["--user","is-active",`${t}.service`],{allowFailure:!0});return String(r?.stdout??"").trim()==="active"}}}function $(t){try{const e=O(t,"utf8"),r=JSON.parse(e);if(r&&typeof r.service_id=="string"&&typeof r.node_path=="string"&&typeof r.cli_path=="string"&&typeof r.root_dir=="string")return r}catch{}return null}function it(t){return u.join(t,"daemon.lock.json")}function L(t){const e=it(t);try{const r=O(e,"utf8"),n=JSON.parse(r);if(typeof n?.pid=="number")return n.pid}catch{}return 0}function B(t){return u.join(t,".profile")}function ot(t){return t.replace(/[.*+?^${}()|[\]\\]/g,"\\$&")}function st(t){const e=[T(t.nodePath),T(t.cliPath)];t.configDir&&e.push("--config-dir",T(t.configDir));const r=e.join(" ");return`${r} status >/dev/null 2>&1 || (nohup ${r} start >/dev/null 2>&1 &)`}function ct(t,e){return`# >>> grix-connector autostart [${t}] >>>
+${e}
 # <<< grix-connector autostart [${t}] <<<
-`}function U(t){const r=et(t);return new RegExp(`(?:^|\\n)# >>> grix-connector autostart \\[${r}\\] >>>\\n[\\s\\S]*?\\n# <<< grix-connector autostart \\[${r}\\] <<<\\n?`,"m")}async function it(t,r,e){let n="";try{n=await f(t,"utf8")}catch{}const a=at(r,e),i=U(r);let s;if(i.test(n))s=n.replace(i,`
+`}function M(t){const e=ot(t);return new RegExp(`(?:^|\\n)# >>> grix-connector autostart \\[${e}\\] >>>\\n[\\s\\S]*?\\n# <<< grix-connector autostart \\[${e}\\] <<<\\n?`,"m")}async function ut(t,e,r){let n="";try{n=await g(t,"utf8")}catch{}const a=ct(e,r),i=M(e);let s;if(i.test(n))s=n.replace(i,`
 ${a}`).replace(/^\n+/,"");else{const o=n.length===0||n.endsWith(`
 `)?"":`
-`;s=`${n}${o}${a}`}s!==n&&(await P(u.dirname(t),{recursive:!0}),await h(t,s,{encoding:"utf8"}))}async function ot(t,r){let e="";try{e=await f(t,"utf8")}catch{return}const n=U(r);if(!n.test(e))return;const a=e.replace(n,"").replace(/^\n+/,"");await h(t,a,{encoding:"utf8"})}function st(){return{platform:"linux",kind:"bare-daemon",async install({serviceID:t,nodePath:r,cliPath:e,configDir:n,stdoutPath:a,stderrPath:i,homeDir:s=p.homedir()}){const o=g(t,s);await P(u.dirname(o),{recursive:!0});const c=u.resolve(u.dirname(u.dirname(a||i||o))),l={schema_version:1,service_id:t,node_path:r,cli_path:e,config_dir:n??"",root_dir:c,stdout_path:a,stderr_path:i,installed_at:Date.now()};await h(o,`${JSON.stringify(l,null,2)}
-`,{encoding:"utf8",mode:384});const m=nt({nodePath:r,cliPath:e,configDir:n??""});return await it(O(s),t,m),{definitionPath:o}},async start({serviceID:t,homeDir:r=p.homedir()}){const e=g(t,r),n=S(e);if(!n)throw new Error(`bare-daemon marker missing: ${e}`);const a=[n.cli_path];n.config_dir&&a.push("--config-dir",n.config_dir),W(n.node_path,a)},async stop({serviceID:t,homeDir:r=p.homedir()}){const e=g(t,r),n=S(e);if(!n)return;const a=N(n.root_dir);if(a>0&&v(a))try{process.kill(a,"SIGTERM")}catch{}},async restart(t){await this.stop(t);const r=Date.now()+5e3,e=g(t.serviceID,t.homeDir??p.homedir()),n=S(e);for(;n&&Date.now()<r;){const a=N(n.root_dir);if(a<=0||!v(a))break;await new Promise(i=>setTimeout(i,100))}await this.start(t)},async uninstall({serviceID:t,homeDir:r=p.homedir()}){const e=g(t,r),n=S(e);if(n){const a=N(n.root_dir);if(a>0&&v(a))try{process.kill(a,"SIGTERM")}catch{}}await w(e,{force:!0}),await ot(O(r),t)},async discoverServices({homeDir:t=p.homedir()}={}){const r=u.join(t,".grix","service"),e=await C(r).catch(()=>[]),n=A("linux"),a=[];for(const i of e){if(!i.startsWith(n)||!i.endsWith(".bare.json"))continue;const s=i.slice(0,-10),o=u.join(r,i),c=S(o);a.push({serviceID:s,definitionPath:o,configDir:c?.config_dir||null})}return a},async isServiceLoaded({serviceID:t,homeDir:r=p.homedir()}){const e=g(t,r),n=S(e);if(!n)return!1;const a=N(n.root_dir);return a>0&&v(a)}}}function ct(t=process.getuid?.()??0){if(process.env.GRIX_FORCE_BARE_DAEMON==="1")return!1;const r=process.env.XDG_RUNTIME_DIR;return!!(r&&R(u.join(r,"bus"))||R(`/run/user/${t}/bus`))}function wt(t=process.platform,r={}){return t==="darwin"?Y():t==="win32"?I():r.systemdUserAvailable??ct()?tt():st()}export{wt as getPlatformServiceAdapter,ct as isSystemdUserBusAvailable,ot as removeProfileAutostart,it as upsertProfileAutostart};
+`;s=`${n}${o}${a}`}s!==n&&(await P(u.dirname(t),{recursive:!0}),await w(t,s,{encoding:"utf8"}))}async function lt(t,e){let r="";try{r=await g(t,"utf8")}catch{return}const n=M(e);if(!n.test(r))return;const a=r.replace(n,"").replace(/^\n+/,"");await w(t,a,{encoding:"utf8"})}function dt(){return{platform:"linux",kind:"bare-daemon",async install({serviceID:t,nodePath:e,cliPath:r,configDir:n,stdoutPath:a,stderrPath:i,homeDir:s=l.homedir()}){const o=y(t,s);await P(u.dirname(o),{recursive:!0});const c=u.resolve(u.dirname(u.dirname(a||i||o))),m={schema_version:1,service_id:t,node_path:e,cli_path:r,config_dir:n??"",root_dir:c,stdout_path:a,stderr_path:i,installed_at:Date.now()};await w(o,`${JSON.stringify(m,null,2)}
+`,{encoding:"utf8",mode:384});const f=st({nodePath:e,cliPath:r,configDir:n??""});return await ut(B(s),t,f),{definitionPath:o}},async start({serviceID:t,homeDir:e=l.homedir()}){const r=y(t,e),n=$(r);if(!n)throw new Error(`bare-daemon marker missing: ${r}`);const a=[n.cli_path];n.config_dir&&a.push("--config-dir",n.config_dir),F(n.node_path,a)},async stop({serviceID:t,homeDir:e=l.homedir()}){const r=y(t,e),n=$(r);if(!n)return;const a=L(n.root_dir);if(a>0&&C(a))try{process.kill(a,"SIGTERM")}catch{}},async restart(t){await this.stop(t);const e=Date.now()+5e3,r=y(t.serviceID,t.homeDir??l.homedir()),n=$(r);for(;n&&Date.now()<e;){const a=L(n.root_dir);if(a<=0||!C(a))break;await new Promise(i=>setTimeout(i,100))}await this.start(t)},async uninstall({serviceID:t,homeDir:e=l.homedir()}){const r=y(t,e),n=$(r);if(n){const a=L(n.root_dir);if(a>0&&C(a))try{process.kill(a,"SIGTERM")}catch{}}await h(r,{force:!0}),await lt(B(e),t)},async discoverServices({homeDir:t=l.homedir()}={}){const e=u.join(t,".grix","service"),r=await v(e).catch(()=>[]),n=A("linux"),a=[];for(const i of r){if(!i.startsWith(n)||!i.endsWith(".bare.json"))continue;const s=i.slice(0,-10),o=u.join(e,i),c=$(o);a.push({serviceID:s,definitionPath:o,configDir:c?.config_dir||null})}return a},async isServiceLoaded({serviceID:t,homeDir:e=l.homedir()}){const r=y(t,e),n=$(r);if(!n)return!1;const a=L(n.root_dir);return a>0&&C(a)}}}function mt(t=process.getuid?.()??0){if(process.env.GRIX_FORCE_BARE_DAEMON==="1")return!1;const e=process.env.XDG_RUNTIME_DIR;return!!(e&&E(u.join(e,"bus"))||E(`/run/user/${t}/bus`))}function St(t=process.platform,e={}){return t==="darwin"?rt():t==="win32"?nt():e.systemdUserAvailable??mt()?at():dt()}export{St as getPlatformServiceAdapter,mt as isSystemdUserBusAvailable,lt as removeProfileAutostart,ut as upsertProfileAutostart};

package/openclaw-plugin/skills/grix-admin/SKILL.md

@@ -1,202 +1,202 @@
----
-name: grix-admin
-description: Responsible for OpenClaw local configuration, binding, and runtime convergence; can create new remote API agents through the current agent's WS channel, and supports querying, creating, modifying agent categories and assigning categories to agents, reusable across agent creation and management flows.
----
-
-# Grix Agent Admin
-
-`grix-admin` is responsible for three things:
-
-1. Landing existing remote agent parameters into local OpenClaw, and handling runtime convergence after binding.
-2. When the current main agent is already online and has the corresponding scope, creating new remote API agents through `grix_admin`'s direct actions, then continuing with local landing.
-3. During agent creation or subsequent agent management, reusing `grix_admin`'s direct actions to query categories, create categories, modify categories, and assign categories to agents.
-
-## Entry Method
-
-1. In most cases, enter this skill from `grix_admin`'s `task` entry; the first line of `task` must clearly state `bind-local`, `create-and-bind`, or `category-manage`.
-2. Only when executing "remote API agent creation / category query / category creation / category modification / category assignment" remote steps within this skill should you directly call `grix_admin` once, without passing `task` again.
-3. In new flows, always explicitly pass `action` when directly calling `grix_admin`:
-   - `create_agent`
-   - `list_categories`
-   - `create_category`
-   - `update_category`
-   - `assign_category`
-4. The legacy direct call format for `create_agent` (passing only `agentName` and other fields without `action`) is still compatible, but should not be used in new flows.
-
-## Direct Action List
-
-1. `action=create_agent`
-   - Required: `agentName`
-   - Optional: `introduction`, `isMain`, `categoryId`, `categoryName`, `parentCategoryId`, `categorySortOrder`
-   - `categoryId` and `categoryName` cannot be provided simultaneously
-   - When `categoryName` is given, it first checks for duplicates under `parentCategoryId`; if not found, creates and assigns
-2. `action=list_categories`
-   - Required: (none)
-3. `action=create_category`
-   - Required: `name`, `parentId`
-   - Optional: `sortOrder`
-4. `action=update_category`
-   - Required: `categoryId`, `name`, `parentId`
-   - Optional: `sortOrder`
-5. `action=assign_category`
-   - Required: `agentId`, `categoryId`
-   - `categoryId=0` means clear the category
-
-## Mode A: bind-local (Initial Handoff from grix-register)
-
-Input fields (written in `grix_admin.task`, all required):
-
-1. First line must be `bind-local`
-2. `agent_name`
-3. `agent_id`
-4. `api_endpoint`
-5. `api_key`
-
-Execution rules:
-
-1. Do not perform remote creation; execute local binding directly. Do not call any script that directly modifies `openclaw.json`.
-2. Prepare local directories first:
-   - `workspace=~/.openclaw/workspace-<agent_name>`
-   - `agentDir=~/.openclaw/agents/<agent_name>/agent`
-   - Persona files go only in the `workspace` root: `IDENTITY.md`, `SOUL.md`, `AGENTS.md`, and optionally `USER.md` / `MEMORY.md`
-   - Do not put persona files in `agentDir`; `agentDir` is the per-agent runtime state directory managed by OpenClaw
-   - If `workspace` is missing required persona files, add minimal files to avoid an empty workspace for the new agent
-3. Read existing configuration; if paths do not exist, treat as empty object / empty array:
-   - `channels.grix.accounts`
-   - `agents.list`
-   - `tools.profile`
-   - `tools.alsoAllow`
-   - `tools.sessions.visibility`
-   - To confirm existing Grix bindings, additionally use `openclaw agents bindings --agent <agent_name> --json` to view the current binding list
-4. Calculate target values for this operation:
-   - `channels.grix.accounts.<agent_name>`: write `name`, `enabled=true`, `apiKey`, `wsUrl`, `agentId`
-   - `agents.list`: ensure entry exists with `id=<agent_name>`, `name=<agent_name>`, `workspace`, `agentDir`, `model`
-   - Grix binding: ensure the target agent is ultimately bound to `grix:<agent_name>`
-   - `tools.profile`: set to `"coding"`
-   - `tools.alsoAllow`: must include at least `message`, `grix_query`, `grix_group`, `grix_register`, `grix_message_send`, `grix_message_unsend`
-   - If the current binding target is the main agent, also ensure that agent's own `tools.alsoAllow` retains `grix_admin`, `grix_egg`, `grix_update`, `openclaw_memory_setup`; this set goes only at the agent level, not in global `tools.alsoAllow`
-   - `tools.sessions.visibility`: set to `"agent"`
-   - If `channels.grix.enabled=false`, change it back to `true`
-5. Rules for determining `model`:
-   - First reuse the existing `model` from that local agent's entry
-   - If the existing entry has none, use `agents.defaults.model.primary`
-   - If still unavailable, clearly state that model is missing, stop execution, do not guess
-6. Write using official CLI item by item; do not overwrite the entire config:
-   - `openclaw config set channels.grix.accounts.<agent_name> '<ACCOUNT_JSON>' --strict-json`
-   - `openclaw config set agents.list '<NEXT_AGENTS_LIST_JSON>' --strict-json`
-   - `openclaw agents bind --agent <agent_name> --bind grix:<agent_name>`
-   - `openclaw config set tools.profile '"coding"' --strict-json`
-   - `openclaw config set tools.alsoAllow '["message","grix_query","grix_group","grix_register","grix_message_send","grix_message_unsend"]' --strict-json`
-   - If the current binding target is the main agent, also merge `grix_admin`, `grix_egg`, `grix_update`, `openclaw_memory_setup` into that agent's own `agents.list` record's `tools.alsoAllow`; do not put this set in global `tools.alsoAllow`
-   - `openclaw config set tools.sessions.visibility '"agent"' --strict-json`
-   - Only when the current config explicitly has `channels.grix.enabled` turned off, execute `openclaw config set channels.grix.enabled true --strict-json`
-7. After writing, must perform static validation:
-   - `openclaw config validate`
-   - `openclaw config get --json channels.grix.accounts.<agent_name>`
-   - `openclaw config get --json agents.list`
-   - `openclaw agents bindings --agent <agent_name> --json`
-8. If this invocation already has real verification conditions, must immediately perform a real routing verification; prefer reusing the current install/acceptance context, do not invent a new probe. The following situations are all considered as binding runtime not yet switched successfully:
-   - Reply falls to the main agent
-   - Reply behaves as the default assistant
-   - Reply still shows old persona, old config, or obvious ID mismatch
-9. Only when this `bind-local` invocation itself handles real verification, and step 7 static validation passed but step 8 real routing verification still fails, is one `openclaw gateway restart` allowed as targeted remediation; after restart, must redo the same round of real routing verification.
-10. Success definition:
-    - Can perform real verification: only "static validation passed + real routing verification passed" counts as `bind-local` complete
-    - This invocation cannot yet perform real verification: can only clearly state "config has been written, runtime not yet tested, needs subsequent upper-level flow to continue verification"; do not claim it has fully taken effect
-
-## Mode B: create-and-bind (Subsequent Management When Main Channel and Scope Are Available)
-
-Fields written in `grix_admin.task`:
-
-1. First line must be `create-and-bind`
-2. `agentName` (required)
-3. `introduction` (optional)
-5. `isMain` (optional, default `false`)
-6. `categoryId` (optional): assign the new agent directly to an existing category
-7. `categoryName` (optional): create if not exists, then assign
-8. `parentCategoryId` (optional): only used in the `categoryName` approach, default `0`
-9. `categorySortOrder` (optional): only used when creating a category
-
-Execution rules:
-
-1. Confirm the current session is bound to a valid Grix account; cross-account execution is prohibited.
-2. If both `categoryId` and `categoryName` are provided, report an error and stop immediately to avoid ambiguity.
-3. Call `grix_admin` only once with `action=create_agent`, delegating remote creation and optional category handling to it; pass:
-   - `action=create_agent`
-   - `agentName`
-   - Optional `introduction`
-   - Optional `isMain`
-   - Optional `categoryId`
-   - Optional `categoryName`
-   - Optional `parentCategoryId`
-   - Optional `categorySortOrder`
-4. After remote creation succeeds, read `createdAgent.id`, `createdAgent.agent_name`, `createdAgent.api_endpoint`, `createdAgent.api_key` from the return result.
-5. If the request included category information, check whether the return already includes the category assignment result; if not, proceed with supplementary steps according to `categoryId` / `categoryName` rules and explain the reason.
-6. In the `categoryName` flow, if multiple categories with the exact same name appear under the same parent, stop and ask the owner to clean up categories or use an explicit `categoryId` instead.
-7. After remote creation and optional category steps succeed, immediately transition to the `bind-local` local binding steps; if this invocation already has real verification context, follow the same "static validation -> real routing verification -> one restart if needed -> same-round retest" convergence rules; otherwise explicitly hand the "continue real verification" responsibility back to the upper-level flow.
-8. `isMain=true` should only be used when actually creating a new main API agent; generally subsequent new agents should not enable this by default.
-9. Throughout the `create-and-bind` flow, do not treat "config written successfully" as completion; only when this invocation itself handles real routing verification and verification fails should one `openclaw gateway restart` be treated as targeted remediation.
-
-## Mode C: category-manage (Category Management)
-
-Fields written in `grix_admin.task`:
-
-1. First line must be `category-manage`
-2. `operation` (required): only `list`, `create`, `update`, `assign` are allowed
-4. `name` (`create` / `update` required)
-5. `parentId` (`create` / `update` required)
-6. `sortOrder` (`create` / `update` optional)
-7. `categoryId` (`update` / `assign` required; for `assign`, `0` means clear)
-8. `agentId` (`assign` required)
-
-Execution rules:
-
-1. Strictly bound to the current session account; cross-account execution is prohibited.
-2. All remote steps must only be completed through `grix_admin`'s direct actions; hand-written HTTP and temporary scripts are prohibited.
-3. `operation=list`
-   - Call `action=list_categories`
-4. `operation=create`
-   - Call `action=create_category`
-5. `operation=update`
-   - Call `action=update_category`
-6. `operation=assign`
-   - Call `action=assign_category`
-   - `categoryId=0` explicitly means clear the agent's current category
-7. If the current management task also includes "creating a new agent", prefer using `create-and-bind`; do not split remote creation into other custom flows.
-
-## Remote Creation Fallback Conditions
-
-If the current task has neither an existing `agent_name`, `agent_id`, `api_endpoint`, `api_key`, nor an available online main channel or `agent.api.create` permission, stop this skill first and clearly prompt the user to create the remote agent through the backend admin path. After obtaining these parameters, proceed with `bind-local`.
-
-## Guardrails (Applicable to All Three Modes)
-
-1. Never ask user for website account/password.
-2. `bind-local` mode must not call back to `grix-register` to avoid circular routing.
-3. All remote creation / category-related actions must only go through `grix_admin` direct actions via the current account's WS channel; do not hand-write HTTP or fall back to legacy scripts.
-4. The complete `api_key` is only passed back once; do not repeatedly echo it in plaintext.
-5. Before local `openclaw config set` / `validate` succeeds, do not claim config is complete; when this invocation can perform real verification, do not claim `bind-local` / `create-and-bind` is complete until real routing verification passes.
-6. During an install private chat, do not manually modify `openclaw.json` and then execute `openclaw gateway restart`.
-7. Do not reference or call `grix_agent_bind.py`; this skill only uses official OpenClaw config commands.
-
-## Error Handling Rules
-
-1. `bind-local` missing fields: clearly state which field is missing and stop.
-2. `create-and-bind` missing `agentName`: clearly state which field is missing and stop.
-3. `create-and-bind` with both `categoryId` and `categoryName`: clearly state the conflict and stop.
-4. `category-manage` missing `operation` or operation-specific fields: clearly state which field is missing and stop.
-5. Remote returns `code=4003` or message explicitly mentions `agent.api.create`: tell the owner to grant `agent.api.create` on the Agent permissions page.
-6. Remote returns `code=4003` or message explicitly mentions `agent.category.list` / `agent.category.create` / `agent.category.update` / `agent.category.assign`: tell the owner to grant the corresponding scope on the Agent permissions page.
-7. Missing remote agent parameters and current account cannot create: clearly require backend admin creation first.
-8. Local config failure: return the failed command and result, then stop; emphasize which `get` / `set` / `validate` step failed.
-9. This invocation handles real routing verification, and after one `openclaw gateway restart` retest still fails: clearly state "static config has been written, but runtime has not yet switched successfully"; converge as failed or partially complete, do not write it as success.
-
-## Response Style
-
-1. Clearly state whether the current execution is `bind-local`, `create-and-bind`, or `category-manage`.
-2. Report in phases: remote creation / category handling (if any) / local config writing / validation results.
-3. Clearly state whether local config has taken effect; if only static config succeeded but this invocation cannot perform real verification, can only write "config has been written, runtime not yet tested, needs subsequent flow to continue verification"; if only the category step succeeded, also state that clearly.
-4. If remote creation succeeded but category or local binding subsequently failed, clearly state it is "partially complete"; do not generically write it as success.
-
-## References
-
-1. [references/api-contract.md](references/api-contract.md)
+---
+name: grix-admin
+description: Responsible for OpenClaw local configuration, binding, and runtime convergence; can create new remote API agents through the current agent's WS channel, and supports querying, creating, modifying agent categories and assigning categories to agents, reusable across agent creation and management flows.
+---
+
+# Grix Agent Admin
+
+`grix-admin` is responsible for three things:
+
+1. Landing existing remote agent parameters into local OpenClaw, and handling runtime convergence after binding.
+2. When the current main agent is already online and has the corresponding scope, creating new remote API agents through `grix_admin`'s direct actions, then continuing with local landing.
+3. During agent creation or subsequent agent management, reusing `grix_admin`'s direct actions to query categories, create categories, modify categories, and assign categories to agents.
+
+## Entry Method
+
+1. In most cases, enter this skill from `grix_admin`'s `task` entry; the first line of `task` must clearly state `bind-local`, `create-and-bind`, or `category-manage`.
+2. Only when executing "remote API agent creation / category query / category creation / category modification / category assignment" remote steps within this skill should you directly call `grix_admin` once, without passing `task` again.
+3. In new flows, always explicitly pass `action` when directly calling `grix_admin`:
+   - `create_agent`
+   - `list_categories`
+   - `create_category`
+   - `update_category`
+   - `assign_category`
+4. The legacy direct call format for `create_agent` (passing only `agentName` and other fields without `action`) is still compatible, but should not be used in new flows.
+
+## Direct Action List
+
+1. `action=create_agent`
+   - Required: `agentName`
+   - Optional: `introduction`, `isMain`, `categoryId`, `categoryName`, `parentCategoryId`, `categorySortOrder`
+   - `categoryId` and `categoryName` cannot be provided simultaneously
+   - When `categoryName` is given, it first checks for duplicates under `parentCategoryId`; if not found, creates and assigns
+2. `action=list_categories`
+   - Required: (none)
+3. `action=create_category`
+   - Required: `name`, `parentId`
+   - Optional: `sortOrder`
+4. `action=update_category`
+   - Required: `categoryId`, `name`, `parentId`
+   - Optional: `sortOrder`
+5. `action=assign_category`
+   - Required: `agentId`, `categoryId`
+   - `categoryId=0` means clear the category
+
+## Mode A: bind-local (Initial Handoff from grix-register)
+
+Input fields (written in `grix_admin.task`, all required):
+
+1. First line must be `bind-local`
+2. `agent_name`
+3. `agent_id`
+4. `api_endpoint`
+5. `api_key`
+
+Execution rules:
+
+1. Do not perform remote creation; execute local binding directly. Do not call any script that directly modifies `openclaw.json`.
+2. Prepare local directories first:
+   - `workspace=~/.openclaw/workspace-<agent_name>`
+   - `agentDir=~/.openclaw/agents/<agent_name>/agent`
+   - Persona files go only in the `workspace` root: `IDENTITY.md`, `SOUL.md`, `AGENTS.md`, and optionally `USER.md` / `MEMORY.md`
+   - Do not put persona files in `agentDir`; `agentDir` is the per-agent runtime state directory managed by OpenClaw
+   - If `workspace` is missing required persona files, add minimal files to avoid an empty workspace for the new agent
+3. Read existing configuration; if paths do not exist, treat as empty object / empty array:
+   - `channels.grix.accounts`
+   - `agents.list`
+   - `tools.profile`
+   - `tools.alsoAllow`
+   - `tools.sessions.visibility`
+   - To confirm existing Grix bindings, additionally use `openclaw agents bindings --agent <agent_name> --json` to view the current binding list
+4. Calculate target values for this operation:
+   - `channels.grix.accounts.<agent_name>`: write `name`, `enabled=true`, `apiKey`, `wsUrl`, `agentId`
+   - `agents.list`: ensure entry exists with `id=<agent_name>`, `name=<agent_name>`, `workspace`, `agentDir`, `model`
+   - Grix binding: ensure the target agent is ultimately bound to `grix:<agent_name>`
+   - `tools.profile`: set to `"coding"`
+   - `tools.alsoAllow`: must include at least `message`, `grix_query`, `grix_group`, `grix_register`, `grix_message_send`, `grix_message_unsend`
+   - If the current binding target is the main agent, also ensure that agent's own `tools.alsoAllow` retains `grix_admin`, `grix_egg`, `grix_update`, `openclaw_memory_setup`; this set goes only at the agent level, not in global `tools.alsoAllow`
+   - `tools.sessions.visibility`: set to `"agent"`
+   - If `channels.grix.enabled=false`, change it back to `true`
+5. Rules for determining `model`:
+   - First reuse the existing `model` from that local agent's entry
+   - If the existing entry has none, use `agents.defaults.model.primary`
+   - If still unavailable, clearly state that model is missing, stop execution, do not guess
+6. Write using official CLI item by item; do not overwrite the entire config:
+   - `openclaw config set channels.grix.accounts.<agent_name> '<ACCOUNT_JSON>' --strict-json`
+   - `openclaw config set agents.list '<NEXT_AGENTS_LIST_JSON>' --strict-json`
+   - `openclaw agents bind --agent <agent_name> --bind grix:<agent_name>`
+   - `openclaw config set tools.profile '"coding"' --strict-json`
+   - `openclaw config set tools.alsoAllow '["message","grix_query","grix_group","grix_register","grix_message_send","grix_message_unsend"]' --strict-json`
+   - If the current binding target is the main agent, also merge `grix_admin`, `grix_egg`, `grix_update`, `openclaw_memory_setup` into that agent's own `agents.list` record's `tools.alsoAllow`; do not put this set in global `tools.alsoAllow`
+   - `openclaw config set tools.sessions.visibility '"agent"' --strict-json`
+   - Only when the current config explicitly has `channels.grix.enabled` turned off, execute `openclaw config set channels.grix.enabled true --strict-json`
+7. After writing, must perform static validation:
+   - `openclaw config validate`
+   - `openclaw config get --json channels.grix.accounts.<agent_name>`
+   - `openclaw config get --json agents.list`
+   - `openclaw agents bindings --agent <agent_name> --json`
+8. If this invocation already has real verification conditions, must immediately perform a real routing verification; prefer reusing the current install/acceptance context, do not invent a new probe. The following situations are all considered as binding runtime not yet switched successfully:
+   - Reply falls to the main agent
+   - Reply behaves as the default assistant
+   - Reply still shows old persona, old config, or obvious ID mismatch
+9. Only when this `bind-local` invocation itself handles real verification, and step 7 static validation passed but step 8 real routing verification still fails, is one `openclaw gateway restart` allowed as targeted remediation; after restart, must redo the same round of real routing verification.
+10. Success definition:
+    - Can perform real verification: only "static validation passed + real routing verification passed" counts as `bind-local` complete
+    - This invocation cannot yet perform real verification: can only clearly state "config has been written, runtime not yet tested, needs subsequent upper-level flow to continue verification"; do not claim it has fully taken effect
+
+## Mode B: create-and-bind (Subsequent Management When Main Channel and Scope Are Available)
+
+Fields written in `grix_admin.task`:
+
+1. First line must be `create-and-bind`
+2. `agentName` (required)
+3. `introduction` (optional)
+5. `isMain` (optional, default `false`)
+6. `categoryId` (optional): assign the new agent directly to an existing category
+7. `categoryName` (optional): create if not exists, then assign
+8. `parentCategoryId` (optional): only used in the `categoryName` approach, default `0`
+9. `categorySortOrder` (optional): only used when creating a category
+
+Execution rules:
+
+1. Confirm the current session is bound to a valid Grix account; cross-account execution is prohibited.
+2. If both `categoryId` and `categoryName` are provided, report an error and stop immediately to avoid ambiguity.
+3. Call `grix_admin` only once with `action=create_agent`, delegating remote creation and optional category handling to it; pass:
+   - `action=create_agent`
+   - `agentName`
+   - Optional `introduction`
+   - Optional `isMain`
+   - Optional `categoryId`
+   - Optional `categoryName`
+   - Optional `parentCategoryId`
+   - Optional `categorySortOrder`
+4. After remote creation succeeds, read `createdAgent.id`, `createdAgent.agent_name`, `createdAgent.api_endpoint`, `createdAgent.api_key` from the return result.
+5. If the request included category information, check whether the return already includes the category assignment result; if not, proceed with supplementary steps according to `categoryId` / `categoryName` rules and explain the reason.
+6. In the `categoryName` flow, if multiple categories with the exact same name appear under the same parent, stop and ask the owner to clean up categories or use an explicit `categoryId` instead.
+7. After remote creation and optional category steps succeed, immediately transition to the `bind-local` local binding steps; if this invocation already has real verification context, follow the same "static validation -> real routing verification -> one restart if needed -> same-round retest" convergence rules; otherwise explicitly hand the "continue real verification" responsibility back to the upper-level flow.
+8. `isMain=true` should only be used when actually creating a new main API agent; generally subsequent new agents should not enable this by default.
+9. Throughout the `create-and-bind` flow, do not treat "config written successfully" as completion; only when this invocation itself handles real routing verification and verification fails should one `openclaw gateway restart` be treated as targeted remediation.
+
+## Mode C: category-manage (Category Management)
+
+Fields written in `grix_admin.task`:
+
+1. First line must be `category-manage`
+2. `operation` (required): only `list`, `create`, `update`, `assign` are allowed
+4. `name` (`create` / `update` required)
+5. `parentId` (`create` / `update` required)
+6. `sortOrder` (`create` / `update` optional)
+7. `categoryId` (`update` / `assign` required; for `assign`, `0` means clear)
+8. `agentId` (`assign` required)
+
+Execution rules:
+
+1. Strictly bound to the current session account; cross-account execution is prohibited.
+2. All remote steps must only be completed through `grix_admin`'s direct actions; hand-written HTTP and temporary scripts are prohibited.
+3. `operation=list`
+   - Call `action=list_categories`
+4. `operation=create`
+   - Call `action=create_category`
+5. `operation=update`
+   - Call `action=update_category`
+6. `operation=assign`
+   - Call `action=assign_category`
+   - `categoryId=0` explicitly means clear the agent's current category
+7. If the current management task also includes "creating a new agent", prefer using `create-and-bind`; do not split remote creation into other custom flows.
+
+## Remote Creation Fallback Conditions
+
+If the current task has neither an existing `agent_name`, `agent_id`, `api_endpoint`, `api_key`, nor an available online main channel or `agent.api.create` permission, stop this skill first and clearly prompt the user to create the remote agent through the backend admin path. After obtaining these parameters, proceed with `bind-local`.
+
+## Guardrails (Applicable to All Three Modes)
+
+1. Never ask user for website account/password.
+2. `bind-local` mode must not call back to `grix-register` to avoid circular routing.
+3. All remote creation / category-related actions must only go through `grix_admin` direct actions via the current account's WS channel; do not hand-write HTTP or fall back to legacy scripts.
+4. The complete `api_key` is only passed back once; do not repeatedly echo it in plaintext.
+5. Before local `openclaw config set` / `validate` succeeds, do not claim config is complete; when this invocation can perform real verification, do not claim `bind-local` / `create-and-bind` is complete until real routing verification passes.
+6. During an install private chat, do not manually modify `openclaw.json` and then execute `openclaw gateway restart`.
+7. Do not reference or call `grix_agent_bind.py`; this skill only uses official OpenClaw config commands.
+
+## Error Handling Rules
+
+1. `bind-local` missing fields: clearly state which field is missing and stop.
+2. `create-and-bind` missing `agentName`: clearly state which field is missing and stop.
+3. `create-and-bind` with both `categoryId` and `categoryName`: clearly state the conflict and stop.
+4. `category-manage` missing `operation` or operation-specific fields: clearly state which field is missing and stop.
+5. Remote returns `code=4003` or message explicitly mentions `agent.api.create`: tell the owner to grant `agent.api.create` on the Agent permissions page.
+6. Remote returns `code=4003` or message explicitly mentions `agent.category.list` / `agent.category.create` / `agent.category.update` / `agent.category.assign`: tell the owner to grant the corresponding scope on the Agent permissions page.
+7. Missing remote agent parameters and current account cannot create: clearly require backend admin creation first.
+8. Local config failure: return the failed command and result, then stop; emphasize which `get` / `set` / `validate` step failed.
+9. This invocation handles real routing verification, and after one `openclaw gateway restart` retest still fails: clearly state "static config has been written, but runtime has not yet switched successfully"; converge as failed or partially complete, do not write it as success.
+
+## Response Style
+
+1. Clearly state whether the current execution is `bind-local`, `create-and-bind`, or `category-manage`.
+2. Report in phases: remote creation / category handling (if any) / local config writing / validation results.
+3. Clearly state whether local config has taken effect; if only static config succeeded but this invocation cannot perform real verification, can only write "config has been written, runtime not yet tested, needs subsequent flow to continue verification"; if only the category step succeeded, also state that clearly.
+4. If remote creation succeeded but category or local binding subsequently failed, clearly state it is "partially complete"; do not generically write it as success.
+
+## References
+
+1. [references/api-contract.md](references/api-contract.md)