@radaros/core 0.3.4 → 0.3.6

package/src/toolkits/websearch.ts

@@ -1,158 +0,0 @@
-import { z } from "zod";
-import type { ToolDef } from "../tools/types.js";
-import type { RunContext } from "../agent/run-context.js";
-import { Toolkit } from "./base.js";
-
-export interface WebSearchConfig {
-  /** Search provider: "tavily" or "serpapi". */
-  provider: "tavily" | "serpapi";
-  /** API key for the search provider. Falls back to TAVILY_API_KEY or SERPAPI_API_KEY env vars. */
-  apiKey?: string;
-  /** Max results to return per search (default 5). */
-  maxResults?: number;
-}
-
-/**
- * Web Search Toolkit — search the web from your agent.
- *
- * Supports Tavily and SerpAPI backends.
- *
- * @example
- * ```ts
- * const search = new WebSearchToolkit({ provider: "tavily" });
- * const agent = new Agent({ tools: [...search.getTools()] });
- * ```
- */
-export class WebSearchToolkit extends Toolkit {
-  readonly name = "websearch";
-  private config: WebSearchConfig;
-
-  constructor(config: WebSearchConfig) {
-    super();
-    this.config = config;
-  }
-
-  private getApiKey(): string {
-    if (this.config.apiKey) return this.config.apiKey;
-
-    const envKey =
-      this.config.provider === "tavily"
-        ? process.env.TAVILY_API_KEY
-        : process.env.SERPAPI_API_KEY;
-
-    if (!envKey) {
-      const envName =
-        this.config.provider === "tavily"
-          ? "TAVILY_API_KEY"
-          : "SERPAPI_API_KEY";
-      throw new Error(
-        `WebSearchToolkit: No API key provided. Set ${envName} env var or pass apiKey in config.`
-      );
-    }
-    return envKey;
-  }
-
-  getTools(): ToolDef[] {
-    const self = this;
-
-    return [
-      {
-        name: "web_search",
-        description:
-          "Search the web for current information. Returns titles, URLs, and snippets from search results.",
-        parameters: z.object({
-          query: z.string().describe("The search query"),
-          maxResults: z
-            .number()
-            .optional()
-            .describe("Maximum number of results (default 5)"),
-        }),
-        execute: async (
-          args: Record<string, unknown>,
-          _ctx: RunContext
-        ): Promise<string> => {
-          const query = args.query as string;
-          const max =
-            (args.maxResults as number) ?? self.config.maxResults ?? 5;
-
-          if (self.config.provider === "tavily") {
-            return self.searchTavily(query, max);
-          }
-          return self.searchSerpApi(query, max);
-        },
-      },
-    ];
-  }
-
-  private async searchTavily(
-    query: string,
-    maxResults: number
-  ): Promise<string> {
-    const apiKey = this.getApiKey();
-    const res = await fetch("https://api.tavily.com/search", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({
-        api_key: apiKey,
-        query,
-        max_results: maxResults,
-        include_answer: true,
-      }),
-    });
-
-    if (!res.ok) {
-      throw new Error(`Tavily search failed: ${res.status} ${res.statusText}`);
-    }
-
-    const data = (await res.json()) as any;
-    const results: string[] = [];
-
-    if (data.answer) {
-      results.push(`Answer: ${data.answer}\n`);
-    }
-
-    for (const r of data.results ?? []) {
-      results.push(`Title: ${r.title}\nURL: ${r.url}\nSnippet: ${r.content}\n`);
-    }
-
-    return results.join("\n---\n") || "No results found.";
-  }
-
-  private async searchSerpApi(
-    query: string,
-    maxResults: number
-  ): Promise<string> {
-    const apiKey = this.getApiKey();
-    const params = new URLSearchParams({
-      q: query,
-      api_key: apiKey,
-      engine: "google",
-      num: String(maxResults),
-    });
-
-    const res = await fetch(
-      `https://serpapi.com/search.json?${params.toString()}`
-    );
-
-    if (!res.ok) {
-      throw new Error(
-        `SerpAPI search failed: ${res.status} ${res.statusText}`
-      );
-    }
-
-    const data = (await res.json()) as any;
-    const results: string[] = [];
-
-    if (data.answer_box?.answer) {
-      results.push(`Answer: ${data.answer_box.answer}\n`);
-    }
-
-    for (const r of (data.organic_results ?? []).slice(0, maxResults)) {
-      results.push(
-        `Title: ${r.title}\nURL: ${r.link}\nSnippet: ${r.snippet ?? ""}\n`
-      );
-    }
-
-    return results.join("\n---\n") || "No results found.";
-  }
-}

