mojentic 1.0.0

package/dist/llm/tools/tell-user.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Tell user tool - displays messages to the user without expecting a response
+ */
+import { BaseTool, ToolArgs, ToolDescriptor, ToolResult } from './tool';
+import { Result } from '../../error';
+/**
+ * Tool that displays messages to the user without expecting a response
+ *
+ * This tool allows the LLM to send important intermediate information to the user
+ * as it works on completing their request. It's useful for providing status updates,
+ * progress information, or other important messages during long-running operations.
+ *
+ * @example
+ * ```typescript
+ * const tool = new TellUserTool();
+ * const result = await tool.run({ message: "Processing your request..." });
+ * // Prints to stdout:
+ * //
+ * //
+ * //
+ * // MESSAGE FROM ASSISTANT:
+ * // Processing your request...
+ * //
+ * // Returns: Ok("Message delivered to user.")
+ * ```
+ */
+export declare class TellUserTool extends BaseTool {
+    run(args: ToolArgs): Promise<Result<ToolResult, Error>>;
+    descriptor(): ToolDescriptor;
+}
+//# sourceMappingURL=tell-user.d.ts.map

package/dist/llm/tools/tell-user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tell-user.d.ts","sourceRoot":"","sources":["../../../src/llm/tools/tell-user.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACxE,OAAO,EAAM,MAAM,EAAE,MAAM,aAAa,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,YAAa,SAAQ,QAAQ;IAClC,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAQ7D,UAAU,IAAI,cAAc;CAoB7B"}

package/dist/llm/tools/tell-user.js

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * Tell user tool - displays messages to the user without expecting a response
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TellUserTool = void 0;
+const tool_1 = require("./tool");
+const error_1 = require("../../error");
+/**
+ * Tool that displays messages to the user without expecting a response
+ *
+ * This tool allows the LLM to send important intermediate information to the user
+ * as it works on completing their request. It's useful for providing status updates,
+ * progress information, or other important messages during long-running operations.
+ *
+ * @example
+ * ```typescript
+ * const tool = new TellUserTool();
+ * const result = await tool.run({ message: "Processing your request..." });
+ * // Prints to stdout:
+ * //
+ * //
+ * //
+ * // MESSAGE FROM ASSISTANT:
+ * // Processing your request...
+ * //
+ * // Returns: Ok("Message delivered to user.")
+ * ```
+ */
+class TellUserTool extends tool_1.BaseTool {
+    async run(args) {
+        const message = args.message || '';
+        console.log(`\n\n\nMESSAGE FROM ASSISTANT:\n${message}`);
+        return (0, error_1.Ok)('Message delivered to user.');
+    }
+    descriptor() {
+        return {
+            type: 'function',
+            function: {
+                name: 'tell_user',
+                description: 'Display a message to the user without expecting a response. Use this to send important intermediate information to the user as you work on completing their request.',
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        message: {
+                            type: 'string',
+                            description: 'The important message you want to display to the user.',
+                        },
+                    },
+                    required: ['message'],
+                },
+            },
+        };
+    }
+}
+exports.TellUserTool = TellUserTool;
+//# sourceMappingURL=tell-user.js.map

package/dist/llm/tools/tell-user.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tell-user.js","sourceRoot":"","sources":["../../../src/llm/tools/tell-user.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,iCAAwE;AACxE,uCAAyC;AAEzC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAa,YAAa,SAAQ,eAAQ;IACxC,KAAK,CAAC,GAAG,CAAC,IAAc;QACtB,MAAM,OAAO,GAAI,IAAI,CAAC,OAAkB,IAAI,EAAE,CAAC;QAE/C,OAAO,CAAC,GAAG,CAAC,kCAAkC,OAAO,EAAE,CAAC,CAAC;QAEzD,OAAO,IAAA,UAAE,EAAC,4BAA4B,CAAC,CAAC;IAC1C,CAAC;IAED,UAAU;QACR,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE;gBACR,IAAI,EAAE,WAAW;gBACjB,WAAW,EACT,sKAAsK;gBACxK,UAAU,EAAE;oBACV,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,OAAO,EAAE;4BACP,IAAI,EAAE,QAAQ;4BACd,WAAW,EAAE,wDAAwD;yBACtE;qBACF;oBACD,QAAQ,EAAE,CAAC,SAAS,CAAC;iBACtB;aACF;SACF,CAAC;IACJ,CAAC;CACF;AA7BD,oCA6BC"}

