Tools can now emit "done" event and end chat early gracefully

package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ztimson/ai-utils",
-	"version": "1.2.8",
+	"version": "1.2.12",
 	"description": "AI Utility library",
 	"author": "Zak Timson",
 	"license": "MIT",

src/antrhopic.ts

@@ -21,10 +21,10 @@ export class Anthropic extends LLMProvider {
 				messages.push(<any>{timestamp, ...h});
 			} else {
 				const textContent = h.content?.filter((c: any) => c.type == 'text').map((c: any) => c.text).join('\n\n');
-				if(textContent) messages.push({timestamp, role: h.role, content: textContent});
+				if(textContent) messages.push({role: h.role, content: textContent, timestamp: timestamp});
 				h.content.forEach((c: any) => {
 					if(c.type == 'tool_use') {
-						messages.push({timestamp, role: 'tool', id: c.id, name: c.name, args: c.input, content: undefined});
+						messages.push({role: 'tool', id: c.id, name: c.name, args: c.input, timestamp: c.timestamp, content: undefined});
 					} else if(c.type == 'tool_result') {
 						const m: any = messages.findLast(m => (<any>m).id == c.tool_use_id);
 						if(m) m[c.is_error ? 'error' : 'content'] = c.content;
@@ -46,7 +46,7 @@ export class Anthropic extends LLMProvider {
 				i++;
 			}
 		}
-		return history.map(({timestamp, ...h}) => h);
+		return history;
 	}
 
 	ask(message: string, options: LLMRequest = {}): AbortablePromise<string | any> {
@@ -83,8 +83,9 @@ export class Anthropic extends LLMProvider {
 				};
 			}
 
-			let resp: any, isFirstMessage = true;
+			let resp: any, isFirstMessage = true, terminal = false;
 			do {
+				requestParams.messages = history.map(({timestamp, ...m}) => m);
 				resp = await this.client.messages.create(requestParams).catch(err => {
 					err.message += `\n\nMessages:\n${JSON.stringify(history, null, 2)}`;
 					throw err;
@@ -113,7 +114,7 @@ export class Anthropic extends LLMProvider {
 							}
 						} else if(chunk.type === 'content_block_stop') {
 							const last = resp.content.at(-1);
-							if(last.input != null) last.input = last.input ? JSONAttemptParse(last.input, {}) : {};
+							if(last?.input != null) last.input = last.input ? JSONAttemptParse(last.input, {}) : {};
 						} else if(chunk.type === 'message_stop') {
 							break;
 						}
@@ -123,31 +124,35 @@ export class Anthropic extends LLMProvider {
 				// Run tools
 				const toolCalls = resp.content.filter((c: any) => c.type === 'tool_use');
 				if(toolCalls.length && !controller.signal.aborted) {
-					history.push({role: 'assistant', content: resp.content});
+					history.push({role: 'assistant', content: resp.content, timestamp: Date.now()});
 					const results = await Promise.all(toolCalls.map(async (toolCall: any) => {
 						const tool = tools.find(findByProp('name', toolCall.name));
 						if(options.stream) options.stream({tool: toolCall.name});
 						if(!tool) return {tool_use_id: toolCall.id, is_error: true, content: 'Tool not found'};
 						try {
-							const result = await tool.fn(toolCall.input, options?.stream, this.ai);
+							// Wrap stream so a tool's `done` ends turn gracefully
+							const toolStream = options.stream && ((chunk: any) => {
+								if(chunk.done) { terminal = true; return; }
+								options.stream!(chunk);
+							});
+							const result = await tool.fn(toolCall.input, toolStream, this.ai);
 							return {type: 'tool_result', tool_use_id: toolCall.id, content: typeof result == 'object' ? JSONSanitize(result) : result};
 						} catch (err: any) {
 							return {type: 'tool_result', tool_use_id: toolCall.id, is_error: true, content: err?.message || err?.toString() || 'Unknown'};
 						}
 					}));
-					history.push({role: 'user', content: results});
+					history.push({role: 'user', content: results, timestamp: Date.now()});
 					requestParams.messages = history;
 				}
-			} while (!controller.signal.aborted && resp.content.some((c: any) => c.type === 'tool_use'));
+			} while (!terminal && !controller.signal.aborted && resp.content.some((c: any) => c.type === 'tool_use'));
 
-			const textContent = resp.content.filter((c: any) => c.type == 'text').map((c: any) => c.text).join('\n\n');
+			if(!terminal) {
-			history.push({role: 'assistant', content: textContent});
+				const textContent = resp.content.filter((c: any) => c.type == 'text').map((c: any) => c.text).join('\n\n');
+				history.push({role: 'assistant', content: textContent, timestamp: Date.now()});
+			}
 			history = this.toStandard(history);
-
 			if(options.stream) options.stream({done: true});
 			if(options.history) options.history.splice(0, options.history.length, ...history);
-
-			// Return parsed JSON if schema provided
 			const finalContent = history.at(-1)?.content;
 			res(options.schema ? JSONAttemptParse(finalContent, finalContent) : finalContent);
 		}), {abort: () => controller.abort()});

