@j-o-r/hello-dave 0.0.7 → 0.0.9

package/docs/toolset.md

@@ -0,0 +1,164 @@
+# ToolSet (\`lib/ToolSet.js\`)
+
+## Overview
+**ToolSet** manages LLM function calls (tools): registration, execution, listing. Integrates with \`Prompt.js\` (via \`execute(prompt)\`) and \`AgentManager.js\` (pre-configured modes, generics). Supports JSON Schema params, async methods. Exports from \`lib/genericToolset.js\`: \`toolsPool\` (11 pre-built tools).
+
+**Uses named exports from \`lib/index.js\` - NO default export.**
+
+Key Features:
+- **Modes**: \`toolChoice: 'auto'|'none'|'required'\` (default \`'auto'\`).
+- **Validation**: Name regex \`/^\[#![a-z_0-9]{2,}$/\`.
+- **Events** (via \`Prompt\`): \`tool_request\`, \`tool_error\`, \`tool_response\`.
+- **Execution**: \`execute(prompt)\` processes \`function_request\`s from last message → calls → adds \`function_response\`s.
+
+## Constructor
+\`\`\`javascript
+import { ToolSet } from '@j-o-r/hello-dave';
+
+new ToolSet(choice = 'auto');  // 'auto'|'none'|'required'
+\`\`\`
+
+## Methods
+| Method | Args | Returns | Description |
+|--------|------|---------|-------------|
+| \`add(name, desc, params, method)\` | \`string\`, \`string\`, \`TSSchema\`, \`async (params) => *\` | \`void\` | Register tool. Overwrites if exists. |
+| \`get(name)\` | \`string\` | \`TSTool\` | Get tool details. |
+| \`delete(name)\` | \`string\` | \`void\` | Remove tool. |
+| \`has(name)\` | \`string\` | \`boolean\` | Exists? |
+| \`list()\` | - | \`TSToolListItem[]\` (sorted) | All tools (name/desc/params). |
+| \`call(name, params)\` | \`string\`, \`object\` | \`Promise<*\>\` | Execute tool. |
+| \`execute(prompt)\` | \`Prompt\` | \`Promise<void>\` | Process last message \`function_request\`s → execute → add \`function_response\`s to \`tool\` role. |
+| \`length\` | - | \`number\` | Tool count. |
+| \`toolChoice\` | - | \`string\` | Getter for mode. |
+
+**TSTool**: \`{description: string, parameters: TSSchema, method: async (params) => *}\`  
+**TSSchema**: OpenAI-style JSON Schema (\`{type: 'object', properties: {...}, required: [...]}\`).
+
+## Generic Tools (\`lib/genericToolset.js\` → \`toolsPool\`)
+| `syntax_check` | Validate syntax (JS/Py/Bash/JSON) via utils/syntax_check.sh. |\n|-----|-----|
+Pre-built \`ToolSet('auto')\` with **11 tools**. Copied via \`AgentManager.addGenericToolcall(name)\` or \`toolsetMode: 'auto'\`.
+
+| Tool Name                  | Description |
+|----------------------------|-------------|
+| \`javascript_interpreter\` | Execute ESM ES6 JavaScript on \`node\`. \`console.log\` captures output. cwd: \`~/devpri/js/hello-dave\`. |
+| \`get_user_env\`           | Get user environment (name, system, city/region/country/timezone, external IP). |
+| \`execute_bash_script\`    | Execute raw Bash script/command (no escaping; verbatim \`$\| < > & " ' \\\\` newlines \`$(())\` \`[[ ]]\`. Heredoc-safe). Ubuntu 25.10. |
+| \`send_email\`             | Send email via \`msmtp\` (to, subject, body). |
+| \`open_link\`              | Open URL/file with \`xdg-open\`. |
+| \`execute_remote_script\`  | Execute raw Bash on remote via SSH (\`ssh://user@host[:port]\`). |
+| \`history_search\`         | Search chat sessions: \`"(todo\\|task)"\` or \`"package.json"\`. Regex in \`.cache/[app]/[prompt]/sessions/*.ndjson\`. |
+| \`read_file\`              | Read raw file in CWD (relative path, no \`/\` \`..\` \`\\\\\`). |
+| \`write_file\`             | Write raw content to file in CWD (relative, as-is; no escaping). Returns bytes written. |
+| \`memory_recall\`          | Recall persistent memory entries from agent-specific storage (\`.cache/[agent]/memory.ndjson\`). |
+| \`memory_write\`           | Write/update persistent memory entries for long-term state (\`.cache/[agent]/memory.ndjson\`). |
+
+## Memory Tools (New)
+These tools provide persistent, agent-specific memory storage in NDJSON format (\`.cache/[agent-name]/memory.ndjson\`). Append-only; latest value per key. Ideal for token efficiency by offloading state/decisions from context.
+
+### \`memory_recall\`
+**Description**: Retrieve the latest values for specified keys from memory file. Returns JSON: \`{key: value, ...}\` or \`{}\` if missing.
+
+**Parameters**:
+\`\`\`json
+{
+  "type": "object",
+  "properties": {
+    "keys": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of memory keys to recall, e.g., ['current_task', 'last_decision']"
+    }
+  },
+  "required": ["keys"]
+}
+\`\`\`
+
+**Example Usage in Agent Prompt**:
+\`\`\`
+Before proceeding, recall your current task and previous decision:
+- Call memory_recall with keys: ["current_task", "last_decision"]
+Then, use the recalled info to avoid repetition.
+\`\`\`
+
+**Token Efficiency**: Stores tasks/decisions externally. Recall only needed state (e.g., 100 tokens) vs. full history (10k+ tokens), preventing loops/re-reasoning.
+
+### \`memory_write\`
+**Description**: Append/update key-value pairs to memory (overwrites prior same-key entries). Returns confirmation with stored entries.
+
+**Parameters**:
+\`\`\`json
+{
+  "type": "object",
+  "properties": {
+    "entries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "key": { "type": "string", "description": "Unique key (e.g., 'current_task')" },
+          "value": { "type": "string", "description": "JSON-stringifiable value" }
+        },
+        "required": ["key", "value"]
+      },
+      "description": "List of {key, value} pairs to store"
+    }
+  },
+  "required": ["entries"]
+}
+\`\`\`
+
+**Example Usage in Agent Prompt**:
+\`\`\`
+After analyzing, store the plan:
+- Call memory_write with entries: [{"key": "current_task", "value": "Implement login feature"}, {"key": "step", "value": "1/5"}]
+\`\`\`
+
+**Token Efficiency**: Persist intermediate results across calls/sessions. Avoids context explosion/loops by recalling compact state instead of regenerating.
+
+## Integration with AgentManager
+In \`setup()\`:
+\`\`\`javascript
+agent.setup({
+  toolsetMode: 'auto',  // Loads all 11 generic tools
+  // or 'required': Empty ToolSet (add manually)
+});
+agent.addGenericToolcall('memory_recall');  // Selective copy post-setup
+\`\`\`
+
+**Custom Tools**:
+\`\`\`javascript
+import { AgentManager } from '@j-o-r/hello-dave';
+
+agent.setup({ toolsetMode: 'required' });
+const ts = agent.getToolset();
+ts.add('math', 'Add numbers', {
+  type: 'object',
+  properties: {a: {type: 'number'}, b: {type: 'number'}},
+  required: ['a', 'b']
+}, async ({a, b}) => a + b);
+\`\`\`
+
+**Workflow** (in \`Prompt.call()\` / API adapters):
+1. LLM → \`function_request\`s (assistant message).
+2. \`ToolSet.execute(prompt)\` → parallel \`call()\` → \`function_response\`s (tool message).
+3. Recurse until text response.
+
+## Examples
+### Standalone ToolSet
+\`\`\`javascript
+import { ToolSet } from '@j-o-r/hello-dave';
+
+const ts = new ToolSet('required');
+ts.add('hello', 'Say hello', {type: 'object', properties: {name: {type: 'string'}}, required: ['name']},
+  async ({name}) => \`Hello, \${name}!\`);
+console.log(await ts.call('hello', {name: 'World'}));  // "Hello, World!"
+\`\`\`
+
+### With Prompt/AgentManager
+See [AgentManager](./agent-manager.md#custom-tools--generics), [Prompt](./prompt-class.md).
+
+**Updated:** March 26, 2026 (11 generics from \`lib/genericToolset.js\`).
+
+See also: [GenericToolset Source](./generic-toolset.md).
+\n## Syntax Validation\nSee [tools-syntax-validation.md](tools-syntax-validation.md) for `write_file` JS checks + `syntax_check` tool.
+\n## Path Resolution\nSee [path-resolution-best-practices.md](path-resolution-best-practices.md) for __dirname vs cwd() in tools (e.g., syntax_check.sh).\\n

package/docs/xai-responses.md

@@ -0,0 +1,111 @@
+# xAI Responses API Integration (`lib/API/x.ai/responses.js`)
+
+## Overview
+This module provides a seamless wrapper for the [xAI Responses API](https://docs.x.ai/docs/api-reference#create-new-response) (formerly Grok API), adapted for the hello-dave framework. It integrates directly with `Prompt.js` and `ToolSet.js`, enabling tool-using agents via `AgentManager`.
+
+**Uses named exports from `lib/index.js` - NO default export.**
+
+Key adaptations:
+- **Unified Interface**: Uses `Prompt` messages/history for input; parses `output` into assistant/tool responses.
+- **Recursive Tool Calls**: Automatically handles `function_call` → execute tools → `function_call_output` loops (up to `GLOBAL.max_recursive_requests`).
+- **Tool Support**: Converts `ToolSet` to xAI `function` tools; supports native xAI tools like `web_search`, `x_search`.
+- **Reasoning & Search**: Configurable `reasoning.effort` (`low`/`medium`/`high`), `search_parameters`.
+- **Streaming**: Not yet implemented (future).
+- **Auth**: Requires `XAIKEY` env var.
+
+Default model: `grok-4-fast-reasoning`. Supports: `grok-4-fast-reasoning`, `grok-4-fast-non-reasoning`, etc.
+
+## Usage in AgentManager
+```javascript
+import { AgentManager } from '@j-o-r/hello-dave';
+
+const agent = new AgentManager({ name: 'weatheragent', secret: 'optional-ws-secret' });
+agent.setup({
+  prompt: 'You are a precise weather expert. Use tools for real-time data.',
+  api: 'xai',
+  options: { model: 'grok-4-fast-reasoning', reasoning: { effort: 'high' } },
+  toolsetMode: 'auto',  // Adds generic tools like web_search
+  contextWindow: 128000
+});
+agent.addGenericToolcall('web_search');  // Optional: Add extras
+
+// CLI mode
+agent.start();  // Interactive chat
+
+// Or direct call
+const response = await agent.directCall('Weather in Amsterdam today?');
+console.log(response);  // Handles search/tools automatically
+```
+
+Under the hood:
+1. `Prompt.setAdaptor(API.text['xai'], toolset, options)` → uses `responses.request()`.
+2. Converts history to xAI `input[]` (system/user/assistant/tool).
+3. POST to `https://api.x.ai/v1/responses`.
+4. Parses `output` → adds text/reasoning/tools to `Prompt`.
+5. If tools needed, `ToolSet.execute()` → recurse until complete.
+
+## Options (XAIOptions)
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `model` | string | `'grok-4-fast-non-reasoning'` | e.g., `'grok-4-fast-reasoning'` |
+| `input` | `XAIInput[]` | `[{role: 'system', content: 'Be precise'}]` | Messages/history |
+| `reasoning.effort` | `'low'\|'medium'\|'high'` | `'medium'` | Reasoning depth |
+| `reasoning.summary` | `'auto'\|'concise'\|'detailed'` | `'auto'` | Reasoning output style |
+| `temperature` | number | `1` (0-2) | Sampling |
+| `parallel_tool_calls` | boolean | `true` | Parallel functions |
+| `tool_choice` | `'auto'` | `'auto'` | Tool selection |
+| `tools` | `XAIFunctionTool[]` | `[]` | From `ToolSet` |
+| `store` | boolean | `false` | Persist response (still bills tokens) |
+| `max_output_tokens` | number | `4000` | Limit |
+| `search_parameters` | object | - | `{max_search_results: 4, mode: 'auto', return_citations: true}` |
+
+**Tool Types**:
+- `function`: From `ToolSet` (name, description, parameters JSONSchema).
+- Native: `web_search`, `x_search` (filters: dates, domains, etc.).
+
+## Example Request (Generated Internally)
+```json
+{
+  "model": "grok-4-fast-reasoning",
+  "input": [
+    {"role": "system", "content": "You are a precise weather expert."},
+    {"role": "user", "content": "Weather in Amsterdam today?"}
+  ],
+  "parallel_tool_calls": true,
+  "reasoning": {"effort": "high"},
+  "search_parameters": {"mode": "auto", "return_citations": true},
+  "tools": [{"type": "function", "name": "web_search", ...}]
+}
+```
+
+## Example Response (Parsed to Prompt)
+- **Text + Citations**: Added as `assistant` text + `log` annotations (URLs).
+- **Function Calls**: `assistant` with `function_request` → `ToolSet.execute()`.
+- **Reasoning**: Prepended as `reasoning` multimodal text.
+
+Sample parsed:
+```
+Today is [date]. Weather: Cloudy, 5°C... [citations]
+```
+Tokens: `input_tokens`, `output_tokens` (incl. `reasoning_tokens`) logged in `Prompt.records`.
+
+## Advanced: Custom Tools
+Extend `ToolSet` before `setup()`:
+```javascript
+import { ToolSet } from '@j-o-r/hello-dave';
+
+const ts = new ToolSet('required');
+ts.add('get_weather', 'Get weather for a location', {
+  type: 'object',
+  properties: { location: {type: 'string'} },
+  required: ['location']
+}, async (params) => `Weather: ${params.location} - 20°C`);  // Handler
+agent.setup({ ..., toolsetMode: ts });
+```
+
+## Errors & Limits
+- `Max recursive calls`: `GLOBAL.max_recursive_requests`.
+- Missing `XAIKEY`: Throws.
+- Invalid last message: Must end in `user`/`tool`.
+
+See `lib/API/x.ai/responses.js` source for full JSDoc/types. Cross-links: [Prompt](../prompt-class.md), [ToolSet](../toolset.md), [AgentManager](agent-manager.md).