package/dist/llm/tools/tool-wrapper.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Tool Wrapper - Wraps agents as tools for agent delegation
+ */
+import { BaseTool, ToolArgs, ToolDescriptor, ToolResult } from './tool';
+import { Result } from '../../error';
+import { Agent } from '../agent';
+/**
+ * Wraps an agent as a tool, enabling agent delegation patterns.
+ *
+ * This allows one agent (coordinator) to use other agents (specialists)
+ * as tools, delegating specific tasks to domain experts.
+ *
+ * @example
+ * ```typescript
+ * const specialist = new Agent(
+ *   new LlmBroker('qwen3:7b', gateway),
+ *   [new DateResolverTool()],
+ *   'You are a temporal specialist...'
+ * );
+ *
+ * const coordinator = new Agent(
+ *   new LlmBroker('qwen3:32b', gateway),
+ *   [new ToolWrapper(specialist, 'temporal_specialist', 'A historian...')],
+ *   'You are a coordinator...'
+ * );
+ * ```
+ */
+export declare class ToolWrapper extends BaseTool {
+    private readonly agent;
+    private readonly toolName;
+    private readonly toolDescription;
+    /**
+     * Creates a new tool wrapper.
+     *
+     * @param agent - The agent to wrap as a tool
+     * @param toolName - Name for the tool (used in function calls)
+     * @param toolDescription - Description of what this agent does
+     */
+    constructor(agent: Agent, toolName: string, toolDescription: string);
+    /**
+     * Execute the wrapped agent with the given input.
+     *
+     * @param args - Tool arguments (must contain 'input' field)
+     * @returns Result containing the agent's response
+     */
+    run(args: ToolArgs): Promise<Result<ToolResult, Error>>;
+    /**
+     * Get the tool descriptor for LLM.
+     *
+     * @returns Tool descriptor with single 'input' parameter
+     */
+    descriptor(): ToolDescriptor;
+}
+//# sourceMappingURL=tool-wrapper.d.ts.map

package/dist/llm/tools/tool-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-wrapper.d.ts","sourceRoot":"","sources":["../../../src/llm/tools/tool-wrapper.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACxE,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAGjC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,WAAY,SAAQ,QAAQ;IASrC,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,eAAe;IAVlC;;;;;;OAMG;gBAEgB,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM;IAK1C;;;;;OAKG;IACG,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAgB7D;;;;OAIG;IACH,UAAU,IAAI,cAAc;CAmB7B"}