src/memory.ts

@@ -430,7 +430,7 @@ ${currentBody}
 		}
 
 		const {backlinks} = extractMetadata(node.content);
-		node.description = update.description;
+		node.description = node.name !== 'Person/User' ? update.description : 'All information about the current user';
 		node.content = this.applyHeader(update.content, this.buildHeader(node, week, newLinks, backlinks));
 		const [e] = await this.llm.embedding(node.content);
 		if(e) node.embedding = e.embedding;
@@ -454,7 +454,7 @@ Rules:
 
 When extracting facts, you MUST also decide the exact destination path:
 - Use an existing node name if the facts clearly belong there
-- All information primary about the user should go under "Personal/..." (e.g., Personal/Info, Personal/Todos)
+- All information primary about the user should go under "People/User"
 - When required, create a new path following collection/subject format (e.g., People/Sarah, Projects/Oxide)
 - For journal entries, use "Journal"
 
@@ -470,8 +470,7 @@ ${this.listNodes(memories).filter(n => !n.name.includes('_temp_') && !n.name.inc
 				},
 				fn: (args: any) => {
 					const subject = args.destination.trim().toLowerCase() === 'journal'
-						? `Journal/${weekKey}`
+						? `Journal/${weekKey}` : args.destination.trim();
-						: args.destination.trim();
 					const facts = buckets.get(subject) ?? [];
 					facts.push(...dedupeFacts(String(args.facts).split(',')));
 					buckets.set(subject, facts);

src/open-ai.ts

@@ -29,11 +29,11 @@ export class OpenAi extends LLMProvider {
 				}));
 				history.splice(i, 1, ...tools);
 				i += tools.length - 1;
-			} else if(h.role === 'tool' && h.content) {
+			} else if(h.role === 'tool') {
 				const record = history.find(h2 => h.tool_call_id == h2.id);
 				if(record) {
-					if(h.content.includes('"error":')) record.error = h.content;
+					if(h.content?.includes('"error":')) record.error = h.content;
-					else record.content = h.content;
+					else record.content = h.content || '';
 				}
 				history.splice(i, 1);
 				i--;
@@ -51,15 +51,16 @@ export class OpenAi extends LLMProvider {
 					content: null,
 					tool_calls: [{ id: h.id, type: 'function', function: { name: h.name, arguments: JSON.stringify(h.args) } }],
 					refusal: null,
-					annotations: []
+					annotations: [],
+					timestamp: h.timestamp,
 				}, {
 					role: 'tool',
 					tool_call_id: h.id,
-					content: h.error || h.content
+					content: h.error || h.content,
+					timestamp: h.timestamp,
 				});
 			} else {
-				const {timestamp, ...rest} = h;
+				result.push(h);
-				result.push(rest);
 			}
 			return result;
 		}, [] as any[]);
@@ -106,8 +107,9 @@ export class OpenAi extends LLMProvider {
 				};
 			}
 