package/src/toolkits/whatsapp.ts

@@ -1,209 +0,0 @@
-import { z } from "zod";
-import type { ToolDef } from "../tools/types.js";
-import type { RunContext } from "../agent/run-context.js";
-import { Toolkit } from "./base.js";
-
-export interface WhatsAppConfig {
-  /** WhatsApp Business API access token. Falls back to WHATSAPP_ACCESS_TOKEN env var. */
-  accessToken?: string;
-  /** WhatsApp Business phone number ID. Falls back to WHATSAPP_PHONE_NUMBER_ID env var. */
-  phoneNumberId?: string;
-  /** API version (default "v22.0"). Falls back to WHATSAPP_VERSION env var. */
-  version?: string;
-  /** Default recipient WhatsApp ID. Falls back to WHATSAPP_RECIPIENT_WAID env var. */
-  recipientWaid?: string;
-}
-
-/**
- * WhatsApp Toolkit — send messages via WhatsApp Business Cloud API (Meta).
- *
- * Uses the WhatsApp Cloud API directly (no Twilio).
- * Setup: https://developers.facebook.com/docs/whatsapp/cloud-api/get-started
- *
- * @example
- * ```ts
- * const whatsapp = new WhatsAppToolkit({
- *   accessToken: "...",
- *   phoneNumberId: "...",
- * });
- * const agent = new Agent({ tools: [...whatsapp.getTools()] });
- * ```
- */
-export class WhatsAppToolkit extends Toolkit {
-  readonly name = "whatsapp";
-  private accessToken: string;
-  private phoneNumberId: string;
-  private version: string;
-  private recipientWaid: string | undefined;
-
-  constructor(config: WhatsAppConfig = {}) {
-    super();
-    this.accessToken =
-      config.accessToken ?? process.env.WHATSAPP_ACCESS_TOKEN ?? "";
-    this.phoneNumberId =
-      config.phoneNumberId ?? process.env.WHATSAPP_PHONE_NUMBER_ID ?? "";
-    this.version =
-      config.version ?? process.env.WHATSAPP_VERSION ?? "v22.0";
-    this.recipientWaid =
-      config.recipientWaid ?? process.env.WHATSAPP_RECIPIENT_WAID;
-  }
-
-  private getBaseUrl(): string {
-    return `https://graph.facebook.com/${this.version}/${this.phoneNumberId}/messages`;
-  }
-
-  private validate(): void {
-    if (!this.accessToken) {
-      throw new Error(
-        "WhatsAppToolkit: accessToken is required. Set WHATSAPP_ACCESS_TOKEN env var or pass in config."
-      );
-    }
-    if (!this.phoneNumberId) {
-      throw new Error(
-        "WhatsAppToolkit: phoneNumberId is required. Set WHATSAPP_PHONE_NUMBER_ID env var or pass in config."
-      );
-    }
-  }
-
-  private resolveRecipient(recipient?: string): string {
-    const r = recipient ?? this.recipientWaid;
-    if (!r) {
-      throw new Error(
-        "WhatsAppToolkit: recipient is required. Provide it in the tool call or set WHATSAPP_RECIPIENT_WAID env var."
-      );
-    }
-    return r.replace(/[^0-9]/g, "");
-  }
-
-  getTools(): ToolDef[] {
-    const self = this;
-
-    return [
-      {
-        name: "whatsapp_send_text",
-        description:
-          "Send a text message to a WhatsApp user via WhatsApp Business Cloud API.",
-        parameters: z.object({
-          text: z.string().describe("The text message to send"),
-          recipient: z
-            .string()
-            .optional()
-            .describe(
-              "Recipient WhatsApp number with country code (e.g. 919876543210). Uses default if omitted."
-            ),
-          previewUrl: z
-            .boolean()
-            .optional()
-            .describe("Enable URL previews in the message (default false)"),
-        }),
-        execute: async (
-          args: Record<string, unknown>,
-          _ctx: RunContext
-        ): Promise<string> => {
-          self.validate();
-          const recipient = self.resolveRecipient(args.recipient as string);
-
-          const res = await fetch(self.getBaseUrl(), {
-            method: "POST",
-            headers: {
-              Authorization: `Bearer ${self.accessToken}`,
-              "Content-Type": "application/json",
-            },
-            body: JSON.stringify({
-              messaging_product: "whatsapp",
-              recipient_type: "individual",
-              to: recipient,
-              type: "text",
-              text: {
-                preview_url: (args.previewUrl as boolean) ?? false,
-                body: args.text as string,
-              },
-            }),
-          });
-
-          if (!res.ok) {
-            const err = await res.text();
-            throw new Error(
-              `WhatsApp send failed: ${res.status} ${err}`
-            );
-          }
-
-          const data = (await res.json()) as any;
-          const msgId = data.messages?.[0]?.id ?? "unknown";
-          return `Message sent successfully to ${recipient}. Message ID: ${msgId}`;
-        },
-      },
-      {
-        name: "whatsapp_send_template",
-        description:
-          "Send a template message to a WhatsApp user. Required for first-time outreach (24-hour messaging window).",
-        parameters: z.object({
-          templateName: z
-            .string()
-            .describe(
-              'The pre-approved template name (e.g. "hello_world")'
-            ),
-          recipient: z
-            .string()
-            .optional()
-            .describe(
-              "Recipient WhatsApp number with country code. Uses default if omitted."
-            ),
-          languageCode: z
-            .string()
-            .optional()
-            .describe('Template language code (default "en_US")'),
-          components: z
-            .array(z.record(z.any()))
-            .optional()
-            .describe(
-              "Template components for dynamic content (header, body, button parameters)"
-            ),
-        }),
-        execute: async (
-          args: Record<string, unknown>,
-          _ctx: RunContext
-        ): Promise<string> => {
-          self.validate();
-          const recipient = self.resolveRecipient(args.recipient as string);
-          const langCode = (args.languageCode as string) ?? "en_US";
-
-          const template: Record<string, unknown> = {
-            name: args.templateName as string,
-            language: { code: langCode },
-          };
-
-          if (args.components) {
-            template.components = args.components;
-          }
-
-          const res = await fetch(self.getBaseUrl(), {
-            method: "POST",
-            headers: {
-              Authorization: `Bearer ${self.accessToken}`,
-              "Content-Type": "application/json",
-            },
-            body: JSON.stringify({
-              messaging_product: "whatsapp",
-              recipient_type: "individual",
-              to: recipient,
-              type: "template",
-              template,
-            }),
-          });
-
-          if (!res.ok) {
-            const err = await res.text();
-            throw new Error(
-              `WhatsApp template send failed: ${res.status} ${err}`
-            );
-          }
-
-          const data = (await res.json()) as any;
-          const msgId = data.messages?.[0]?.id ?? "unknown";
-          return `Template message "${args.templateName}" sent to ${recipient}. Message ID: ${msgId}`;
-        },
-      },
-    ];
-  }
-}

