@j-o-r/hello-dave 0.0.1 → 0.0.3

package/examples/spawndave.js

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+import { AgentManager } from '@j-o-r/hello-dave';
+import { parseArgs } from '@j-o-r/sh';
+
+const name = 'spawndave';
+const api = 'xai';
+let secret = '';
+
+const args = parseArgs();
+const help = args['help'] || false;
+const connect = args['connect'] ? args['connect'] : undefined;
+const serve = args['serve'] ? parseInt(args['serve']) : undefined;
+
+const options = { tools: [] };
+
+options.tools.push({ type: 'web_search' });
+
+if (args['secret']) {
+  secret = args['secret'];
+}
+
+if (args['model'] || true) {
+  options.model = args['model'] || 'grok-4-fast-reasoning';  // Up-to-date as of 2026
+}
+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']);
+}
+options.reasoning = { effort: 'high', summary: 'auto' };
+
+const contextWindow = args['context'] ? parseInt(args['context']) : 500000;
+const toolsetMode = 'auto';
+
+function printHelp() {
+  console.log(`${name} --help: Interactive AI Agent Creator (Fully Portable - Works Anywhere!)
+
+Guides you to create custom @j-o-r/hello-dave CLI agents (bin/<name>.js) w/ full support for CLI, WS Server (--serve), WS Client (--connect), hybrids, and **multi-agent CodeServer patterns**.
+
+PORTABLE: Runs in ANY project (auto-installs deps, no local docs needed). Docs: https://codeberg.org/duin/hello-dave (agent-manager.md, codeserver-pattern.md).
+
+USAGE:
+  npx @j-o-r/hello-dave spawndave         # Interactive creation
+  npx @j-o-r/hello-dave spawndave --name myagent "Desc"  # Semi-auto
+  echo "Create CodeServer launcher" | npx @j-o-r/hello-dave spawndave  # Multi-agent
+
+OPTIONS: --model [...] --temp [...] --secret [...]
+
+PROCESS:
+1. Inspect project, auto-install deps (@j-o-r/hello-dave @j-o-r/sh).
+2. Gather: name, desc, tools, prompt.
+3. Generate/validate ESM script (node --check + tool rules).
+4. Write ./bin/<name>.js, chmod +x, **CLI auto-test**.
+5. **Server/Client Guide**: Test --serve → --connect; hybrids.
+6. **CodeServer Aware**: Generates PM2 launchers (self-contained, like examples/CodeServer).
+
+EXAMPLES (Generated Agents):
+  ./bin/myagent.js                       # CLI
+  echo 'query' | ./bin/myagent.js        # One-shot
+  ./bin/myagent.js --serve 8081          # WS Server
+  ./bin/myagent.js --connect ws://...:8081/ws --secret KEY  # WS Client
+  ./bin/myagent.js --serve 8081 --connect ws://other:8080/ws  # Hybrid
+  ./examples/MyServer 8081 mysecret      # Multi-agent PM2 (generated)
+
+**Multi-Agent**: "Generate launcher script like CodeServer pattern for myagent + todoagent".
+`);
+  process.exit();
+}
+
+if (help) printHelp();
+
+const REPO_URL = 'https://codeberg.org/duin/hello-dave';
+const DOCS_BASE = `${REPO_URL}/src/branch/main/docs/`;
+const EXAMPLES_URL = `${REPO_URL}/src/branch/main/examples/`;
+
+const promptParts = [
+  'You are AgentCreator, expert in @j-o-r/hello-dave. Create production-ready CLI agents (bin/<name>.js) **portably** anywhere (no local docs needed).',
+  '',
+  '**AGENT NAME RULE ⚠️**: name MUST be lowercase a-z0-9_ min 2 chars (/^[a-z_0-9_]{2,}$/). EX: myagent, codeagent, ws_tool.',
+  '',
+  '**IMPORTS CRITICAL ⚠️**: **NAMED imports ONLY** - NO default! `import { AgentManager } from \'@j-o-r/hello-dave\';` `import { parseArgs } from \'@j-o-r/sh\';`',
+  '',
+  '**PORTABILITY**: Auto-install deps: `@j-o-r/hello-dave @j-o-r/sh`. Absolute imports. NO local file refs (docs/examples).',
+  '',
+  '**INITIAL INSPECT** (execute_bash_script):',
+  '1. `npm ls @j-o-r/hello-dave @j-o-r/sh 2>/dev/null || echo MISSING` → If MISSING: `npm i @j-o-r/hello-dave @j-o-r/sh --save-exact`.',
+  '2. `mkdir -p bin examples`.',
+  '3. `cat package.json` (project name). `ls -la bin/`.',
+  '',
+  '**TOOL RULES (CRITICAL - NO MIX)**:',
+  '- **XAI Natives** (pre-setup): `options.tools.push({ type: \'web_search\' });` etc.',
+  '- **Generics** (post-setup): `agent.addGenericToolcall(\'read_file\');` w/ `toolsetMode: \'auto\'`.',
+  'Default: web_search + execute_bash_script/read_file/write_file.',
+  '',
+  '**PROCESS (EXACT)**:',
+  '1. INSPECT & SETUP.',
+  '2. GATHER (conversational): **name (validate /^[a-z_0-9_]{2,}$/ or reject)**, desc, api(\'xai\'), model/options, tools, custom prompt, CLI intro/help.',
+  '3. GENERATE & VALIDATE: Use blueprint. Write temp_validate.js, `node --check temp_validate.js` (PASS), grep toolsetMode/auto (1x), generics/addGeneric (≥1 if used), natives/push (≥1 if used), NO options.tools.function.read_file. rm temp.',
+  '4. REVIEW: Show ```js``` + "✅ node --check | Tools OK". Edit if needed.',
+  '5. DEPLOY: `write_file ./bin/${name}.js FULL_CODE`, `chmod +x ./bin/${name}.js`.',
+  '6. **TEST**: `execute_bash_script \'./bin/${name}.js "Briefly describe yourself and your modes (CLI/server/client)"\'` → Show output.',
+  '7. **SERVER/CLIENT GUIDE**: "Test server: ./bin/${name}.js --serve 8081 (find free port). Client: echo \'query\' | ./bin/${name}.js --connect ws://localhost:8081/ws --secret SECRET".',
+  '8. **CodeServer MULTI-AGENT**: If requested (e.g., "multi-agent", "CodeServer"), generate **self-contained Bash launcher** (PM2-managed main server + subs). Write to examples/<Name>Server (e.g., examples/CodeServer). Use blueprint below. PM2: Assume installed (`npm i -g pm2`).',
+  '',
+  '**AGENT BLUEPRINT** (COPY/REPLACE - Plain backticks ` NO ESCAPES):',
+  `\`#!/usr/bin/env node
+import { AgentManager } from '@j-o-r/hello-dave';
+import { parseArgs } from '@j-o-r/sh';
+
+const name = 'AGENTNAME';  // ← REPLACE w/ lowercase /^[a-z_0-9_]{2,}$/
+const api = 'xai';
+let secret = '';
+
+const args = parseArgs();
+const help = args['help'] || false;
+const connect = args['connect'] ? args['connect'] : undefined;
+const serve = args['serve'] ? parseInt(args['serve']) : undefined;
+
+const options = { tools: [] };
+
+// NATIVES HERE e.g. options.tools.push({ type: 'web_search' });
+
+if (args['secret']) { secret = args['secret']; }
+if (args['model'] || true) { options.model = args['model'] || 'grok-4-fast-reasoning'; }
+if (args['temperature']) { options.temperature = parseFloat(args['temperature']); } else { options.temperature = 0.8; }
+options.reasoning = { effort: 'medium', summary: 'auto' };
+
+const contextWindow = args['context'] ? parseInt(args['context']) : 500000;
+const toolsetMode = 'auto';
+
+function printHelp() {
+  console.log(\`AGENTNAME --help: AGENTDESC
+
+Full modes: CLI, WS Server (--serve), WS Client (--connect), Hybrid.
+
+Repo docs: https://codeberg.org/duin/hello-dave (agent-manager.md, codeserver-pattern.md).
+
+USAGE:
+  ./bin/AGENTNAME             # Interactive CLI
+  echo "query" | ./bin/AGENTNAME  # One-shot
+  ./bin/AGENTNAME --serve 8081    # WS Server
+  ./bin/AGENTNAME --connect ws://host:8081/ws --secret KEY  # WS Client
+  ./bin/AGENTNAME --serve 8081 --connect ws://other:8080/ws  # Hybrid
+
+OPTIONS: --model ... --secret ...
+
+EXAMPLES:
+  Chain: Server A --connect B → delegates to B.
+  Multi-Agent: Generate/use PM2 launcher (CodeServer pattern).\`);
+  process.exit();
+}
+
+if (help) printHelp();
+
+const prompt = \`You are AGENTNAME, AGENTDESC.
+
+CUSTOMPROMPT\`.trim();
+
+const agent = new AgentManager({ name, secret });
+agent.setup({ prompt, api, options, toolsetMode, contextWindow });
+
+// GENERICS HERE e.g. agent.addGenericToolcall('execute_bash_script');
+
+const cliIntro = \`🤖 AGENTNAME ready! Modes: CLI/Server/Client/Hybrid.
+
+CLIINTRO\`.trim();
+
+const toolName = 'agent_' + name;
+const toolDescription = \`AGENTDESC. Supports WS chaining/multi-agent.\`.trim();
+
+await agent.start(serve, connect, cliIntro, toolName, toolDescription);\``,
+  '',
+  '**CODE_SERVER BLUEPRINT** (Bash for multi-agent - Self-contained, like CodeServer pattern):',
+  `\`#!/bin/bash
+# Portable Multi-Agent Launcher (PM2-managed: main server + subs)
+# Run: npm i -g pm2 (once)
+if [ $# -lt 1 ] || [ $# -gt 2 ]; then
+  echo "Usage: $0 <PORT> [SECRET]  # PORT:1024-65535, SECRET:>=3 chars (def:123)"
+  exit 1
+fi
+PORT="$1"
+SECRET="\${2:-123}"
+if [ \${#SECRET} -lt 3 ]; then echo "SECRET too short"; exit 1; fi
+if ! [[ "$PORT" =~ ^[0-9]+$ ]] || [ "$PORT" -lt 1024 ] || [ "$PORT" -gt 65535 ]; then echo "Bad PORT"; exit 1; fi
+
+SCRIPT_DIR="\$( cd "\$( dirname "\${BASH_SOURCE[0]}" )" && pwd )"
+PROJECT_DIR="\$( cd "\$( dirname "\${SCRIPT_DIR}" )" && pwd )"
+FOLDER=\$(basename "$PROJECT_DIR")
+
+echo "Starting <MainAgent>Server on port \${PORT} in '\$FOLDER' w/ SECRET '\$SECRET'..."
+
+# Cleanup old PM2
+pm2 delete "\${FOLDER}_mainagent_\${PORT}" 2>/dev/null || true
+pm2 delete "\${FOLDER}_sub1agent_\${PORT}" 2>/dev/null || true  # Add per sub
+# ... more subs
+
+# Main server
+pm2 start "\${SCRIPT_DIR}/bin/mainagent.js" --name "\${FOLDER}_mainagent_\${PORT}" -- --serve "\${PORT}" --tools javascript --secret "\${SECRET}"
+# Subs as clients
+pm2 start "\${SCRIPT_DIR}/bin/sub1agent.js" --name "\${FOLDER}_sub1agent_\${PORT}" -- --connect "ws://127.0.0.1:\${PORT}/ws" --secret "\${SECRET}"
+# ... more: pm2 start ... sub2agent.js ...
+
+echo "Processes: pm2 list | grep '\${FOLDER}_\${PORT}'"
+echo "Connect: npx @j-o-r/hello-dave dave --connect ws://127.0.0.1:\${PORT}/ws --secret '\${SECRET}'"\``,
+  '',
+  'Enthusiastic, step-by-step. Match portable style. **ALWAYS validate name regex before generate/deploy.** Current date: 2026. Models: grok-4-fast-reasoning/grok-beta. CodeServer pattern: https://codeberg.org/duin/hello-dave/src/branch/main/examples/CodeServer'
+];
+
+const prompt = promptParts.join('\\n');
+
+const agent = new AgentManager({ name, secret });
+agent.setup({
+  prompt,
+  api,
+  options,
+  toolsetMode,
+  contextWindow
+});
+
+agent.addGenericToolcall('execute_bash_script');
+agent.addGenericToolcall('read_file');
+agent.addGenericToolcall('write_file');
+agent.addGenericToolcall('javascript_interpreter');
+
+const cliIntro = `🤖 ${name} (${options.model}) ready! (context: ${contextWindow})
+
+Portable Agent Creator: Builds CLI/WS agents + CodeServer launchers **anywhere** (auto-deps, online docs).
+
+Examples: 
+- "Create code-review agent: name=coderev, desc=Git diff analyzer, tools=read_file execute_bash_script web_search"
+- "Generate CodeServer launcher for coderev + tododave + npmdave"`.trim();
+
+const toolName = 'spawn_dave';
+const toolDescription = `Portable creator for CLI/WS agents (bin/<name>.js) + PM2 multi-agent launchers. Validates/tests/deploys. No local docs needed (uses repo: https://codeberg.org/duin/hello-dave).`.trim();
+
+await agent.start(serve, connect, cliIntro, toolName, toolDescription);

