agent-policy-kit 0.0.0-stage → 0.1.0

package/src/detect.mjs

@@ -0,0 +1,136 @@
+import * as fs from 'node:fs/promises';
+import { constants } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+
+const CLIENTS = ['codex','claude','kimi','agy'];
+const OUTPUT_LIMIT = 65536;
+const VERSION = String.raw`(\d{1,4}\.\d{1,4}\.\d{1,4}(?:-[A-Za-z0-9][A-Za-z0-9.-]{0,63})?(?:\+[A-Za-z0-9][A-Za-z0-9.-]{0,63})?)`;
+function failure(code) { return Object.assign(new Error(code),{code}); }
+function options({env=process.env,hostHome=os.homedir(),timeoutMs=5000} = {}) {
+  if (!env || typeof env !== 'object' || typeof hostHome !== 'string' || !path.isAbsolute(hostHome) || hostHome.includes('\0') || !Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw failure('INVALID_DETECTION_OPTIONS');
+  return {env,hostHome:path.resolve(hostHome),timeoutMs};
+}
+function candidates(client,{env,hostHome}) {
+  const dirs = typeof env.PATH === 'string' ? env.PATH.split(path.delimiter) : [];
+  const names = process.platform === 'win32' ? [client + '.exe',client] : [client];
+  const result = [];
+  for (const dir of dirs) {
+    // Never search the working directory through empty/relative PATH segments.
+    if (!path.isAbsolute(dir) || dir.includes('\0')) continue;
+    for (const name of names) result.push({file:path.join(dir,name),origin:'path'});
+  }
+  const conventional = client === 'kimi' ? ['.kimi-code/bin/kimi']
+    : client === 'claude' ? ['.local/bin/claude','.claude/local/claude']
+    : [`.local/bin/${client}`];
+  for (const relative of conventional) result.push({file:path.join(hostHome,relative),origin:'known_location'});
+  return result.filter((candidate,index) => result.findIndex(c=>c.file === candidate.file) === index);
+}
+async function inspect(file) {
+  try {
+    const executable = await fs.realpath(file);
+    const stat = await fs.stat(executable);
+    if (!stat.isFile()) return {status:'invalid'};
+    await fs.access(executable,constants.X_OK);
+    return {status:'executable',executable};
+  } catch (error) {
+    return {status:error.code === 'ENOENT' || error.code === 'ENOTDIR' ? 'not_found' : 'invalid'};
+  }
+}
+function probe(executable,arg,{env,timeoutMs}) {
+  return new Promise(resolve => {
+    let child, timer, settled = false, size = 0;
+    const ownGroup = process.platform !== 'win32';
+    const buffers = [];
+    const killOwned = () => {
+      if (!child?.pid) return;
+      try { if (ownGroup) process.kill(-child.pid,'SIGKILL'); else child.kill('SIGKILL'); } catch {}
+    };
+    const alive = () => {
+      if (!child?.pid) return false;
+      if (!ownGroup) return child.exitCode === null && child.signalCode === null;
+      try { process.kill(-child.pid,0); return true; } catch (error) { return error.code !== 'ESRCH'; }
+    };
+    const finish = async (status) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      killOwned();
+      child?.stdout?.destroy(); child?.stderr?.destroy();
+      for (let elapsed = 0; alive() && elapsed < 500; elapsed += 20) await new Promise(done=>setTimeout(done,20));
+      if (status === 'ok' && alive()) status = 'invalid';
+      resolve({status,output:status === 'ok' ? Buffer.concat(buffers).toString('utf8') : ''});
+    };
+    try { child = spawn(executable,[arg],{env,stdio:['ignore','pipe','pipe'],shell:false,windowsHide:true,detached:ownGroup}); }
+    catch { finish('invalid'); return; }
+    timer = setTimeout(()=>finish('timeout'),timeoutMs);
+    for (const stream of [child.stdout,child.stderr]) stream.on('data',chunk=>{
+      size += chunk.length;
+      if (size > OUTPUT_LIMIT) finish('invalid'); else buffers.push(chunk);
+    });
+    // A wrapper can exit successfully while descendants retain inherited pipes.
+    // Its dedicated POSIX group remains ours; stop it before waiting for close.
+    child.on('exit',killOwned);
+    child.on('error',()=>finish('invalid'));
+    child.on('close',code=>finish(code === 0 ? 'ok' : 'invalid'));
+  });
+}
+function identity(client,output) {
+  const patterns = {
+    codex:[new RegExp(String.raw`^\s*codex(?:-cli)?\s+v?${VERSION}(?:\s|$)`,'im')],
+    claude:[new RegExp(String.raw`^\s*v?${VERSION}\s+\(Claude Code\)(?:\s|$)`,'im'),new RegExp(String.raw`^\s*Claude Code\s+v?${VERSION}(?:\s|$)`,'im')],
+    kimi:[new RegExp(String.raw`^\s*kimi(?:\s+code(?:\s+cli)?)?(?:,?\s+version)?\s+v?${VERSION}(?:\s|$)`,'im')],
+    agy:[new RegExp(String.raw`^\s*(?:Antigravity|agy)\s+v?${VERSION}(?:\s|$)`,'im')],
+  };
+  for (const pattern of patterns[client]) { const match = output.match(pattern); if (match && match[1].length <= 128) return match[1]; }
+  return null;
+}
+async function verify(client,executable,opts) {
+  const version = await probe(executable,'--version',opts);
+  if (version.status !== 'ok') return {status:version.status};
+  const branded = identity(client,version.output);
+  if (branded) return {status:'detected',version:branded};
+  if (client !== 'kimi' && client !== 'agy') return {status:'invalid'};
+  const number = version.output.match(new RegExp(String.raw`^\s*v?${VERSION}(?:\s|$)`));
+  if (!number || number[1].length > 128) return {status:'invalid'};
+  const help = await probe(executable,'--help',opts);
+  if (help.status !== 'ok') return {status:help.status};
+  const known = client === 'kimi' ? /\bKimi (?:Code(?: CLI)?|CLI)\b/i.test(help.output)
+      && (/\busage:\s*kimi\b/i.test(help.output) || /moonshotai\.github\.io\/kimi-code\//i.test(help.output))
+    : /\bAntigravity\b/i.test(help.output) && /\busage:\s*agy\b/i.test(help.output)
+      || /Usage of agy:/i.test(help.output) && /Available subcommands:/i.test(help.output)
+        && ['--agent','--model','--effort'].every(flag=>help.output.includes(flag));
+  return known ? {status:'detected',version:number[1]} : {status:'invalid'};
+}
+
+export async function resolveClient(client,opts = {}) {
+  if (!CLIENTS.includes(client)) throw failure('INVALID_CLIENT');
+  const settings = options(opts);
+  let best = {client,status:'not_found',version:null,origin:null,executable:null};
+  const checked = new Set();
+  for (const candidate of candidates(client,settings)) {
+    const inspected = await inspect(candidate.file);
+    if (inspected.status === 'not_found') continue;
+    if (inspected.status === 'invalid') {
+      if (best.status === 'not_found') best = {...best,status:'invalid',origin:candidate.origin};
+      continue;
+    }
+    if (checked.has(inspected.executable)) continue;
+    checked.add(inspected.executable);
+    const result = await verify(client,inspected.executable,settings);
+    if (result.status === 'detected') return {client,status:'detected',version:result.version,origin:candidate.origin,executable:inspected.executable};
+    if (result.status === 'timeout' || best.status === 'not_found') best = {...best,status:result.status,origin:candidate.origin};
+  }
+  return best;
+}
+export async function detectClients(opts = {}) {
+  return Promise.all(CLIENTS.map(client=>resolveClient(client,opts)));
+}
+export function summarizeDetection(records) {
+  return records.filter(r=>CLIENTS.includes(r?.client)).map(({client,status,version,origin})=>{
+    status = ['detected','not_found','invalid','timeout'].includes(status) ? status : 'invalid';
+    if (status === 'detected' && (typeof version !== 'string' || version.length > 128 || !new RegExp(`^${VERSION}$`).test(version))) status = 'invalid';
+    return {client,status,version:status === 'detected' ? version : null,origin:['path','known_location'].includes(origin) ? origin : null};
+  });
+}

package/src/explicit.mjs

@@ -0,0 +1,82 @@
+// Pure command codec, also embedded in the offline configuration page.
+export const TOOL_FLAGS=Object.freeze({codex:'codex',claude:'claude',kimi:'kimi',antigravity:'agy'});
+export const EXPLICIT_FIELDS=Object.freeze(['roles','max-concurrent',...Object.keys(TOOL_FLAGS),...Object.keys(TOOL_FLAGS).map(flag=>'avoid-'+flag)]);
+const EXPLICIT_MODEL=/^[A-Za-z0-9][A-Za-z0-9._:@/\[\]-]{0,127}$/;
+const EXPLICIT_EFFORTS=['none','minimal','low','medium','high','xhigh','max'];
+function invalidExplicit(){throw Object.assign(new Error('Invalid explicit configuration.'),{code:'INVALID_EXPLICIT_CONFIG'});}
+function explicitList(value,limit){
+ if(typeof value!=='string'||!value.length)invalidExplicit();
+ const list=value.split(',').map(value=>value.trim());
+ if(!list.length||list.length>limit||list.some(value=>!value)||new Set(list).size!==list.length)invalidExplicit();
+ return list;
+}
+
+export function parseExplicitOptions(options,roleIds){
+ if(!options||typeof options!=='object'||Array.isArray(options))invalidExplicit();
+ const fields=Object.getOwnPropertyDescriptors(options);
+ if(Object.entries(fields).some(([key,value])=>!EXPLICIT_FIELDS.includes(key)||value.get||value.set||typeof value.value!=='string'))invalidExplicit();
+ options=Object.fromEntries(Object.entries(fields).map(([key,value])=>[key,value.value]));
+ if(Object.values(fields).reduce((size,value)=>size+value.value.length,0)>65536)invalidExplicit();
+ const requested=explicitList(options.roles,roleIds.length);
+ if(requested.some(role=>!roleIds.includes(role)))invalidExplicit();
+ const roles=roleIds.filter(role=>requested.includes(role)),maxConcurrent=Number(options['max-concurrent']);
+ if(!/^[1-9]\d*$/.test(options['max-concurrent'])||!Number.isInteger(maxConcurrent)||maxConcurrent>32)invalidExplicit();
+ for(const flag of Object.keys(TOOL_FLAGS))if(options['avoid-'+flag]!==undefined&&options[flag]===undefined)invalidExplicit();
+ const clients={};
+ for(const flag of Object.keys(options).filter(flag=>Object.hasOwn(TOOL_FLAGS,flag))){
+  const client=TOOL_FLAGS[flag],choices={};
+  for(const entry of explicitList(options[flag],roles.length)){
+   const at=entry.indexOf('='),role=entry.slice(0,at).trim(),value=entry.slice(at+1).trim();
+   if(at<1||!roles.includes(role)||Object.hasOwn(choices,role))invalidExplicit();
+   let model=value,effort=null;
+   if(client==='agy'){if(!['pro','flash','flash_lite','inherit'].includes(model))invalidExplicit();}
+   else{
+    const colon=value.lastIndexOf(':');if(colon<1)invalidExplicit();
+    model=value.slice(0,colon);const level=value.slice(colon+1);
+    if(level!=='native'&&!EXPLICIT_EFFORTS.includes(level))invalidExplicit();effort=level==='native'?null:level;
+   }
+   if(!EXPLICIT_MODEL.test(model))invalidExplicit();choices[role]={model,effort};
+  }
+  if(Object.keys(choices).length!==roles.length)invalidExplicit();
+  const avoidModels=options['avoid-'+flag]===undefined?[]:explicitList(options['avoid-'+flag],32);
+  if(avoidModels.some(model=>!EXPLICIT_MODEL.test(model)))invalidExplicit();
+  const first=choices[roles[0]];
+  clients[client]={code:{...first},light:{...first},roles:Object.fromEntries(roles.map(role=>[role,choices[role]])),avoidModels};
+ }
+ if(!Object.keys(clients).length)invalidExplicit();
+ return {schemaVersion:1,maxConcurrent,...(roles.length===roleIds.length?{}:{selectedRoles:roles}),clients};
+}
+
+export function explicitOptions(config,roleCatalog){
+ const legacy={worker:'code',reviewer:'code',explorer:'light',routine:'light'};
+ if(!Array.isArray(roleCatalog)||!roleCatalog.length)invalidExplicit();
+ const definitions=roleCatalog.map(role=>typeof role==='string'?{id:role,kind:legacy[role]}:role);
+ if(definitions.some(role=>!role||typeof role.id!=='string'||!['code','light'].includes(role.kind))||new Set(definitions.map(role=>role.id)).size!==definitions.length)invalidExplicit();
+ const roleIds=definitions.map(role=>role.id),kinds=new Map(definitions.map(role=>[role.id,role.kind]));
+ if(!config||config.schemaVersion!==1||!config.clients||typeof config.clients!=='object'||Array.isArray(config.clients))invalidExplicit();
+ const selected=config.selectedRoles??roleIds;
+ if(!Array.isArray(selected)||!selected.length||new Set(selected).size!==selected.length||selected.some(role=>!roleIds.includes(role)))invalidExplicit();
+ const roles=roleIds.filter(role=>selected.includes(role));
+ const options={roles:roles.join(','),'max-concurrent':String(config.maxConcurrent)};
+ for(const [client,preferences]of Object.entries(config.clients)){
+  const flag=Object.keys(TOOL_FLAGS).find(flag=>TOOL_FLAGS[flag]===client);if(!flag||!preferences)invalidExplicit();
+  options[flag]=roles.map(role=>{
+   const selected=preferences.roles?.[role]??preferences[kinds.get(role)];
+   if(!selected||typeof selected.model!=='string'||!EXPLICIT_MODEL.test(selected.model)||(selected.effort!==null&&!EXPLICIT_EFFORTS.includes(selected.effort)))invalidExplicit();
+   if(client==='agy'&&selected.effort!==null)invalidExplicit();
+   return `${role}=${selected.model}${client==='agy'?'':':'+(selected.effort??'native')}`;
+  }).join(',');
+  if(!Array.isArray(preferences.avoidModels)||preferences.avoidModels.some(model=>typeof model!=='string'||!EXPLICIT_MODEL.test(model)))invalidExplicit();
+  if(preferences.avoidModels.length)options['avoid-'+flag]=preferences.avoidModels.join(',');
+ }
+ parseExplicitOptions(options,roleIds);
+ return options;
+}
+
+export function formatExplicitCommand(config,version,roleCatalog){
+ if(typeof version!=='string'||!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(version))throw new Error('Invalid release version.');
+ const options=explicitOptions(config,roleCatalog),quote=value=>"'"+value.replaceAll("'","'\"'\"'")+"'";
+ const lines=[`npx --yes --ignore-scripts --package agent-policy-kit@${version} agent-policy setup`];
+ for(const [name,value]of Object.entries(options))lines.push(`--${name} ${name==='max-concurrent'?value:quote(value)}`);
+ lines.push('--apply');return lines.join(' \\\n  ');
+}