package/src/tools/define-tool.ts

@@ -1,22 +0,0 @@
-import type { z } from "zod";
-import type { RunContext } from "../agent/run-context.js";
-import type { ToolDef, ToolResult, ToolCacheConfig } from "./types.js";
-
-export function defineTool<T extends z.ZodObject<any>>(config: {
-  name: string;
-  description: string;
-  parameters: T;
-  execute: (
-    args: z.infer<T>,
-    ctx: RunContext
-  ) => Promise<string | ToolResult>;
-  cache?: ToolCacheConfig;
-}): ToolDef {
-  return {
-    name: config.name,
-    description: config.description,
-    parameters: config.parameters,
-    execute: config.execute as ToolDef["execute"],
-    cache: config.cache,
-  };
-}

package/src/tools/tool-executor.ts

@@ -1,221 +0,0 @@
-import { createRequire } from "node:module";
-import type { ToolCall } from "../models/types.js";
-import type { RunContext } from "../agent/run-context.js";
-import type { ToolDef, ToolCallResult, ToolResult } from "./types.js";
-
-const _require = createRequire(import.meta.url);
-
-interface CacheEntry {
-  result: string | ToolResult;
-  expiresAt: number;
-}
-
-export class ToolExecutor {
-  private tools: Map<string, ToolDef>;
-  private concurrency: number;
-  private cache = new Map<string, CacheEntry>();
-  private cachedDefs: Array<{
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
-  }> | null = null;
-
-  constructor(tools: ToolDef[], concurrency: number = 5) {
-    this.tools = new Map(tools.map((t) => [t.name, t]));
-    this.concurrency = concurrency;
-    this.cachedDefs = this.buildToolDefinitions();
-  }
-
-  clearCache(): void {
-    this.cache.clear();
-  }
-
-  private getCacheKey(toolName: string, args: Record<string, unknown>): string {
-    const sortedArgs = JSON.stringify(args, Object.keys(args).sort());
-    return `${toolName}:${sortedArgs}`;
-  }
-
-  private getCached(toolName: string, args: Record<string, unknown>): (string | ToolResult) | undefined {
-    const tool = this.tools.get(toolName);
-    if (!tool?.cache) return undefined;
-
-    const key = this.getCacheKey(toolName, args);
-    const entry = this.cache.get(key);
-    if (!entry) return undefined;
-
-    if (Date.now() > entry.expiresAt) {
-      this.cache.delete(key);
-      return undefined;
-    }
-
-    return entry.result;
-  }
-
-  private setCache(toolName: string, args: Record<string, unknown>, result: string | ToolResult): void {
-    const tool = this.tools.get(toolName);
-    if (!tool?.cache) return;
-
-    const key = this.getCacheKey(toolName, args);
-    this.cache.set(key, {
-      result,
-      expiresAt: Date.now() + tool.cache.ttl,
-    });
-  }
-
-  async executeAll(
-    toolCalls: ToolCall[],
-    ctx: RunContext
-  ): Promise<ToolCallResult[]> {
-    const results: ToolCallResult[] = [];
-
-    for (let i = 0; i < toolCalls.length; i += this.concurrency) {
-      const batch = toolCalls.slice(i, i + this.concurrency);
-      const batchResults = await Promise.allSettled(
-        batch.map((tc) => this.executeSingle(tc, ctx))
-      );
-
-      for (let j = 0; j < batchResults.length; j++) {
-        const settled = batchResults[j];
-        const tc = batch[j];
-
-        if (settled.status === "fulfilled") {
-          results.push(settled.value);
-        } else {
-          results.push({
-            toolCallId: tc.id,
-            toolName: tc.name,
-            result: `Error: ${settled.reason?.message ?? "Unknown error"}`,
-            error: settled.reason?.message ?? "Unknown error",
-          });
-        }
-      }
-    }
-
-    return results;
-  }
-
-  private async executeSingle(
-    toolCall: ToolCall,
-    ctx: RunContext
-  ): Promise<ToolCallResult> {
-    const tool = this.tools.get(toolCall.name);
-    if (!tool) {
-      return {
-        toolCallId: toolCall.id,
-        toolName: toolCall.name,
-        result: `Error: Tool "${toolCall.name}" not found`,
-        error: `Tool "${toolCall.name}" not found`,
-      };
-    }
-
-    ctx.eventBus.emit("tool.call", {
-      runId: ctx.runId,
-      toolName: toolCall.name,
-      args: toolCall.arguments,
-    });
-
-    const cachedResult = this.getCached(toolCall.name, toolCall.arguments);
-    if (cachedResult !== undefined) {
-      const resultContent =
-        typeof cachedResult === "string" ? cachedResult : cachedResult.content;
-
-      ctx.eventBus.emit("tool.result", {
-        runId: ctx.runId,
-        toolName: toolCall.name,
-        result: `[cached] ${resultContent}`,
-      });
-
-      return {
-        toolCallId: toolCall.id,
-        toolName: toolCall.name,
-        result: cachedResult,
-      };
-    }
-
-    const parsed = tool.parameters.safeParse(toolCall.arguments);
-    if (!parsed.success) {
-      const errMsg = `Invalid arguments: ${parsed.error.message}`;
-      const result: ToolCallResult = {
-        toolCallId: toolCall.id,
-        toolName: toolCall.name,
-        result: errMsg,
-        error: errMsg,
-      };
-
-      ctx.eventBus.emit("tool.result", {
-        runId: ctx.runId,
-        toolName: toolCall.name,
-        result: errMsg,
-      });
-
-      return result;
-    }
-
-    const rawResult = await tool.execute(parsed.data, ctx);
-    const resultContent =
-      typeof rawResult === "string" ? rawResult : rawResult.content;
-
-    this.setCache(toolCall.name, toolCall.arguments, rawResult);
-
-    ctx.eventBus.emit("tool.result", {
-      runId: ctx.runId,
-      toolName: toolCall.name,
-      result: resultContent,
-    });
-
-    return {
-      toolCallId: toolCall.id,
-      toolName: toolCall.name,
-      result: rawResult,
-    };
-  }
-
-  getToolDefinitions(): Array<{
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
-  }> {
-    if (this.cachedDefs) return this.cachedDefs;
-    this.cachedDefs = this.buildToolDefinitions();
-    return this.cachedDefs;
-  }
-
-  private buildToolDefinitions(): Array<{
-    name: string;
-    description: string;
-    parameters: Record<string, unknown>;
-  }> {
-    const { zodToJsonSchema } = _require("zod-to-json-schema");
-    const defs: Array<{
-      name: string;
-      description: string;
-      parameters: Record<string, unknown>;
-    }> = [];
-
-    for (const tool of this.tools.values()) {
-      if (tool.rawJsonSchema) {
-        defs.push({
-          name: tool.name,
-          description: tool.description,
-          parameters: tool.rawJsonSchema,
-        });
-      } else {
-        const jsonSchema = zodToJsonSchema(tool.parameters, {
-          target: "jsonSchema7",
-          $refStrategy: "none",
-        }) as Record<string, unknown>;
-
-        delete jsonSchema["$schema"];
-        delete jsonSchema["additionalProperties"];
-
-        defs.push({
-          name: tool.name,
-          description: tool.description,
-          parameters: jsonSchema,
-        });
-      }
-    }
-
-    return defs;
-  }
-}