package/docs/xai_collections.md

@@ -0,0 +1,106 @@
+[x.ai collections](https://docs.x.ai/docs/guides/using-collections/api)
+
+
+Creating a collection:
+
+```bash
+curl https://management-api.x.ai/v1/collections \
+  -X POST \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \
+  -d '{"collection_name": "SEC Filings"}'
+```
+
+Listing collections:
+```bash
+curl https://management-api.x.ai/v1/collections \
+  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
+```
+
+Viewing collection configuration:
+```bash
+'curl https://management-api.x.ai/v1/collections/collection_dbc087b1-6c99-493d-86c6-b401fee34a9d \
+  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
+```
+
+Updating collection configuration
+```bash
+curl https://management-api.x.ai/v1/collections/collection_dbc087b1-6c99-493d-86c6-b401fee34a9d \
+  -X PUT \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \
+  -d '{"collection_name": "SEC Filings (New)"}'
+```
+
+Uploading documents:
+
+```bash
+# Step 1: Upload file
+curl https://api.x.ai/v1/files \
+  -H "Authorization: Bearer $XAI_API_KEY" \
+  -F file=@tesla-20241231.html
+
+# Step 2: Add file to collection (use file_id from step 1)
+curl -X POST https://management-api.x.ai/v1/collections/$COLLECTION_ID/documents/$FILE_ID \
+  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
+
+```
+
+Uploading with metadata fields
+
+```bash
+curl https://management-api.x.ai/v1/collections/collection_dbc087b1-6c99-493d-86c6-b401fee34a9d/documents \
+  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY" \
+  -F "name=paper.pdf" \
+  -F "data=@paper.pdf" \
+  -F "content_type=application/pdf" \
+  -F 'fields={"author": "Sandra Kim", "year": "2024", "title": "Q3 Revenue Analysis"}'
+
+```
+
+Searching documents
+
+```bash
+curl https://api.x.ai/v1/documents/search \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $XAI_API_KEY" \
+  -d '{
+    "query": "What were the key revenue drivers based on the SEC filings?",
+    "source": {
+      "collection_ids": ["collection_dbc087b1-6c99-493d-86c6-b401fee34a9d"]
+    }
+  }'
+```
+
+```bash
+curl https://api.x.ai/v1/documents/search \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer $XAI_API_KEY" \
+  -d '{
+      "query": "What were the key revenue drivers based on the SEC filings?",
+      "source": {
+          "collection_ids": [
+              "collection_dbc087b1-6c99-493d-86c6-b401fee34a9d"
+          ]
+      },
+      "retrieval_mode": {"type": "hybrid"}
+}'
+```
+
+
+Deleting a document:
+
+```bash
+curl https://management-api.x.ai/v1/collections/collection_dbc087b1-6c99-493d-86c6-b401fee34a9d/documents/file_55a709d4-8edc-4f83-84d9-9f04fe49f832 \
+  -X DELETE \
+  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
+
+```
+
+Deleting a collection
+
+```bash
+curl https://management-api.x.ai/v1/collections/collection_dbc087b1-6c99-493d-86c6-b401fee34a9d \
+  -X DELETE \
+  -H "Authorization: Bearer $XAI_MANAGEMENT_API_KEY"
+```

package/lib/genericToolset.js

@@ -44,8 +44,82 @@ const getJSError = (errorStr) => {
 	}
 	return result;
 };