package/examples/todoDave.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+import { AgentManager } from '@j-o-r/hello-dave';
+import { parseArgs, readIn } from '@j-o-r/sh';
+
+const name = 'todo_dave';
+const api = 'xai';
+let secret = '';
+
+const input = ''; // await readIn() /* not compabtible with `pm2` */;
+const args = parseArgs();
+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 : []};
+
+if (args['secret']) { // model gets default value
+	secret= args['secret'];
+}
+// Set properties only if provided via command line (except model which has default)
+if (args['model'] || true) { // model gets default value
+	// @ts-ignore
+	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; // args['reasoning'] ? args['reasoning'] : null;
+if (reasoning) {
+	options.reasoning = {
+		effort:'medium',
+		summary: 'auto'
+	}
+}
+
+options.tools.push({
+	type: 'web_search'
+});
+const toolsetMode = 'auto';
+const contextWindow = args['context'] ? parseInt(args['context']) : 250000;
+
+// Copy from the generic toolset
+function printHelp() {
+	console.log(`
+'${name} --help' You are looking at it.
+'
+OPTIONS: 
+--tokens [number]: max generated tokens 
+--context [number] : truncate message history to context-windows size default 130000
+--temperature [float] : -2 / +2
+--model [grok-4|grok-3|grok-3-mini|grok-3-mini-fast|grok-code-fast-1]
+--top_p [float]: number > 0, 0.1 means no top_p
+--reasoning [low|high]
+--tools [javascript,bash] comma seperated list
+`);
+	process.exit()
+}
+
+if (help) {
+	printHelp();
+}
+
+const tool_call_description = `
+Project TODO list manager. Maintains TODO.md with tasks in Markdown checklists.
+Inspects current TODO.md, adds/checks/completes tasks based on input, updates the file.
+Suggests next actions, stores future important tasks.
+`.trim();
+const tool_call_name = 'todo_agent';
+const prompt = `
+You are an expert TODO manager for this project. TODO.md stores tasks in Markdown format with checklists:
+
+## TODO (high priority pending)
+- [ ] Task 1
+
+## In Progress
+- [ ] Task 2
+
+## Later (future tasks)
+- [ ] Important task to do later
+
+## Done
+- [x] Completed task
+
+ALWAYS:
+
+1. Inspect the current TODO.md file if it exists (use \`cat TODO.md\` or similar).
+
+2. Understand the user input: 
+   - Add new tasks: "add task: Fix bug in foo.js"
+   - Complete: "done: task X" or mark specific
+   - Check status: "status" or "what's next?"
+   - Prioritize/reorganize
+   - Archive old done tasks if too many
+
+3. Update TODO.md with changes. Keep it organized, add dates if useful (e.g., - [ ] 2026-02-24: Task).
+
+4. Write the FULL updated content to ./TODO.md.
+
+5. In your response, summarize:
+   - Current status (pending count, next suggested)
+   - Changes made
+   - Updated TODO.md preview (first 10 lines or key sections)
+
+If no TODO.md, create one inspecting the project (package.json, README.md, git status) for initial tasks like "Review code", "Add tests", etc.
+
+Use tools to inspect files as needed (ls, cat, git log, etc.).
+`.trim();
+const agent = new AgentManager({ name, secret });
+agent.setup({
+	prompt,
+	api,
+	options,
+	toolsetMode,
+	contextWindow
+});
+const toolset = agent.getToolset();
+if (toolset) {
+	agent.addGenericToolcall('execute_bash_script');
+}
+const cliIntro = `
+${name} ${options.model}.
+- context: ${contextWindow}
+`.trim();
+
+await agent.start(serve, connect, cliIntro, tool_call_name, tool_call_description);

package/lib/API/openai.com/reponses/text.js

@@ -22,12 +22,12 @@ import { sleep } from '@j-o-r/sh';
 * @property {number} [max_output_tokens=4000] - Maximum number of output tokens.
 * @property {number} [max_tool_calls=10] - Maximum number of tool calls allowed.
 * @property {?Object} [metadata=null] - Optional metadata object.
-* @property {'gpt-4.1'|'GPT-4o'|'o3'|'o3-mini'|'o4-mini'|'o1'|'o3-pro'} [model='gpt-4.1'] - Model version to use.
+* @property {'gpt-5.4'|'gpt-5-mini'|'gpt-5-nano'|'gpt-5-pro'} [model='gpt-5-mini'] - Model version to use.
 * @property {?string} [prompt=null] - Reusable prompt string.
 * @property {Object} [reasoning={effort: 'medium', summary: 'auto'}] - Reasoning configuration.
 * @property {'low'|'medium'|'high'|null} reasoning.effort - Effort level for reasoning.
 * @property {'auto'|'concise'|'detailed'} reasoning.summary - Summary type for reasoning.
-* @property {'low'|'medium'|'high'} [search]
+* @property {'low'|'medium'|'high'} [search] - Convenience: Adds `{type: "web_search_preview", search_context_size: search}` tool.
 * @property {'auto'} [service_tier='auto'] - Service tier option, default is auto-selected.
 * @property {boolean} [store=false] - Whether to store the response or not.
 * @property {boolean} [stream=false] - Whether to stream the response or not.
@@ -36,7 +36,7 @@ import { sleep } from '@j-o-r/sh';
 * @property {'text'|'json_schema'} text.format - Summary type for reasoning.
 * @property {boolean} [parallel_tool_calls=true] - Allow parallel tool calls if true.
 * @property {'auto'} [tool_choice='auto'] - Tool choice setting, default is auto-selected.
-* @property {OAToolCall[]} tools=[] Array of tool call objects.
+* @property {OpenAITool[]} [tools=[]] - Array of tool objects: custom function tools (`OAToolCall`) or built-in OpenAI tools (e.g., `{type: "web_search_preview"}`).
 * @property {?number } top_logprobs=null An integer between 0 and 20 specifying the number of most likely tokens to return at each token position, each with an associated log probability.
 * @property {?number } top_p=1 Top-p sampling value between 0 and 1.
 * @property {?string} [previous_response_id] - Needed reponse_id to validate tool calls on the next request
@@ -51,6 +51,14 @@ import { sleep } from '@j-o-r/sh';
 * @property {Object.<string, OAParameterProperty>} parameters.properties - An object describing each parameter property.
 * @property {string[]} [parameters.required] - An array of required parameter names.
 */
+/**
+ * @typedef {Object} OABuiltinTool
+ * @property {'code_interpreter'|'file_search'|'computer'|'web_search'} type - Type of built-in OpenAI tool (Responses API).
+ * @property {'low'|'medium'|'high'} [search_context_size] - Context size for `web_search_preview` only.
+ */
+/**
+ * @typedef {OAToolCall | OABuiltinTool} OpenAITool
+ */
 
 /**
 * @typedef {Object} OAParameterProperty
@@ -247,23 +255,9 @@ function getBody(prompt, toolset, options) {
 	if (toolset) {
 		// @ts-ignore
 		body.tool_choice = toolset.toolChoice;
-		body.tools = generateTools(toolset);
+		body.tools = [...body.tools, ...generateTools(toolset)];
 		body.parallel_tool_calls = true;
-		// parallel_tool_calls
-	}
-	// Add OPENAI SEARCH
-	// in the toolset
-	if (body.search) {
-		if (!body.tools) {
-			body.tools = [];
-		}
-		body.tools.push({
-			type: 'web_search_preview',
-			// @ts-ignore
-			search_context_size: body.search
-		})
 	}
-	delete body.search;
 	return body;
 
 }