@radaros/core 0.3.1 → 0.3.3

package/src/models/providers/google.ts

@@ -82,6 +82,12 @@ export class GoogleProvider implements ModelProvider {
       }
     }
 
+    if (options?.reasoning?.enabled) {
+      config.thinkingConfig = {
+        thinkingBudget: options.reasoning.budgetTokens ?? 10000,
+      };
+    }
+
     const params: Record<string, unknown> = {
       model: this.modelId,
       contents,
@@ -116,6 +122,12 @@ export class GoogleProvider implements ModelProvider {
     if (options?.topP !== undefined) config.topP = options.topP;
     if (options?.stop) config.stopSequences = options.stop;
 
+    if (options?.reasoning?.enabled) {
+      config.thinkingConfig = {
+        thinkingBudget: options.reasoning.budgetTokens ?? 10000,
+      };
+    }
+
     const params: Record<string, unknown> = {
       model: this.modelId,
       contents,
@@ -142,7 +154,9 @@ export class GoogleProvider implements ModelProvider {
       if (!candidate?.content?.parts) continue;
 
       for (const part of candidate.content.parts) {
-        if (part.text) {
+        if (part.thought) {
+          yield { type: "thinking", text: part.text ?? "" };
+        } else if (part.text) {
           yield { type: "text", text: part.text };
         }
 
@@ -313,16 +327,19 @@ export class GoogleProvider implements ModelProvider {
     return cleaned;
   }
 
-  private normalizeResponse(response: any): ModelResponse {
+  private normalizeResponse(response: any): ModelResponse & { thinking?: string } {
     const candidate = response.candidates?.[0];
     const parts = candidate?.content?.parts ?? [];
 
     let textContent = "";
+    let thinkingContent = "";
     const toolCalls: ToolCall[] = [];
     let toolCallCounter = 0;
 
     for (const part of parts) {
-      if (part.text) {
+      if (part.thought && part.text) {
+        thinkingContent += part.text;
+      } else if (part.text) {
         textContent += part.text;
       }
       if (part.functionCall) {
@@ -334,10 +351,12 @@ export class GoogleProvider implements ModelProvider {
       }
     }
 
+    const thinkingTokens = response.usageMetadata?.thoughtsTokenCount ?? 0;
     const usage: TokenUsage = {
       promptTokens: response.usageMetadata?.promptTokenCount ?? 0,
       completionTokens: response.usageMetadata?.candidatesTokenCount ?? 0,
       totalTokens: response.usageMetadata?.totalTokenCount ?? 0,
+      ...(thinkingTokens > 0 ? { reasoningTokens: thinkingTokens } : {}),
     };
 
     let finishReason: ModelResponse["finishReason"] = "stop";
@@ -347,7 +366,7 @@ export class GoogleProvider implements ModelProvider {
     else if (candidate?.finishReason === "SAFETY")
       finishReason = "content_filter";
 
-    return {
+    const result: ModelResponse & { thinking?: string } = {
       message: {
         role: "assistant",
         content: textContent || null,
@@ -357,5 +376,11 @@ export class GoogleProvider implements ModelProvider {
       finishReason,
       raw: response,
     };
+
+    if (thinkingContent) {
+      result.thinking = thinkingContent;
+    }
+
+    return result;
   }
 }

package/src/models/providers/openai.ts

@@ -72,8 +72,12 @@ export class OpenAIProvider implements ModelProvider {
       messages: this.toOpenAIMessages(messages),
     };
 
-    if (options?.temperature !== undefined)
-      params.temperature = options.temperature;
+    if (options?.reasoning?.enabled) {
+      params.reasoning_effort = options.reasoning.effort ?? "medium";
+    } else {
+      if (options?.temperature !== undefined)
+        params.temperature = options.temperature;
+    }
     if (options?.maxTokens !== undefined)
       params.max_tokens = options.maxTokens;
     if (options?.topP !== undefined) params.top_p = options.topP;
@@ -98,8 +102,12 @@ export class OpenAIProvider implements ModelProvider {
       stream: true,
     };
 
-    if (options?.temperature !== undefined)
-      params.temperature = options.temperature;
+    if (options?.reasoning?.enabled) {
+      params.reasoning_effort = options.reasoning.effort ?? "medium";
+    } else {
+      if (options?.temperature !== undefined)
+        params.temperature = options.temperature;
+    }
     if (options?.maxTokens !== undefined)
       params.max_tokens = options.maxTokens;
     if (options?.topP !== undefined) params.top_p = options.topP;
@@ -165,11 +173,16 @@ export class OpenAIProvider implements ModelProvider {
         }
       }
 
+      if (delta?.reasoning_content) {
+        yield { type: "thinking", text: delta.reasoning_content };
+      }
+
       if (choice.finish_reason) {
         for (const [, tc] of activeToolCalls) {
           yield { type: "tool_call_end", toolCallId: tc.id };
         }
 
+        const reasoningTkns = chunk.usage?.completion_tokens_details?.reasoning_tokens ?? 0;
         yield {
           type: "finish",
           finishReason:
@@ -181,6 +194,7 @@ export class OpenAIProvider implements ModelProvider {
                 promptTokens: chunk.usage.prompt_tokens ?? 0,
                 completionTokens: chunk.usage.completion_tokens ?? 0,
                 totalTokens: chunk.usage.total_tokens ?? 0,
+                ...(reasoningTkns > 0 ? { reasoningTokens: reasoningTkns } : {}),
               }
             : undefined,
         };
@@ -287,7 +301,7 @@ export class OpenAIProvider implements ModelProvider {
     }));
   }
 
-  private normalizeResponse(response: any): ModelResponse {
+  private normalizeResponse(response: any): ModelResponse & { thinking?: string } {
     const choice = response.choices[0];
     const msg = choice.message;
 
@@ -297,10 +311,12 @@ export class OpenAIProvider implements ModelProvider {
       arguments: JSON.parse(tc.function.arguments || "{}"),
     }));
 
+    const reasoningTokens = response.usage?.completion_tokens_details?.reasoning_tokens ?? 0;
     const usage: TokenUsage = {
       promptTokens: response.usage?.prompt_tokens ?? 0,
       completionTokens: response.usage?.completion_tokens ?? 0,
       totalTokens: response.usage?.total_tokens ?? 0,
+      ...(reasoningTokens > 0 ? { reasoningTokens } : {}),
     };
 
     let finishReason: ModelResponse["finishReason"] = "stop";
@@ -309,7 +325,7 @@ export class OpenAIProvider implements ModelProvider {
     else if (choice.finish_reason === "content_filter")
       finishReason = "content_filter";
 
-    return {
+    const result: ModelResponse & { thinking?: string } = {
       message: {
         role: "assistant",
         content: msg.content ?? null,
@@ -319,5 +335,11 @@ export class OpenAIProvider implements ModelProvider {
       finishReason,
       raw: response,
     };
+
+    if (msg.reasoning_content) {
+      result.thinking = msg.reasoning_content;
+    }
+
+    return result;
   }
 }

package/src/models/providers/vertex.ts

@@ -108,6 +108,12 @@ export class VertexAIProvider implements ModelProvider {
       }
     }
 
+    if (options?.reasoning?.enabled) {
+      config.thinkingConfig = {
+        thinkingBudget: options.reasoning.budgetTokens ?? 10000,
+      };
+    }
+
     const params: Record<string, unknown> = {
       model: this.modelId,
       contents,
@@ -140,6 +146,12 @@ export class VertexAIProvider implements ModelProvider {
     if (options?.topP !== undefined) config.topP = options.topP;
     if (options?.stop) config.stopSequences = options.stop;
 
+    if (options?.reasoning?.enabled) {
+      config.thinkingConfig = {
+        thinkingBudget: options.reasoning.budgetTokens ?? 10000,
+      };
+    }
+
     const params: Record<string, unknown> = {
       model: this.modelId,
       contents,
@@ -163,7 +175,9 @@ export class VertexAIProvider implements ModelProvider {
       if (!candidate?.content?.parts) continue;
 
       for (const part of candidate.content.parts) {
-        if (part.text) {
+        if (part.thought) {
+          yield { type: "thinking", text: part.text ?? "" };
+        } else if (part.text) {
           yield { type: "text", text: part.text };
         }
 
@@ -354,16 +368,21 @@ export class VertexAIProvider implements ModelProvider {
     return cleaned;
   }
 
-  private normalizeResponse(response: any): ModelResponse {
+  private normalizeResponse(response: any): ModelResponse & { thinking?: string } {
     const candidate = response.candidates?.[0];
     const parts = candidate?.content?.parts ?? [];
 
     let textContent = "";
+    let thinkingContent = "";
     const toolCalls: ToolCall[] = [];
     let toolCallCounter = 0;
 
     for (const part of parts) {
-      if (part.text) textContent += part.text;
+      if (part.thought && part.text) {
+        thinkingContent += part.text;
+      } else if (part.text) {
+        textContent += part.text;
+      }
       if (part.functionCall) {
         toolCalls.push({
           id: `vertex_tc_${toolCallCounter++}`,
@@ -373,10 +392,12 @@ export class VertexAIProvider implements ModelProvider {
       }
     }
 
+    const thinkingTokens = response.usageMetadata?.thoughtsTokenCount ?? 0;
     const usage: TokenUsage = {
       promptTokens: response.usageMetadata?.promptTokenCount ?? 0,
       completionTokens: response.usageMetadata?.candidatesTokenCount ?? 0,
       totalTokens: response.usageMetadata?.totalTokenCount ?? 0,
+      ...(thinkingTokens > 0 ? { reasoningTokens: thinkingTokens } : {}),
     };
 
     let finishReason: ModelResponse["finishReason"] = "stop";
@@ -386,7 +407,7 @@ export class VertexAIProvider implements ModelProvider {
     else if (candidate?.finishReason === "SAFETY")
       finishReason = "content_filter";
 
-    return {
+    const result: ModelResponse & { thinking?: string } = {
       message: {
         role: "assistant",
         content: textContent || null,
@@ -396,5 +417,11 @@ export class VertexAIProvider implements ModelProvider {
       finishReason,
       raw: response,
     };
+
+    if (thinkingContent) {
+      result.thinking = thinkingContent;
+    }
+
+    return result;
   }
 }

package/src/models/types.ts

@@ -64,6 +64,7 @@ export interface TokenUsage {
   promptTokens: number;
   completionTokens: number;
   totalTokens: number;
+  reasoningTokens?: number;
 }
 
 // ── Model response ────────────────────────────────────────────────────────
@@ -77,6 +78,7 @@ export interface ModelResponse {
 
 export type StreamChunk =
   | { type: "text"; text: string }
+  | { type: "thinking"; text: string }
   | { type: "tool_call_start"; toolCall: { id: string; name: string } }
   | { type: "tool_call_delta"; toolCallId: string; argumentsDelta: string }
   | { type: "tool_call_end"; toolCallId: string }
@@ -84,6 +86,14 @@ export type StreamChunk =
 
 // ── Model config ──────────────────────────────────────────────────────────
 
+export interface ReasoningConfig {
+  enabled: boolean;
+  /** Reasoning effort for OpenAI o-series models. */
+  effort?: "low" | "medium" | "high";
+  /** Token budget for thinking (Anthropic / Gemini). */
+  budgetTokens?: number;
+}
+
 export interface ModelConfig {
   temperature?: number;
   maxTokens?: number;
@@ -92,6 +102,8 @@ export interface ModelConfig {
   responseFormat?: "text" | "json" | { type: "json_schema"; schema: Record<string, unknown>; name?: string };
   /** Per-request API key override. When provided, the provider uses this key instead of the one set at construction. */
   apiKey?: string;
+  /** Enable extended thinking / reasoning. */
+  reasoning?: ReasoningConfig;
 }
 
 // ── Helpers ───────────────────────────────────────────────────────────────

package/src/toolkits/duckduckgo.ts

@@ -0,0 +1,256 @@
+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 DuckDuckGoConfig {
+  /** Enable web search (default true). */
+  enableSearch?: boolean;
+  /** Enable news search (default true). */
+  enableNews?: boolean;
+  /** Fixed max results per query (default 5). */
+  maxResults?: number;
+}
+
+/**
+ * DuckDuckGo Toolkit — search the web and news without any API key.
+ *
+ * Uses the DuckDuckGo HTML API (no key required).
+ *
+ * @example
+ * ```ts
+ * const ddg = new DuckDuckGoToolkit();
+ * const agent = new Agent({ tools: [...ddg.getTools()] });
+ * ```
+ */
+export class DuckDuckGoToolkit extends Toolkit {
+  readonly name = "duckduckgo";
+  private config: DuckDuckGoConfig;
+
+  constructor(config: DuckDuckGoConfig = {}) {
+    super();
+    this.config = {
+      enableSearch: config.enableSearch ?? true,
+      enableNews: config.enableNews ?? true,
+      maxResults: config.maxResults ?? 5,
+    };
+  }
+
+  getTools(): ToolDef[] {
+    const tools: ToolDef[] = [];
+
+    if (this.config.enableSearch) {
+      tools.push(this.buildSearchTool());
+    }
+
+    if (this.config.enableNews) {
+      tools.push(this.buildNewsTool());
+    }
+
+    return tools;
+  }
+
+  private buildSearchTool(): ToolDef {
+    const self = this;
+    return {
+      name: "duckduckgo_search",
+      description:
+        "Search the web using DuckDuckGo. Returns titles, URLs, and snippets. No API key required.",
+      parameters: z.object({
+        query: z.string().describe("The search query"),
+        maxResults: z
+          .number()
+          .optional()
+          .describe("Maximum number of results (default 5)"),
+      }),
+      async execute(
+        args: Record<string, unknown>,
+        _ctx: RunContext
+      ): Promise<string> {
+        const query = args.query as string;
+        const max = (args.maxResults as number) ?? self.config.maxResults ?? 5;
+        return self.search(query, max);
+      },
+    };
+  }
+
+  private buildNewsTool(): ToolDef {
+    const self = this;
+    return {
+      name: "duckduckgo_news",
+      description:
+        "Get the latest news from DuckDuckGo. Returns headlines, sources, URLs, and dates.",
+      parameters: z.object({
+        query: z.string().describe("The news search query"),
+        maxResults: z
+          .number()
+          .optional()
+          .describe("Maximum number of results (default 5)"),
+      }),
+      async execute(
+        args: Record<string, unknown>,
+        _ctx: RunContext
+      ): Promise<string> {
+        const query = args.query as string;
+        const max = (args.maxResults as number) ?? self.config.maxResults ?? 5;
+        return self.searchNews(query, max);
+      },
+    };
+  }
+
+  private async search(query: string, maxResults: number): Promise<string> {
+    const url = `https://api.duckduckgo.com/?q=${encodeURIComponent(query)}&format=json&no_redirect=1&no_html=1&skip_disambig=1`;
+
+    const res = await fetch(url, {
+      headers: { "User-Agent": "RadarOS/1.0" },
+    });
+
+    if (!res.ok) {
+      throw new Error(`DuckDuckGo search failed: ${res.status}`);
+    }
+
+    const data = (await res.json()) as any;
+    const results: string[] = [];
+
+    if (data.Abstract) {
+      results.push(
+        `Answer: ${data.Abstract}\nSource: ${data.AbstractSource}\nURL: ${data.AbstractURL}`
+      );
+    }
+
+    const topics = data.RelatedTopics ?? [];
+    for (const topic of topics.slice(0, maxResults)) {
+      if (topic.Text && topic.FirstURL) {
+        results.push(`${topic.Text}\nURL: ${topic.FirstURL}`);
+      }
+      if (topic.Topics) {
+        for (const sub of topic.Topics.slice(0, 2)) {
+          if (sub.Text && sub.FirstURL) {
+            results.push(`${sub.Text}\nURL: ${sub.FirstURL}`);
+          }
+        }
+      }
+    }
+
+    if (results.length === 0 && data.Redirect) {
+      return `Redirect: ${data.Redirect}`;
+    }
+
+    if (results.length === 0) {
+      const htmlResults = await this.scrapeHtmlSearch(query, maxResults);
+      if (htmlResults) return htmlResults;
+      return "No results found.";
+    }
+
+    return results.join("\n\n---\n\n");
+  }
+
+  private async scrapeHtmlSearch(
+    query: string,
+    maxResults: number
+  ): Promise<string | null> {
+    const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query)}`;
+
+    const res = await fetch(url, {
+      headers: {
+        "User-Agent":
+          "Mozilla/5.0 (compatible; RadarOS/1.0; +https://radaros.dev)",
+      },
+    });
+
+    if (!res.ok) return null;
+
+    const html = await res.text();
+
+    const results: string[] = [];
+    const linkRegex =
+      /<a[^>]*class="result__a"[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi;
+    const snippetRegex =
+      /<a[^>]*class="result__snippet"[^>]*>([\s\S]*?)<\/a>/gi;
+
+    const links: { url: string; title: string }[] = [];
+    let match;
+    while ((match = linkRegex.exec(html)) !== null) {
+      const rawUrl = match[1];
+      const title = match[2].replace(/<[^>]*>/g, "").trim();
+      const decoded = this.decodeDdgUrl(rawUrl);
+      if (title && decoded) {
+        links.push({ url: decoded, title });
+      }
+    }
+
+    const snippets: string[] = [];
+    while ((match = snippetRegex.exec(html)) !== null) {
+      snippets.push(match[1].replace(/<[^>]*>/g, "").trim());
+    }
+
+    for (let i = 0; i < Math.min(links.length, maxResults); i++) {
+      results.push(
+        `Title: ${links[i].title}\nURL: ${links[i].url}\nSnippet: ${snippets[i] ?? ""}`
+      );
+    }
+
+    return results.length > 0 ? results.join("\n\n---\n\n") : null;
+  }
+
+  private decodeDdgUrl(url: string): string | null {
+    if (url.startsWith("//duckduckgo.com/l/?uddg=")) {
+      const match = url.match(/uddg=([^&]*)/);
+      if (match) return decodeURIComponent(match[1]);
+    }
+    if (url.startsWith("http")) return url;
+    return null;
+  }
+
+  private async searchNews(
+    query: string,
+    maxResults: number
+  ): Promise<string> {
+    const url = `https://html.duckduckgo.com/html/?q=${encodeURIComponent(query + " news")}&iar=news`;
+
+    const res = await fetch(url, {
+      headers: {
+        "User-Agent":
+          "Mozilla/5.0 (compatible; RadarOS/1.0; +https://radaros.dev)",
+      },
+    });
+
+    if (!res.ok) {
+      throw new Error(`DuckDuckGo news search failed: ${res.status}`);
+    }
+
+    const html = await res.text();
+    const results: string[] = [];
+
+    const linkRegex =
+      /<a[^>]*class="result__a"[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi;
+    const snippetRegex =
+      /<a[^>]*class="result__snippet"[^>]*>([\s\S]*?)<\/a>/gi;
+
+    const links: { url: string; title: string }[] = [];
+    let match;
+    while ((match = linkRegex.exec(html)) !== null) {
+      const rawUrl = match[1];
+      const title = match[2].replace(/<[^>]*>/g, "").trim();
+      const decoded = this.decodeDdgUrl(rawUrl);
+      if (title && decoded) {
+        links.push({ url: decoded, title });
+      }
+    }
+
+    const snippets: string[] = [];
+    while ((match = snippetRegex.exec(html)) !== null) {
+      snippets.push(match[1].replace(/<[^>]*>/g, "").trim());
+    }
+
+    for (let i = 0; i < Math.min(links.length, maxResults); i++) {
+      results.push(
+        `Title: ${links[i].title}\nURL: ${links[i].url}\nSnippet: ${snippets[i] ?? ""}`
+      );
+    }
+
+    return results.length > 0
+      ? results.join("\n\n---\n\n")
+      : "No news results found.";
+  }
+}

package/src/tools/define-tool.ts

@@ -1,6 +1,6 @@
 import type { z } from "zod";
 import type { RunContext } from "../agent/run-context.js";
-import type { ToolDef, ToolResult } from "./types.js";
+import type { ToolDef, ToolResult, ToolCacheConfig } from "./types.js";
 
 export function defineTool<T extends z.ZodObject<any>>(config: {
   name: string;
@@ -10,11 +10,13 @@ export function defineTool<T extends z.ZodObject<any>>(config: {
     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,19 +1,61 @@
 import { createRequire } from "node:module";
 import type { ToolCall } from "../models/types.js";
 import type { RunContext } from "../agent/run-context.js";
-import type { ToolDef, ToolCallResult } from "./types.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>();
 
   constructor(tools: ToolDef[], concurrency: number = 5) {
     this.tools = new Map(tools.map((t) => [t.name, t]));
     this.concurrency = concurrency;
   }
 
+  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
@@ -66,6 +108,24 @@ export class ToolExecutor {
       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}`;
@@ -89,6 +149,8 @@ export class ToolExecutor {
     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,