+// /**
+// * Try to prevent double escaping by LLMS models
+// * When a string stays a string it is probably double escaped
+// * @parameter {string} s
+// * @returns {string}
+// */
+// const guessOverEscaping = (s) => {
+// 	let test;
+// 	if (typeof s === 'string') {
+// 		try {
+// 			test = JSON.parse(s);
+// 		} catch (_e) { }
+// 		if (typeof test === 'string') {
+// 			return test;
+// 		}
+// 	}
+// 	return s;
+// }
 
 /**
+ * Try to prevent double escaping by LLMs.
+ * Handles common patterns like \"path\", \\\"path\\\", JSON strings,
+ * and multiple layers while being much safer on complex bash/JS scripts.
+ */
+const guessOverEscaping = (s) => {
+	if (typeof s !== 'string') return s;
+
+	let current = s.trim();
+	const seen = new Set();
+	let iterations = 0;
+	const MAX_ITER = 6; // safety limit
+
+	while (iterations < MAX_ITER && !seen.has(current)) {
+		seen.add(current);
+		iterations++;
+
+		// 1. Most reliable: JSON.parse (undoes proper JSON string escaping)
+		try {
+			const parsed = JSON.parse(current);
+			if (typeof parsed === 'string') {
+				current = parsed;
+				continue;
+			}
+		} catch (e) { }
+
+		// 2. Specifically strip the pattern you saw: \"...\"  (including the backslashes)
+		if (current.startsWith('\\"') && current.endsWith('\\"')) {
+			current = current.slice(2, -2);
+			continue;
+		}
+
+		// 3. Strip normal outer quotes, but protect JSON objects/arrays
+		if (current.startsWith('"') && current.endsWith('"') && current.length > 2) {
+			const inner = current.slice(1, -1);
+			const trimmedInner = inner.trim();
+			if (!trimmedInner.startsWith('{') && !trimmedInner.startsWith('[')) {
+				current = inner;
+				continue;
+			}
+		}
+
+		// 4. Conservative global unescape of \" → "
+		//    Only applied to short strings without newlines (i.e. not full scripts)
+		if (!current.includes('\n') && (current.match(/\\"/g) || []).length >= 1) {
+			const lessEscaped = current.replace(/\\"/g, '"');
+			if (lessEscaped !== current) {
+				current = lessEscaped;
+				continue;
+			}
+		}
+
+		break; // no more productive changes
+	}
+
+	return current;
+};/**
  * @module lib/genericToolset
  * Secure utility tools for code execution, file I/O, system ops. Pre-populated ToolSet.
  * 
@@ -71,9 +145,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,23 +167,34 @@ tools.add(
 
 tools.add(
 	'execute_bash_script',
-	'Execute raw bash script or command (no escaping needed).',
+	'Execute raw bash script or command (no escaping needed). Supports timeout to prevent hangs.',
 	{
 		type: 'object',
 		properties: {
 			bash_script: {
 				type: 'string',
-				description: `Raw bash verbatim. Supports all syntax safely via heredoc. System: ${user.system}`
+				description: `Raw bash verbatim. 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.'
 			}
 		},
 		required: ['bash_script']
 	},
 	async (params) => {
+		const timeoutSec = Number(params.timeout ?? 300);
+		const bash_script = guessOverEscaping(params.bash_script);
+		if (isNaN(timeoutSec) || timeoutSec < 0) throw new Error('Invalid timeout');
+		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}
+${bash_script}
 ${delim}
-`.run();
+`.options({ timeout }).run();
+
 	}
 );
 
@@ -125,12 +211,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();
 	}
@@ -146,22 +235,36 @@ 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.',
+	'Run bash on remote via SSH. Supports timeout to prevent hangs.',
 	{
 		type: 'object',
 		properties: {
 			url: { type: 'string', description: 'ssh://user@host[:port]' },
-			script: { type: 'string', description: 'Raw script' }
+			script: { type: 'string', description: 'Raw script' },
+			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.'
+			}
 		},
 		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;
 		if (!url.startsWith('ssh://')) throw new Error('ssh://user@host[:port]');
 		const withoutProto = url.slice(6);
 		const parts = withoutProto.split(':');
@@ -169,12 +272,7 @@ tools.add(
 		if (parts.length > 1) { userHost = parts[0]; port = parseInt(parts[1]); }
 		const [user, host] = userHost.split('@');
 		if (!user || !host) throw new Error('Invalid SSH URL');
-
-		const delim = `END_SCRIPT_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
-		return await SH`ssh -p ${port} ${user}@${host} bash <<'${delim}'
-${script}
-${delim}
-`.run();
+		return await SH`ssh -p ${port} ${user}@${host} bash`.options({ timeout: timeoutMs }).run(script);
 	}
 );
 
@@ -190,7 +288,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();
 	}
@@ -207,7 +306,7 @@ tools.add(
 		required: ['file']
 	},
 	async (params) => {
-		const file = params.file?.trim();
+		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 /, .., \\\\).');
 		}
@@ -229,8 +328,8 @@ tools.add(
 		required: ['file', 'content']
 	},
 	async (params) => {
-		const file = params.file?.trim();
-		const content = params.content ?? '';
+		let file = guessOverEscaping(params.file?.trim());
+		let content = guessOverEscaping(params.content ?? '');
 		if (typeof file !== 'string' || !file || file.startsWith('/') || file.includes('..') || file.includes('\\\\')) {
 			throw new Error('Relative CWD path only.');
 		}
@@ -240,29 +339,29 @@ tools.add(
 		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'}`);
+		const temp1 = path.join(dir, `temp_${Date.now()}_${Math.random().toString(36).slice(2, 6)}${ext || '.tmp'}`);
 		await fs.writeFile(temp1, content, 'utf8');
 
 		try {
 			await SH`${syntaxCheckSh} ${[temp1]}`.run();
 			validationMsg = ' ✓ Syntax OK';
 		} catch (e) {
-			if (!['.js','.mjs'].includes(ext)) {
-				await fs.unlink(temp1).catch(()=>{}); 
+			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`);
+			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(()=>{}); 
+				await fs.unlink(temp1).catch(() => { });
 				validationMsg = ' ✓ Fixed JS';
 			} catch {
-				await fs.unlink(temp1).catch(()=>{}); 
-				await fs.unlink(temp2).catch(()=>{}); 
+				await fs.unlink(temp1).catch(() => { });
+				await fs.unlink(temp2).catch(() => { });
 				throw new Error(`Syntax error (fix failed): ${e.message}`);
 			}
 		}
@@ -289,7 +388,7 @@ 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.');
@@ -297,4 +396,4 @@ tools.add(
 	}
 );
 
-export default tools;
+export default tools;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@j-o-r/hello-dave",
   "type": "module",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "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",