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

package/lib/AgentManager.js

@@ -2,14 +2,15 @@ import { Prompt, Cli, AgentClient, AgentServer, API, ToolSet, Session, env } fro
 import toolsPool from './genericToolset.js'
 /**
 * @typedef {import('./API/x.ai/text.js').XOptions} XOptions
+* @typedef {import('./API/x.ai/responses.js').XAIOptions} XAIOptions
 * @typedef {import('./API/openai.com/reponses/text.js').OAOptions} OAOptions
 * @typedef {import('./API/anthropic.com/text.js').ANTHOptions} ANTHOptions
 */
 /**
 * @typedef {Object} Setup
 * @property {string} prompt - Initial system prompt
-* @property {OAOptions|XOptions|ANTHOptions} options - Model options
-* @property {'gpt'|'grok'|'claude'} api - AI endpoint to use
+* @property {XAIOptions|OAOptions|XOptions|ANTHOptions} options - Model options
+* @property {'gpt'|'xai'|'claude'} api - AI endpoint to use
 * @property {number} [contextWindow] - The size in tokens for the context/session
 * @property {'auto'|'required'|void} [toolsetMode] - 
 * @property {boolean} [debug] - verbose output
@@ -17,6 +18,7 @@ import toolsPool from './genericToolset.js'
 /**
 * @typedef {Object} Options
 * @property {string} name - Agent name
+* @property {string} secret - Secret string for WS access authorisation (server and client secrets should match)
 * @property {string} [cachePath] - path to session/record storage 
 */
 class AgentManager {
@@ -25,13 +27,24 @@ class AgentManager {
   /** @type {Session} */
   #sessionStorage;
   #name = 'agent';
+  #secret = '';
   #cachePath = '.cache/hello-dave';
   #debug = false;
+  #model = '';
+  #contextWindow = 0;
+  #sysPrompt = '';
   /**
   * @param {Options} options
   */
   constructor(options) {
     this.#name = options.name || this.#name;
+    if (options.secret && typeof options.secret === 'string') {
+      this.#secret = Buffer.from(options.secret).toString('base64');
+    } 
+    const validNameRegex = /^[a-z_0-9]{2,}$/;
+    if (!validNameRegex.test(this.#name)) {
+      throw new Error(`Invalid agent 'name' in options: '${this.#name}'. Must match /^[a-z_0-9]{2,}$/ (lowercase a-z, digits, underscores; min 2 chars).`);
+    }
     this.#cachePath = options.cachePath || this.#cachePath;
   }
 
@@ -47,6 +60,12 @@ class AgentManager {
     	toolsetMode = null,
     	debug = false
     } = setup;
+    this.#sysPrompt = prompt;
+    this.#contextWindow = contextWindow;
+    if (options?.model) this.#model = options.model;
+    this.#sysPrompt = prompt;
+    this.#contextWindow = contextWindow;
+    if (options?.model) this.#model = options.model;
     let toolset;
     if (toolsetMode) {
     	toolset = new ToolSet(toolsetMode);
@@ -65,7 +84,7 @@ class AgentManager {
   * Start a CLI for local usage
   * @param {string} description - introduction message for the CLI user
   */
-  startCli(description) {
+  #startCli(description) {
     if (!this.#prompt) throw new Error('Run setup first');
     const cli = new Cli({ prompt: this.#prompt, session: this.#sessionStorage, description });
     setTimeout(() => {
@@ -82,9 +101,9 @@ class AgentManager {
   * @param {string} description - function_call description
   * @param {string} [url='ws://127.0.0.1:8000/ws'] - ws URL
   */
-  attach(name, description, url = 'ws://127.0.0.1:8000/ws') {
+  #attach(name, description, url = 'ws://127.0.0.1:8000/ws') {
     if (!this.#prompt) throw new Error('Run setup first');
-    return new AgentClient({ prompt: this.#prompt, name, description, url });
+    return new AgentClient({ prompt: this.#prompt, name, description, url, secret: this.#secret });
   }
 
   /**
@@ -95,12 +114,13 @@ class AgentManager {
   * @param {string} description - function_call description
   * @param {number} [port=8000] - Start the dynamic toolset server on this port
   */
-  enableServer(name, description = '', port = 8000) {
+  #enableServer(name, description = '', port = 8000) {
     if (!this.#prompt) throw new Error('Run setup first');
     if (!this.#prompt.toolset) throw new Error('No toolset defined');
     const server = new AgentServer({
     	port,
     	name,
+    	secret: this.#secret,
     	description,
     	prompt: this.#prompt,
     	session: this.#sessionStorage,
@@ -131,13 +151,62 @@ class AgentManager {
   	return env();
   }
   /**
-  * @param {string} name - the toolname
-  */
+   * Add (copy) a pre-defined toolcall to the function_calls
+   * @param {'read_file'|'write_file'|'get_user_env'|'execute_bash_script'|'send_email'|'open_link'|'execute_remote_script'|'history_search'|'javascript_interpreter'} name - name /^[a-z_0-9]{2,}$/ e.g. 'execute_bash_script'
+   */
   addGenericToolcall(name) {
+    const validNameRegex = /^[a-z_0-9]{2,}$/;
+    if (!validNameRegex.test(name)) {
+      throw new Error(`Invalid 'name': '${name}'. Must match /^[a-z_0-9]{2,}$/ (lowercase a-z, digits, underscores; min 2 chars).`);
+    }
     if (!this.#prompt.toolset) throw new Error('No ToolSet defined')
-    let tool  = toolsPool.get(name);
+    let tool = toolsPool.get(name);
     if (!tool) throw new Error('Tool not defined')
-  	this.#prompt.toolset.add(name, tool.description, tool.parameters, tool.method);
+    this.#prompt.toolset.add(name, tool.description, tool.parameters, tool.method);
+  }
+  
+  /**
+   * Smart launcher: Dispatches to CLI/server/attach/direct. Auto-gens cliIntro/desc if empty.
+   * @param {number} [servePort] - Server port (if no input).
+   * @param {string} [connectUrl] - WS to attach. e.g. ws://127.0.0.1:8091/ws
+   * @param {string} [cliIntro=""] - CLI intro (auto-gen if falsy).
+   * @param {string} [toolName=""] - name /^[a-z_0-9]{2,}$/ Tool name for server/attach (defaults to agent.name).
+   * @param {string} [toolDescription=""] - Tool desc (auto-gen if falsy).
+   */
+  async start(servePort, connectUrl, cliIntro = "", toolName = "", toolDescription = "") {
+    if (!this.#prompt) throw new Error("Run setup first");
+
+    const validNameRegex = /^[a-z_0-9]{2,}$/;
+
+    toolName = toolName || this.#name;
+    // Validate 'toolName' (or fallback agent name)
+    if (!validNameRegex.test(toolName)) {
+      throw new Error(`Invalid 'toolName' (or agent #name): '${toolName}'. Must match /^[a-z_0-9]{2,}$/ (lowercase a-z, digits, underscores; min 2 chars).`);
+    }
+
+    if (!toolDescription && this.#sysPrompt) {
+      toolDescription = this.#sysPrompt.slice(0, 100).trim() + "...";
+    }
+
+    if (!cliIntro) {
+      const introStr = this.#name + " " + (this.#model || "unknown-model") + " - context: " + this.#contextWindow;
+      cliIntro = introStr.trim();
+    }
+    if (servePort) {
+      console.log(toolName);
+      console.log(toolDescription);
+      this.#enableServer(toolName, toolDescription, servePort);
+      // A server can also be a client
+      if (connectUrl) {
+        this.#attach(toolName, toolDescription, connectUrl);
+      }
+    } else if (connectUrl) {
+      // Connect to a agent 'server' and enable via websocket / toolcalls
+      this.#attach(toolName, toolDescription, connectUrl);
+    } else {
+      // Terminal user CLI
+      this.#startCli(cliIntro);
+    }
   }
 }
 

package/lib/AgentServer.js

@@ -19,11 +19,12 @@ let ws;
 * @property {messageContent} content
 */
 /**
-* @typedef {(conn: import('@j-o-r/apiserver/types/WebSocketServer.js').WebSocketConnection) => Promise<boolean>} AuthFunction
+* @typedef {(conn: import('@j-o-r/apiserver/types/WebSocketServer.js').WebSocketConnection, req: any) => Promise<boolean>} AuthFunction
 */
 /**
 * @typedef {Object} AgentServerOptions
 * @property {string} name
+* @property {string} secret - server access secret
 * @property {string} description
 * @property {Prompt} prompt
 * @property {Session} session
@@ -32,7 +33,7 @@ let ws;
 * @property {boolean} [debug = false] 
 */
 
- const ACTIONS = [
+const ACTIONS = [
 	// Agent / Toolset function calls
 	'agent_introduction', // Describe your task, your purpose and usage. This is a reaction on a 'introduce' requests
 	'agent_error',        // Message error
@@ -42,6 +43,7 @@ let ws;
 	'user_introduction',  // Websocket client connection on open
 	'user_request',       // A client user request
 	'server_response',    // A reponse to a user request
+	'server_error',    // A reponse to a user request
 	'user_reset',         // User requests a new session
 	'user_sessionlist',   // Request a list of sessions
 	'user_loadsession',   // Request to load a session
@@ -129,6 +131,7 @@ class AgentServer {
 	#debug = false;
 	#port = 8000;
 	#name = '';
+  #secret = ''; // access secret
 	#description = '';
 	/** @type {Prompt} */
 	#prompt
@@ -136,7 +139,9 @@ class AgentServer {
 	#session
 	/** @type {AuthFunction} */
 	#auth = async (conn) => {
-		return true;
+		const q = conn.client.query;
+		const key = q.get('wssrc_id');
+		return key === this.#secret;
 	}
 	/**
 	* @param {AgentServerOptions} options
@@ -152,16 +157,25 @@ class AgentServer {
 			this.#auth = options.auth;
 		}
 		this.#name = options.name;
+		this.#secret = options.secret;
 		this.#description = options.description;
 		this.#session = options.session;
 		this.#prompt = options.prompt;
-		const events = Object.keys(this.#prompt.EVENTS);
-		events.forEach((evt) => {
-			this.#prompt.on(evt, (_msg) => {
-				console.log(evt);
-			});
-		});
 		this.#debug = options.debug;
+		// LOG EVENTS
+		 const events = Object.keys(this.#prompt.EVENTS);
+		 events.forEach((evt) => {
+		 	this.#prompt.on(evt, (_msg) => {
+		 		// log events
+		 		console.log(`** ${this.#name} e:${evt}**`);
+		 		if (evt === 'tool_request') {
+		 			console.log(`tool execute: ${this.#name} ${_msg.name} ${_msg.call_id}`);
+		 		} else if (evt === 'tool_error') {
+		 			console.log(`tool error:`);
+		 			console.log(JSON.stringify(_msg, null, '  '));
+		 		}
+		 	});
+		 });
 		// start 
 		(async () => {
 			await this._start();
@@ -213,8 +227,8 @@ class AgentServer {
 					const key = `${conn.id}:${msg.id}`; // Assume client includes original 'id' in response
 					const pending = pendingResponses.get(key);
 					if (pending) {
-            try { clearInterval(pending.timer); } catch {}
-            pending.resolve(msg.content);
+						try { clearInterval(pending.timer); } catch { }
+						pending.resolve(msg.content);
 						pendingResponses.delete(key);
 					}
 					return;
@@ -223,8 +237,8 @@ class AgentServer {
 					const key = `${conn.id}:${msg.id}`; // Assume client includes original 'id' in response
 					const pending = pendingResponses.get(key);
 					if (pending) {
-            try { clearInterval(pending.timer); } catch {}
-            pending.reject(msg.content);
+						try { clearInterval(pending.timer); } catch { }
+						pending.reject(msg.content);
 						pendingResponses.delete(key);
 					}
 					return;
@@ -245,13 +259,23 @@ class AgentServer {
 					}
 					// Bind to THIS prompt
 					console.log(`user_request:>>\n${msg.content}\n`);
-					const content = await this.#prompt.call(msg.content);
-					ws.sendToConnection(conn.id, JSON.stringify({
-						action: 'server_response',
-						id,
-						content
-					}));
-					console.log(`server_reponse:>>\n${content}\n`);
+					try {
+						const content = await this.#prompt.call(msg.content);
+						ws.sendToConnection(conn.id, JSON.stringify({
+							action: 'server_response',
+							id,
+							content
+						}));
+						console.log(`server_reponse:>>\n${content}\n`);
+					} catch (e) {
+						console.log(`server_error:>>\n`);
+						console.error(e);
+						ws.sendToConnection(conn.id, JSON.stringify({
+							action: 'server_error',
+							id,
+							e
+						}));
+					}
 				}
 				if (msg.action === 'user_reset') {
 					const id = msg.id;
@@ -322,7 +346,7 @@ class AgentServer {
 			}
 		});
 		await server.create('v1', { port, host: '127.0.0.1', ws, strict: DEBUG, verbose: DEBUG }, API);
-		console.log(`ws running on port: ${port}`);
+		console.log(`Websocket server: ws://127.0.0.1:${port}/ws`);
 	}
 	/**
 	* Send a reset messages to all clients

package/lib/Cli.js

@@ -138,24 +138,30 @@ class Cli {
 		]);
 		// Write messages
 		this.#prompt.on('message', (msg) => {
+			let write = false;
 			if (msg.role === 'reasoning') {
 				const content = this.#prompt.contentToString(msg.content);
 				cli.focus('util');
 				cli.write(`REASONING: ---------\n${content}\n---------\n`);
+				write = true;
 			} else if (msg.role === 'log') {
 				const content = this.#prompt.contentToString(msg.content);
 				cli.focus('log');
 				cli.write(content);
+				write = true;
 			} else if (msg.role === 'assistant') {
 				if (msg.content[0].type === 'text') {
 					const content = this.#prompt.contentToString(msg.content);
 					if (content.trim() !== '') {
 						cli.focus('assistant');
 						cli.write(content);
+						write = true;
 					}
 				}
 			}
-			cli.startSpinner();
+			if (write) {
+			  cli.startSpinner();
+			}
 		});
 		this.#prompt.on('truncated', () => {
 			cli.focus('log');

package/lib/Prompt.js

@@ -11,15 +11,17 @@ import { pruneResolvedToolIOByCallIdExceptLast as pruneResolvedToolIOByCallIdExc
 /**
 * @typedef {import('./API/openai.com/reponses/text.js').request} OARequest
 * @typedef {import('./API/x.ai/text.js').request} XRequest
+* @typedef {import('./API/x.ai/responses.js').request} XAIRequest
 * @typedef {import('./API/anthropic.com/text.js').request} ANTHRequest
 * 
 * @typedef {import('./API/x.ai/text.js').XOptions} XOptions
+* @typedef {import('./API/x.ai/responses.js').XAIOptions} XAIOptions
 * @typedef {import('./API/openai.com/reponses/text.js').OAOptions} OAOptions
 * @typedef {import('./API/anthropic.com/text.js').ANTHOptions} ANTHOptions
 *
 * @typedef {import('./ToolSet.js').default} ToolSet
-* @typedef {OARequest|XRequest|ANTHRequest} request - The AI model to use for chat functionality.
-* @typedef {OAOptions|XOptions|ANTHOptions} options - Model options
+* @typedef {OARequest|XRequest|ANTHRequest|XAIRequest} request - The AI model to use for chat functionality.
+* @typedef {OAOptions|XOptions|ANTHOptions|XAIOptions} options - Model options
 */
 
 /** 

package/lib/ToolSet.js

@@ -126,6 +126,7 @@ class ToolSet {
 	* Execute a method
 	* @param {string} name
 	* @param {object} params
+	* @returns {Promise<*>}
 	*/
 	async call(name, params) {
 		if (!this.has(name)) {
@@ -158,8 +159,8 @@ class ToolSet {
 			try {
 				response = await this.call(call.function_request.name, JSON.parse(call.function_request.parameters));
 			} catch (error) {
-				prompt.emit(prompt.EVENTS.tool_error, { name: call.function_request.name, call_id: call.function_request.call_id, error });
 				response = `Error: ${error.name} - ${error.message}`;
+				prompt.emit(prompt.EVENTS.tool_error, { name: call.function_request.name, call_id: call.function_request.call_id, error: response });
 			}
 			const duration = new Date().getTime() - startTime;
 			prompt.emit(prompt.EVENTS.tool_response, { name: call.function_request.name, call_id: call.function_request.call_id, duration });

package/lib/genericToolset.js

@@ -1,5 +1,11 @@
-import { SH } from '@j-o-r/sh'
+import { SH, bashEscape } from '@j-o-r/sh'
 import { ToolSet, env } from './index.js'
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 
 const user = await env();
 const environment = ` 
@@ -33,27 +39,6 @@ const getJSError = (errorStr) => {
 	return result;
 }
 
-/**
-* bash escape a string suitable as an argument on the commandline
-* for javascript code
-* @param {string} x
-* @retruns {string}
-*/
-const bashEscape = (x) => {
-	let str = String(x).trim();
-	// the trick is to double escape escape vars first
-	str = str.replace(/\\/g, '\\\\');
-	// then add escaping for oddities
-	// Replace literal escape sequences like \n, \t, \r in quoted strings
-	str = str.replace(/(['"])\\(.)\1/g, '$1\\\\$2$1');
-	// escape $ (is a BASH var)
-	str = str.replace(/\$/g, '\\$');
-	// Escape backticks
-	str = str.replace(/`/g, '\\`');
-	// Escape quotes
-	str = str.replace(/"/g, '\\"');
-	return str;
-}
 tools.add(
 	'javascript_interpreter',
 	`Execute ESM ES6 javascript on \`node\`.`,
@@ -67,37 +52,21 @@ tools.add(
 		},
 		required: ['script']
 	},
-	// @ts-ignore
 	async (params) => {
-		// @ts-ignore
-		const script = bashEscape(params.script);
 		let response = '';
 		try {
-			// Execute script
-			response = await SH`node -e "${script}"`.run();
+			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}
+${delim}
+`.run();
 		} catch (e) {
-			const errorStr = e.toString()
-			response = getJSError(errorStr)
+			const errorStr = e.toString();
+			response = getJSError(errorStr);
 		}
 		return response;
 	}
 );
-tools.add(
-	'bash_cmd',
-	`Execute a Bash command on ${user.system}.`,
-	{
-		type: 'object',
-		properties: {
-			command: {
-				type: 'string',
-				description: 'The bash command.',
-			}
-		},
-		required: ['command']
-	},
-	// @ts-ignore
-	async (params) => (await SH`${params.command}`.run())
-);
 tools.add(
 	'get_user_env', // name
 	'Get the user location, name and OS environment', // desciption
@@ -113,11 +82,11 @@ tools.add(
 
 tools.add(
 	'execute_bash_script',
-	'Execute a bash script.',
+	'Execute a bash script or command. (char escaping not needed)',
 	{
 		type: 'object',
 		properties: {
-			bash_script: { type: 'string', description: `The bash script to execute (${user.system})` }
+			bash_script: { type: 'string', description: `RAW bash script (LITERAL TEXT: NO ESCAPING—output $, |, <, >, &, ", ', \\, \` , newlines, $(()), [[ ]] verbatim. Heredoc delimiter handles safely. EX: echo "$((1+1)) | grep \'<&>\"hi$USER\"\' && ls -la\`. (${user.system})` }
 		},
 		required: ['bash_script']
 	},
@@ -129,27 +98,6 @@ ${delim}
 `.run()
 	}
 );
-/*
-### nu shell Assumptions and Prerequisites
-- You can install it via your package manager (e.g., on Ubuntu: `sudo apt install nushell` or download from the [official Nushell releases](https://github.com/nushell/nushell/releases)).
-- The tool will use a heredoc approach (similar to the Bash tool) to pass the script content to `nu` for execution. This ensures multi-line scripts work reliably.
-- The output from `nu` will be returned as-is, preserving its structured format (e.g., tables or JSON), which is beneficial for LLM consumption.o
-*/
-tools.add(
-	'execute_nushell_script',
-	'Execute a Nushell script.',
-	{
-		type: 'object',
-		properties: {
-			nushell_script: { type: 'string', description: `The Nushell script to execute (${user.system})` }
-		},
-		required: ['nushell_script']
-	},
-	async (params) => {
-		const script = bashEscape(params.nushell_script);
-		return await SH`nu -c "${script}"`.run()
-	}
-);
 
 tools.add(
 	'send_email',
@@ -176,11 +124,11 @@ ${delim}
 );
 tools.add(
 	'open_link',
-	'Open an url in local user environment.',
+	'Open an url or file in the local user environment. (xdg-open)',
 	{
 		type: 'object',
 		properties: {
-			url: { type: 'string', description: 'Link to open' }
+			url: { type: 'string', description: 'file | URL' }
 		},
 		required: ['url']
 	},
@@ -190,18 +138,17 @@ tools.add(
 );
 tools.add(
 	'execute_remote_script',
-	'Execute a script (bash, nu, python, javascript) on a remote machine via SSH. Default type: nu.',
+	'Execute bash script on a remote machine via SSH.',
 	{
 		type: 'object',
 		properties: {
-			type: { type: 'string', enum: ['bash','nu','python','javascript'], description: 'Type of script (default: bash)' },
 			url: { type: 'string', description: 'SSH URL, e.g., ssh://user@host or ssh://user@host:port' },
-			script: { type: 'string', description: 'The script code to execute remotely' }
+			script: { type: 'string', description: 'RAW script code to execute remotely (no escaping needed)' }
 		},
 		required: ['url', 'script']
 	},
 	async (params) => {
-		const { url, type = 'bash', script } = params;
+		const { url, script } = params;
 		if (!url.startsWith('ssh://')) throw new Error('Invalid SSH URL');
 		const withoutProto = url.slice(6);
 		const parts = withoutProto.split(':');
@@ -212,23 +159,113 @@ tools.add(
 			port = parseInt(parts[1]);
 		}
 		const [user, host] = userHost.split('@');
-		if (!user || !host) throw new Error('Invalid SSH URL format');
-		let command;
-		if (type === 'nu') {
-			const escaped = bashEscape(script);
-			command = `nu -c "${escaped}"`;
-		} else {
-			const interpreters = { bash: 'bash', python: 'python3', javascript: 'node' };
-			const interpreter = interpreters[type];
-			if (!interpreter) throw new Error('Unsupported type');
-			const delim = `END_REMOTE_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
-			command = `${interpreter} <<'${delim}'
+		if (!user || !host) throw new Error('Invalid SSH URL format: use ssh://user@host[:port]');
+
+		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();
+
+	}
+);
+tools.add(
+  'history_search',
+  `Search previous LLM chat sessions or list them hierarchically.
+Example query: "(todo|task)" or "package.json".
+Searches filenames & content in .cache/[app]/[prompt]/sessions/*.ndjson (case-insensitive regex, with context).
+Omit query (or use empty string) to list sessions (see utils/list_sessions.sh).`,
+  {
+    type: 'object',
+    properties: {
+      query: {
+        type: 'string',
+        description: `Search query or regex (quoted for multi-word/regex). Omit or empty for list mode.`
+      }
+    },
+    required: []
+  },
+  async (params) => {
+    const history_search = path.resolve(__dirname, '..', 'utils', 'search_sessions.sh');
+    const list_sessions = path.resolve(__dirname, '..', 'utils', 'list_sessions.sh');
+    if (typeof params.query === 'string' && params.query.trim() !== '') {
+      const escapedQuery = bashEscape(params.query);
+      return await SH`${history_search} "${escapedQuery}"`.run();
+    } else {
+      return await SH`${list_sessions}`.run();
+    }
+  }
+);
+tools.add(
+	'read_file',
+	'Read the raw content of a file strictly within the current working directory (CWD). Paths must be relative (no leading /, no ..).',
+	{
+		type: 'object',
+		properties: {
+			file: {
+				type: 'string',
+				description: `Relative path to the file within CWD, e.g., 'path/to/file.txt' (no escaping needed). cwd: ${user.cwd}`
+			}
+		},
+		required: ['file']
+	},
+	async (params) => {
+		const file = params.file?.trim();
+		if (typeof file !== 'string' || !file) {
+			throw new Error('Valid relative file path required.');
+		}
+		if (file.startsWith('/') || file.includes('..') || file.includes('\\\\')) {
+			throw new Error('Path must be relative within CWD only (no `/`, `..`, or `\\\\`).');
+		}
+		const resolvedPath = path.resolve(process.cwd(), file);
+		if (!resolvedPath.startsWith(process.cwd())) {
+			throw new Error(`Path '${file}' escapes CWD scope.`);
+		}
+		try {
+			const content = await fs.readFile(resolvedPath, 'utf8');
+			return content;
+		} catch (e) {
+			throw new Error(`Failed to read '${file}': ${e.message}`);
 		}
-		return await SH`ssh -p ${port} ${user}@${host} '${command}'`.run()
 	}
 );
 
+tools.add(
+	'write_file',
+	'Write raw content to a file strictly within the current working directory (CWD). Paths must be relative (no leading /, no ..). Content written as-is (no escaping).',
+	{
+		type: 'object',
+		properties: {
+			file: {
+				type: 'string',
+				description: `Relative path to the file within CWD, e.g., 'path/to/file.txt' (no escaping needed).`
+			},
+			content: {
+				type: 'string',
+				description: `Raw content to write (as-is, no char escaping needed; supports newlines, $, |, <, >, &, ", ', \\, etc.).`
+			}
+		},
+		required: ['file', 'content']
+	},
+	async (params) => {
+		const file = params.file?.trim();
+		const content = params.content ?? '';
+		if (typeof file !== 'string' || !file) {
+			throw new Error('Valid relative file path required.');
+		}
+		if (file.startsWith('/') || file.includes('..') || file.includes('\\\\')) {
+			throw new Error('Path must be relative within CWD only (no `/`, `..`, or `\\\\`).');
+		}
+		const resolvedPath = path.resolve(process.cwd(), file);
+		if (!resolvedPath.startsWith(process.cwd())) {
+			throw new Error(`Path '${file}' escapes CWD scope.`);
+		}
+		try {
+			await fs.writeFile(resolvedPath, content, 'utf8');
+			return `Successfully wrote to '${file}' (${Buffer.byteLength(content, 'utf8')} bytes).`;
+		} catch (e) {
+			throw new Error(`Failed to write '${file}': ${e.message}`);
+		}
+	}
+);
 export default tools