package/dist/llm/tools/tool-wrapper.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * Tool Wrapper - Wraps agents as tools for agent delegation
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolWrapper = void 0;
+const tool_1 = require("./tool");
+const models_1 = require("../models");
+/**
+ * Wraps an agent as a tool, enabling agent delegation patterns.
+ *
+ * This allows one agent (coordinator) to use other agents (specialists)
+ * as tools, delegating specific tasks to domain experts.
+ *
+ * @example
+ * ```typescript
+ * const specialist = new Agent(
+ *   new LlmBroker('qwen3:7b', gateway),
+ *   [new DateResolverTool()],
+ *   'You are a temporal specialist...'
+ * );
+ *
+ * const coordinator = new Agent(
+ *   new LlmBroker('qwen3:32b', gateway),
+ *   [new ToolWrapper(specialist, 'temporal_specialist', 'A historian...')],
+ *   'You are a coordinator...'
+ * );
+ * ```
+ */
+class ToolWrapper extends tool_1.BaseTool {
+    agent;
+    toolName;
+    toolDescription;
+    /**
+     * Creates a new tool wrapper.
+     *
+     * @param agent - The agent to wrap as a tool
+     * @param toolName - Name for the tool (used in function calls)
+     * @param toolDescription - Description of what this agent does
+     */
+    constructor(agent, toolName, toolDescription) {
+        super();
+        this.agent = agent;
+        this.toolName = toolName;
+        this.toolDescription = toolDescription;
+    }
+    /**
+     * Execute the wrapped agent with the given input.
+     *
+     * @param args - Tool arguments (must contain 'input' field)
+     * @returns Result containing the agent's response
+     */
+    async run(args) {
+        const input = args.input;
+        if (!input) {
+            return { ok: true, value: { error: 'input is required' } };
+        }
+        // Create initial messages from agent's behavior
+        const messages = this.agent.createInitialMessages();
+        // Append the input as a user message
+        messages.push(models_1.Message.user(input));
+        // Call the agent's broker with the agent's tools
+        return this.agent.getBroker().generate(messages, this.agent.getTools());
+    }
+    /**
+     * Get the tool descriptor for LLM.
+     *
+     * @returns Tool descriptor with single 'input' parameter
+     */
+    descriptor() {
+        return {
+            type: 'function',
+            function: {
+                name: this.toolName,
+                description: this.toolDescription,
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        input: {
+                            type: 'string',
+                            description: 'Instructions for this agent.',
+                        },
+                    },
+                    required: ['input'],
+                },
+            },
+        };
+    }
+}
+exports.ToolWrapper = ToolWrapper;
+//# sourceMappingURL=tool-wrapper.js.map

package/dist/llm/tools/tool-wrapper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-wrapper.js","sourceRoot":"","sources":["../../../src/llm/tools/tool-wrapper.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,iCAAwE;AAGxE,sCAAoC;AAEpC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAa,WAAY,SAAQ,eAAQ;IASpB;IACA;IACA;IAVnB;;;;;;OAMG;IACH,YACmB,KAAY,EACZ,QAAgB,EAChB,eAAuB;QAExC,KAAK,EAAE,CAAC;QAJS,UAAK,GAAL,KAAK,CAAO;QACZ,aAAQ,GAAR,QAAQ,CAAQ;QAChB,oBAAe,GAAf,eAAe,CAAQ;IAG1C,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,GAAG,CAAC,IAAc;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAe,CAAC;QACnC,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,KAAK,EAAE,mBAAmB,EAAE,EAAE,CAAC;QAC7D,CAAC;QAED,gDAAgD;QAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,qBAAqB,EAAE,CAAC;QAEpD,qCAAqC;QACrC,QAAQ,CAAC,IAAI,CAAC,gBAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAEnC,iDAAiD;QACjD,OAAO,IAAI,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED;;;;OAIG;IACH,UAAU;QACR,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE;gBACR,IAAI,EAAE,IAAI,CAAC,QAAQ;gBACnB,WAAW,EAAE,IAAI,CAAC,eAAe;gBACjC,UAAU,EAAE;oBACV,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,KAAK,EAAE;4BACL,IAAI,EAAE,QAAQ;4BACd,WAAW,EAAE,8BAA8B;yBAC5C;qBACF;oBACD,QAAQ,EAAE,CAAC,OAAO,CAAC;iBACpB;aACF;SACF,CAAC;IACJ,CAAC;CACF;AA9DD,kCA8DC"}

package/dist/llm/tools/tool.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Tool system for LLM function calling
+ */
+import { Result } from '../../error';
+/**
+ * JSON Schema definition for tool parameters
+ */
+export interface JsonSchema {
+    type: string;
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+    required?: string[];
+    description?: string;
+    enum?: unknown[];
+    [key: string]: unknown;
+}
+/**
+ * Function descriptor for tool calling
+ */
+export interface FunctionDescriptor {
+    name: string;
+    description: string;
+    parameters: JsonSchema;
+}
+/**
+ * Tool descriptor for LLM
+ */
+export interface ToolDescriptor {
+    type: 'function';
+    function: FunctionDescriptor;
+}
+/**
+ * Arguments passed to a tool
+ */
+export type ToolArgs = Record<string, unknown>;
+/**
+ * Result of a tool execution
+ */
+export type ToolResult = Record<string, unknown> | string | number | boolean | null;
+/**
+ * Interface for LLM tools
+ */
+export interface LlmTool {
+    /**
+     * Execute the tool with the given arguments
+     */
+    run(args: ToolArgs): Promise<Result<ToolResult, Error>>;
+    /**
+     * Get the tool descriptor for LLM
+     */
+    descriptor(): ToolDescriptor;
+    /**
+     * Get the tool name
+     */
+    name(): string;
+    /**
+     * Check if tool name matches given name
+     */
+    matches(name: string): boolean;
+}
+/**
+ * Abstract base class for tools
+ */
+export declare abstract class BaseTool implements LlmTool {
+    abstract run(args: ToolArgs): Promise<Result<ToolResult, Error>>;
+    abstract descriptor(): ToolDescriptor;
+    name(): string;
+    matches(name: string): boolean;
+}
+//# sourceMappingURL=tool.d.ts.map

