@agentforge/tools 0.5.0 → 0.5.2

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import * as _agentforge_core from '@agentforge/core';
+import { HumanRequestPriority } from '@agentforge/core';
 import { z } from 'zod';
 
 /**
@@ -1389,4 +1390,146 @@ declare const uuidValidator: _agentforge_core.Tool<{
     message: string;
 }>;
 
-export { DuckDuckGoProvider, type HttpResponse, type RetryConfig, type ScraperResult, type SearchProvider, type SearchResult, SerperProvider, type UrlValidationResult, type WebSearchInput, type WebSearchOutput, arrayFilter, arrayGroupBy, arrayMap, arraySort, calculator, createDuckDuckGoProvider, createSerperProvider, creditCardValidator, csvGenerator, csvParser, csvToJson, currentDateTime, dateArithmetic, dateComparison, dateDifference, dateFormatter, directoryCreate, directoryDelete, directoryList, emailValidator, extractImages, extractLinks, fileAppend, fileDelete, fileExists, fileReader, fileSearch, fileWriter, htmlParser, httpClient, httpGet, httpPost, ipValidator, jsonMerge, jsonParser, jsonQuery, jsonStringify, jsonToCsv, jsonToXml, jsonValidator, mathFunctions, objectOmit, objectPick, pathBasename, pathDirname, pathExtension, pathJoin, pathNormalize, pathParse, pathRelative, pathResolve, phoneValidator, randomNumber, searchResultSchema, statistics, stringCaseConverter, stringJoin, stringLength, stringReplace, stringSplit, stringSubstring, stringTrim, urlBuilder, urlQueryParser, urlValidator, urlValidatorSimple, uuidValidator, webScraper, webSearch, webSearchOutputSchema, webSearchSchema, xmlGenerator, xmlParser, xmlToJson };
+/**
+ * Types for askHuman tool and human-in-the-loop workflows
+ * @module tools/agent/ask-human/types
+ */
+
+/**
+ * Input schema for askHuman tool
+ */
+declare const AskHumanInputSchema: z.ZodObject<{
+    /**
+     * The question to ask the human
+     */
+    question: z.ZodString;
+    /**
+     * Optional context to help the human understand the question
+     */
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    /**
+     * Priority level for this request
+     */
+    priority: z.ZodDefault<z.ZodEnum<["low", "normal", "high", "critical"]>>;
+    /**
+     * Timeout in milliseconds (0 = no timeout)
+     */
+    timeout: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Default response if timeout occurs
+     */
+    defaultResponse: z.ZodOptional<z.ZodString>;
+    /**
+     * Suggested responses (for UI to show as options)
+     */
+    suggestions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    timeout: number;
+    question: string;
+    priority: "low" | "normal" | "high" | "critical";
+    context?: Record<string, any> | undefined;
+    defaultResponse?: string | undefined;
+    suggestions?: string[] | undefined;
+}, {
+    question: string;
+    timeout?: number | undefined;
+    context?: Record<string, any> | undefined;
+    priority?: "low" | "normal" | "high" | "critical" | undefined;
+    defaultResponse?: string | undefined;
+    suggestions?: string[] | undefined;
+}>;
+/**
+ * Input type for askHuman tool
+ */
+type AskHumanInput = z.infer<typeof AskHumanInputSchema>;
+/**
+ * Output from askHuman tool
+ */
+interface AskHumanOutput {
+    /**
+     * The human's response
+     */
+    response: string;
+    /**
+     * Metadata about the interaction
+     */
+    metadata: {
+        /**
+         * Unique ID for this request
+         */
+        requestId: string;
+        /**
+         * When the request was created
+         */
+        requestedAt: number;
+        /**
+         * When the response was received
+         */
+        respondedAt: number;
+        /**
+         * How long it took to get a response (ms)
+         */
+        duration: number;
+        /**
+         * Whether this was a timeout response
+         */
+        timedOut: boolean;
+        /**
+         * Priority level
+         */
+        priority: HumanRequestPriority;
+    };
+}
+
+/**
+ * Create the askHuman tool
+ *
+ * This tool enables human-in-the-loop workflows by pausing agent execution
+ * and waiting for human input. It uses LangGraph's interrupt mechanism.
+ *
+ * @example
+ * ```typescript
+ * import { createAskHumanTool } from '@agentforge/tools';
+ *
+ * const askHuman = createAskHumanTool();
+ *
+ * // In your agent
+ * const tools = [askHuman, ...otherTools];
+ *
+ * // The agent can call this tool to ask for human input
+ * // When called, it will pause execution and wait for a response
+ * ```
+ *
+ * @returns The askHuman tool
+ */
+declare function createAskHumanTool(): _agentforge_core.Tool<{
+    question: string;
+    timeout?: number | undefined;
+    context?: Record<string, any> | undefined;
+    priority?: "low" | "normal" | "high" | "critical" | undefined;
+    defaultResponse?: string | undefined;
+    suggestions?: string[] | undefined;
+}, AskHumanOutput>;
+/**
+ * Default instance of the askHuman tool
+ *
+ * @example
+ * ```typescript
+ * import { askHumanTool } from '@agentforge/core';
+ *
+ * const agent = createReActAgent({
+ *   llm,
+ *   tools: [askHumanTool, ...otherTools],
+ * });
+ * ```
+ */
+declare const askHumanTool: _agentforge_core.Tool<{
+    question: string;
+    timeout?: number | undefined;
+    context?: Record<string, any> | undefined;
+    priority?: "low" | "normal" | "high" | "critical" | undefined;
+    defaultResponse?: string | undefined;
+    suggestions?: string[] | undefined;
+}, AskHumanOutput>;
+
+export { type AskHumanInput, AskHumanInputSchema, type AskHumanOutput, DuckDuckGoProvider, type HttpResponse, type RetryConfig, type ScraperResult, type SearchProvider, type SearchResult, SerperProvider, type UrlValidationResult, type WebSearchInput, type WebSearchOutput, arrayFilter, arrayGroupBy, arrayMap, arraySort, askHumanTool, calculator, createAskHumanTool, createDuckDuckGoProvider, createSerperProvider, creditCardValidator, csvGenerator, csvParser, csvToJson, currentDateTime, dateArithmetic, dateComparison, dateDifference, dateFormatter, directoryCreate, directoryDelete, directoryList, emailValidator, extractImages, extractLinks, fileAppend, fileDelete, fileExists, fileReader, fileSearch, fileWriter, htmlParser, httpClient, httpGet, httpPost, ipValidator, jsonMerge, jsonParser, jsonQuery, jsonStringify, jsonToCsv, jsonToXml, jsonValidator, mathFunctions, objectOmit, objectPick, pathBasename, pathDirname, pathExtension, pathJoin, pathNormalize, pathParse, pathRelative, pathResolve, phoneValidator, randomNumber, searchResultSchema, statistics, stringCaseConverter, stringJoin, stringLength, stringReplace, stringSplit, stringSubstring, stringTrim, urlBuilder, urlQueryParser, urlValidator, urlValidatorSimple, uuidValidator, webScraper, webSearch, webSearchOutputSchema, webSearchSchema, xmlGenerator, xmlParser, xmlToJson };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import * as _agentforge_core from '@agentforge/core';
+import { HumanRequestPriority } from '@agentforge/core';
 import { z } from 'zod';
 
 /**
@@ -1389,4 +1390,146 @@ declare const uuidValidator: _agentforge_core.Tool<{
     message: string;
 }>;
 
-export { DuckDuckGoProvider, type HttpResponse, type RetryConfig, type ScraperResult, type SearchProvider, type SearchResult, SerperProvider, type UrlValidationResult, type WebSearchInput, type WebSearchOutput, arrayFilter, arrayGroupBy, arrayMap, arraySort, calculator, createDuckDuckGoProvider, createSerperProvider, creditCardValidator, csvGenerator, csvParser, csvToJson, currentDateTime, dateArithmetic, dateComparison, dateDifference, dateFormatter, directoryCreate, directoryDelete, directoryList, emailValidator, extractImages, extractLinks, fileAppend, fileDelete, fileExists, fileReader, fileSearch, fileWriter, htmlParser, httpClient, httpGet, httpPost, ipValidator, jsonMerge, jsonParser, jsonQuery, jsonStringify, jsonToCsv, jsonToXml, jsonValidator, mathFunctions, objectOmit, objectPick, pathBasename, pathDirname, pathExtension, pathJoin, pathNormalize, pathParse, pathRelative, pathResolve, phoneValidator, randomNumber, searchResultSchema, statistics, stringCaseConverter, stringJoin, stringLength, stringReplace, stringSplit, stringSubstring, stringTrim, urlBuilder, urlQueryParser, urlValidator, urlValidatorSimple, uuidValidator, webScraper, webSearch, webSearchOutputSchema, webSearchSchema, xmlGenerator, xmlParser, xmlToJson };
+/**
+ * Types for askHuman tool and human-in-the-loop workflows
+ * @module tools/agent/ask-human/types
+ */
+
+/**
+ * Input schema for askHuman tool
+ */
+declare const AskHumanInputSchema: z.ZodObject<{
+    /**
+     * The question to ask the human
+     */
+    question: z.ZodString;
+    /**
+     * Optional context to help the human understand the question
+     */
+    context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    /**
+     * Priority level for this request
+     */
+    priority: z.ZodDefault<z.ZodEnum<["low", "normal", "high", "critical"]>>;
+    /**
+     * Timeout in milliseconds (0 = no timeout)
+     */
+    timeout: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Default response if timeout occurs
+     */
+    defaultResponse: z.ZodOptional<z.ZodString>;
+    /**
+     * Suggested responses (for UI to show as options)
+     */
+    suggestions: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    timeout: number;
+    question: string;
+    priority: "low" | "normal" | "high" | "critical";
+    context?: Record<string, any> | undefined;
+    defaultResponse?: string | undefined;
+    suggestions?: string[] | undefined;
+}, {
+    question: string;
+    timeout?: number | undefined;
+    context?: Record<string, any> | undefined;
+    priority?: "low" | "normal" | "high" | "critical" | undefined;
+    defaultResponse?: string | undefined;
+    suggestions?: string[] | undefined;
+}>;
+/**
+ * Input type for askHuman tool
+ */
+type AskHumanInput = z.infer<typeof AskHumanInputSchema>;
+/**
+ * Output from askHuman tool
+ */
+interface AskHumanOutput {
+    /**
+     * The human's response
+     */
+    response: string;
+    /**
+     * Metadata about the interaction
+     */
+    metadata: {
+        /**
+         * Unique ID for this request
+         */
+        requestId: string;
+        /**
+         * When the request was created
+         */
+        requestedAt: number;
+        /**
+         * When the response was received
+         */
+        respondedAt: number;
+        /**
+         * How long it took to get a response (ms)
+         */
+        duration: number;
+        /**
+         * Whether this was a timeout response
+         */
+        timedOut: boolean;
+        /**
+         * Priority level
+         */
+        priority: HumanRequestPriority;
+    };
+}
+
+/**
+ * Create the askHuman tool
+ *
+ * This tool enables human-in-the-loop workflows by pausing agent execution
+ * and waiting for human input. It uses LangGraph's interrupt mechanism.
+ *
+ * @example
+ * ```typescript
+ * import { createAskHumanTool } from '@agentforge/tools';
+ *
+ * const askHuman = createAskHumanTool();
+ *
+ * // In your agent
+ * const tools = [askHuman, ...otherTools];
+ *
+ * // The agent can call this tool to ask for human input
+ * // When called, it will pause execution and wait for a response
+ * ```
+ *
+ * @returns The askHuman tool
+ */
+declare function createAskHumanTool(): _agentforge_core.Tool<{
+    question: string;
+    timeout?: number | undefined;
+    context?: Record<string, any> | undefined;
+    priority?: "low" | "normal" | "high" | "critical" | undefined;
+    defaultResponse?: string | undefined;
+    suggestions?: string[] | undefined;
+}, AskHumanOutput>;
+/**
+ * Default instance of the askHuman tool
+ *
+ * @example
+ * ```typescript
+ * import { askHumanTool } from '@agentforge/core';
+ *
+ * const agent = createReActAgent({
+ *   llm,
+ *   tools: [askHumanTool, ...otherTools],
+ * });
+ * ```
+ */
+declare const askHumanTool: _agentforge_core.Tool<{
+    question: string;
+    timeout?: number | undefined;
+    context?: Record<string, any> | undefined;
+    priority?: "low" | "normal" | "high" | "critical" | undefined;
+    defaultResponse?: string | undefined;
+    suggestions?: string[] | undefined;
+}, AskHumanOutput>;
+
+export { type AskHumanInput, AskHumanInputSchema, type AskHumanOutput, DuckDuckGoProvider, type HttpResponse, type RetryConfig, type ScraperResult, type SearchProvider, type SearchResult, SerperProvider, type UrlValidationResult, type WebSearchInput, type WebSearchOutput, arrayFilter, arrayGroupBy, arrayMap, arraySort, askHumanTool, calculator, createAskHumanTool, createDuckDuckGoProvider, createSerperProvider, creditCardValidator, csvGenerator, csvParser, csvToJson, currentDateTime, dateArithmetic, dateComparison, dateDifference, dateFormatter, directoryCreate, directoryDelete, directoryList, emailValidator, extractImages, extractLinks, fileAppend, fileDelete, fileExists, fileReader, fileSearch, fileWriter, htmlParser, httpClient, httpGet, httpPost, ipValidator, jsonMerge, jsonParser, jsonQuery, jsonStringify, jsonToCsv, jsonToXml, jsonValidator, mathFunctions, objectOmit, objectPick, pathBasename, pathDirname, pathExtension, pathJoin, pathNormalize, pathParse, pathRelative, pathResolve, phoneValidator, randomNumber, searchResultSchema, statistics, stringCaseConverter, stringJoin, stringLength, stringReplace, stringSplit, stringSubstring, stringTrim, urlBuilder, urlQueryParser, urlValidator, urlValidatorSimple, uuidValidator, webScraper, webSearch, webSearchOutputSchema, webSearchSchema, xmlGenerator, xmlParser, xmlToJson };

