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

package/lib/Agent.js

@@ -0,0 +1,271 @@
+import Prompt from './Prompt.js';
+import Session from './Session.js';
+import ToolSet from './ToolSet.js';
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+/**
+ * @typedef {import("./API/x.ai/responses.js").XAIOptions} XAIOptions
+ * @typedef {import("./API/openai.com/reponses/text.js").OAOptions} OAOptions
+ * @typedef {import("./API/anthropic.com/text.js").ANTHOptions} ANTHOptions
+ */
+
+/**
+ * @typedef {Object} AgentConfig
+ * @property {string} prompt - Initial system prompt (can be loaded via Agent.loadPrompt for extended agents)
+ * @property {Function} api - Chat adaptor function from API.chat.* (e.g. API.chat.xai)
+ * @property {XAIOptions|OAOptions|Object} [options] - Model options
+ * @property {number} [contextWindow=300000]
+ * @property {"auto"|"required"|null} [toolsetMode]
+ * @property {boolean} [debug=false]
+ * @property {string} [secret] - Plain text secret (will be base64 encoded internally)
+ * @property {string} [cachePath=".cache/@j-o-r/hello-dave"]
+ * @property {string} call_name - Agent/tool name (required). Must match /^[a-z0-9_]{2,}$/. Recommended: derive via Agent.deriveCallName(import.meta.url)
+ * @property {string} call_description - Description for the tool (required, non-empty string)
+ * @property {string} [cliIntro] - CLI intro message (stored for future use)
+ * @property {boolean} [debug=true] - show debug information
+ */
+
+/** @const {RegExp} Validates agent names (lowercase a-z0-9_, min 2 chars). No uppercase, no hyphens. */
+const validNameRegex = /^[a-z0-9_]{2,}$/;
+
+class Agent {
+  /** @private @type {Prompt} */
+  #prompt;
+  /** @private @type {Session} */
+  #sessionStorage;
+  /** @private @type {string} */
+  #name = 'agent';
+  /** @private @type {string} */
+  #secret = '';
+  /** @private @type {string} */
+  #cachePath = '.cache/hello-dave';
+  /** @private @type {boolean} */
+  #debug = true;
+  /** @private @type {string} */
+  #model = '';
+  /** @private @type {number} */
+  #contextWindow = 0;
+  /** @private @type {string} */
+  #sysPrompt = '';
+  /** @private @type {string} */
+  #description = '';
+  /** @private @type {string} */
+  #cliIntro = '';
+
+  /**
+   * Creates a new Agent instance.
+   * Minimal core skeleton (no run(), no CLI parsing, no server/client logic).
+   * All configuration is passed via the constructor.
+   * Designed to be used by AgentLauncher and for clean handoff support.
+   *
+   * @param {AgentConfig} config
+   */
+  constructor(config = {}) {
+    const {
+      prompt,
+      api,
+      options = null,
+      contextWindow = 300000,
+      toolsetMode = null,
+      debug = true,
+      secret = "",
+      cachePath,
+      call_name,
+      call_description,
+      cliIntro
+    } = config;
+
+    if (secret && typeof secret === "string") {
+      this.#secret = Buffer.from(secret).toString("base64");
+    }
+
+    this.#cachePath = cachePath || this.#cachePath;
+    this.#sysPrompt = prompt;
+    this.#contextWindow = contextWindow;
+    if (options?.model) this.#model = options.model;
+
+    // call_name is required and becomes the agent name
+    if (!call_name || typeof call_name !== "string" || !validNameRegex.test(call_name)) {
+      throw new Error(`"call_name" is required and must match /^[a-z0-9_]{2,}$/ (lowercase letters, digits, underscore only; min 2 chars). File must be <name>.js.`);
+    }
+    this.#name = call_name;   // name === call_name
+
+    // call_description is required and must be non-empty
+    if (!call_description || typeof call_description !== "string" || call_description.trim() === "") {
+      throw new Error(`"call_description" is required and must be a non-empty string`);
+    }
+    this.#description = call_description;
+
+    if (cliIntro !== undefined) {
+      this.#cliIntro = cliIntro;
+    }
+
+    let toolset;
+    if (toolsetMode) {
+      toolset = new ToolSet(toolsetMode);
+    }
+    if (debug) {
+      this.#debug = true;
+    }
+
+    this.#prompt = new Prompt(contextWindow);
+    this.#sessionStorage = new Session(this.#name, this.#prompt, this.#cachePath);
+    this.#prompt.add("system", prompt, true);
+    this.#prompt.setAdaptor(api, toolset, options);
+    return this;
+  }
+
+  // ──────────────────────────────────────────────────────────────────────────
+  // Static helpers for consistent agent authoring
+  // ──────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Derives the canonical `call_name` from the agent's own filename.
+   * This makes the **filename the single source of truth** for the agent name.
+   *
+   * Recommended usage in every agent:
+   *   const call_name = Agent.deriveCallName(import.meta.url);
+   *
+   * @param {string} importMetaUrl - Always pass `import.meta.url` from the agent module.
+   * @returns {string} The derived call_name (basename without extension)
+   * @throws {Error} If the derived name is invalid.
+   */
+  static deriveCallName(importMetaUrl) {
+    if (!importMetaUrl || typeof importMetaUrl !== 'string') {
+      throw new Error('Agent.deriveCallName(import.meta.url) is required. Pass import.meta.url from your agent file.');
+    }
+
+    const filePath = fileURLToPath(importMetaUrl);
+    const parsed = path.parse(filePath);
+    const name = parsed.name; // e.g. "code_agent" from "code_agent.js"
+
+    if (!validNameRegex.test(name)) {
+      throw new Error(
+        `Derived call_name "${name}" (from filename "${parsed.base}") is invalid.\n` +
+        `Agent filenames must match /^[a-z0-9_]{2,}$/ (lowercase a-z, 0-9, underscore only, min 2 chars).`
+      );
+    }
+
+    return name;
+  }
+
+  /**
+   * Loads the external system prompt for "extended" agents.
+   *
+   * Looks for a pure Markdown sibling prompt file in the same directory as the
+   * calling agent. The filename is always `<call_name>.prompt.md`, where
+   * `call_name` is derived from the calling agent filename.
+   *
+   * Two common patterns:
+   *
+   * 1. Simple one-file agent (internal prompt):
+   *    const prompt = `You are ...`;   // define inline
+   *
+   * 2. Extended agent (external Markdown prompt):
+   *    const prompt = await Agent.loadPrompt(import.meta.url);
+   *    // Automatically loads ./<call_name>.prompt.md as UTF-8 text.
+   *
+   * @param {string} importMetaUrl - Pass `import.meta.url` from the agent module.
+   * @param {Object} [options]
+   * @param {boolean} [options.required=true] - If true, throws when no external prompt file is found.
+   * @param {string|null} [options.fallback=null] - Prompt to return if no external file is found and required=false.
+   * @returns {Promise<string>} The Markdown prompt content (trimmed).
+   * @throws {Error} When required=true and no prompt file can be found, or when the prompt file cannot be read.
+   */
+  static async loadPrompt(importMetaUrl, options = {}) {
+    const { required = true, fallback = null } = options;
+
+    const call_name = this.deriveCallName(importMetaUrl);
+
+    const filePath = fileURLToPath(importMetaUrl);
+    const dir = path.dirname(filePath);
+    const promptPath = path.join(dir, `${call_name}.prompt.md`);
+
+    if (fs.existsSync(promptPath)) {
+      try {
+        const content = fs.readFileSync(promptPath, 'utf8');
+        return content.trim();
+      } catch (err) {
+        throw new Error(
+          `Failed to load prompt for "${call_name}" from ${promptPath}: ${err.message}`
+        );
+      }
+    }
+
+    if (required) {
+      throw new Error(
+        `External prompt file not found for agent "${call_name}".\n` +
+        `Expected: ${promptPath}\n\n` +
+        `For "simple" one-file agents, define the prompt as a template literal inside the .js file instead.\n` +
+        `For "extended" agents, create a pure Markdown sibling file named ${call_name}.prompt.md.`
+      );
+    }
+
+    return fallback;
+  }
+
+  // ──────────────────────────────────────────────────────────────────────────
+
+  /**
+   * @returns {string}
+   */
+  info() {
+    const sys = this.#sysPrompt;
+    const sessionInfo = this.#sessionStorage.info();
+    const promptInfo = this.#prompt.info();
+    const info = `\nSESSION:\n${sessionInfo}\n\nPROMPT:\n\----\n${sys}\n\----\n${promptInfo}\n\nDESCRIPTION:\n${this.#description}`;
+    return info;
+  }
+
+  /**
+   * Direct synchronous call to the underlying Prompt.
+   * @param {string} input - User input.
+   * @returns {Promise<string>} Response.
+   */
+  async directCall(input) {
+    const res = await this.#prompt.call(input);
+    return res;
+  }
+
+  /** @returns {Prompt} Underlying Prompt instance. */
+  getPrompt() { return this.#prompt; }
+
+  /** @returns {Session} Underlying Session instance (for CLI and handoff support). */
+  getSession() { return this.#sessionStorage; }
+
+  /** @returns {ToolSet|null} Toolset if configured. */
+  getToolset() { return this.#prompt.toolset; }
+
+  /** @returns {string} Agent name (from call_name). */
+  get name() { return this.#name; }
+
+  /** @returns {string} Agent description. */
+  get description() { return this.#description; }
+
+  /** @returns {string} CLI intro (if provided). */
+  get cliIntro() { return this.#cliIntro; }
+
+  /** @returns {string} Base64-encoded secret (if provided). */
+  get secret() { return this.#secret; }
+
+  /** @returns {string} Cache path. */
+  get cachePath() { return this.#cachePath; }
+
+  /** @returns {number} Context window size. */
+  get contextWindow() { return this.#contextWindow; }
+
+  /** @returns {string} Model name (if set via options). */
+  get model() { return this.#model; }
+
+  destructor() {
+    try {
+      this.getPrompt().removeAllListeners();
+    } catch (e) {};
+  }
+
+}
+
+export default Agent;

package/lib/Agent.js.old

@@ -0,0 +1,284 @@
+import { Prompt, Cli, AgentClient, AgentServer, API, ToolSet, Session, env } from './index.js';
+
+/**
+ * @typedef {import("./API/x.ai/responses.js").XAIOptions} XAIOptions
+ * @typedef {import("./API/openai.com/reponses/text.js").OAOptions} OAOptions
+ * @typedef {import("./API/anthropic.com/text.js").ANTHOptions} ANTHOptions
+ */
+
+/**
+ * @typedef {Object} AgentConfig
+ * @property {string} prompt - Initial system prompt
+ * @property {Function} api - Chat adaptor function from API.chat.* (e.g. API.chat.xai)
+ * @property {XAIOptions|OAOptions|Object} [options] - Model options
+ * @property {number} [contextWindow=300000]
+ * @property {"auto"|"required"|null} [toolsetMode]
+ * @property {boolean} [debug=false]
+ * @property {string} [secret] - Plain text secret (will be base64 encoded internally)
+ * @property {string} [cachePath=".cache/hello-dave"]
+ * @property {string} call_name - Tool name (required, validated /^[a-z_0-9]{2,}$/)
+ * @property {string} call_description - Description for the tool (required, non-empty string)
+ * @property {string} [cliIntro] - CLI intro message
+ * @property {boolean} [debug=true] - show debug information
+ */
+
+/** @const {RegExp} Validates agent/tool names (lowercase a-z0-9_, min 2 chars). */
+const validNameRegex = /^[a-z_0-9]{2,}$/;
+
+class Agent {
+  /** @private @type {Prompt} */
+  #prompt;
+  /** @private @type {Session} */
+  #sessionStorage;
+  /** @private @type {string} */
+  #name = 'agent';
+  /** @private @type {string} */
+  #secret = '';
+  /** @private @type {string} */
+  #cachePath = '.cache/hello-dave';
+  /** @private @type {boolean} */
+  #debug = true;
+  /** @private @type {string} */
+  #model = '';
+  /** @private @type {number} */
+  #contextWindow = 0;
+  /** @private @type {string} */
+  #sysPrompt = '';
+  /** @private @type {string} */
+  #description = '';
+  /** @private @type {string} */
+  #cliIntro = '';
+
+  /**
+   * Creates a new Agent instance.
+   * All configuration is passed via the constructor.
+   *
+   * @param {AgentConfig} config
+   */
+  constructor(config = {}) {
+    const {
+      prompt,
+      api,
+      options = null,
+      contextWindow = 300000,
+      toolsetMode = null,
+      debug = true,
+      secret = "",
+      cachePath,
+      call_name,
+      call_description,
+      cliIntro
+    } = config;
+
+
+    if (secret && typeof secret === "string") {
+      this.#secret = Buffer.from(secret).toString("base64");
+    }
+
+    this.#cachePath = cachePath || this.#cachePath;
+    this.#sysPrompt = prompt;
+    this.#contextWindow = contextWindow;
+    if (options?.model) this.#model = options.model;
+
+    // call_name is required and becomes the agent name
+    if (!call_name || typeof call_name !== "string" || !validNameRegex.test(call_name)) {
+      throw new Error(`"call_name" is required and must match /^[a-z_0-9]{2,}$/`);
+    }
+    this.#name = call_name;   // name === call_name
+
+    // call_description is required and must be non-empty
+    if (!call_description || typeof call_description !== "string" || call_description.trim() === "") {
+      throw new Error(`"call_description" is required and must be a non-empty string`);
+    }
+    this.#description = call_description;
+
+    if (cliIntro !== undefined) {
+      this.#cliIntro = cliIntro;
+    }
+
+    let toolset;
+    if (toolsetMode) {
+      toolset = new ToolSet(toolsetMode);
+    }
+    if (debug) {
+      this.#debug = true;
+    }
+
+    this.#prompt = new Prompt(contextWindow);
+    this.#sessionStorage = new Session(this.#name, this.#prompt, this.#cachePath);
+    this.#prompt.add("system", prompt, true);
+    this.#prompt.setAdaptor(api, toolset, options);
+    return this;
+  }
+
+  /**
+   * @private
+   * Launches interactive CLI mode.
+   * @param {string} description - CLI intro message.
+   * @returns {void}
+   * @throws {Error} No setup() called.
+   */
+  #startCli(description) {
+    if (!this.#prompt) throw new Error('Run setup first');
+    const cli = new Cli({ prompt: this.#prompt, session: this.#sessionStorage, description });
+    setTimeout(() => {
+      cli.start();
+    }, 1000);
+  }
+  /**
+  * @returns {string}
+  */
+  info() {
+    const sys = this.#sysPrompt;
+		const sessionInfo = this.#sessionStorage.info();
+		const promptInfo = this.#prompt.info();
+		const info = `\nSESSION:\n${sessionInfo}\n\nPROMPT:\n\----\n${sys}\n\----\n${promptInfo}\n\nDESCRIPTION:\n${this.#description}`;
+		return info;
+  }
+
+  /**
+   * @private
+   * Attaches this agent as a WS client to another server (for chaining agents).
+   * @param {string} name - Tool name.
+   * @param {string} description - Tool desc.
+   * @param {string} [url='ws://127.0.0.1:8000/ws'] - Target WS URL.
+   * @returns {AgentClient} New client instance.
+   * @throws {Error} No setup().
+   */
+  #attach(name, description, url = 'ws://127.0.0.1:8000/ws') {
+    if (!this.#prompt) throw new Error('Run setup first');
+    return new AgentClient({ prompt: this.#prompt, name, description, url, secret: this.#secret });
+  }
+
+  /**
+   * @private
+   * Enables server mode: Registers this agent for remote tool calls.
+   * Optionally attaches as client too.
+   * @param {string} name - Server/tool name.
+   * @param {string} [description=''] - Desc (auto from sysPrompt).
+   * @param {number} [port=8000] - Port.
+   * @returns {void}
+   * @throws {Error} No setup/toolset.
+   */
+  #enableServer(name, description = '', port = 8000) {
+    if (!this.#prompt) throw new Error('Run setup first');
+    if (!this.#prompt.toolset) throw new Error('No toolset defined');
+    const server = new AgentServer({
+      port,
+      name,
+      secret: this.#secret,
+      description,
+      prompt: this.#prompt,
+      session: this.#sessionStorage,
+      debug: this.#debug
+    });
+    this.#prompt.on('reset', () => {
+      server.resetAll();
+    });
+  }
+
+  /**
+   * Direct synchronous call to the underlying Prompt.
+   * @param {string} input - User input.
+   * @returns {Promise<string>} Response.
+   * @throws {Error} No setup.
+   */
+  async directCall(input) {
+    const res = await this.#prompt.call(input);
+    return res;
+  }
+
+  /** @returns {Prompt} Underlying Prompt instance. */
+  getPrompt() { return this.#prompt; }
+
+  /** @returns {ToolSet|null} Toolset if configured. */
+  getToolset() { return this.#prompt.toolset; }
+
+  /**
+   * High-level entry point.
+   * Parses CLI args (--serve, --connect, --secret, positional, --help) and decides between directCall or start() modes.
+   * Uses the call_name / call_description / cliIntro values set in the constructor.
+   *
+   * For direct-call (positional input), the result is automatically printed to stdout.
+   * This allows every agent script to simply end with `await agent.run();`
+   * without any extra boilerplate for capturing output.
+   *
+   * @returns {Promise<any>}
+   */
+  async run() {
+    const call_name = this.#name || "";
+    const call_description = this.#description || "";
+    const cliIntro = this.#cliIntro || "";
+
+    const args = process.argv.slice(2);
+    const hasHelp = args.includes("--help");
+    if (hasHelp) {
+      console.log("Usage: node agent.js [--serve PORT] [--connect URL] [--secret SECRET] [positional input] [--help] [--info]");
+      return;
+    }
+    const info = args.includes("--info");
+    if (info) {
+      console.log(this.info());
+      return;
+    }
+    const serveIndex = args.indexOf("--serve");
+    const connectIndex = args.indexOf("--connect");
+    const secretIndex = args.indexOf("--secret");
+
+    let servePort = null;
+    let connectUrl = null;
+    let cliSecret = null;
+
+    if (serveIndex !== -1 && args[serveIndex + 1]) servePort = parseInt(args[serveIndex + 1], 10);
+    if (connectIndex !== -1 && args[connectIndex + 1]) connectUrl = args[connectIndex + 1];
+    if (secretIndex !== -1 && args[secretIndex + 1]) cliSecret = args[secretIndex + 1];
+
+    // Handle --secret in run() (overrides constructor secret if provided)
+    if (cliSecret && typeof cliSecret === "string") {
+      this.#secret = Buffer.from(cliSecret).toString("base64");
+    }
+
+    // Positional argument → directCall (one-shot mode)
+    const positional = args.filter(a => !a.startsWith("--"));
+    const input = positional.length > 0 ? positional[0] : null;
+    if (input && !servePort && !connectUrl) {
+      const result = await this.#prompt.call(input);
+      if (result != null) {
+        console.log(result);
+      }
+      return result;
+    }
+
+    // === Combined start() logic ===
+    const toolName = call_name || this.#name;
+    if (!validNameRegex.test(toolName)) {
+      throw new Error(`Invalid "toolName": "${toolName}". Must match /^[a-z_0-9]{2,}$/`);
+    }
+
+    let finalDescription = call_description;
+    if (!finalDescription && this.#sysPrompt) {
+      finalDescription = this.#sysPrompt.slice(0, 100).trim() + "...";
+    }
+
+    let finalCliIntro = cliIntro;
+    if (!finalCliIntro) {
+      const introStr = `${this.#name} ${this.#model || "unknown-model"} - context: ${this.#contextWindow}`;
+      finalCliIntro = introStr.trim();
+    }
+
+    if (servePort) {
+      console.log(toolName);
+      console.log(finalDescription);
+      this.#enableServer(toolName, finalDescription, servePort);
+      if (connectUrl) {
+        this.#attach(toolName, finalDescription, connectUrl);
+      }
+    } else if (connectUrl) {
+      this.#attach(toolName, finalDescription, connectUrl);
+    } else {
+      this.#startCli(finalCliIntro);
+    }
+  }
+}
+
+export default Agent;