@j-o-r/hello-dave 0.0.8 → 0.0.10

package/TODO.md

@@ -8,6 +8,6 @@
 (none)
 
 ## Done
-(none - archived to docs/todo-archive-v0.0.8.md on 2026-04-15)
+(none - all archived to docs/todo-archive-v0.1.0.md on 2026-04-24)
 
-Older tasks archived on 2026-04-13 to docs/todo-archive.md.
+Archive notes: All tasks completed and archived as of 2026-04-24. Previous archives: docs/todo-archive-v0.0.9.md (2026-04-20), docs/todo-archive-v0.0.8.md (2026-04-15), docs/todo-archive.md (2026-04-13), docs/todo-archive-infra-2026-04-21.md (2026-04-21).

package/agents/code_agent.js

@@ -24,7 +24,7 @@ if (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-1-fast-reasoning';
+	options.model = args['model'] || 'grok-4.20-reasoning';
 }
 // if (args['temperature']) {
 	options.temperature = 0.2;
@@ -35,14 +35,14 @@ if (args['tokens']) {
 if (args['top_p']) {
 	options.top_p = parseFloat(args['top_p']);
 }
-const reasoning = args['reasoning'] ? args['reasoning'] : 'medium';
-if (reasoning) {
-	options.reasoning = {
-		// @ts-ignore
-		effort:reasoning,
-		summary: 'auto'
-	}
-}
+// const reasoning = args['reasoning'] ? args['reasoning'] : 'medium';
+// if (reasoning) {
+// 	options.reasoning = {
+// 		// @ts-ignore
+// 		effort:reasoning,
+// 		summary: 'auto'
+// 	}
+// }
 const toolsetMode = 'auto';
 const contextWindow = args['context'] ? parseInt(args['context']) : 2565000;
 

package/agents/spawn_agent.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { AgentManager } from '@j-o-r/hello-dave';
 import { parseArgs } from '@j-o-r/sh';
-import fs from 'fs';  // Added for local fallback
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
 
 const name = 'spawn_agent';
 const api = 'xai';
@@ -66,6 +68,7 @@ function printHelp() {
 - **Tools follow YOUR CWD** (e.g., cd /tmp/proj && ./spawn_agent.js → tools in /tmp/proj).
 - **Hybrid Modes**: PROJECT (agents/*.js exist): Auto-deploy/test. FRESH (empty agents/): Code + manual bash.
 - **Custom Tools**: natives=web_search, generics=read_file, custom={type:'git_diff',...}
+- **Prompt**: Loaded with priority to local file inside the @j-o-r/hello-dave npm module (docs/prompt/spawn_agent.md), fallback to live repo fetch.
 
 ## OPTIONS:
 --model [grok-4-fast-reasoning|...] (default: grok-4-fast-reasoning)
@@ -91,19 +94,38 @@ Test new agent: ./agents/NEW.js --help | 'describe' | --serve 8081 --secret abc
 
 Custom ex: natives=[{type:'mytool'}], generics=read_file
 
-Live prompt: https://codeberg.org/duin/hello-dave/raw/branch/main/docs/prompt/spawn_agent.md`.trim();
+Prompt priority: local relative to @j-o-r/hello-dave module or live https://codeberg.org/duin/hello-dave/raw/branch/main/docs/prompt/spawn_agent.md`.trim();
 
 const REPO_URL = 'https://codeberg.org/duin/hello-dave';
 
-
 async function fetchLivePrompt() {
-  // Priority 1: Remote
-    const promptUrl = `${REPO_URL}/raw/branch/main/docs/prompt/spawn_agent.md`;
-    const response = await fetch(promptUrl);
-    if (!response.ok) {
-      throw new Error(`HTTP ${response.status}`);
+  const promptFile = 'docs/prompt/spawn_agent.md';
+
+  // Priority 1: Local relative to the installed @j-o-r/hello-dave module (best for npm/offline)
+  try {
+    const require = createRequire(import.meta.url);
+    const packageJsonPath = require.resolve('@j-o-r/hello-dave/package.json');
+    const moduleRoot = path.dirname(packageJsonPath);
+    const localPromptPath = path.join(moduleRoot, promptFile);
+    if (fs.existsSync(localPromptPath)) {
+      const localPrompt = fs.readFileSync(localPromptPath, 'utf8');
+      console.log(`[spawn_agent] Loaded prompt locally from module: ${localPromptPath}`);
+      return localPrompt;
     }
-    return await response.text();
+  } catch (localErr) {
+    console.warn('[spawn_agent] Local module prompt load skipped:', localErr.message);
+  }
+
+  // Priority 2: Live remote (for latest updates)
+  const promptUrl = `${REPO_URL}/raw/branch/main/${promptFile}`;
+  console.log(`[spawn_agent] Fetching live prompt: ${promptUrl}`);
+  const response = await fetch(promptUrl);
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`);
+  }
+  const text = await response.text();
+  console.log('[spawn_agent] Loaded live prompt from Codeberg');
+  return text;
 }
 
 const agent = new AgentManager({ name, secret });
@@ -126,6 +148,7 @@ agent.addGenericToolcall('javascript_interpreter');
 const cliIntro = `🤖 ${name} (${options.model}) ready! (context: ${contextWindow})
 
 Portable Creator: PROJECT (agents/*.js exist): Auto. FRESH (empty): Manual code.
+Prompt: local in @j-o-r/hello-dave module preferred.
 
 Ex: "Create testagent: desc=Tester, natives=web_search"`.trim();
 
@@ -134,4 +157,4 @@ if (input) {
   console.log(RES);
 } else {
   await agent.start(serve, connect, cliIntro, tool_call_name, tool_call_description);
-}
+}

package/bin/dave.js

@@ -118,9 +118,9 @@ if (args.clear) {
 		};
 		options.tools.push({ type: 'web_search' });
 		options.tools.push({ type: 'x_search' });
-		options.model = args.model || 'grok-4-1-fast-reasoning';
+		options.model = args.model || 'grok-4.20-reasoning';
 		options.temperature = 0.2;
-		options.reasoning = { effort: 'medium', summary: 'auto' };
+		// options.reasoning = { effort: 'medium', summary: 'auto' };
 
 		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.

package/docs/agent-dave-websocket-protocol.md

@@ -0,0 +1,180 @@
+# Agent Dave WebSocket Protocol
+
+**Version**: 0.0.8 (as of April 2026)  
+**Repository**: https://codeberg.org/duin/hello-dave  
+**Core Files**:
+- `lib/AgentServer.js` — Central hub, registers agents as dynamic tools, handles user interactions and sessions.
+- `lib/AgentClient.js` — Agent-side wrapper (Prompt + ToolSet), queue-based message processor, auto-reconnect, epoch-based reset handling.
+- `lib/wsIO.js` — One-shot WS client for CLI tools (`dave --connect`, `wsio()` helper).
+
+## Overview
+
+The protocol enables **multi-agent collaboration** over WebSocket. 
+
+- A central **AgentServer** listens on `ws://127.0.0.1:<port>/ws`.
+- **AgentClient** instances connect, introduce themselves, and get registered as **dynamic tools** in the server's `ToolSet`.
+- The server exposes these agents to the main Prompt, allowing the LLM to call them like any other tool (`agent_query` / `agent_response`).
+- **User/CLI interaction** uses `user_*` actions (via `wsIO.js` or `dave` CLI).
+- All messages are **JSON** objects with an `action` field validated against a fixed list.
+- **Authentication**: `?wssrc_id=<secret>` query param (plain in AgentServer, base64 in wsIO.js).
+- **Reset handling**: Broadcast `reset`, clients use an `#epoch` counter to invalidate in-flight work.
+- **Response matching**: Uses `id` (timestamp-based) + pending map on server.
+
+This design turns specialized agents (code, todo, memory, readme, etc.) into callable tools while supporting direct CLI, interactive REPL, and one-shot queries.
+
+## Message Format
+
+Every message is a JSON object:
+
+```json
+{
+  "action": "one_of_the_actions_below",
+  "content": "string or object (varies)",
+  "id": "unique_timestamp_string_or_number",
+  "name"?: "agent_name_on_introduction"
+}
+```
+
+### Supported Actions (ACTIONS array in AgentServer.js)
+
+**Agent ↔ Server (Tool Calls)**
+- `agent_introduction` — Agent registers itself (sends `name` + `description`).
+- `agent_query` — Server calls an agent tool with natural language `content` (query).
+- `agent_response` — Agent returns result.
+- `agent_error` — Agent reports failure.
+
+**User/CLI ↔ Server**
+- `user_introduction` — CLI connects (sent by wsIO.js).
+- `user_request` — User query to main prompt.
+- `server_response` — Final answer from main prompt.
+- `server_error` — Error from main prompt.
+- `user_reset` — Reset current session.
+- `user_sessionlist` — Request list of saved sessions.
+- `user_loadsession` — Load a previous session.
+- `user_info` — Get server/prompt/session info.
+
+**Server → Clients (broadcasts/responses)**
+- `reset` — Broadcast to all agents on reset.
+- `server_reset`, `server_sessionlist`, `server_sessionloaded`, `server_info` — Responses to user actions.
+
+Unknown actions cause immediate client disconnection.
+
+## Key Interactions & Sequence Diagrams
+
+### 1. Agent Registration & Tool Call
+
+```mermaid
+sequenceDiagram
+    participant AgentClient
+    participant AgentServer
+    participant Prompt/ToolSet
+
+    AgentClient->>AgentServer: WS connect + ?wssrc_id=secret
+    AgentClient->>AgentServer: {action: "agent_introduction", name: "code", content: "Code execution agent..."}
+    AgentServer->>ToolSet: add("code", description, schema, handler)
+    Note over ToolSet,AgentServer: Tool now available to LLM
+
+    Prompt->>ToolSet: LLM decides to call "code" with query
+    ToolSet->>AgentServer: handler(query) → Promise
+    AgentServer->>AgentClient: {action: "agent_query", id: "1745...", content: "Write a bash script..."}
+    AgentClient->>AgentClient: #queue.push(), #processOne()
+    AgentClient->>Prompt: prompt.call(query)
+    AgentClient->>AgentServer: {action: "agent_response", id: "1745...", content: "```bash ...```"}
+    AgentServer->>Prompt: resolve(promise)
+    Prompt->>LLM: Continue with tool result
+```
+
+### 2. User One-Shot Query (via wsIO.js or dave --connect)
+
+```mermaid
+sequenceDiagram
+    participant CLI (wsIO)
+    participant AgentServer
+    participant Prompt
+
+    CLI->>AgentServer: WS connect + wssrc_id
+    CLI->>AgentServer: {action: "user_introduction", id: X}
+    CLI->>AgentServer: {action: "user_request", id: Y, content: "Hello Dave"}
+    AgentServer->>Prompt: prompt.call("Hello Dave")
+    Prompt->>LLM: Full reasoning + tool calls (may call registered agents)
+    Prompt-->>AgentServer: Final content
+    AgentServer->>CLI: {action: "server_response", id: Y, content: "..."}
+    CLI->>CLI: resolve promise, close WS
+```
+
+### 3. Reset Handling
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant AgentServer
+    participant AgentClient
+
+    User->>AgentServer: {action: "user_reset"}
+    AgentServer->>Prompt: prompt.reset()
+    AgentServer-->>All Agents: broadcast {action: "reset"}
+    AgentClient->>AgentClient: #epoch++, #queue=[], prompt.reset()
+```
+
+## Implementation Details
+
+- **Server-side pending responses**: `pendingResponses` Map keyed by `${conn.id}:${msg.id}` with timeout via `setInterval` (30s intervals, max 20 → 10min).
+- **Client-side queue**: Strict sequential processing (`#processing` guard, 2s polling interval by default). Prevents race conditions in tool calls.
+- **Auto-reconnect**: AgentClient retries every 5s on close.
+- **Session Management**: Integrated with `Session.js` for `user_sessionlist` / `user_loadsession`.
+- **wsIO.js specifics**: Sends both `user_introduction` + action in one connection, matches response by `id`, then closes. Uses base64 secret.
+
+## Optimizations & Suggestions
+
+**Current Strengths**
+- Simple JSON, no complex framing.
+- Epoch prevents stale responses after reset.
+- Dynamic tool registration — agents can be added at runtime.
+
+**Potential Improvements**
+1. **Performance**:
+   - Replace polling interval in AgentClient with event-driven queue (e.g. `setImmediate` or microtask after each message).
+   - Use a proper request-response correlation library or WebSocket subprotocol.
+   - Add backpressure handling for high-volume tool calls.
+
+2. **Reliability**:
+   - Heartbeat/ping-pong to detect dead connections faster than timeout.
+   - Exponential backoff on reconnect.
+   - Persistent message IDs (UUID instead of timestamp).
+   - Schema validation for all incoming messages (e.g. Zod or JSON Schema).
+
+3. **Observability**:
+   - Add structured logging (instead of console.log).
+   - Metrics: active clients, avg response time, error rate.
+   - OpenTelemetry or Prometheus integration.
+
+4. **Security**:
+   - Current secret is weak (query param). Consider JWT or mTLS for production.
+   - Rate limiting per connection.
+   - Validate `content` size.
+
+5. **Extensibility**:
+   - Support binary messages for large data (e.g. images, files).
+   - Add `agent_stream` for streaming responses from agents.
+   - Formalize as a subprotocol (`Sec-WebSocket-Protocol: agent-dave-v1`).
+
+6. **Documentation**:
+   - Generate Mermaid diagrams automatically from code comments.
+   - Add protocol test suite in `scenarios/`.
+
+**Next Steps** (from TODO):
+- Complete sequence diagrams (expand the Mermaid examples above).
+- Identify specific performance bottlenecks via profiling.
+- Create formal spec with error codes and versioning.
+
+## References
+
+- `lib/AgentServer.js`
+- `lib/AgentClient.js`
+- `lib/wsIO.js`
+- `agents/spawn_agent.js` (uses this protocol for hybrid/server/client modes)
+- `docs/multi-agent-clusters.md`
+- `docs/prompt/spawn_agent.md`
+
+*Last updated: April 20, 2026*  
+*This document was generated as part of the TODO task "Document and review the 'agent dave websocket protocol'."*

package/docs/dependencies.md

@@ -0,0 +1,7 @@
+
+
+## A linux based os with
+
+`node`
+`spellcheck`
+`msmtp`

package/docs/prompt/spawn_agent.md

@@ -1,59 +1,61 @@
-You are AgentCreator, expert @j-o-r/hello-dave. Create portable CLI/WS agents (./agents/<name>.js). **Tools use exec CWD** (/tmp OK).
+You are AgentCreator, expert @j-o-r/hello-dave. Create portable CLI/WS agents (./agents/<name>.js). **Tools use exec CWD** (/tmp OK).
 
-**NAME RULE**: lowercase a-z0-9_ min2 (/^[a-z_0-9_]{2,}$/) or reject with "Invalid name".
+**NAME RULE**: lowercase a-z0-9_ min2 (/^[a-z_0-9_]{2,}$/) or reject with \"Invalid name\".
 
 **IMPORTS**: NAMED only: AgentManager from '@j-o-r/hello-dave'; parseArgs from '@j-o-r/sh'.
 
-**PORTABILITY**: Auto-npm deps via INSPECT. Absolute imports. No local refs. fetchLivePrompt from repo raw URL.
+**PORTABILITY**: Auto-npm deps via INSPECT. Absolute imports. No local refs. fetchLivePrompt from repo raw URL (or local module path if available).
 
 **PRIORITIES**: Safety (temp files: /tmp/temp_agent.js + rm), blueprint 100% VERBATIM from TEMPLATE below, STRICT step-by-step tool sequence. NO hallucination - follow PROCESS exactly.
 
+**NEW: Escaping & Syntax**: The write_file tool now automatically calls syntax_check.sh --fix. This repairs common LLM over-escaping (template literals, ${}, backticks, etc.). You no longer need to manually fix escaping in generated code. Always use write_file for PROJECT mode.
+
 **INITIAL INSPECT SCRIPT** (MANDATORY FIRST TOOL CALL - execute_bash_script EXACTLY this verbatim):
 ```
-npm ls @j-o-r/hello-dave @j-o-r/sh 2&gt;/dev/null || echo 'MISSING: npm i @j-o-r/hello-dave @j-o-r/sh --save-exact'
+npm ls @j-o-r/hello-dave @j-o-r/sh 2>/dev/null || echo 'MISSING: npm i @j-o-r/hello-dave @j-o-r/sh --save-exact'
 mkdir -p agents
-NUM_AGENTS=$(ls agents/*.js 2&gt;/dev/null | wc -l 2&gt;/dev/null || echo 0)
-PM2_CHECK=$(pm2 list 2&gt;/dev/null | grep hello-dave || echo Standalone)
-echo "NUM_AGENTS: $NUM_AGENTS"
-echo "LAUNCH_MODE: $PM2_CHECK"
-if [ "$NUM_AGENTS" -gt 0 ]; then echo PROJECT; else echo FRESH; fi
+NUM_AGENTS=$(ls agents/*.js 2>/dev/null | wc -l 2>/dev/null || echo 0)
+PM2_CHECK=$(pm2 list 2>/dev/null | grep hello-dave || echo Standalone)
+echo \"NUM_AGENTS: $NUM_AGENTS\"
+echo \"LAUNCH_MODE: $PM2_CHECK\"
+if [ \"$NUM_AGENTS\" -gt 0 ]; then echo PROJECT; else echo FRESH; fi
 ```
 
 **Parse INSPECT output**:
-- If 'MISSING: ...' → Respond: "Run: npm i @j-o-r/hello-dave @j-o-r/sh --save-exact" and STOP.
-- PROJECT (NUM_AGENTS &gt;0): Full auto-deploy/validate/test using tools.
+- If 'MISSING: ...' → Respond: \"Run: npm i @j-o-r/hello-dave @j-o-r/sh --save-exact\" and STOP.
+- PROJECT (NUM_AGENTS >0): Full auto-deploy/validate/test using tools (write_file + syntax_check.sh --fix).
 - FRESH (NUM_AGENTS=0): Print code + manual bash deploy/test commands.
-- LAUNCH_MODE: Standalone | CodeServer (PM2: port=9000 secret=123). For CodeServer, add to cliIntro: "Client mode: --connect ws://127.0.0.1:9000/ws --secret 123". Test with that.
+- LAUNCH_MODE: Standalone | CodeServer (PM2: port=9000 secret=123). For CodeServer, add to cliIntro: \"Client mode: --connect ws://127.0.0.1:9000/ws --secret 123\". Test with that.
 
 **TOOLS**:
 - NATIVES: options.tools.push({ type: 'web_search' });
-- GENERICS: agent.addGenericToolcall('read_file'); etc.
+- GENERICS: agent.addGenericToolcall('read_file'); agent.addGenericToolcall('write_file'); etc. (always include write_file and syntax_check if useful).
 - CUSTOM: options.tools.push({type:'custom', description:'...', parameters:{...}})
 
 **STRICT MANDATORY PROCESS** (exact tool calls in sequence, even for one-shot directCall. NO skipping):
 1. **execute_bash_script** with INITIAL INSPECT SCRIPT (verbatim). Parse output for MODE/LAUNCH_MODE/MISSING.
-2. **Extract/VALIDATE name** from query (e.g. "Create foo_agent: ..."). Reject if invalid.
+2. **Extract/VALIDATE name** from query (e.g. \"Create foo_agent: ...\"). Reject if invalid.
 3. **If PROJECT**: 
-   - execute_bash_script "ls agents/*.js | head -3" 
-   - read_file one example (e.g. agents/spawn_agent.js) to confirm blueprint.
-4. **GATHER specs** from query: desc, api=xai (default), model=grok-4-fast-reasoning, temp=0.8, tokens=..., top_p=..., natives=[], generics=[], custom=[], prompt_src (repo/docs/prompt/&lt;name&gt;.md or hardcoded), cliIntro.
-5. **GENERATE code** EXACTLY from **AGENT BLUEPRINT TEMPLATE** below, filling placeholders. NO deviations.
+   - execute_bash_script \"ls agents/*.js | head -3\" 
+   - read_file one example (e.g. agents/spawn_agent.js or agents/weather_man.js) to confirm blueprint.
+4. **GATHER specs** from query: desc, api=xai (default), model=grok-4-fast-reasoning, temp=0.8, tokens=..., top_p=..., natives=[], generics=[], custom=[], prompt_src (repo/docs/prompt/<name>.md or hardcoded), cliIntro.
+5. **GENERATE code** EXACTLY from **AGENT BLUEPRINT TEMPLATE** below, filling placeholders. NO deviations. Use clean template literals.
 6. **PROJECT AUTO-DEPLOY**:
-   - write_file temp_agent.js "&lt;generated_code&gt;"
-   - execute_bash_script "node --check temp_agent.js &amp;&amp; echo 'SYNTAX:OK' || echo 'SYNTAX:FAIL'"
-   - execute_bash_script "grep -q 'agent.start(' temp_agent.js &amp;&amp; grep -q 'new AgentManager' temp_agent.js &amp;&amp; echo 'BLUEPRINT:OK' || echo 'BLUEPRINT:FAIL'"
-   - If both OK: execute_bash_script "mv temp_agent.js agents/${name}.js &amp;&amp; chmod +x agents/${name}.js &amp;&amp; echo 'DEPLOYED'"
-   - Test: execute_bash_script "./agents/${name}.js --help"
-   - Cleanup: execute_bash_script "rm -f temp_agent.js"
+   - write_file temp_agent.js \"<generated_code>\"   (this now auto-repairs escaping via syntax_check.sh --fix)
+   - execute_bash_script \"node --check temp_agent.js && echo 'SYNTAX:OK' || echo 'SYNTAX:FAIL'\"
+   - execute_bash_script \"grep -q 'agent.start(' temp_agent.js && grep -q 'new AgentManager' temp_agent.js && echo 'BLUEPRINT:OK' || echo 'BLUEPRINT:FAIL'\"
+   - If both OK: execute_bash_script \"mv temp_agent.js agents/${name}.js && chmod +x agents/${name}.js && echo 'DEPLOYED'\"
+   - Test: execute_bash_script \"./agents/${name}.js --help\"
+   - Cleanup: execute_bash_script \"rm -f temp_agent.js\"
    - If fail any step: rm temp_agent.js, explain error.
 7. **FRESH MANUAL**:
    - Print generated code verbatim.
-   - Print bash: "mkdir -p agents; chmod +x agents/${name}.js; echo '&lt;code&gt;' &gt; agents/${name}.js"
-   - Test: "./agents/${name}.js --help"
-8. **CODE_SERVER**: cliIntro += " (CodeServer client ready: --connect ws://127.0.0.1:9000/ws --secret 123)"
+   - Print bash: \"mkdir -p agents; chmod +x agents/${name}.js; cat > agents/${name}.js << 'EOF' ... EOF\"
+   - Test: \"./agents/${name}.js --help\"
+8. **CODE_SERVER**: cliIntro += \" (CodeServer client ready: --connect ws://127.0.0.1:9000/ws --secret 123)\"
 9. **Multi/PM2**: If query mentions cluster, generate PM2 launcher.
 
-**AGENT BLUEPRINT TEMPLATE** (FILL ${...} EXACTLY, NO CHANGES):
+**AGENT BLUEPRINT TEMPLATE** (FILL ${...} EXACTLY, NO CHANGES - use clean backticks):
 ```
 #!/usr/bin/env node
 import { AgentManager } from '@j-o-r/hello-dave';
@@ -66,7 +68,7 @@ let secret = '';
 const args = parseArgs();
 
 let input;
-if (args._.length === 1 &amp;&amp; typeof args._[0] === 'string' &amp;&amp; args._[0].trim() !== '') {
+if (args._.length === 1 && typeof args._[0] === 'string' && args._[0].trim() !== '') {
 	input = args._[0].trim();
 }
 
@@ -75,14 +77,14 @@ const connect = args['connect'] ? args['connect'] : undefined;
 const serve = args['serve'] ? parseInt(args['serve']) : undefined;
 
 const options = { tools: [] };
-${natives || 'options.tools.push({ type: "web_search" });'}
+${natives || 'options.tools.push({ type: \"web_search\" });'}
 ${custom_tools || ''}
 
 if (args['secret']) {
 	secret = args['secret'];
 }
 if (args['model'] || true) {
-	options.model = args['model'] || '${model || "grok-4-fast-reasoning"}';
+	options.model = args['model'] || '${model || \"grok-4-fast-reasoning\"}';
 }
 if (args['temperature']) {
 	options.temperature = parseFloat(args['temperature']);
@@ -100,13 +102,13 @@ const toolsetMode = 'auto';
 const contextWindow = args['context'] ? parseInt(args['context']) : 250000;
 
 function printHelp() {
-	console.log(\`'\${name} --help' You are looking at it.
+	console.log(`'${name} --help' You are looking at it.
 
 ## DESCRIPTION
 ${desc}
 
 ## USAGE MODES:
-### 1. Direct Call: ./${name}.js "query"
+### 1. Direct Call: ./${name}.js \"query\"
 ### 2. Interactive: ./${name}.js
 ### 3. WS Server: ./${name}.js --serve 8080 [--secret abc]
 ### 4. WS Client: ./${name}.js --connect ws://host:port/ws --secret abc
@@ -115,7 +117,7 @@ ${desc}
 ## OPTIONS:
 --model --temp --tokens --top_p --context
 
-\`);
+`);
 	process.exit();
 }
 
@@ -124,21 +126,21 @@ if (help) {
 }
 
 const tool_call_name = '${name}';
-const tool_call_description = \`${desc.trim()}
+const tool_call_description = `${desc.trim()}
 
-Live prompt: https://codeberg.org/duin/hello-dave/raw/branch/main/docs/prompt/${name}.md\`.trim();
+Live prompt: https://codeberg.org/duin/hello-dave/raw/branch/main/docs/prompt/${name}.md`.trim();
 
 const REPO_URL = 'https://codeberg.org/duin/hello-dave';
 
 async function fetchLivePrompt() {
-  const promptUrl = \`\${REPO_URL}/raw/branch/main/docs/prompt/${name}.md\`;
+  const promptUrl = `${REPO_URL}/raw/branch/main/docs/prompt/${name}.md`;
   try {
     const response = await fetch(promptUrl);
-    if (!response.ok) throw new Error(\`HTTP \${response.status}\`);
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
     return await response.text();
   } catch (e) {
     console.warn('Live prompt fetch failed, using fallback.');
-    return \`${prompt_fallback || 'Default agent prompt.'}\`;
+    return `${prompt_fallback || 'Default agent prompt.'}`;
   }
 }
 
@@ -154,11 +156,11 @@ agent.setup({
   contextWindow
 });
 
-${generics || 'agent.addGenericToolcall("read_file"); agent.addGenericToolcall("write_file"); agent.addGenericToolcall("execute_bash_script");'}
+${generics || 'agent.addGenericToolcall(\"read_file\"); agent.addGenericToolcall(\"write_file\"); agent.addGenericToolcall(\"execute_bash_script\"); agent.addGenericToolcall(\"javascript_interpreter\");'}
 
-const cliIntro = \`🤖 \${name} (\${options.model}) ready! (context: \${contextWindow})
+const cliIntro = `🤖 ${name} (${options.model}) ready! (context: ${contextWindow})
 ${cli_intro || desc.substring(0,100) + '...'}
-${launch_mode_note || ''}\`.trim();
+${launch_mode_note || ''}`.trim();
 
 if (input) {
   const RES = await agent.directCall(input);
@@ -168,6 +170,6 @@ if (input) {
 }
 ```
 
-**In ALL responses**: Report MODE/LAUNCH_MODE after INSPECT. End with "Agent ${name} ready! Test: ./agents/${name}.js --help"
+**In ALL responses**: Report MODE/LAUNCH_MODE after INSPECT. End with \"Agent ${name} ready! Test: ./agents/${name}.js --help\"
 
-Date: April 13, 2026. 🚀 Enforce blueprint strictly. See docs/multi-agent-clusters.md.
+Date: April 21, 2026. The write_file tool now auto-repairs escaping via syntax_check.sh --fix. Use clean template literals in generated code. 🚀 Enforce blueprint strictly. See docs/multi-agent-clusters.md.

package/docs/todo-archive-infra-2026-04-21.md

@@ -0,0 +1,15 @@
+# Archived Infrastructure Tasks - 2026-04-21
+
+These tasks related to VPS/CDN setup and publishing agents were removed from TODO.md as they are not core to the hello-dave project.
+
+## Archived from TODO (high priority pending)
+
+- Create a personal CDN on VPS using SSH + Nginx to serve static assets (images, HTML, JS) so that Grok / browse_page tools can directly access them without crawling or conversion issues
+  - Subtask: Set up VPS and SSH access
+  - Subtask: Install and configure Nginx for static file serving
+  - Subtask: Implement security measures (e.g., firewall, SSL/TLS, access controls)
+  - Subtask: Upload and organize static assets
+  - Subtask: Test with previous image test case and verify direct access via tools
+
+- Create publish_agent.js in agents/ for secure deployment of documents to remote VPS (Nginx + ~/htdocs or /var/www/htdocs). Features: persistent config for multiple VPS (SSH host, port, user, htdocs path, http base URL), ask for missing endpoints on first use, generate long/obscure/randomized filenames for privacy (especially sensitive files), clean old/unused files in htdocs, rsync or scp with safety, support for static publishing of docs/markdown/html. Integrate with memory_agent for config persistence if possible. High privacy focus.
+

package/docs/todo-archive-v0.1.0.md

@@ -0,0 +1,32 @@
+# Archived TODO Items - v0.1.0 (2026-04-24)
+
+This archive contains all completed tasks from TODO.md as of 2026-04-24. No pending tasks remain.
+
+## Previously High Priority Pending
+- [x] 2026-04-24: Review and enhance genericToolset.js for better tool definitions, including validation for execute_bash_script parameters.
+
+## Previously In Progress
+- [x] 2026-04-23: Create dedicated test for execute_bash_script tool in scenarios/ folder. The test should be comprehensive, testing timeout, error cases, complex scripts, shebang, and safety (no escaping, CWD only). Reference the definition in lib/genericToolset.js
+
+## Previously Later/Future Tasks
+- [x] Review and add unit tests for agent toolsets (e.g., web_search, execute_bash_script in lib/)
+- [x] Update CHANGELOG.md and prepare for v0.1.0 release (add new features like multi-agent improvements)
+- [x] Enhance documentation: Add examples for hybrid spawn_agent modes in README.md and docs/
+- [x] Implement additional agents: e.g., integration_agent for chaining Grok/OpenAI/Anthropic
+- [x] Optimize WebSocket protocol: Implement suggested optimizations from docs/agent-dave-websocket-protocol.md
+
+## Previously Done (Prior to This Archive)
+- [x] 2026-04-24: Confirm genericToolset.js and its dedicated test are complete (including tests for tool definitions and validation).
+- [x] 2026-04-22: Create TDD test in scenarios/ for escaping fix in syntax_check and write_file before any further implementation. Use test_agent if needed.
+- [x] 2026-04-24: Implement bash tool fixes for execute_bash_script, including shebang support, strict mode enforcement, and input validation improvements.
+- [x] 2026-04-24: Update syntax_check.sh with shebang, strict mode, and enhanced validation for safer script execution.
+- [x] Document and review the "agent dave websocket protocol". Focus on communication between lib/AgentServer.js (central hub), lib/AgentClient.js (agent connections), and lib/wsIO.js (user interaction). Include description of the protocol, sequence diagrams if possible, and optimization suggestions.
+  - [x] Subtask: Review and analyze source files (AgentServer.js, AgentClient.js, wsIO.js)
+  - [x] Subtask: Summarize findings from review - Protocol uses JSON messages with 'action' from fixed ACTIONS list, bidirectional query/response with IDs for matching, introduction for registration, user_* for CLI/WS interaction, reset handling with epoch, pending response map with timeout. Suggestion: Add sequence diagram in Mermaid and document in docs/agent-dave-websocket-protocol.md.
+  - [x] Subtask: Document the protocol structure and message formats
+  - [x] Subtask: Create sequence diagrams for key interactions (Mermaid diagrams added to the new docs file)
+  - [x] Subtask: Identify and suggest optimizations for performance and reliability (detailed section added with 6 categories of improvements)
+
+## Archive Notes
+Older tasks archived on 2026-04-20 to docs/todo-archive-v0.0.9.md. Previous archives: docs/todo-archive-v0.0.8.md (2026-04-15), docs/todo-archive.md (2026-04-13).
+Infrastructure tasks archived to docs/todo-archive-infra-2026-04-21.md on 2026-04-21.

package/lib/fafs.js

@@ -45,7 +45,7 @@ new CacheAsync(APP_CACHE, true, 'bin');
  * @property {string} secret - Secret key for cache encryption/security
  */
 const GLOBAL = {
-	max_recursive_requests: 20,
+	max_recursive_requests: 50,
 	default_cache: APP_CACHE,
 	secret: 'tdb.e3a0cd73dd6a429283f921f9fc1bad41'
 }
@@ -126,4 +126,4 @@ export {
 	GLOBAL,
 	env,
 	systemInfo
-}
+}

package/lib/genericToolset.js

@@ -7,7 +7,7 @@ import { fileURLToPath } from 'node:url';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-// STANDARDIZED UTILS PATHS (hoisted constants for performance/consistency)
+// STANDARDIZED UTILS PATHS
 const utilsDir = path.resolve(__dirname, '..', 'utils');
 const searchSessionsSh = path.join(utilsDir, 'search_sessions.sh');
 const listSessionsSh = path.join(utilsDir, 'list_sessions.sh');
@@ -26,16 +26,62 @@ ExternalIp: ${user.external_ip}
 const tools = new ToolSet('auto');
 
 /**
- * Reduces verbose JavaScript evaluation error output to essential info (line number + core message).
- * @param {string} errorStr - Full Node.js error string.
- * @returns {string} Simplified error.
- * @private
+ * Single source of truth for cleaning over-escaped strings from LLMs.
+ * Basic cleaning only. Heavy repair (especially for JS template literals)
+ * is now centralized in utils/syntax_check.sh (repair_file logic).
  */
+const guessOverEscaping = (s) => {
+	if (typeof s !== 'string') return s;
+
+	let current = s.trim();
+	const seen = new Set();
+	let iterations = 0;
+	const MAX_ITER = 6;
+
+	while (iterations < MAX_ITER && !seen.has(current)) {
+		seen.add(current);
+		iterations++;
+
+		try {
+			const parsed = JSON.parse(current);
+			if (typeof parsed === 'string') {
+				current = parsed;
+				continue;
+			}
+		} catch (e) { }
+
+		if (current.startsWith('\\"') && current.endsWith('\\"')) {
+			current = current.slice(2, -2);
+			continue;
+		}
+
+		if (current.startsWith('"') && current.endsWith('"') && current.length > 2) {
+			const inner = current.slice(1, -1).trim();
+			if (!inner.startsWith('{') && !inner.startsWith('[')) {
+				current = inner;
+				continue;
+			}
+		}
+
+		if (!current.includes('\n') && (current.match(/\\"/g) || []).length >= 1) {
+			const lessEscaped = current.replace(/\\"/g, '"');
+			if (lessEscaped !== current) {
+				current = lessEscaped;
+				continue;
+			}
+		}
+
+		break;
+	}
+
+	return current;
+};
+
 const getJSError = (errorStr) => {
 	let result = '';
 	const linematch = errorStr.match(/\[eval\]:(\d+)/);
 	const lineNumber = linematch ? linematch[1] : '';
-	const match = errorStr.split(/\" \"\[eval\]:\d+/s);
+	const match = errorStr.split(/" "\[eval\]:\d+/s);
 	if (match.length > 1) {
 		const res = match[1].split('\n').slice(0, -10).join('\n');
 		result = `Error: line ${lineNumber}\n${res} `;
@@ -47,14 +93,13 @@ const getJSError = (errorStr) => {
 
 /**
  * @module lib/genericToolset
- * Secure utility tools for code execution, file I/O, system ops. Pre-populated ToolSet.
- * 
- * @example
- * import tools from './lib/genericToolset.js';
- * await tools.call('get_user_env', {});
- * 
- * @see {@link module:./index~ToolSet}
+ * Secure utility tools. 
+ * write_file writes content, then runs syntax_check.sh WITHOUT --fix.
+ * On syntax error the error details are returned in the tool response
+ * (file is kept so LLM agents can read_file, inspect escaping issues,
+ * and submit a corrected version on the next write_file call).
  */
+
 tools.add(
 	'javascript_interpreter',
 	'Execute ESM ES6 JavaScript on node.',
@@ -71,9 +116,10 @@ tools.add(
 	async (params) => {
 		let response = '';
 		try {
+			const script = guessOverEscaping(params.script);
 			const delim = `JS_STDIN_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 6)}`;
 			response = await SH`cat <<'${delim}' | node --input-type=module -
-${params.script}
+${script}
 ${delim}
 `.run();
 		} catch (e) {
@@ -92,33 +138,57 @@ tools.add(
 
 tools.add(
 	'execute_bash_script',
-	'Execute raw bash script or command (no escaping needed). Supports timeout to prevent hangs.',
+	'Execute raw bash script or command (no escaping needed). Supports timeout.',
 	{
 		type: 'object',
 		properties: {
 			bash_script: {
 				type: 'string',
-				description: `Raw bash verbatim. Supports all syntax safely via stdin. System: ${user.system}`
+				description: `
+**Write raw bash exactly** as it should appear in a .sh file. Use normal bash escaping only (\`'\\''\` for single quotes inside single quotes, \`\\$\` for literal dollar, etc.).
+
+Do NOT add extra backslashes for JSON, JavaScript, or XML. The system parses the JSON then passes your exact text to bash via stdin.
+
+Correct example you should output in the parameter:
+
+\`\`\`bash
+echo 'Single quotes: '\\''quoted'\\'''
+echo "Double quotes: \\"quoted\\""
+echo "Dollar: \\$HOME = $HOME"
+echo \\\`date\\\`
+echo -e 'Pipe test:\\n1\\n2' | cat
+\`\`\`
+Supports all syntax safely via stdin. System: ${user.system}`
 			},
 			timeout: {
 				type: 'number',
 				default: 360,
-				description: 'Max execution time in seconds (default 360 seconds, 0 is no timeout). Uses @j-o-r/sh timeout (ms) with SIGTERM on expiry to prevent hangs from interactive prompts or slow commands.'
+				description: 'Max execution time in seconds (default 360).'
+			},
+			strict: {
+				type:'boolean' ,
+				default: false,
+				description: 'Validate bash script STRICT first before it is being executed.'
 			}
 		},
 		required: ['bash_script']
 	},
 	async (params) => {
+		function escapeForBashTemplate(bashContent) {
+			return bashContent;
+		}
 		const timeoutSec = Number(params.timeout ?? 300);
+		const prams = params.strict? '' : '-S error';
+		const bash_script = escapeForBashTemplate(params.bash_script);
 		if (isNaN(timeoutSec) || timeoutSec < 0) throw new Error('Invalid timeout');
+		console.log(bash_script);
 		const timeout = timeoutSec * 1000;
-		// return await SH`bash`.options({ timeout: timeoutMs }).run(params.bash_script);
-    const delim = `END_SCRIPT_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
-		return await SH`bash <<'${delim}'
-${params.bash_script}
-${delim}
-`.options({timeout}).run();
-
+		const valid = SH`shellcheck ${prams} -`.runSync(bash_script).stdout.toString().trim();
+		if (valid !== '') {
+			console.log(valid);
+			throw new Error(valid);
+		}
+		return await SH`bash`.options({ timeout }).run(bash_script);
 	}
 );
 
@@ -135,12 +205,15 @@ tools.add(
 		required: ['to', 'subject', 'body']
 	},
 	async (params) => {
+		const to = guessOverEscaping(params.to);
+		const subject = guessOverEscaping(params.subject);
+		const body = guessOverEscaping(params.body);
 		const delim = `END_EMAIL_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
 		return await SH`msmtp ${params.to} <<'${delim}'
-To: ${params.to}
-Subject: ${params.subject}
+To: ${to}
+Subject: ${subject}
 
-${params.body}
+${body}
 ${delim}
 `.run();
 	}
@@ -156,12 +229,15 @@ tools.add(
 		},
 		required: ['url']
 	},
-	async (params) => await SH`xdg-open ${[params.url]}`.run()
+	async (params) => {
+		let url = guessOverEscaping(params.url?.trim());
+		return await SH`xdg-open ${[url]}`.run();
+	}
 );
 
 tools.add(
 	'execute_remote_script',
-	'Run bash on remote via SSH. Supports timeout to prevent hangs.',
+	'Run bash on remote via SSH.',
 	{
 		type: 'object',
 		properties: {
@@ -170,13 +246,16 @@ tools.add(
 			timeout: {
 				type: 'number',
 				default: 30,
-				description: 'Max execution time in seconds (default 30). Uses @j-o-r/sh timeout (ms) with SIGTERM on SSH process expiry.'
+				description: 'Max execution time in seconds (default 30).'
 			}
 		},
 		required: ['url', 'script']
 	},
 	async (params) => {
-		const { url, script } = params;
+		let { url, script } = params;
+		url = guessOverEscaping(url);
+		script = guessOverEscaping(script);
+
 		const timeoutSec = Number(params.timeout ?? 30);
 		if (isNaN(timeoutSec) || timeoutSec <= 0) throw new Error('Invalid timeout');
 		const timeoutMs = timeoutSec * 1000;
@@ -203,7 +282,8 @@ tools.add(
 	},
 	async (params) => {
 		if (typeof params.query === 'string' && params.query.trim()) {
-			return await SH`${searchSessionsSh} "${bashEscape(params.query)}"`.run();
+			const q = guessOverEscaping(params.query);
+			return await SH`${searchSessionsSh} "${bashEscape(q)}"`.run();
 		}
 		return await SH`${listSessionsSh}`.run();
 	}
@@ -220,9 +300,9 @@ tools.add(
 		required: ['file']
 	},
 	async (params) => {
-		const file = params.file?.trim();
-		if (typeof file !== 'string' || !file || file.startsWith('/') || file.includes('..') || file.includes('\\\\')) {
-			throw new Error('Relative CWD path only (no /, .., \\\\).');
+		let file = guessOverEscaping(params.file?.trim());
+		if (typeof file !== 'string' || !file || file.startsWith('/') || file.includes('..') || file.includes('\\')) {
+			throw new Error('Relative CWD path only (no /, .., \\).');
 		}
 		const resolved = path.resolve(process.cwd(), file);
 		if (!resolved.startsWith(process.cwd())) throw new Error('Escapes CWD.');
@@ -232,7 +312,7 @@ tools.add(
 
 tools.add(
 	'write_file',
-	'Write/validate file in CWD. Auto-syntax check + JS fix + chmod.',
+	'Write/validate file in CWD. Writes content to file then runs syntax_check.sh (no --fix). Syntax errors (if any) are reported back in the response so LLM can inspect escaping and correct on next call. File is kept on error.',
 	{
 		type: 'object',
 		properties: {
@@ -242,52 +322,39 @@ tools.add(
 		required: ['file', 'content']
 	},
 	async (params) => {
-		const file = params.file?.trim();
-		const content = params.content ?? '';
-		if (typeof file !== 'string' || !file || file.startsWith('/') || file.includes('..') || file.includes('\\\\')) {
-			throw new Error('Relative CWD path only.');
+		let fileParam = guessOverEscaping(params.file?.trim());
+		let content = guessOverEscaping(params.content ? params.content : '');
+
+		if (typeof fileParam !== 'string' || !fileParam || fileParam.startsWith('/') || fileParam.includes('..') || fileParam.includes('\\')) {
+			throw new Error('Relative CWD path only (no /, .., \\).');
 		}
-		const resolved = path.resolve(process.cwd(), file);
+		const resolved = path.resolve(process.cwd(), fileParam);
 		if (!resolved.startsWith(process.cwd())) throw new Error('Escapes CWD.');
-		const dir = path.dirname(resolved);
-		const ext = path.extname(file);
-		let finalContent = content, validationMsg = '';
 
-		const temp1 = path.join(dir, `temp_${Date.now()}_${Math.random().toString(36).slice(2,6)}${ext || '.tmp'}`);
-		await fs.writeFile(temp1, content, 'utf8');
+		const dir = path.dirname(resolved);
+		await fs.mkdir(dir, { recursive: true });
+		await fs.writeFile(resolved, content, 'utf8');
 
+		let validationMsg = '';
 		try {
-			await SH`${syntaxCheckSh} ${[temp1]}`.run();
-			validationMsg = ' ✓ Syntax OK';
-		} catch (e) {
-			if (!['.js','.mjs'].includes(ext)) {
-				await fs.unlink(temp1).catch(()=>{}); 
-				throw new Error(`Syntax error: ${e.message}`);
-			}
-			let fixed = content.replace(/\\\\`/g, '\\`').replace(/\\\`/g, '`').replace(/\\`/g, '`').replace(/\\\$/g, '$').replace(/\\\${/g, '${');
-			const temp2 = path.join(dir, `temp_fix_${Date.now()}_${Math.random().toString(36).slice(2,6)}.js`);
-			await fs.writeFile(temp2, fixed, 'utf8');
-			try {
-				await SH`${syntaxCheckSh} ${[temp2]}`.run();
-				finalContent = fixed;
-				await fs.rename(temp2, resolved);
-				await fs.unlink(temp1).catch(()=>{}); 
-				validationMsg = ' ✓ Fixed JS';
-			} catch {
-				await fs.unlink(temp1).catch(()=>{}); 
-				await fs.unlink(temp2).catch(()=>{}); 
-				throw new Error(`Syntax error (fix failed): ${e.message}`);
-			}
+			const checkOutput = await SH`${syntaxCheckSh} ${resolved}`.run();
+			validationMsg = checkOutput ? ` ${checkOutput.trim()}` : ' ✓ Syntax OK';
+		} catch (checkErr) {
+			const errText = checkErr?.toString() || 'Unknown syntax error';
+			validationMsg = ` [Syntax Error] ${getJSError(errText) || errText}`;
+			// File is intentionally kept so LLM can read_file and fix escaping
 		}
 
-		if (validationMsg === ' ✓ Syntax OK') await fs.rename(temp1, resolved);
-
-		if (finalContent.startsWith('#!')) {
-			await SH`chmod +x ${[resolved]}`.run();
-			validationMsg += ' ✓ +x';
+		if (content.trim().startsWith('#!')) {
+			try {
+				await SH`chmod +x ${[resolved]}`.run();
+				validationMsg += ' ✓ +x';
+			} catch (e) {
+				validationMsg += ' (chmod failed)';
+			}
 		}
 
-		return `Wrote ${file} (${Buffer.byteLength(finalContent, 'utf8')} bytes).${validationMsg}`;
+		return `Wrote ${fileParam} (${Buffer.byteLength(content, 'utf8')} bytes).${validationMsg}`;
 	}
 );
 
@@ -302,11 +369,18 @@ tools.add(
 		required: ['file']
 	},
 	async (params) => {
-		const file = params.file?.trim();
+		const file = guessOverEscaping(params.file?.trim());
 		if (typeof file !== 'string' || !file) throw new Error('Relative path required.');
 		const resolved = path.resolve(process.cwd(), file);
 		if (!resolved.startsWith(process.cwd())) throw new Error('Escapes CWD.');
-		return await SH`${syntaxCheckSh} ${[resolved]}`.run();
+
+		const args = resolved;
+		try {
+			const out = await SH`${syntaxCheckSh} ${args}`.run();
+			return out || 'Syntax validation passed';
+		} catch (e) {
+			return `Syntax check failed: ${e.toString()}`;
+		}
 	}
 );
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@j-o-r/hello-dave",
   "type": "module",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "ESM toolkit for building AI agents with unified access to Grok (XAI), OpenAI, and Anthropic endpoints",
   "main": "./lib/index.js",
   "types": "./types/index.d.ts",

package/utils/syntax_check.sh

@@ -1,20 +1,20 @@
 #!/bin/bash
 # utils/syntax_check.sh - Multi-language syntax validation
-# Usage: ./utils/syntax_check.sh <file> [--fix|--verbose]
-# Detects lang from ext/shebang, runs checker. Returns 0=OK, 1=error.
-# Integrates with write_file tool retries.
+# Usage: ./utils/syntax_check.sh <file>
+# Detects lang from ext/shebang, runs checker.
+# Captures stdout+stderr from each syntax tool and echoes it back to STDOUT.
+# Returns 0=OK, 1=error. Integrates with write_file lib/genericToolset.js tool.
 
 set -euo pipefail
 
 FILE="${1?Error: Provide file path}"
-VERBOSE="${2:-}"
-FIX="${VERBOSE:0:4}==--fix"
+MODE="${2:-}"
 
 [ ! -f "$FILE" ] && { echo "❌ File not found: $FILE"; exit 1; }
 
 # Detect language
 EXT="${FILE##*.}"
-SHEBANG=$(head -n1 "$FILE" 2>/dev/null | cut -d' ' -f1)
+SHEBANG=$(head -n1 "$FILE" 2>/dev/null | cut -d' ' -f1 || true)
 
 detect_lang() {
   case "$SHEBANG" in
@@ -35,26 +35,70 @@ detect_lang() {
 LANG=$(detect_lang)
 echo "🔍 Validating $FILE (lang: $LANG)"
 
+# Helper to run checker, capture all output (stdout+stderr), echo it, then print status
+run_check() {
+  local cmd="$1"
+  local label="$2"
+  local ok_msg="✅ ${label} OK"
+  local err_msg="❌ ${label} syntax error"
+
+  echo "→ Running: $cmd"
+  if output=$(eval "$cmd" 2>&1); then
+    if [ -n "$output" ]; then
+      echo "$output"
+    fi
+    echo "$ok_msg"
+    return 0
+  else
+    if [ -n "$output" ]; then
+      echo "$output"
+    else
+      echo "(No output from checker - exited with error)"
+    fi
+    echo "$err_msg"
+    return 1
+  fi
+}
+
 case "$LANG" in
   js)
-    node --check "$FILE" && echo "✅ JS OK" || { echo "❌ JS syntax error"; exit 1; }
+    run_check "node --check \"$FILE\"" "JS" || exit 1
     ;;
   py)
-    python3 -m py_compile "$FILE" && echo "✅ Python OK" || { echo "❌ Python syntax error"; exit 1; }
+    run_check "python3 -m py_compile \"$FILE\"" "Python" || exit 1
     ;;
   bash|sh)
-    bash -n "$FILE" && echo "✅ Bash OK" || { echo "❌ Bash syntax error"; exit 1; }
-    # Optional: shellcheck if installed
-    if command -v shellcheck >/dev/null; then
-      shellcheck "$FILE" || echo "⚠️ Shellcheck warnings"
+    run_check "shellcheck \"$FILE\"" "Bash" || exit 1
+
+    # Optional: shellcheck (warnings only, does not fail build)
+    if command -v shellcheck >/dev/null 2>&1; then
+      echo "→ Running: shellcheck \"$FILE\""
+      if shell_output=$(shellcheck "$FILE" 2>&1); then
+        if [ -n "$shell_output" ]; then
+          echo "$shell_output"
+        fi
+        echo "✅ Shellcheck passed"
+      else
+        echo "$shell_output"
+        echo "⚠️ Shellcheck found issues (warnings only)"
+      fi
     fi
     ;;
   json)
-    node -e "JSON.parse(require('fs').readFileSync(process.argv[1], 'utf8'))" "$FILE" && echo "✅ JSON OK" || { echo "❌ JSON invalid"; exit 1; }
+    run_check "node -e '
+      try {
+        JSON.parse(require(\"fs\").readFileSync(process.argv[1], \"utf8\"));
+        console.log(\"JSON is valid\");
+      } catch (e) {
+        console.error(e.message);
+        process.exit(1);
+      }
+    ' \"$FILE\"" "JSON" || exit 1
     ;;
   unknown)
-    echo "⚠️ Unknown lang for $EXT / shebang: $SHEBANG"
-    exit 0  # Non-fatal
+    echo "⚠️ Unknown language for extension .$EXT / shebang: $SHEBANG"
+    echo "✅ Skipping syntax check"
+    exit 0
     ;;
 esac