package/dist/llm/tools/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../../src/llm/tools/tool.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAErC;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,OAAO,EAAE,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE/C;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAEpF;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB;;OAEG;IACH,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC,CAAC;IAExD;;OAEG;IACH,UAAU,IAAI,cAAc,CAAC;IAE7B;;OAEG;IACH,IAAI,IAAI,MAAM,CAAC;IAEf;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;CAChC;AAED;;GAEG;AACH,8BAAsB,QAAS,YAAW,OAAO;IAC/C,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAChE,QAAQ,CAAC,UAAU,IAAI,cAAc;IAErC,IAAI,IAAI,MAAM;IAId,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAG/B"}

package/dist/llm/tools/tool.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * Tool system for LLM function calling
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseTool = void 0;
+/**
+ * Abstract base class for tools
+ */
+class BaseTool {
+    name() {
+        return this.descriptor().function.name;
+    }
+    matches(name) {
+        return this.name() === name;
+    }
+}
+exports.BaseTool = BaseTool;
+//# sourceMappingURL=tool.js.map

package/dist/llm/tools/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../../src/llm/tools/tool.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAqEH;;GAEG;AACH,MAAsB,QAAQ;IAI5B,IAAI;QACF,OAAO,IAAI,CAAC,UAAU,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC;IACzC,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,OAAO,IAAI,CAAC,IAAI,EAAE,KAAK,IAAI,CAAC;IAC9B,CAAC;CACF;AAXD,4BAWC"}

package/dist/llm/tools/web-search-tool.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Web search tool - searches the web using DuckDuckGo
+ */
+import { BaseTool, ToolArgs, ToolDescriptor, ToolResult } from './tool';
+import { Result } from '../../error';
+/**
+ * Search result interface
+ */
+export interface SearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+/**
+ * Tool that searches the web using DuckDuckGo Lite
+ */
+export declare class WebSearchTool extends BaseTool {
+    private readonly baseUrl;
+    private readonly maxResults;
+    run(args: ToolArgs): Promise<Result<ToolResult, Error>>;
+    descriptor(): ToolDescriptor;
+    /**
+     * Parse search results from DuckDuckGo Lite HTML
+     */
+    private parseResults;
+    /**
+     * Strip HTML tags from a string
+     */
+    private stripHtmlTags;
+    /**
+     * Decode HTML entities
+     */
+    private decodeHtmlEntities;
+}
+//# sourceMappingURL=web-search-tool.d.ts.map

package/dist/llm/tools/web-search-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-search-tool.d.ts","sourceRoot":"","sources":["../../../src/llm/tools/web-search-tool.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACxE,OAAO,EAAW,MAAM,EAAE,MAAM,aAAa,CAAC;AAE9C;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,qBAAa,aAAc,SAAQ,QAAQ;IACzC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuC;IAC/D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAM;IAE3B,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IA0B7D,UAAU,IAAI,cAAc;IAqB5B;;OAEG;IACH,OAAO,CAAC,YAAY;IA4BpB;;OAEG;IACH,OAAO,CAAC,aAAa;IAIrB;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAkB3B"}