package/dist/index.js

@@ -8,6 +8,7 @@ import { XMLParser, XMLBuilder } from 'fast-xml-parser';
 import { promises } from 'fs';
 import * as path3 from 'path';
 import { format, parse as parse$1, isValid, add, sub, differenceInDays, differenceInHours, differenceInMinutes, isAfter, isBefore } from 'date-fns';
+import { randomUUID } from 'crypto';
 
 // src/web/http-client.ts
 var HttpMethod = z.enum(["GET", "POST", "PUT", "DELETE", "PATCH", "HEAD", "OPTIONS"]);
@@ -1967,7 +1968,84 @@ var uuidValidator = toolBuilder().name("uuid-validator").description("Validate i
     message: valid ? `Valid UUID v${version}` : "Invalid UUID format"
   };
 }).build();
+var AskHumanInputSchema = z.object({
+  /**
+   * The question to ask the human
+   */
+  question: z.string().min(1).describe("The question to ask the human"),
+  /**
+   * Optional context to help the human understand the question
+   */
+  context: z.record(z.any()).optional().describe("Additional context for the question"),
+  /**
+   * Priority level for this request
+   */
+  priority: z.enum(["low", "normal", "high", "critical"]).default("normal").describe("Priority level for this request"),
+  /**
+   * Timeout in milliseconds (0 = no timeout)
+   */
+  timeout: z.number().min(0).default(0).describe("Timeout in milliseconds (0 = no timeout)"),
+  /**
+   * Default response if timeout occurs
+   */
+  defaultResponse: z.string().optional().describe("Default response if timeout occurs"),
+  /**
+   * Suggested responses (for UI to show as options)
+   */
+  suggestions: z.array(z.string()).optional().describe("Suggested responses for the human")
+});
+function createAskHumanTool() {
+  return toolBuilder().name("ask-human").description(
+    "Ask a human for input or approval. Use this when you need human guidance, approval for a critical action, or clarification on ambiguous requirements. The agent execution will pause until the human responds."
+  ).category(ToolCategory.UTILITY).schema(AskHumanInputSchema).implement(async (input) => {
+    const validatedInput = input;
+    const requestId = randomUUID();
+    const requestedAt = Date.now();
+    let interrupt;
+    try {
+      const langgraph = await import('@langchain/langgraph');
+      interrupt = langgraph.interrupt;
+    } catch (error) {
+      throw new Error(
+        "askHuman tool requires @langchain/langgraph to be installed. Install it with: npm install @langchain/langgraph"
+      );
+    }
+    if (!interrupt) {
+      throw new Error(
+        "interrupt function not found in @langchain/langgraph. Make sure you are using a compatible version of LangGraph."
+      );
+    }
+    const humanRequest = {
+      id: requestId,
+      question: validatedInput.question,
+      context: validatedInput.context,
+      priority: validatedInput.priority,
+      createdAt: requestedAt,
+      timeout: validatedInput.timeout,
+      defaultResponse: validatedInput.defaultResponse,
+      suggestions: validatedInput.suggestions,
+      status: "pending"
+    };
+    const response = interrupt(humanRequest);
+    const respondedAt = Date.now();
+    const duration = respondedAt - requestedAt;
+    const timedOut = validatedInput.timeout > 0 && duration >= validatedInput.timeout;
+    const finalResponse = timedOut && validatedInput.defaultResponse ? validatedInput.defaultResponse : response || "";
+    return {
+      response: finalResponse,
+      metadata: {
+        requestId,
+        requestedAt,
+        respondedAt,
+        duration,
+        timedOut,
+        priority: validatedInput.priority
+      }
+    };
+  }).build();
+}
+var askHumanTool = createAskHumanTool();
 