package/src/tools/types.ts

@@ -1,36 +0,0 @@
-import type { z } from "zod";
-import type { RunContext } from "../agent/run-context.js";
-
-export interface Artifact {
-  type: string;
-  data: unknown;
-  mimeType?: string;
-}
-
-export interface ToolResult {
-  content: string;
-  artifacts?: Artifact[];
-}
-
-export interface ToolCacheConfig {
-  /** Time-to-live in milliseconds. Cached results expire after this duration. */
-  ttl: number;
-}
-
-export interface ToolDef {
-  name: string;
-  description: string;
-  parameters: z.ZodObject<any>;
-  execute: (args: Record<string, unknown>, ctx: RunContext) => Promise<string | ToolResult>;
-  /** Raw JSON Schema to send to the LLM, bypassing Zod-to-JSON conversion (used by MCP tools). */
-  rawJsonSchema?: Record<string, unknown>;
-  /** Enable result caching for this tool. */
-  cache?: ToolCacheConfig;
-}
-
-export interface ToolCallResult {
-  toolCallId: string;
-  toolName: string;
-  result: string | ToolResult;
-  error?: string;
-}

package/src/utils/retry.ts

@@ -1,56 +0,0 @@
-export interface RetryConfig {
-  maxRetries: number;
-  initialDelayMs: number;
-  maxDelayMs: number;
-  retryableErrors?: (error: unknown) => boolean;
-}
-
-const DEFAULT_CONFIG: RetryConfig = {
-  maxRetries: 3,
-  initialDelayMs: 500,
-  maxDelayMs: 10_000,
-  retryableErrors: isRetryableError,
-};
-
-function isRetryableError(error: unknown): boolean {
-  if (error && typeof error === "object") {
-    const status = (error as any).status ?? (error as any).statusCode;
-    if (status === 429 || (status >= 500 && status < 600)) return true;
-
-    const code = (error as any).code;
-    if (code === "ECONNRESET" || code === "ETIMEDOUT" || code === "ENOTFOUND") return true;
-
-    const msg = (error as any).message;
-    if (typeof msg === "string" && /rate.limit|too.many.requests|overloaded/i.test(msg)) return true;
-  }
-  return false;
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((resolve) => setTimeout(resolve, ms));
-}
-
-export async function withRetry<T>(
-  fn: () => Promise<T>,
-  config?: Partial<RetryConfig>
-): Promise<T> {
-  const cfg = { ...DEFAULT_CONFIG, ...config };
-  let lastError: unknown;
-
-  for (let attempt = 0; attempt <= cfg.maxRetries; attempt++) {
-    try {
-      return await fn();
-    } catch (error) {
-      lastError = error;
-      if (attempt >= cfg.maxRetries || !cfg.retryableErrors!(error)) throw error;
-
-      const delay = Math.min(
-        cfg.initialDelayMs * Math.pow(2, attempt) + Math.random() * 200,
-        cfg.maxDelayMs
-      );
-      await sleep(delay);
-    }
-  }
-
-  throw lastError;
-}