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

package/lib/AgentLauncher.js

@@ -0,0 +1,593 @@
+import Agent from './Agent.js';
+import Cli from './Cli.js';
+import cli from '@j-o-r/cli';   // only for optional direct banner if needed
+import { createAgentLoader } from './agentLoader.js';
+import { configureDefaultHandOffToolset } from './handOffToolset.js';
+
+/**
+ * @module AgentLauncher
+ *
+ * AgentLauncher provides a clean, reusable way to discover, load, run, and
+ * hand-off between "clean" Agent instances (those built with the unified
+ * Agent class and exported via `export default agent;`).
+ *
+ * Primary responsibilities:
+ *   - Discovery: `list()` returns all agents found in the standard locations
+ *     without importing them (now includes a short `desc`).
+ *   - Loading: `load(name)` resolves, imports, and validates a clean Agent.
+ *   - Execution: `run()` handles CLI argument parsing, one-shot calls,
+ *     --help/--info, and interactive CLI startup.
+ *   - In-process handoff: Listens for the 'agent:handoff' event on the active
+ *     Prompt and seamlessly swaps the active agent (including rebinding the
+ *     single long-lived Cli instance when in interactive mode).
+ *
+ * Design highlights:
+ *   - A single Cli instance is kept for the lifetime of the launcher in
+ *     interactive mode. On handoff we call `cli.rebind(...)` instead of
+ *     creating a new Cli (which would duplicate global key handlers).
+ *   - Handoffs are always "fresh": the new agent starts with only its own
+ *     system prompt + the provided context. No conversation history is copied.
+ *   - Same-name "handoff" (self-reset) is supported as a deliberate fresh-start
+ *     / token-reduction mechanism. The current agent is fully replaced with a
+ *     newly loaded instance of itself + the new focused context.
+ *   - Old agents are cleaned up via `destructor()` (removes listeners, aids GC).
+ *   - Works for both interactive CLI and non-interactive / one-shot usage.
+ *
+ * Typical usage (from user code or a thin launcher script):
+ *   ```js
+ *   import { AgentLauncher } from '@j-o-r/hello-dave';
+ *
+ *   const launcher = new AgentLauncher();
+ *   const agents = await launcher.list();
+ *   await launcher.load('code_agent');
+ *   await launcher.run();   // handles argv, one-shot, or interactive CLI
+ *   ```
+ *
+ * Thin launcher example (agents/code_launcher.js style):
+ *   ```js
+ *   import AgentLauncher from '../lib/AgentLauncher.js';
+ *   const launcher = new AgentLauncher();
+ *   await launcher.load('code_agent');
+ *   await launcher.run();
+ *   ```
+ *
+ * Handoff support is automatic once an agent registers the hand_over / load_agent
+ * tools (see lib/handOffToolset.js and agents that call
+ * `toolset.addFrom(API.toolset.generic.handoff, 'hand_over')`).
+ *
+ * @see Agent
+ * @see agentLoader
+ * @see handOffToolset
+ */
+
+/**
+ * The main launcher for clean Agent-based agents.
+ *
+ * @class AgentLauncher
+ */
+class AgentLauncher {
+  /**
+   * The currently active Agent instance (after a successful load()).
+   * @private
+   * @type {Agent|null}
+   */
+  #activeAgent = null;
+
+  /**
+   * The single long-lived Cli instance used in interactive mode.
+   * Rebound (never recreated) on handoff to avoid duplicate global handlers.
+   * @private
+   * @type {Cli|null}
+   */
+  #cli = null;
+
+  /**
+   * Cached name of the active agent (mirrors agent.name).
+   * @private
+   * @type {string}
+   */
+  #name = 'no_name';
+
+  /**
+   * Whether the launcher is currently running in interactive CLI mode.
+   * Set by #startCli() and used to decide handoff behavior (rebind vs. direct trigger).
+   * @private
+   * @type {boolean}
+   */
+  #isInteractive = false;
+
+  /**
+   * Project-aware loader used for list/load/handoff operations.
+   * @private
+   * @type {ReturnType<import('./agentLoader.js').createAgentLoader>}
+   */
+  #loader;
+
+  /**
+   * Creates a new AgentLauncher.
+   *
+   * Pass `{ from: import.meta.url }` from the consuming project to resolve
+   * project-local agents relative to that project's nearest package.json.
+   *
+   * @constructor
+   * @param {import('./agentLoader.js').AgentLoaderOptions} [options={}] - Loader options.
+   *
+   * @example
+   * const launcher = new AgentLauncher({ from: import.meta.url });
+   * await launcher.load('weather_agent');
+   * await launcher.run();
+   */
+  constructor(options = {}) {
+    this.#loader = createAgentLoader(options);
+
+    // Keep the default API.toolset.generic.handoff singleton aligned with this
+    // launcher's discovery context for existing agents that borrow that toolset.
+    configureDefaultHandOffToolset({
+      listAgents: () => this.#loader.listAgents()
+    });
+  }
+
+  /**
+   * List all discoverable agents without loading or executing any of them.
+   *
+   * Performs a lightweight filesystem scan of the configured agent directory.
+   * For each agent it attempts a safe import to extract
+   * a short description (`desc`). Incompatible agents or agents that throw
+   * on import (side effects, top-level `await agent.run()`, missing exports, etc.)
+   * receive `desc: '[ERROR]'`.
+   *
+   * Search location when constructed with `{ from: import.meta.url }`:
+   *   1. <nearest-package-root-from-from>/agents/
+   *
+   * Only files whose basename matches the valid agent name pattern are returned.
+   * See `lib/agentLoader.js` for the exact regex (`validAgentNameRegex`).
+   *
+   * @async
+   * @returns {Promise<Array<{name: string, path: string, desc: string}>>}
+   *   Array of discovered agents. Each object contains:
+   *   - `name`: the agent identifier (basename without `.js`)
+   *   - `path`: absolute path to the agent module on disk
+   *   - `desc`: short description (from the agent's `description` / `call_description`),
+   *             or the literal string `'[ERROR]'` when the agent is incompatible or fails to load
+   *
+   * @example
+   * const launcher = new AgentLauncher();
+   * const list = await launcher.list();
+   * console.log(list);
+   * // [
+   * //   { name: 'code_agent', path: '/.../agents/code_agent.js', desc: 'Main coding expert. Handles implementation...' },
+   * //   { name: 'weather_agent', path: '/.../agents/weather_agent.js', desc: 'Weather Agent: Specialized in current weather...' },
+   * //   { name: 'test_agent', path: '/.../agents/test_agent.js', desc: '[ERROR]' },
+   * //   ...
+   * // ]
+   *
+   * @example
+   * // Just the names + descriptions
+   * const summary = (await launcher.list()).map(a => `${a.name}: ${a.desc}`);
+   *
+   * @see module:agentLoader#listAgents
+   */
+  async list() {
+    return this.#loader.listAgents();
+  }
+
+  /**
+   * Load a clean Agent by name and make it the active agent.
+   *
+   * If `agentName` is omitted, it is read from the first non-flag positional
+   * argument in `process.argv` (after the script name).
+   *
+   * Internally delegates to `loadAgent()` from the agent loader, which:
+   *   - Resolves the module path (same configured directory as `list()`)
+   *   - Dynamically imports the module
+   *   - Extracts the default export (or factory function)
+   *   - Validates that the result is a proper Agent instance
+   *
+   * After successful load, the previous active agent (if any) is cleaned up
+   * via its `destructor()` method, and the new agent's 'agent:handoff' listener
+   * is attached.
+   *
+   * @async
+   * @param {string} [agentName] - Name of the agent to load (e.g. "code_agent").
+   *   Must be a valid agent name (see agentLoader.js for the pattern).
+   *   If omitted, read from process.argv.
+   * @param {Array<any>} [extraArgs=[]] - Optional arguments passed through to
+   *   the agent module if it exports a factory function instead of an instance.
+   * @returns {Promise<AgentLauncher>} Returns `this` for chaining.
+   * @throws {Error} If no agent name can be determined, or if loading/validation fails.
+   *
+   * @example
+   * const launcher = new AgentLauncher();
+   * await launcher.load('code_agent');
+   *
+   * @example
+   * // Load from argv (typical when used from a thin launcher script)
+   * await launcher.load();   // reads first positional from process.argv
+   *
+   * @example
+   * // With extra args for a factory-style agent
+   * await launcher.load('my_agent', ['--debug']);
+   *
+   * @see module:agentLoader#loadAgent
+   * @see #_setActiveAgent
+   */
+  async load(agentName, extraArgs = []) {
+    if (!agentName) {
+      const argv = process.argv.slice(2);
+      const positionals = argv.filter(a => !a.startsWith('--'));
+      agentName = positionals[0];
+    }
+
+    if (!agentName) {
+      throw new Error('No agent name provided. Usage: node ... <agent_name> [message]');
+    }
+
+    const agent = await this.#loader.loadAgent(agentName, extraArgs);
+
+    this.#setActiveAgent(agent);
+    return this;
+  }
+
+  /**
+   * Internal method that replaces the current active agent and wires up
+   * handoff listeners and cleanup.
+   *
+   * Handoff / replacement safety steps:
+   *   1. If an old agent exists, call its `destructor()` (removes all listeners
+   *      from its Prompt and Session).
+   *   2. Swap in the new agent and update the cached name.
+   *   3. Attach the handoff listener on the *new* prompt.
+   *
+   * This method is called by both `load()` (initial load or explicit reload)
+   * and `#handleHandoff()` (during in-process agent handoff or self-reset).
+   *
+   * @private
+   * @param {Agent} agent - A validated Agent instance to make active.
+   *
+   * @see Agent#destructor
+   * @see #_handleHandoff
+   */
+  #setActiveAgent(agent) {
+    if (this.#activeAgent) {
+      // Remove ALL listeners from the previous agent (via its destructor)
+      this.#activeAgent.destructor();
+    }
+
+    this.#activeAgent = agent;
+    this.#name = agent.name;
+
+    // Re-attach handoff listener on the *new* prompt
+    this.#activeAgent.getPrompt().on('agent:handoff', this.#handleHandoff.bind(this));
+  }
+
+  /**
+   * Handles the 'agent:handoff' event emitted by the active Prompt.
+   *
+   * This is the core of in-process agent handoff (including same-agent resets).
+   * It is automatically registered on every newly loaded agent.
+   *
+   * Expected payload shape (matches the `hand_over` / `load_agent` tool schema
+   * in lib/handOffToolset.js):
+   * ```js
+   * {
+   *   agent: 'target_agent_name',   // required (can be same as current for reset)
+   *   context: '...'                // required – everything the new/reset agent needs
+   * }
+   * ```
+   *
+   * Design decision – "fresh handoff":
+   * We deliberately **never** copy previous conversation history into the new
+   * agent. Reasons:
+   *   - Prevents uncontrolled growth of session size / token usage
+   *   - Keeps the new agent's context clean and task-focused
+   *   - Forces explicit, high-quality handoff context from the previous agent
+   *
+   * Same-name handoff (self-reset) is intentionally supported:
+   *   - Useful for token reduction after long/drifted conversations.
+   *   - The agent must provide a genuinely new, focused task in the context.
+   *   - It is **not** intended for meta "reload yourself" commands.
+   *
+   * Context injection behavior:
+   *   - The raw `context` from the tool is wrapped with clear markers before injection.
+   *   - This makes the handoff visible to the user in the CLI.
+   *   - It also gives the receiving agent an explicit signal ("this is a handoff / fresh start")
+   *     instead of blindly treating the previous agent's context string as a direct user command.
+   *   - Different phrasing is used for normal cross-agent handoff vs. same-agent self-reset.
+   *
+   * Behavior differs by mode:
+   *   - Interactive (`#isInteractive && #cli`): Rebind the existing Cli instance
+   *     to the new prompt/session + description (with a handoff/reset banner), then
+   *     call `cli.start(initialContext)`.
+   *   - Non-interactive / one-shot: Inject context (if any) as a non-sticky
+   *     user message and trigger a request on the new prompt.
+   *
+   * @async
+   * @private
+   * @param {Object} [payload={}] - Handoff payload from the tool.
+   * @param {string} payload.agent - Name of the target agent to load (may equal current name).
+   * @param {string} [payload.context] - Context/instructions for the new/reset agent.
+   *
+   * @see module:handOffToolset
+   * @see #_setActiveAgent
+   */
+  async #handleHandoff(payload = {}) {
+    const target = payload.agent || payload.target || payload.name;
+
+    if (!target || typeof target !== 'string') {
+      console.warn('[AgentLauncher] Handoff event received without a valid agent name');
+      return;
+    }
+
+    const currentName = this.#name || (this.#activeAgent && this.#activeAgent.name);
+    const isSelfReset = currentName && target === currentName;
+
+    let context = payload.context;
+    const hasContext = context && typeof context === 'string' && context.trim().length > 0;
+
+    // Wrap the raw context string that came from the previous agent's hand_over / load_agent tool call.
+    // Reasons:
+    //   - Makes the injected context clearly visible to the human in the terminal (as a user message).
+    //   - Gives the newly loaded agent an explicit, intentional signal instead of silently
+    //     treating the previous agent's internal context as a direct user instruction.
+    //   - Allows different messaging for normal handoff vs. deliberate same-agent "fresh start" reset.
+    if (hasContext) {
+      if (isSelfReset) {
+        // Self-reset / fresh-start case (same agent name): emphasize clean slate + new focused task.
+        context = `---fresh-start-context\n${context}\n---\n\nFresh start. Proceed with the task below.`;
+      } else {
+        // Normal cross-agent handoff: signal that this is a deliberate transfer to a (different) specialist.
+        context = `---handover-context\n${context}\n---\n\nConfirm handover and proceed with the task below.`;
+      }
+    }
+
+    if (isSelfReset) {
+      console.log(`[AgentLauncher] Self-reset requested for "${target}" (fresh context, no history).`);
+    } else {
+      console.log(`[AgentLauncher] Handoff requested → loading new agent: "${target}"`);
+    }
+
+    let newAgent;
+    try {
+      newAgent = await this.#loader.loadAgent(target);
+    } catch (err) {
+      console.error(`[AgentLauncher] Failed to load handoff target "${target}":`, err.message);
+      return;
+    }
+
+    // Replace the active agent completely.
+    // #setActiveAgent will:
+    //   - call destructor on the old agent (removes listeners, helps GC)
+    //   - swap prompt + session
+    //   - re-attach the handoff listener
+    this.#setActiveAgent(newAgent);
+
+    if (isSelfReset) {
+      console.log(`[AgentLauncher] Agent reset complete. Fresh instance of ${newAgent.name} now active.`);
+    } else {
+      console.log(`[AgentLauncher] Active agent replaced. Now running: ${newAgent.name || target}`);
+    }
+
+    if (this.#isInteractive && this.#cli) {
+      console.log('[AgentLauncher] Rebinding existing CLI to the new/reset agent (no new Cli instance)...');
+
+      const banner = isSelfReset
+        ? `\n\n=== AGENT RESET (FRESH START) ===\nResetting: ${newAgent.name}\n(fresh state — only its own system prompt + new focused context)\nPrevious conversation history was discarded to reduce tokens.\n========================\n`
+        : `\n\n=== AGENT HANDOFF ===\nNow running: ${newAgent.name}\n(fresh state — only its own system prompt + injected context)\nNo previous conversation history was transferred.\n========================\n`;
+
+      const newDescription = banner + (newAgent.cliIntro || newAgent.description || newAgent.name || '');
+
+      this.#cli.rebind(
+        newAgent.getPrompt(),
+        newAgent.getSession(),
+        newDescription
+      );
+
+      const initialContext = hasContext ? context : '';
+
+      setTimeout(() => {
+        this.#cli.start(initialContext);
+      }, 120);
+    } else {
+      // Non-interactive / one-shot path
+      if (hasContext) {
+        try {
+          const newPrompt = newAgent.getPrompt();
+          newPrompt.add('user', context, false);
+        } catch (err) {
+          console.warn('[AgentLauncher] Failed to inject handoff/reset context (non-interactive):', err.message);
+        }
+      } else {
+        console.log('[AgentLauncher] No context provided with handoff/reset. New agent starts with only its system prompt.');
+      }
+
+      try {
+        await newAgent.getPrompt().triggerRequest();
+      } catch (err) {
+        console.error('[AgentLauncher] Error triggering request after handoff/reset:', err.message);
+      }
+    }
+  }
+
+  /**
+   * Start the interactive CLI for the currently loaded agent.
+   *
+   * Creates a single Cli instance (if not already present) bound to the
+   * active agent's Prompt and Session, then calls `cli.start()` after a
+   * short delay (to allow the terminal to be ready).
+   *
+   * Sets the internal `#isInteractive` flag, which affects handoff behavior.
+   *
+   * @private
+   * @throws {Error} If there is no active agent (call `load()` first).
+   *
+   * @see Cli
+   * @see #run
+   */
+  #startCli() {
+    this.#isInteractive = true;
+    const agent = this.#activeAgent;
+    if (!agent) {
+      throw new Error('AgentLauncher has no active agent. Call load() first.');
+    }
+
+    const prompt = agent.getPrompt();
+    const session = agent.getSession();
+
+    const description = (agent.cliIntro !== '') ? agent.cliIntro : agent.description;
+
+    this.#cli = new Cli({
+      prompt,
+      session,
+      description
+    });
+
+    setTimeout(() => {
+      this.#cli.start();
+    }, 1000);
+  }
+
+  /**
+   * Main entry point. Orchestrates argument parsing and execution mode.
+   *
+   * Behavior (checked in this order):
+   *   1. `--help`   → Print usage and return.
+   *   2. `--info`   → Print agent.info() (or raw agent) and return.
+   *   3. If no active agent → automatically call `load()` (reads from argv).
+   *   4. One-shot mode: if a second positional argument exists after the agent
+   *      name, treat the rest of the line as a message and call
+   *      `activeAgent.directCall(message)`.
+   *   5. Default: start interactive CLI via `#startCli()`.
+   *
+   * @async
+   * @returns {Promise<any>} In one-shot mode, returns the result of directCall.
+   *   In other modes, returns undefined.
+   *
+   * @example
+   * // From a thin launcher script that already called load()
+   * await launcher.run();
+   *
+   * @example
+   * // One-shot usage (message after agent name)
+   * // node ... code_agent "Refactor the Session class"
+   * const result = await launcher.run();
+   *
+   * @see #load
+   * @see #_startCli
+   */
+  async run() {
+    const args = process.argv.slice(2);
+
+    if (args.includes('--help')) {
+      console.log('Usage: node utils/launch_agent.js <agent_name> [message] [--info] [--help]');
+      console.log('');
+      console.log('  launcher.run() starts the interactive CLI (after load()).');
+      console.log('  A message after the agent name performs a one-shot directCall.');
+      console.log('');
+      console.log('  --info   Print agent info and exit');
+      return;
+    }
+
+    if (args.includes('--info')) {
+      const agent = this.#activeAgent;
+      if (agent && typeof agent.info === 'function') {
+        console.log(agent.info());
+      } else {
+        console.log(agent || 'No active agent');
+      }
+      return;
+    }
+
+    if (!this.#activeAgent) {
+      await this.load();
+    }
+
+    // One-shot: second positional after agent name
+    const positionals = args.filter(a => !a.startsWith('--'));
+    const message = positionals.length > 1 ? positionals.slice(1).join(' ') : null;
+
+    if (message) {
+      const result = await this.#activeAgent.directCall(message);
+      if (result != null) console.log(result);
+      return result;
+    }
+
+    // Default: start interactive CLI
+    this.#startCli();
+  }
+
+  // ────────────────────────────────────────────────────────────────────────────
+  // Public accessors
+  // ────────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Returns the currently active Agent instance (or null if none loaded).
+   *
+   * @returns {Agent|null}
+   */
+  getActiveAgent() {
+    return this.#activeAgent;
+  }
+  /**
+   * Directly assign an already-created Agent instance as the active agent.
+   *
+   * This is the programmatic alternative to `load()`. Use it when the caller
+   * has constructed an agent manually, or when testing an agent module that is
+   * outside the configured agent loader search paths.
+   *
+   * The previous active agent, if any, is cleaned up via `destructor()`. The new
+   * agent becomes the launcher's active agent and has the launcher's
+   * `agent:handoff` listener attached to its Prompt, just like agents loaded via
+   * `load()`.
+   *
+   * The supplied agent is assumed to be a valid `Agent` instance. Unlike
+   * `load()`, this method does not resolve, import, or validate an agent module
+   * through the configured agent loader.
+   *
+   * @param {Agent} newAgent - Existing Agent instance to make active.
+   * @returns {AgentLauncher} Returns `this` for chaining.
+   *
+   * @example
+   * const launcher = new AgentLauncher();
+   * launcher.setActiveAgent(agent);
+   * await launcher.run();
+   *
+   * @see #load
+   * @see #getActiveAgent
+   */
+  setActiveAgent(newAgent) {
+    this.#setActiveAgent(newAgent);
+    return this;
+  }
+
+  /**
+   * Returns the Prompt belonging to the active agent (or null).
+   *
+   * Useful for advanced scenarios where you need direct access to the
+   * underlying prompt (e.g. to listen to events manually).
+   *
+   * @returns {import('./Prompt.js').default|null}
+   */
+  getPrompt() {
+    return this.#activeAgent?.getPrompt() || null;
+  }
+
+  /**
+   * Returns the Session belonging to the active agent (or null).
+   *
+   * @returns {import('./Session.js').default|null}
+   */
+  getSession() {
+    return this.#activeAgent?.getSession() || null;
+  }
+
+  /**
+   * The name of the currently active agent (or 'no_name' if none loaded).
+   *
+   * @type {string}
+   */
+  get name() {
+    return this.#name;
+  }
+}
+
+export default AgentLauncher;