-			let resp: any, isFirstMessage = true;
+			let resp: any, isFirstMessage = true, terminal = false;
 			do {
+				requestParams.messages = history.map(({timestamp, ...m}) => m);
 				resp = await this.client.chat.completions.create(requestParams).catch(err => {
 					err.message += `\n\nMessages:\n${JSON.stringify(history, null, 2)}`;
 					throw err;
@@ -116,7 +118,7 @@ export class OpenAi extends LLMProvider {
 				if(options.stream) {
 					if(!isFirstMessage) options.stream({text: '\n\n'});
 					else isFirstMessage = false;
-					resp.choices = [{message: {role: 'assistant', content: '', tool_calls: []}}];
+					resp.choices = [{message: {role: 'assistant', content: '', tool_calls: [], timestamp: Date.now()}}];
 					for await (const chunk of resp) {
 						if(controller.signal.aborted) break;
 						if(chunk.choices[0].delta.content) {
@@ -158,28 +160,32 @@ export class OpenAi extends LLMProvider {
 					const results = await Promise.all(toolCalls.map(async (toolCall: any) => {
 						const tool = tools?.find(findByProp('name', toolCall.function.name));
 						if(options.stream) options.stream({tool: toolCall.function.name});
-						if(!tool) return {role: 'tool', tool_call_id: toolCall.id, content: '{"error": "Tool not found"}'};
+						if(!tool) return {role: 'tool', tool_call_id: toolCall.id, content: '{"error": "Tool not found"}', timestamp: Date.now()};
 						try {
 							const args = JSONAttemptParse(toolCall.function.arguments, {});
-							const result = await tool.fn(args, options.stream, this.ai);
+							// Wrap stream so a tool's `done` ends turn gracefully
-							return {role: 'tool', tool_call_id: toolCall.id, content: typeof result == 'object' ? JSONSanitize(result) : result};
+							const toolStream = options.stream && ((chunk: any) => {
+								if(chunk.done) { terminal = true; return; }
+								options.stream!(chunk);
+							});
+							const result = await tool.fn(args, toolStream, this.ai);
+							return {role: 'tool', tool_call_id: toolCall.id, content: typeof result == 'object' ? JSONSanitize(result) : result, timestamp: Date.now()};
 						} catch (err: any) {
-							return {role: 'tool', tool_call_id: toolCall.id, content: JSONSanitize({error: err?.message || err?.toString() || 'Unknown'})};
+							return {role: 'tool', tool_call_id: toolCall.id, content: JSONSanitize({error: err?.message || err?.toString() || 'Unknown'}), timestamp: Date.now()};
 						}
 					}));
 					history.push(...results);
 					requestParams.messages = history;
 				}
-			} while (!controller.signal.aborted && resp.choices?.[0]?.message?.tool_calls?.length);
+			} while (!terminal && !controller.signal.aborted && resp.choices?.[0]?.message?.tool_calls?.length);
 
-			const textContent = resp.choices[0].message.content?.trim() || '';
+			if(!terminal) {
-			history.push({role: 'assistant', content: textContent});
+				const textContent = resp.choices[0].message.content?.trim() || '';
+				history.push({role: 'assistant', content: textContent, timestamp: Date.now()});
+			}
 			history = this.toStandard(history);
-
 			if(options.stream) options.stream({done: true});
 			if(options.history) options.history.splice(0, options.history.length, ...history);
-
-			// Return parsed JSON if schema provided
 			const finalContent = history.at(-1)?.content;
 			res(options.schema ? JSONAttemptParse(finalContent, finalContent) : finalContent);
 		}), {abort: () => controller.abort()});

src/tools.ts

@@ -451,6 +451,99 @@ export const GetDevice: AiTool = {
 	}
 }
 
+export const GetWikipediaTool: AiTool = {
+	name: 'get_wikipedia',
+	description: 'Search Wikipedia for matching articles',
+	args: {
+		query: {type: 'string', description: 'Search term or article title', required: true},
+		mode: {type: 'string', description: 'search - look for articles, summary - intro of first found article (default), full - complete first found article', enum: ['search', 'summary', 'full'], default: 'summary'},
+		ua: {type: 'string', description: 'User Agent'},
+	},
+	fn: async ({query, mode, ua}) => {
+		class WikipediaClient {
+			useragent = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)';
+
+			constructor(useragent: string) {
+				this.useragent = useragent;
+			}
+
+			async get(url) {
+				const resp = await fetch(url, {headers: {'User-Agent': this.useragent}});
+				return resp.json();
+			}
+
+			api(params) {
+				const qs = new URLSearchParams({...params, format: 'json', utf8: '1'}).toString();
+				return this.get(`https://en.wikipedia.org/w/api.php?${qs}`);
+			}
+
+			clean(text) {
+				const cutoffs = ['== See also ==', '== References ==', '== Bibliography ==', '== External links =='];
+				for (const marker of cutoffs) {
+					const idx = text.indexOf(marker);
+					if (idx !== -1) text = text.slice(0, idx);
+				}
+
+				return text
+					.replace(/^={4}\s*(.+?)\s*={4}$/gm, '#### $1')
+					.replace(/^={3}\s*(.+?)\s*={3}$/gm, '### $1')
+					.replace(/^={2}\s*(.+?)\s*={2}$/gm, '## $1')
+					.replace(/\n{3,}/g, '\n\n')
+					.replace(/ {2,}/g, ' ')
+					.replace(/\[\d+]/g, '')
+					.trim();
+			}
+
+			async searchTitles(query: string, limit = 6) {
+				const data = await this.api({action: 'query', list: 'search', srsearch: query, srlimit: limit, srprop: 'snippet'});
+				return data.query?.search || [];
+			}
+
+			async fetchExtract(title: string, introOnly = false) {
+				const params: any = {action: 'query', prop: 'extracts', titles: title, explaintext: 1, redirects: 1};
+				if(introOnly) params.exintro = 1;
+				const data = await this.api(params);
+				const page: any = Object.values(data.query?.pages || {})[0];
+				return this.clean(page?.extract || '');
+			}
+
+			pageUrl(title: string) {
+				return `https://en.wikipedia.org/wiki/${encodeURIComponent(title.replace(/ /g, '_'))}`;
+			}
+
+			stripHtml(text: string) {
+				return text.replace(/<[^>]+>/g, '');
+			}
+
+			async lookup(query: string, detail = 'summary') {
+				const results = await this.searchTitles(query, 6);
+				if(!results.length) return `❌ No Wikipedia articles found for "${query}"`;
+				const title = results[0].title;
+				const url = this.pageUrl(title);
+				const introOnly = detail !== 'full';
+				const content = await this.fetchExtract(title, introOnly);
+				return `## ${title}\n🔗 ${url}\n\n${content}`;
+			}
+
+			async search(query: string) {
+				const results = await this.searchTitles(query, 8);
+				if(!results.length) return `❌ No results for "${query}"`;
+				const lines = [`### Search results for "${query}"\n`];
+				for(let i = 0; i < results.length; i++) {
+					const r = results[i];
+					const snippet = this.stripHtml(r.snippet || '').trim();
+					lines.push(`**${i + 1}. ${r.title}**\n${snippet}\n${this.pageUrl(r.title)}`);
+				}
+				return lines.join('\n\n');
+			}
+		}
+
+		const wiki = new WikipediaClient(ua);
+		if(mode === 'search') return wiki.search(query);
+		return wiki.lookup(query, mode || 'summary');
+	}
+};
+
 export const GeoCodeTool: AiTool = {
 	name: 'geo_code',
 	description: 'Converts coordinates to address OR vice versa',
@@ -527,8 +620,8 @@ export const GeoWeatherTool: AiTool = {
 	},
 }
 