package/dist/llm/tools/web-search-tool.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Web search tool - searches the web using DuckDuckGo
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebSearchTool = void 0;
+const tool_1 = require("./tool");
+const error_1 = require("../../error");
+/**
+ * Tool that searches the web using DuckDuckGo Lite
+ */
+class WebSearchTool extends tool_1.BaseTool {
+    baseUrl = 'https://lite.duckduckgo.com/lite/';
+    maxResults = 10;
+    async run(args) {
+        const query = args.query;
+        if (!query || typeof query !== 'string' || query.trim().length === 0) {
+            return (0, error_1.Err)(new Error('Query parameter is required and must be a non-empty string'));
+        }
+        try {
+            const encodedQuery = encodeURIComponent(query.trim());
+            const url = `${this.baseUrl}?q=${encodedQuery}`;
+            const response = await fetch(url);
+            if (!response.ok) {
+                return (0, error_1.Err)(new Error(`Search request failed with status ${response.status}`));
+            }
+            const html = await response.text();
+            const results = this.parseResults(html);
+            return (0, error_1.Ok)(JSON.stringify(results, null, 2));
+        }
+        catch (error) {
+            return (0, error_1.Err)(error instanceof Error ? error : new Error('Unknown error during web search'));
+        }
+    }
+    descriptor() {
+        return {
+            type: 'function',
+            function: {
+                name: 'web_search',
+                description: 'Search the web for information using DuckDuckGo. Returns organic search results.',
+                parameters: {
+                    type: 'object',
+                    properties: {
+                        query: {
+                            type: 'string',
+                            description: 'The search query',
+                        },
+                    },
+                    required: ['query'],
+                },
+            },
+        };
+    }
+    /**
+     * Parse search results from DuckDuckGo Lite HTML
+     */
+    parseResults(html) {
+        const results = [];
+        // DuckDuckGo Lite uses table rows for results
+        // Each result has a structure like:
+        // <tr><td>...</td></tr> (ad/info rows)
+        // <tr><td valign="top">N.</td><td><a rel="nofollow" href="URL">Title</a><br>Snippet</td></tr>
+        // Match result rows with numbered entries
+        // Using [\s\S] instead of . with 's' flag for better compatibility
+        const resultPattern = /<tr>\s*<td[^>]*valign="top"[^>]*>\d+\.<\/td>\s*<td[^>]*>[\s\S]*?<a[^>]*href="([^"]+)"[^>]*>(.*?)<\/a>(?:<br\s*\/?>|\s*)([\s\S]*?)<\/td>\s*<\/tr>/gi;
+        let match;
+        while ((match = resultPattern.exec(html)) !== null && results.length < this.maxResults) {
+            const url = this.decodeHtmlEntities(match[1].trim());
+            const title = this.stripHtmlTags(this.decodeHtmlEntities(match[2].trim()));
+            const snippet = this.stripHtmlTags(this.decodeHtmlEntities(match[3].trim()));
+            // Only include results with meaningful content
+            if (url && title && snippet) {
+                results.push({ title, url, snippet });
+            }
+        }
+        return results;
+    }
+    /**
+     * Strip HTML tags from a string
+     */
+    stripHtmlTags(text) {
+        return text.replace(/<[^>]*>/g, '').trim();
+    }
+    /**
+     * Decode HTML entities
+     */
+    decodeHtmlEntities(text) {
+        const entities = {
+            '&amp;': '&',
+            '&lt;': '<',
+            '&gt;': '>',
+            '&quot;': '"',
+            '&#39;': "'",
+            '&nbsp;': ' ',
+        };
+        let result = text;
+        for (const [entity, char] of Object.entries(entities)) {
+            // eslint-disable-next-line security/detect-non-literal-regexp -- Entity patterns are from controlled set
+            result = result.replace(new RegExp(entity, 'g'), char);
+        }
+        return result;
+    }
+}
+exports.WebSearchTool = WebSearchTool;
+//# sourceMappingURL=web-search-tool.js.map

