@j-o-r/hello-dave 0.1.1 → 0.1.4

package/lib/agentLoader.js

@@ -0,0 +1,369 @@
+/**
+ * lib/agentLoader.js
+ *
+ * Internal loader and discovery utilities for clean Agent-based agents.
+ *
+ * Supports both default framework discovery and caller-bound discovery via:
+ *
+ *   const loader = createAgentLoader({ from: import.meta.url });
+ *
+ * Search / discovery order:
+ *   - When `from` is supplied: only <nearest-package-root-from-from>/agents
+ *   - Otherwise: only <framework-package-root>/agents
+ *
+ * @module agentLoader
+ */
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Valid agent name pattern.
+ *
+ * @const {RegExp}
+ */
+const validAgentNameRegex = /^[a-z0-9_]{2,}$/;
+
+/**
+ * @typedef {object} AgentLoaderOptions
+ * @property {string|URL} [from] - Caller module URL/path, usually caller import.meta.url.
+ * @property {(string|URL)[]} [agentDirs] - Explicit agent directories. Used only when `from` is not supplied.
+ */
+
+/**
+ * Return true when a child path is the base path or nested under it.
+ *
+ * @param {string} base - Real absolute base directory.
+ * @param {string} child - Real absolute candidate path.
+ * @returns {boolean} Whether child is inside base.
+ */
+const isInsidePath = (base, child) => {
+  const relative = path.relative(base, child);
+  return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+};
+
+/**
+ * Convert a filesystem path or file URL to an absolute filesystem path.
+ *
+ * @param {string|URL} value - Path or file URL.
+ * @returns {string} Absolute filesystem path.
+ */
+function toPath(value) {
+  if (value instanceof URL) return fileURLToPath(value);
+  if (typeof value === 'string' && value.startsWith('file:')) return fileURLToPath(value);
+  return path.resolve(String(value));
+}
+
+/**
+ * Return true if a path exists and is readable.
+ *
+ * @param {string} targetPath - Filesystem path to check.
+ * @returns {Promise<boolean>} True when the path is readable.
+ */
+async function canRead(targetPath) {
+  try {
+    await fs.access(targetPath, fs.constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Find the nearest package root by walking upward until package.json is found.
+ *
+ * @param {string|URL} from - Starting file path, directory path, or file URL.
+ * @returns {Promise<string|null>} Package root path, or null.
+ */
+export async function findNearestPackageRoot(from) {
+  if (!from) return null;
+
+  let currentPath = toPath(from);
+
+  try {
+    const stat = await fs.stat(currentPath);
+    if (stat.isFile()) currentPath = path.dirname(currentPath);
+  } catch {
+    currentPath = path.dirname(currentPath);
+  }
+
+  let currentDir = path.resolve(currentPath);
+
+  while (true) {
+    const packageJsonPath = path.join(currentDir, 'package.json');
+    if (await canRead(packageJsonPath)) return currentDir;
+
+    const parentDir = path.dirname(currentDir);
+    if (parentDir === currentDir) return null;
+    currentDir = parentDir;
+  }
+}
+
+/**
+ * Push a directory into a list if present.
+ *
+ * @param {string[]} dirs - Directory accumulator.
+ * @param {string|null|undefined} dir - Directory candidate.
+ * @returns {void}
+ */
+function pushDir(dirs, dir) {
+  if (dir) dirs.push(path.resolve(dir));
+}
+
+/**
+ * Build ordered agent directory candidates.
+ *
+ * When `options.from` is supplied, discovery is intentionally strict: the only
+ * directory searched is the `agents` directory under the nearest package root
+ * found from that caller module URL/path.
+ *
+ * @param {AgentLoaderOptions} [options={}] - Loader options.
+ * @returns {Promise<string[]>} Absolute agent directory candidates.
+ */
+export async function getAgentDirs(options = {}) {
+  const dirs = [];
+
+  if (options.from) {
+    const callerRoot = await findNearestPackageRoot(options.from);
+    if (!callerRoot) {
+      throw new Error(`Could not find package.json from ${String(options.from)}`);
+    }
+
+    return [path.join(callerRoot, 'agents')];
+  }
+
+  if (Array.isArray(options.agentDirs)) {
+    for (const dir of options.agentDirs) pushDir(dirs, toPath(dir));
+    return [...new Set(dirs)];
+  }
+
+  const frameworkRoot = await findNearestPackageRoot(import.meta.url);
+  return [frameworkRoot ? path.join(frameworkRoot, 'agents') : path.resolve(__dirname, '..', 'agents')];
+}
+
+/**
+ * Build roots allowed for direct path loading.
+ *
+ * @param {AgentLoaderOptions} [options={}] - Loader options.
+ * @returns {Promise<string[]>} Real absolute allowed roots.
+ */
+async function getAllowedDirectPathRoots(options = {}) {
+  const roots = [];
+
+  if (options.from) {
+    const callerRoot = await findNearestPackageRoot(options.from);
+    if (!callerRoot) {
+      throw new Error(`Could not find package.json from ${String(options.from)}`);
+    }
+    roots.push(callerRoot);
+  } else if (Array.isArray(options.agentDirs)) {
+    for (const dir of options.agentDirs) roots.push(toPath(dir));
+  } else {
+    const frameworkRoot = await findNearestPackageRoot(import.meta.url);
+    roots.push(frameworkRoot || path.resolve(__dirname, '..'));
+  }
+
+  const realRoots = [];
+  for (const root of roots) {
+    try {
+      realRoots.push(await fs.realpath(root));
+    } catch {}
+  }
+
+  return [...new Set(realRoots)];
+}
+
+/**
+ * Resolve a direct `.js` agent path supplied on the command line.
+ *
+ * @param {string} agentPath - Relative or absolute path to an agent module.
+ * @param {AgentLoaderOptions} [options={}] - Loader options.
+ * @returns {Promise<string|null>} Real absolute path, or null when not path-like.
+ * @throws {Error} If the path-like spec is invalid or unsafe.
+ */
+const resolveDirectAgentPath = async (agentPath, options = {}) => {
+  if (!agentPath.includes('/') && !agentPath.includes('\\')) return null;
+
+  const resolved = path.resolve(process.cwd(), agentPath);
+  const parsed = path.parse(resolved);
+  if (parsed.ext !== '.js' || !validAgentNameRegex.test(parsed.name)) {
+    throw new Error(
+      `Invalid agent path "${agentPath}". Direct agent paths must end in <valid_agent_name>.js, ` +
+      `where the basename matches /^[a-z0-9_]{2,}$/ (for example agents/gpt_agent.js).`
+    );
+  }
+
+  const realFile = await fs.realpath(resolved);
+  const allowedRoots = await getAllowedDirectPathRoots(options);
+  if (!allowedRoots.some(root => isInsidePath(root, realFile))) {
+    throw new Error(`Agent path "${agentPath}" escapes the configured project/package roots`);
+  }
+
+  await fs.access(realFile, fs.constants.R_OK);
+  return realFile;
+};
+
+/**
+ * Discover all available agents by performing a lightweight filesystem scan.
+ *
+ * @param {AgentLoaderOptions} [options={}] - Loader options.
+ * @returns {Promise<Array<{name: string, path: string, desc: string}>>}
+ *   Array of discovered agents.
+ */
+export async function listAgents(options = {}) {
+  const dirCandidates = await getAgentDirs(options);
+
+  /** @type {Map<string, {name: string, path: string, desc: string}>} */
+  const found = new Map();
+
+  for (const dir of dirCandidates) {
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.js')) continue;
+
+        const base = entry.name.replace(/\.js$/, '');
+        if (!validAgentNameRegex.test(base) || found.has(base)) continue;
+
+        const fullPath = path.join(dir, entry.name);
+        let desc = '[ERROR]';
+
+        try {
+          const mod = await import(pathToFileURL(fullPath).href);
+          let agent = mod.default ?? mod.agent ?? mod;
+
+          if (typeof agent === 'function') {
+            try {
+              agent = await agent();
+            } catch {
+              agent = null;
+            }
+          }
+
+          if (agent && typeof agent === 'object') {
+            if (typeof agent.description === 'string' && agent.description.trim()) {
+              desc = agent.description.trim();
+            } else if (typeof agent.call_description === 'string' && agent.call_description.trim()) {
+              desc = agent.call_description.trim();
+            }
+          }
+
+          if ((!desc || desc === '[ERROR]') && typeof mod.call_description === 'string' && mod.call_description.trim()) {
+            desc = mod.call_description.trim();
+          }
+
+          if (!desc || typeof desc !== 'string' || desc.length === 0) {
+            desc = '[ERROR]';
+          } else if (desc.length > 180) {
+            desc = `${desc.slice(0, 177).trimEnd()}...`;
+          }
+        } catch {
+          desc = '[ERROR]';
+        }
+
+        found.set(base, { name: base, path: fullPath, desc });
+      }
+    } catch {
+      // Directory does not exist or is not readable — silently skip.
+    }
+  }
+
+  return Array.from(found.values());
+}
+
+/**
+ * Resolve the absolute path to an agent module by name.
+ *
+ * @param {string} agentName - The agent identifier or safe direct path.
+ * @param {AgentLoaderOptions} [options={}] - Loader options.
+ * @returns {Promise<string>} Absolute path to the matching .js file.
+ */
+export async function resolveAgentPath(agentName, options = {}) {
+  if (!agentName || typeof agentName !== 'string') {
+    throw new Error('agentName is required');
+  }
+
+  const directPath = await resolveDirectAgentPath(agentName, options);
+  if (directPath) return directPath;
+
+  if (!validAgentNameRegex.test(agentName)) {
+    throw new Error(
+      `Invalid agentName "${agentName}". ` +
+      `Must match /^[a-z0-9_]{2,}$/ (lowercase letters a-z, digits 0-9, and underscore _ only; min 2 characters). ` +
+      `Or pass a safe direct path like agents/gpt_agent.js.`
+    );
+  }
+
+  const fileName = `${agentName}.js`;
+  const dirCandidates = await getAgentDirs(options);
+  const candidates = dirCandidates.map(dir => path.join(dir, fileName));
+
+  for (const p of candidates) {
+    if (await canRead(p)) return p;
+  }
+
+  const searched = candidates.map(c => `  - ${c}`).join('\n');
+  throw new Error(`Agent "${agentName}" not found.\nSearched:\n${searched}`);
+}
+
+/**
+ * Load (import + validate) a clean Agent instance by name.
+ *
+ * @param {string} agentName - Agent identifier to load.
+ * @param {Array<any>} [extraArgs=[]] - Optional factory arguments.
+ * @param {AgentLoaderOptions} [options={}] - Loader options.
+ * @returns {Promise<import('./Agent.js').default>} Loaded Agent instance.
+ */
+export async function loadAgent(agentName, extraArgs = [], options = {}) {
+  const resolved = await resolveAgentPath(agentName, options);
+  const mod = await import(pathToFileURL(resolved).href);
+  let agent = mod.default ?? mod.agent ?? mod;
+
+  if (!agent) {
+    throw new Error(`Module ${resolved} did not export a usable default.`);
+  }
+
+  if (typeof agent === 'function') {
+    agent = await agent(...extraArgs);
+  }
+
+  if (agent && typeof agent === 'object') {
+    try {
+      if (Object.isExtensible(agent)) {
+        agent.__loadedFrom = resolved;
+        agent.__loadedAs = path.parse(resolved).name;
+        if (extraArgs.length) agent.__extraArgs = extraArgs;
+      }
+    } catch {}
+  }
+
+  if (!agent || typeof agent.getPrompt !== 'function' || typeof agent.name !== 'string') {
+    throw new Error(`Loaded "${agentName}" is not a valid Agent instance. Use clean Agent-based agents for handoff.`);
+  }
+
+  return agent;
+}
+
+/**
+ * Create an isolated agent loader bound to a caller/project context.
+ *
+ * @param {AgentLoaderOptions} [options={}] - Loader options.
+ * @returns {{
+ *   getAgentDirs: () => Promise<string[]>,
+ *   listAgents: () => Promise<Array<{name: string, path: string, desc: string}>>,
+ *   resolveAgentPath: (agentName: string) => Promise<string>,
+ *   loadAgent: (agentName: string, extraArgs?: Array<any>) => Promise<import('./Agent.js').default>
+ * }} Configured loader API.
+ */
+export function createAgentLoader(options = {}) {
+  return {
+    getAgentDirs: () => getAgentDirs(options),
+    listAgents: () => listAgents(options),
+    resolveAgentPath: (agentName) => resolveAgentPath(agentName, options),
+    loadAgent: (agentName, extraArgs = []) => loadAgent(agentName, extraArgs, options)
+  };
+}