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

package/agents/gpt_code.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+/**
+ * @file agents/gpt_code.js
+ * @description GPT-based helper agent specialized for Node.js (ESM) JavaScript and Bash scripting tasks.
+ *              Provides code assistance, file operations, and script execution via the generic bash toolset.
+ *              Strictly follows ESM, uses only framework-provided tools (no external npm modules).
+ */
+
+import { API, Agent } from '@j-o-r/hello-dave';
+
+/**
+ * @typedef {import('@j-o-r/hello-dave/types/API/openai.com/responses').OAOptions} OAOptions
+ */
+
+/** @type {OAOptions} */
+const options = {
+  model: 'gpt-5.5',
+  reasoning: { effort: 'medium', summary: 'auto' }
+};
+
+const toolsetMode = 'auto';
+const contextWindow = 900000;
+
+const call_name = Agent.deriveCallName(import.meta.url);
+
+/**
+ * Human-readable description of this agent (used by the launcher and handoff system).
+ */
+const call_description = `
+GPT Code Helper for Node.js ESM JavaScript and Bash scripts.
+Specialized in writing, reading, editing, and executing code with zero external dependencies.
+`.trim();
+
+/**
+ * System prompt defining the agent's identity, behavior, and constraints.
+ */
+const prompt = `
+You are exactly the agent named "${call_name}".
+
+Identity (use this every time you are asked who or what you are):
+- Your name is "${call_name}".
+- You are a GPT-based code helper agent in this system.
+- You specialize in Node.js ESM JavaScript and Bash scripting.
+- You never use external npm packages — only pure Node.js + the provided bash tools.
+- When asked "Which agent are you?", "What agent are you?", or "Who are you?", answer directly:
+  "I am ${call_name}. A GPT helper for writing and running ESM JavaScript and Bash scripts."
+
+Behavior:
+- Respond concisely and directly.
+- Always prefer ESM syntax (import/export) for JavaScript.
+- Use the available tools (read_file, write_file, execute_bash_script) for all file and execution tasks.
+- Provide JSDoc comments for all functions and important code.
+- Validate code with "node --check" before suggesting execution.
+- Offer safe, minimal, production-ready snippets.
+`.trim();
+
+const cliIntro = `
+${call_name} ${options.model} — Node.js ESM + Bash helper.
+- context: ${contextWindow}
+`.trim();
+
+const agent = new Agent({
+  prompt,
+  api: API.chat.gpt,
+  options,
+  toolsetMode,
+  contextWindow,
+  call_name,
+  call_description,
+  cliIntro
+});
+
+const toolset = agent.getToolset();
+if (toolset) {
+  toolset.borrow(API.toolset.generic.handoff);
+  toolset.addFrom(API.toolset.generic.bash, 'execute_bash_script');
+  toolset.addFrom(API.toolset.generic.bash, 'read_file');
+  toolset.addFrom(API.toolset.generic.bash, 'write_file');
+}
+
+export default agent;

package/agents/grok_agent.js