package/dist/llm/tools/web-search-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"web-search-tool.js","sourceRoot":"","sources":["../../../src/llm/tools/web-search-tool.ts"],"names":[],"mappings":";AAAA;;GAEG;;;AAEH,iCAAwE;AACxE,uCAA8C;AAW9C;;GAEG;AACH,MAAa,aAAc,SAAQ,eAAQ;IACxB,OAAO,GAAG,mCAAmC,CAAC;IAC9C,UAAU,GAAG,EAAE,CAAC;IAEjC,KAAK,CAAC,GAAG,CAAC,IAAc;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAe,CAAC;QAEnC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACrE,OAAO,IAAA,WAAG,EAAC,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC,CAAC;QACtF,CAAC;QAED,IAAI,CAAC;YACH,MAAM,YAAY,GAAG,kBAAkB,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC;YACtD,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,MAAM,YAAY,EAAE,CAAC;YAEhD,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;YAElC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,OAAO,IAAA,WAAG,EAAC,IAAI,KAAK,CAAC,qCAAqC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;YAChF,CAAC;YAED,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,MAAM,OAAO,GAAG,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;YAExC,OAAO,IAAA,UAAE,EAAC,IAAI,CAAC,SAAS,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;QAC9C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,IAAA,WAAG,EAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC,CAAC;QAC5F,CAAC;IACH,CAAC;IAED,UAAU;QACR,OAAO;YACL,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE;gBACR,IAAI,EAAE,YAAY;gBAClB,WAAW,EACT,kFAAkF;gBACpF,UAAU,EAAE;oBACV,IAAI,EAAE,QAAQ;oBACd,UAAU,EAAE;wBACV,KAAK,EAAE;4BACL,IAAI,EAAE,QAAQ;4BACd,WAAW,EAAE,kBAAkB;yBAChC;qBACF;oBACD,QAAQ,EAAE,CAAC,OAAO,CAAC;iBACpB;aACF;SACF,CAAC;IACJ,CAAC;IAED;;OAEG;IACK,YAAY,CAAC,IAAY;QAC/B,MAAM,OAAO,GAAmB,EAAE,CAAC;QAEnC,8CAA8C;QAC9C,oCAAoC;QACpC,uCAAuC;QACvC,8FAA8F;QAE9F,0CAA0C;QAC1C,mEAAmE;QACnE,MAAM,aAAa,GACjB,oJAAoJ,CAAC;QAEvJ,IAAI,KAAK,CAAC;QACV,OAAO,CAAC,KAAK,GAAG,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;YACvF,MAAM,GAAG,GAAG,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YACrD,MAAM,KAAK,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YAC3E,MAAM,OAAO,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;YAE7E,+CAA+C;YAC/C,IAAI,GAAG,IAAI,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC5B,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACK,aAAa,CAAC,IAAY;QAChC,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7C,CAAC;IAED;;OAEG;IACK,kBAAkB,CAAC,IAAY;QACrC,MAAM,QAAQ,GAA2B;YACvC,OAAO,EAAE,GAAG;YACZ,MAAM,EAAE,GAAG;YACX,MAAM,EAAE,GAAG;YACX,QAAQ,EAAE,GAAG;YACb,OAAO,EAAE,GAAG;YACZ,QAAQ,EAAE,GAAG;SACd,CAAC;QAEF,IAAI,MAAM,GAAG,IAAI,CAAC;QAClB,KAAK,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;YACtD,yGAAyG;YACzG,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,IAAI,CAAC,CAAC;QACzD,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AA9GD,sCA8GC"}

package/dist/llm/utils/image.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Image utilities for converting file paths to base64 data URIs
+ */
+/**
+ * Read an image file and convert it to a base64 data URI
+ *
+ * @param filePath - Path to the image file
+ * @returns Base64 data URI string (e.g., "data:image/jpeg;base64,...")
+ */
+export declare function imageToDataUri(filePath: string): string;
+/**
+ * Create a message content item for an image
+ *
+ * @param filePath - Path to the image file
+ * @returns ContentItem for the image
+ */
+export declare function imageContent(filePath: string): {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+};
+/**
+ * Create a message content item for text
+ */
+export declare function textContent(text: string): {
+    type: "text";
+    text: string;
+};
+//# sourceMappingURL=image.d.ts.map