-export { DuckDuckGoProvider, SerperProvider, arrayFilter, arrayGroupBy, arrayMap, arraySort, calculator, createDuckDuckGoProvider, createSerperProvider, creditCardValidator, csvGenerator, csvParser, csvToJson, currentDateTime, dateArithmetic, dateComparison, dateDifference, dateFormatter, directoryCreate, directoryDelete, directoryList, emailValidator, extractImages, extractLinks, fileAppend, fileDelete, fileExists, fileReader, fileSearch, fileWriter, htmlParser, httpClient, httpGet, httpPost, ipValidator, jsonMerge, jsonParser, jsonQuery, jsonStringify, jsonToCsv, jsonToXml, jsonValidator, mathFunctions, objectOmit, objectPick, pathBasename, pathDirname, pathExtension, pathJoin, pathNormalize, pathParse, pathRelative, pathResolve, phoneValidator, randomNumber, searchResultSchema, statistics, stringCaseConverter, stringJoin, stringLength, stringReplace, stringSplit, stringSubstring, stringTrim, urlBuilder, urlQueryParser, urlValidator, urlValidatorSimple, uuidValidator, webScraper, webSearch, webSearchOutputSchema, webSearchSchema, xmlGenerator, xmlParser, xmlToJson };
+export { AskHumanInputSchema, DuckDuckGoProvider, SerperProvider, arrayFilter, arrayGroupBy, arrayMap, arraySort, askHumanTool, calculator, createAskHumanTool, createDuckDuckGoProvider, createSerperProvider, creditCardValidator, csvGenerator, csvParser, csvToJson, currentDateTime, dateArithmetic, dateComparison, dateDifference, dateFormatter, directoryCreate, directoryDelete, directoryList, emailValidator, extractImages, extractLinks, fileAppend, fileDelete, fileExists, fileReader, fileSearch, fileWriter, htmlParser, httpClient, httpGet, httpPost, ipValidator, jsonMerge, jsonParser, jsonQuery, jsonStringify, jsonToCsv, jsonToXml, jsonValidator, mathFunctions, objectOmit, objectPick, pathBasename, pathDirname, pathExtension, pathJoin, pathNormalize, pathParse, pathRelative, pathResolve, phoneValidator, randomNumber, searchResultSchema, statistics, stringCaseConverter, stringJoin, stringLength, stringReplace, stringSplit, stringSubstring, stringTrim, urlBuilder, urlQueryParser, urlValidator, urlValidatorSimple, uuidValidator, webScraper, webSearch, webSearchOutputSchema, webSearchSchema, xmlGenerator, xmlParser, xmlToJson };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map