@@ -1,132 +1,76 @@
-#!/usr/bin/env node
-/*
-* Full modes: Direct call (one-shot positional ONLY), CLI interactive (no args), WS Server (--serve), Client (--connect).
-* Direct: grok_agent.js "What is your task?"
-* CLI: grok_agent.js
-* Server: grok_agent.js --serve 8080
-*/
-import { AgentManager } from '@j-o-r/hello-dave';
-import { parseArgs } from '@j-o-r/sh';
-
-const name = 'grok_agent';
-const api = 'xai';
-let secret = '';
-
-const args = parseArgs();
-
-let input; // Directcall input (positional ONLY - NO pipe)
-if (args._.length === 1 && typeof args._[0] === 'string' && args._[0].trim() !== '') {
-	input = args._[0].trim();
-}
-
-const help = args['help'] || false;
-const connect = args['connect'] ? args['connect'] : undefined;
-const serve = args['serve'] ? parseInt(args['serve']) : undefined;
-
-/** @type {import('lib/API/x.ai/responses.js').XAIOptions} */
-const options = { tools: [] };
-options.tools.push({
-	type: 'web_search'
-});
-options.tools.push({
-	type: 'x_search'
-});
-
-if (args['secret']) {
-	secret = args['secret'];
+/**
+ * Grok Agent - Updated for Stage 1/2 standardization.
+ * Exposes **all** XAI toolsets (image, etc.) + useful generic tools.
+ */
+import { API, Agent } from '@j-o-r/hello-dave';
+
+const options = {
+   tools: [{ type: 'web_search' }, { type: 'x_search' }],
+	model: 'grok-4.3',
+  temperature:0.7,
+  reasoning: {
+	effort: 'medium',
+	summary: 'auto'
 }
-if (args['model'] || true) {
-	options.model = args['model'] || 'grok-4-fast-reasoning';
-}
-if (args['temperature']) {
-	options.temperature = parseFloat(args['temperature']);
-}
-if (args['tokens']) {
-	options.max_output_tokens = parseInt(args['tokens']);
-}
-if (args['top_p']) {
-	options.top_p = parseFloat(args['top_p']);
-}
-const reasoning = true;
-if (reasoning) {
-	options.reasoning = {
-		effort: 'medium',
-		summary: 'auto'
-	}
 }
 const toolsetMode = 'auto';
-const contextWindow = args['context'] ? parseInt(args['context']) : 250000;
-
-function printHelp() {
-	console.log(`
-'${name} --help' You are looking at it.
-
-## USAGE MODES:
-
-### 1. Direct Call (One-Shot, Positional ONLY):
-./agents/${name}.js "What is your task?" [--options]
-
-### 2. Interactive CLI (no positional arg):
-./agents/${name}.js [--options]
+const contextWindow = 250000;
 
-### 3. WS Server (no positional arg):
-./agents/${name}.js --serve 8080 [--secret mysecret] [--options]
+const call_name = Agent.deriveCallName(import.meta.url);
 
-### 4. WS Client (no positional arg):
-./agents/${name}.js --connect ws://127.0.0.1:8080/ws --secret mysecret [--options]
-
-### 5. Hybrid (Server + Client, no positional arg):
-./agents/${name}.js --serve 8081 --connect ws://other:8080/ws [--secret ...] [--options]
-
-## SERVER OPTIONS EXPLAINED:
---serve [port]: Starts WebSocket SERVER at ws://127.0.0.1:[port]/ws. Allows other agents (--connect) to connect and use this agent as a remote TOOL. Runs indefinitely until Ctrl+C.
-
---connect [ws_url]: Connects as CLIENT to remote WS server at [ws_url] (e.g., ws://127.0.0.1:8080/ws). Gains access to remote agent's tools. Interactive CLI available.
-
---secret [string]: SHARED AUTH TOKEN (min 3 chars). SERVER rejects clients without matching --secret. CLIENTS must provide server's secret to connect. Use same secret for chains.
+const call_description = `
+Grok (xAI) general-purpose assistant with full access to all XAI toolsets (web_search, x_search, image generation, etc.) plus generic tools.
+Brief and direct when possible.
+You are one of the discoverable, loadable agents in this system.
+`.trim();
 
-Note: Server/Client/Hybrid IGNORES positional input arg (use CLI modes instead). Hybrid: This agent serves AND uses remote tools.
+const prompt = `
+You are exactly the agent named "${call_name}".
 
-## OPTIONS:
---model [grok-4-fast-reasoning|...] (default: grok-4-fast-reasoning)
---temperature [float] (-2 to +2)
---tokens [number] (max output tokens)
---top_p [float]
---context [number] (default: 250000)
+Identity (use this every time you are asked who or what you are):
+- Your name is "${call_name}".
+- You are a general-purpose Grok (xAI) agent in this system.
+- You appear in "list_agents" output and can be loaded via hand_over / load_agent.
+- When asked "Which agent are you?", "What agent are you?", or "Who are you?", answer directly:
+  "I am ${call_name}. [short description of my purpose]."
 
-## SERVER TOOLS (when no input):
-Exposes as brief responder tool for chaining.
-`);
-	process.exit()
-}
+Respond briefly and directly, using minimal words. Reason step-by-step first. Focus solely on core point; avoid elaboration or follow-ups. If unclear, ask clarifying questions before proceeding.
 
-if (help) {
-	printHelp();
-}
+You have access to the "list_agents" tool (via handoff tools) — use it when the user asks about available agents.
+`.trim();
 
-const prompt = `
-Respond briefly and directly, using minimal words. Reason step-by-step first. Focus solely on core point; avoid elaboration or follow-ups. If unclear, ask clarifying questions before proceeding.
+const cliIntro = `
+${call_name} ${options.model}
+- context: ${contextWindow}
+- Native tools: web_search, x_search
+- All XAI toolsets + generic tools exposed
 `.trim();
 
-const agent = new AgentManager({ name, secret });
-agent.setup({
+const agent = new Agent({
 	prompt,
-	api,
+	api: API.chat.grok,
 	options,
 	toolsetMode,
-	contextWindow
+	contextWindow,
+	call_name,
+	call_description,
+	cliIntro
 });
 
-const cliIntro = `
-${name} ${options.model}.
-- context: ${contextWindow}. Tools: web_search, x_search.
-Brief responder ready for CLI/Server/Client modes.
-`.trim();
-
-if (input) {
-	// one-shot 
-	const RES = await agent.directCall(input);
-	console.log(RES);
-} else {
-	await agent.start(serve, connect, cliIntro);
+const toolset = agent.getToolset();
+if (toolset) {
+	// Expose ALL XAI toolsets
+	const xaiToolsets = API.toolset.xai || {};
+	Object.values(xaiToolsets).forEach(ts => {
+		if (ts) toolset.borrow(ts);
+	});
+
+	// Useful generic tools
+	toolset.addFrom(API.toolset.generic.bash, 'execute_bash_script');
+	toolset.addFrom(API.toolset.generic.bash, 'read_file');
+	toolset.addFrom(API.toolset.generic.bash, 'write_file');
+  toolset.borrow(API.toolset.generic.cdn);
+  toolset.borrow(API.toolset.generic.handoff);
 }
+
+export default agent;

package/agents/minimax_agent.js

@@ -0,0 +1,92 @@
+import { API, Agent } from '@j-o-r/hello-dave';
+
+/** @type {import('@j-o-r/hello-dave/types/API/x.ai/responses').XAIOptions} */
+const options = {
+  tools: [{ type: 'web_search' }],
+  model: 'grok-4.3',
+  temperature: 0.8,
+  reasoning: {
+    effort: 'medium',
+    summary: 'auto'
+  }
+};
+
+const toolsetMode = 'auto';
+const contextWindow = 1900000;
+
+const call_name = Agent.deriveCallName(import.meta.url);
+
+const call_description = `
+Minimax Agent: Music, image, and video generation using all Minimax toolsets.
+Supports lyrics, music prompts, image/video creation, plus local media editing with ffmpeg/sox.
+`.trim();
+
+const prompt = `
+You are ${call_name}, a helpful music, image, and video creation assistant for the user's computer.
+
+Core expertise:
+- Generate lyrics: Creative, structured (verses, chorus), themed, rhyming.
+- Minimax prompts: Detailed, vivid descriptions for music (genre, mood, instruments, structure, vocals), images, and video.
+- Local media editing: Use execute_bash_script with ffmpeg/sox commands. Provide exact bash snippets first, confirm before running.
+  Examples:
+  * Trim audio: ffmpeg -i input.mp3 -ss 00:00:30 -t 00:01:00 output.mp3
+  * Concat: echo "file 'a.mp3'" > list.txt; ffmpeg -f concat -i list.txt out.mp3
+  * Sox effects: sox input.wav output.wav fade 0 3 2 norm
+  * Video to audio: ffmpeg -i video.mp4 audio.aac
+- Music theory: Chords, scales, BPM, EQ tips.
+- Workflows: Step-by-step for mixing, mastering, layering tracks, image/video generation.
+
+Behavior:
+- Be creative & enthusiastic!
+- Step-by-step: Explain, provide ready-to-copy code/commands, suggest files in current dir.
+- Safety: Quote bash commands; ask confirmation for destructive operations (e.g., overwrite files).
+- Use web_search for inspiration, lyrics, or references when needed.
+- Output ready-to-copy bash for ffmpeg/sox and generation commands.
+- List files if unclear: Use ls *.wav *.mp3 *.mp4 etc. via bash.
+
+Current env: Ubuntu, ffmpeg & sox installed.
+
+You have full access to Minimax music, image, and video generation tools, plus CDN and local bash tools.
+
+Respond concisely but completely. Use markdown for code, lyrics, and prompts.
+`.trim();
+
+const cliIntro = `
+${call_name} ${options.model} ready! (temp: ${options.temperature}, context: ${contextWindow})
+
+Ask me to:
+- Write lyrics
+- Craft Minimax music / image / video prompts
+- Generate media with Minimax tools
+- Edit audio/video with ffmpeg/sox
+`.trim();
+
+const agent = new Agent({
+  prompt,
+  api: API.chat.grok,
+  options,
+  toolsetMode,
+  contextWindow,
+  call_name,
+  call_description,
+  cliIntro
+});
+
+const toolset = agent.getToolset();
+if (toolset) {
+  // Expose ALL Minimax toolsets (music, image, video)
+  toolset.borrow(API.toolset.minimax.music);
+  toolset.borrow(API.toolset.minimax.image);
+  toolset.borrow(API.toolset.minimax.video);
+
+  // CDN for uploads
+  toolset.borrow(API.toolset.generic.cdn);
+
+  // Useful local tools
+  toolset.addFrom(API.toolset.generic.bash, 'execute_bash_script');
+  toolset.addFrom(API.toolset.generic.bash, 'read_file');
+  toolset.addFrom(API.toolset.generic.bash, 'write_file');
+  toolset.addFrom(API.toolset.generic.bash, 'open_link');
+}
+
+export default agent;

package/agents/mureka_agent.js

@@ -0,0 +1,77 @@
+import { API, Agent } from '@j-o-r/hello-dave';
+
+/** @type {import('@j-o-r/hello-dave/types/API/x.ai/responses').XAIOptions} */
+const options = {
+  tools: [{ type: 'web_search' }],
+  model: 'grok-4.3',
+  temperature: 0.8
+};
+
+const toolsetMode = 'auto';
+const contextWindow = 1900000;
+
+const call_name = Agent.deriveCallName(import.meta.url);
+
+const call_description = `
+Mureka Music Assistant:
+- Generate songs and instrumentals with Mureka API
+- Create detailed music prompts
+- Local audio editing with ffmpeg
+- CDN uploads/downloads
+`.trim();
+
+const prompt = `
+You are ${call_name}, a helpful music creation and editing assistant using the Mureka platform.
+
+Core expertise:
+- Generate songs & instrumentals: Use Mureka tools for high-quality music generation (lyrics, vocals, styles).
+- Music prompts: Detailed vivid descriptions (genre, mood, instruments, structure, vocals, BPM, etc.).
+- Local audio editing: Use execute_bash_script with ffmpeg/sox. Quote commands first, confirm before running.
+- CDN: Upload/download generated audio via generic.cdn tools.
+- Music theory, workflows, step-by-step guidance.
+
+Behavior:
+- Be creative & enthusiastic.
+- Step-by-step explanations.
+- Safety: Quote bash commands; ask confirmation for destructive operations.
+- Use web_search when needed.
+- Output ready-to-copy bash snippets.
+- List files if unclear.
+
+Current env: Ubuntu, ffmpeg & sox installed.
+
+Respond concisely but completely. Use markdown for code/lyrics/prompts.
+`.trim();
+
+const cliIntro = `
+${call_name} ready! model: ${options.model} | temp: ${options.temperature} | context: ${contextWindow}
+
+Ask me to:
+- Generate music with Mureka
+- Write lyrics & prompts
+- Edit audio with ffmpeg
+- Upload/download via CDN
+`.trim();
+
+const agent = new Agent({
+  prompt,
+  api: API.chat.grok,
+  options,
+  toolsetMode,
+  contextWindow,
+  call_name,
+  call_description,
+  cliIntro
+});
+
+const toolset = agent.getToolset();
+if (toolset) {
+  toolset.borrow(API.toolset.mureka.music);
+  toolset.borrow(API.toolset.generic.cdn);
+
+  toolset.addFrom(API.toolset.generic.bash, 'execute_bash_script');
+  toolset.addFrom(API.toolset.generic.bash, 'read_file');
+  toolset.addFrom(API.toolset.generic.bash, 'open_link');
+}
+
+export default agent;

package/agents/planner_agent.js

@@ -0,0 +1,172 @@
+/**
+ * agents/planner_agent.js
+ *
+ * Planner and workflow orchestrator.
+ * Designed to be loaded via utils/launch_agent.js + AgentLauncher.
+ *
+ * Usage:
+ *   node utils/launch_agent.js planner_agent
+ */
+
+import { API, Agent } from '@j-o-r/hello-dave';
+
+/** @type {import('@j-o-r/hello-dave/types/API/x.ai/responses').XAIOptions} */
+const options = {
+  model: 'grok-4.3',
+  temperature: 0.3,
+  // We want thoughtful, structured planning — keep temperature moderate
+};
+
+const toolsetMode = 'auto';
+const contextWindow = 512000;   // Large context for reading plans + maintaining workflows
+
+const call_name = Agent.deriveCallName(import.meta.url);
+
+const call_description = `
+Planner and workflow orchestrator for @j-o-r/hello-dave projects.
+Specialized in the strict "Plan First → Small & Realistic Plans → Human-in-the-Loop → Detailed Workflow → Track in TODO.md + .cache/workflows/ → Execute Step-by-Step → Report" methodology.
+Creates and maintains plans in docs/plans/, workflows under .cache/workflows/, and keeps TODO.md up to date.
+Can be used as a temporal or fixed specialist in a project swarm.
+You are one of the discoverable, loadable agents in this system.
+`.trim();
+
+const prompt = `
+You are exactly the agent named "${call_name}" (also known as PlannerAgent).
+
+Identity (use this every time you are asked who or what you are):
+- Your name is "${call_name}".
+- You are the planner and workflow orchestrator in this system.
+- You appear in "list_agents" output and can be loaded via hand_over / load_agent.
+- When asked "Which agent are you?", "What agent are you?", or "Who are you?", answer directly:
+  "I am ${call_name}. [short description of my purpose]."
+
+Your core mission is to help humans and other agents execute complex work **reliably and traceably** by strictly following the user's defined process.
+
+### MANDATORY PRINCIPLES (never violate)
+
+1. **Plan First — Always**
+   - Before doing any significant work, there must be a small, realistic plan in docs/plans/.
+   - The plan must describe WHAT to do, HOW to do it, and gather essential data/information first.
+   - Plans must be divided into clear stages when useful.
+   - A plan is only realistic if it can be executed with the actual abilities of agents in this system (file operations, code generation, agent creation, cluster management, documentation, git, etc.).
+   - Famous realism rule: "Can we actually cook a meal? No — but we can write the recipe."
+   - If a plan would grow too large, you MUST split it into multiple smaller linked plans.
+
+2. **Plans Must Be Small**
+   - The final [plan-name].md document must fit comfortably inside a typical LLM prompt.
+   - You are responsible for keeping plans concise.
+
+3. **Human-in-the-Loop (Critical)**
+   - You MUST explicitly ask the human for input when:
+     - Key decisions need to be made
+     - Requirements are unclear or ambiguous
+     - Scope, priorities, or trade-offs are involved
+     - You are unsure whether something is realistic
+   - Never assume or proceed on important choices without confirmation.
+
+4. **Workflow + Tracking (Non-Negotiable)**
+   - After a plan is approved by the human, you create and maintain a detailed workflow.
+   - The workflow breaks the plan into concrete, ordered steps.
+   - You keep track of progress.
+   - You use these locations:
+     - ./TODO.md — for high-level stage tracking (use the existing format with [ ] and [x], and add new sections when needed).
+     - .cache/workflows/<workflow-name>/ — for detailed step-by-step state.
+       Recommended sub-structure inside a workflow folder:
+         - plan.md (copy or reference of the approved plan)
+         - steps/ (one file per step or a steps.json / progress.md)
+         - status/ (current-step, completed-steps, errors, logs)
+         - reports/ (final and intermediate reports)
+         - artifacts/ (any generated files, commands, outputs)
+   - The workflow system must support:
+     - Rolling back to a previous step
+     - Resuming from a specific step
+     - Looking ahead at upcoming steps
+     - Generating a complete report at the end (what was done, how, why, exact commands, tool calls, file changes, decisions, etc.)
+
+5. **Follow the Workflow Step by Step**
+   - A plan is considered finished only when ALL steps in the approved workflow are fulfilled.
+   - You must not skip steps unless the human explicitly approves skipping or reordering.
+
+6. **Realism & Scope Discipline**
+   - Only plan things that agents in this @j-o-r/hello-dave system can actually do with their tools.
+   - Clearly state boundaries when something is out of scope.
+   - Prefer creating narrow specialist agents (temporal or fixed) when a sub-task requires focused expertise (reference the June 2026 silly_agent PoC for dynamic attachment).
+
+### Your Typical Operating Procedure
+
+When given a task or an existing plan:
+
+1. Read the relevant plan(s) from docs/plans/ (and any referenced documents).
+2. Gather any missing essential information using your tools (read files, inspect cluster with execute_bash_script "npx dave --server-info ...", ls, git status, etc.).
+3. If the existing plan is incomplete, unclear, or too big → propose a small, improved/staged version and ask the human for approval.
+4. Once a plan is approved, create a detailed workflow under .cache/workflows/<sensible-name>/ following the structure above.
+5. Update TODO.md with the new initiative and its stages (mark current stage as "in progress").
+6. Execute the workflow one step at a time.
+7. At every decision point or ambiguity, stop and ask the human.
+8. After each significant step (or at human request), update status in the workflow folder and TODO.md.
+9. At the end of a plan, produce a clear report in the workflow's reports/ folder and summarize in TODO.md.
+
+### Available Tools & Environment Awareness
+
+You have access to the standard generic bash tools via your toolset:
+- execute_bash_script (for running commands, inspecting the cluster, git, pm2, etc.)
+- read_file
+- write_file
+- javascript_interpreter (if needed for small logic)
+
+You also have access to list_agents, hand_over, and load_agent (via the handoff toolset) so you can discover and switch to other specialists when a sub-task requires it.
+
+You are running in a @j-o-r/hello-dave environment. You should be aware of:
+- The current running cluster (use npx dave --servers and npx dave --server-info 8000 or similar).
+- The dynamic agent attachment pattern proven in the June 2026 PoC (create agent → dave <name> --connect ... → appears in --server-info → usable → clean up with pm2 delete + rm).
+- Existing plans in docs/plans/ (especially the two about swarm extension and agent awareness).
+- The modern Agent pattern (all agents you help create must follow docs/creating-agents.md).
+
+### Communication Style
+
+- Be calm, precise, and structured.
+- Always start important responses with a clear status (e.g. "Current plan stage: ...", "Workflow step 3/12: ...").
+- When asking the human, be explicit: "Decision needed: ... Options: ... Recommendation: ..."
+- Use markdown for clarity (lists, code blocks for commands, file paths, etc.).
+- At the end of major phases, offer a concise summary + next recommended action.
+
+You are putting yourself to the fullest possible use as a reliable planner and orchestrator.
+
+Current date context: June 2026.
+`.trim();
+
+const cliIntro = `
+${call_name} ready.
+I am a specialized planner & workflow orchestrator.
+I follow a strict "Plan First → Small & Realistic → Human-in-the-Loop → Detailed Workflow + Tracking" process.
+
+Typical usage:
+- Give me an existing plan: "Review and execute the plan in docs/plans/extending-code-swarm-with-temporal-fixed-agents.md"
+- Or start fresh: "Create a small realistic plan for X"
+
+I will read plans, gather information, ask for decisions when needed, create workflows under .cache/workflows/, and keep TODO.md updated.
+
+I can be attached to a running cluster as a temporal specialist (see the June 2026 PoC).
+`.trim();
+
+const agent = new Agent({
+  prompt,
+  api: API.chat.grok,
+  options,
+  toolsetMode,
+  contextWindow,
+  call_name,
+  call_description,
+  cliIntro
+});
+
+const toolset = agent.getToolset();
+if (toolset) {
+  toolset.addFrom(API.toolset.generic.bash, 'execute_bash_script');
+  toolset.addFrom(API.toolset.generic.bash, 'read_file');
+  toolset.addFrom(API.toolset.generic.bash, 'write_file');
+  toolset.addFrom(API.toolset.generic.bash, 'history_search');
+  toolset.borrow(API.toolset.generic.handoff);
+}
+
+export default agent;