package/dist/llm/utils/image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../../src/llm/utils/image.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUvD;AAoBD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM;;;;;EAO5C;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM;;;EAKvC"}

package/dist/llm/utils/image.js

@@ -0,0 +1,65 @@
+"use strict";
+/**
+ * Image utilities for converting file paths to base64 data URIs
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.imageToDataUri = imageToDataUri;
+exports.imageContent = imageContent;
+exports.textContent = textContent;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * Read an image file and convert it to a base64 data URI
+ *
+ * @param filePath - Path to the image file
+ * @returns Base64 data URI string (e.g., "data:image/jpeg;base64,...")
+ */
+function imageToDataUri(filePath) {
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- User-provided image paths required for multimodal LLM input
+    const imageBuffer = (0, node_fs_1.readFileSync)(filePath);
+    const base64 = imageBuffer.toString('base64');
+    // Determine MIME type from file extension
+    const ext = (0, node_path_1.extname)(filePath).toLowerCase();
+    const mimeType = getMimeType(ext);
+    return `data:${mimeType};base64,${base64}`;
+}
+/**
+ * Get MIME type from file extension
+ */
+function getMimeType(ext) {
+    const mimeTypes = {
+        '.jpg': 'image/jpeg',
+        '.jpeg': 'image/jpeg',
+        '.png': 'image/png',
+        '.gif': 'image/gif',
+        '.webp': 'image/webp',
+        '.bmp': 'image/bmp',
+        '.svg': 'image/svg+xml',
+    };
+    // eslint-disable-next-line security/detect-object-injection -- Safe dictionary lookup with known keys and fallback
+    return mimeTypes[ext] || 'image/jpeg';
+}
+/**
+ * Create a message content item for an image
+ *
+ * @param filePath - Path to the image file
+ * @returns ContentItem for the image
+ */
+function imageContent(filePath) {
+    return {
+        type: 'image_url',
+        image_url: {
+            url: imageToDataUri(filePath),
+        },
+    };
+}
+/**
+ * Create a message content item for text
+ */
+function textContent(text) {
+    return {
+        type: 'text',
+        text,
+    };
+}
+//# sourceMappingURL=image.js.map

package/dist/llm/utils/image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.js","sourceRoot":"","sources":["../../../src/llm/utils/image.ts"],"names":[],"mappings":";AAAA;;GAEG;;AAWH,wCAUC;AA0BD,oCAOC;AAKD,kCAKC;AA9DD,qCAAuC;AACvC,yCAAoC;AAEpC;;;;;GAKG;AACH,SAAgB,cAAc,CAAC,QAAgB;IAC7C,kIAAkI;IAClI,MAAM,WAAW,GAAG,IAAA,sBAAY,EAAC,QAAQ,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAE9C,0CAA0C;IAC1C,MAAM,GAAG,GAAG,IAAA,mBAAO,EAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;IAC5C,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAElC,OAAO,QAAQ,QAAQ,WAAW,MAAM,EAAE,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,SAAS,WAAW,CAAC,GAAW;IAC9B,MAAM,SAAS,GAA2B;QACxC,MAAM,EAAE,YAAY;QACpB,OAAO,EAAE,YAAY;QACrB,MAAM,EAAE,WAAW;QACnB,MAAM,EAAE,WAAW;QACnB,OAAO,EAAE,YAAY;QACrB,MAAM,EAAE,WAAW;QACnB,MAAM,EAAE,eAAe;KACxB,CAAC;IAEF,mHAAmH;IACnH,OAAO,SAAS,CAAC,GAAG,CAAC,IAAI,YAAY,CAAC;AACxC,CAAC;AAED;;;;;GAKG;AACH,SAAgB,YAAY,CAAC,QAAgB;IAC3C,OAAO;QACL,IAAI,EAAE,WAAoB;QAC1B,SAAS,EAAE;YACT,GAAG,EAAE,cAAc,CAAC,QAAQ,CAAC;SAC9B;KACF,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,SAAgB,WAAW,CAAC,IAAY;IACtC,OAAO;QACL,IAAI,EAAE,MAAe;QACrB,IAAI;KACL,CAAC;AACJ,CAAC"}