-export const NetFetchTool: AiTool = {
+export const WebFetchTool: AiTool = {
-	name: 'net_fetch',
+	name: 'web_fetch',
 	description: 'Make HTTP request to URL',
 	args: {
 		url: {type: 'string', description: 'URL to fetch', required: true},
@@ -544,9 +637,9 @@ export const NetFetchTool: AiTool = {
 	}) => new Http({url: args.url, headers: args.headers}).request({method: args.method || 'GET', body: args.body})
 }
 
-export const NetFlareSolverTool = (host: string) => {
+export const WebFlareSolverTool = (host: string) => {
 	return {
-		name: 'net_flaresolverr',
+		name: 'web_flaresolverr',
 		description: 'Use a flaresolverr proxy to bypass cloudflare bot detection',
 		args: {
 			url: {type: 'string', description: 'URL to fetch', required: true},
@@ -595,8 +688,8 @@ export const NetFlareSolverTool = (host: string) => {
 	}
 }
 
-export const NetReadTool: AiTool = {
+export const WebReadTool: AiTool = {
-	name: 'net_read',
+	name: 'web_read',
 	description: 'Extract clean content from webpages, or convert media/documents to accessible formats',
 	args: {
 		url: {type: 'string', description: 'URL to read', required: true},
@@ -699,8 +792,8 @@ export const NetReadTool: AiTool = {
 	}
 };
 
-export const NetSearchTool: AiTool = {
+export const WebSearchTool: AiTool = {
-	name: 'net_search',
+	name: 'web_search',
 	description: 'Use duckduckgo (anonymous) to find find relevant online resources. Returns a list of URLs that works great with the `read_webpage` tool',
 	args: {
 		query: {type: 'string', description: 'Search string', required: true},
@@ -724,96 +817,3 @@ export const NetSearchTool: AiTool = {
 		return results;
 	}
 }
-
-export const WikipediaTool: AiTool = {
-	name: 'get_wikipedia',
-	description: 'Search Wikipedia for matching articles',
-	args: {
-		query: {type: 'string', description: 'Search term or article title', required: true},
-		mode: {type: 'string', description: 'search - look for articles, summary - intro of first found article (default), full - complete first found article', enum: ['search', 'summary', 'full'], default: 'summary'},
-		ua: {type: 'string', description: 'User Agent'},
-	},
-	fn: async ({query, mode, ua}) => {
-		class WikipediaClient {
-			useragent = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)';
-
-			constructor(useragent: string) {
-				this.useragent = useragent;
-			}
-
-			async get(url) {
-				const resp = await fetch(url, {headers: {'User-Agent': this.useragent}});
-				return resp.json();
-			}
-
-			api(params) {
-				const qs = new URLSearchParams({...params, format: 'json', utf8: '1'}).toString();
-				return this.get(`https://en.wikipedia.org/w/api.php?${qs}`);
-			}
-
-			clean(text) {
-				const cutoffs = ['== See also ==', '== References ==', '== Bibliography ==', '== External links =='];
-				for (const marker of cutoffs) {
-					const idx = text.indexOf(marker);
-					if (idx !== -1) text = text.slice(0, idx);
-				}
-
-				return text
-					.replace(/^={4}\s*(.+?)\s*={4}$/gm, '#### $1')
-					.replace(/^={3}\s*(.+?)\s*={3}$/gm, '### $1')
-					.replace(/^={2}\s*(.+?)\s*={2}$/gm, '## $1')
-					.replace(/\n{3,}/g, '\n\n')
-					.replace(/ {2,}/g, ' ')
-					.replace(/\[\d+]/g, '')
-					.trim();
-			}
-
-			async searchTitles(query: string, limit = 6) {
-				const data = await this.api({action: 'query', list: 'search', srsearch: query, srlimit: limit, srprop: 'snippet'});
-				return data.query?.search || [];
-			}
-
-			async fetchExtract(title: string, introOnly = false) {
-				const params: any = {action: 'query', prop: 'extracts', titles: title, explaintext: 1, redirects: 1};
-				if(introOnly) params.exintro = 1;
-				const data = await this.api(params);
-				const page: any = Object.values(data.query?.pages || {})[0];
-				return this.clean(page?.extract || '');
-			}
-
-			pageUrl(title: string) {
-				return `https://en.wikipedia.org/wiki/${encodeURIComponent(title.replace(/ /g, '_'))}`;
-			}
-
-			stripHtml(text: string) {
-				return text.replace(/<[^>]+>/g, '');
-			}
-
-			async lookup(query: string, detail = 'summary') {
-				const results = await this.searchTitles(query, 6);
-				if(!results.length) return `❌ No Wikipedia articles found for "${query}"`;
-				const title = results[0].title;
-				const url = this.pageUrl(title);
-				const introOnly = detail !== 'full';
-				const content = await this.fetchExtract(title, introOnly);
-				return `## ${title}\n🔗 ${url}\n\n${content}`;
-			}
-
-			async search(query: string) {
-				const results = await this.searchTitles(query, 8);
-				if(!results.length) return `❌ No results for "${query}"`;
-				const lines = [`### Search results for "${query}"\n`];
-				for(let i = 0; i < results.length; i++) {
-					const r = results[i];
-					const snippet = this.stripHtml(r.snippet || '').trim();
-					lines.push(`**${i + 1}. ${r.title}**\n${snippet}\n${this.pageUrl(r.title)}`);
-				}
-				return lines.join('\n\n');
-			}
-		}
-
-		const wiki = new WikipediaClient(ua);
-		if(mode === 'search') return wiki.search(query);
-		return wiki.lookup(query, mode || 'summary');
-	}
-};