@hemansubedi/aether-ai 1.0.0

package/src/tools/registry.ts

@@ -0,0 +1,54 @@
+import type { ToolDef, ToolCall } from "../types.js";
+
+export type ToolExecutor = (args: Record<string, any>) => Promise<string>;
+
+interface RegisteredTool extends ToolDef {
+  execute: ToolExecutor;
+}
+
+export class ToolRegistry {
+  private tools = new Map<string, RegisteredTool>();
+
+  register(def: ToolDef, execute: ToolExecutor): void {
+    this.tools.set(def.name, { ...def, execute });
+  }
+
+  get(name: string): RegisteredTool | undefined {
+    return this.tools.get(name);
+  }
+
+  list(): ToolDef[] {
+    return Array.from(this.tools.values()).map((t) => ({
+      name: t.name,
+      description: t.description,
+      parameters: t.parameters,
+    }));
+  }
+
+  toJSON(): Array<{
+    type: "function";
+    function: { name: string; description: string; parameters: Record<string, any> };
+  }> {
+    return this.list().map((t) => ({
+      type: "function",
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: t.parameters,
+      },
+    }));
+  }
+
+  async executeTool(name: string, args: Record<string, any>): Promise<string> {
+    const registered = this.tools.get(name);
+    if (!registered) {
+      return `ERROR: Unknown tool "${name}". Available tools: ${Array.from(this.tools.keys()).join(", ")}`;
+    }
+    try {
+      return await registered.execute(args ?? {});
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return `ERROR executing tool "${name}": ${message}`;
+    }
+  }
+}

package/src/tools/vision.ts

@@ -0,0 +1,152 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ToolDef } from "../types.js";
+import { getConfig } from "../config.js";
+import { createProvider } from "../providers/index.js";
+
+// Locally-installed vision-capable model (verified 2026-09-02).
+const VISION_MODEL = "hf.co/OBLITERATUS/Qwen3.8-27B-OBLITERATED:Q4_K_M";
+
+export interface VisionProvider {
+  name: string;
+  chatVision(
+    messages: Array<{ role: string; content: string; images?: string[] }>,
+    opts?: { signal?: AbortSignal; maxTokens?: number }
+  ): AsyncIterable<{ text?: string; error?: string }>;
+}
+
+/**
+ * Find a vision-capable provider by inspecting the configured models for the
+ * known vision model. Falls back to any provider that lists the vision model.
+ */
+export async function findVisionProvider(): Promise<VisionProvider | null> {
+  const cfg = getConfig();
+
+  // 1. Any provider that has the vision model configured. Force the provider
+  //    to use ONLY the vision model so resolveModel()/models[0] picks it.
+  for (const p of cfg.providers) {
+    if (!p.enabled) continue;
+    if (p.models.includes(VISION_MODEL)) {
+      try {
+        const visionConfig: any = { ...p, models: [VISION_MODEL] };
+        return wrapProvider(await createProvider(visionConfig), p.name);
+      } catch {
+        // try next
+      }
+    }
+  }
+
+  // 2. Any provider whose listModels() includes the vision model.
+  for (const p of cfg.providers) {
+    if (!p.enabled) continue;
+    try {
+      const probe = await createProvider(p);
+      const models = await probe.listModels();
+      if (models.includes(VISION_MODEL)) {
+        const visionConfig: any = { ...p, models: [VISION_MODEL] };
+        return wrapProvider(await createProvider(visionConfig), p.name);
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  return null;
+}
+
+function wrapProvider(provider: any, name: string): VisionProvider {
+  return {
+    name,
+    async *chatVision(messages, opts?) {
+      try {
+        // Ollama's OpenAI-compatible endpoint expects `content` as a string
+        // plus a top-level `images` array of base64 strings on the message.
+        // Other OpenAI-compatible providers accept content arrays; send the
+        // Ollama form since that is the primary vision path here.
+        const serialised = messages.map((m) => ({
+          role: m.role,
+          content: m.content,
+          ...(m.images ? { images: m.images } : {}),
+        }));
+        for await (const chunk of provider.chat(serialised as any, [], {
+          signal: opts?.signal,
+          maxTokens: opts?.maxTokens,
+        })) {
+          if (chunk.type === "text" && chunk.text) yield { text: chunk.text };
+          if (chunk.type === "error" && chunk.error) yield { error: chunk.error };
+        }
+      } catch (err) {
+        yield { error: (err as Error).message };
+      }
+    },
+  };
+}
+
+export function makeVisionTool(rootDir: string): { def: ToolDef; execute: (args: Record<string, any>) => Promise<string> } {
+  return {
+    def: {
+      name: "DescribeImage",
+      description:
+        "Describe an image file at a given path using a vision-capable model. Returns a textual description.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "path to the image file" },
+          question: { type: "string", default: "Describe this image in detail.", description: "question about the image" },
+        },
+        required: ["path"],
+      },
+    },
+    execute: async (args) => {
+      const rel = String(args.path ?? "");
+      // Resolve relative to the project root, but allow absolute paths to
+      // image files anywhere on the filesystem (that is the tool's purpose).
+      const target = path.isAbsolute(rel)
+        ? rel
+        : path.resolve(rootDir, rel);
+      const question = String(args.question ?? "Describe this image in detail.");
+
+      let buf: Buffer;
+      try {
+        if (!fs.existsSync(target)) {
+          return `ERROR: image not found: ${rel}`;
+        }
+        if (!fs.statSync(target).isFile()) {
+          return `ERROR: path "${rel}" is not a file`;
+        }
+        buf = fs.readFileSync(target);
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return `ERROR reading image "${rel}": ${message}`;
+      }
+
+      const b64 = buf.toString("base64");
+
+      const provider = await findVisionProvider();
+      if (!provider) {
+        return "No vision-capable provider available.";
+      }
+
+      const messages = [
+        {
+          role: "user",
+          content: question,
+          images: [b64],
+        },
+      ];
+
+      let text = "";
+      try {
+        for await (const chunk of provider.chatVision(messages, { maxTokens: 1024 })) {
+          if (chunk.text) text += chunk.text;
+          if (chunk.error) return `ERROR: vision provider failed: ${chunk.error}`;
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return `ERROR: vision provider failed: ${message}`;
+      }
+
+      return text.trim() || "(no description returned)";
+    },
+  };
+}

package/src/tools/websearch.ts

@@ -0,0 +1,130 @@
+import type { ToolDef } from "../types.js";
+
+const DDG_URL = "https://html.duckduckgo.com/html/";
+const USER_AGENT =
+  "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/126.0.0.0 Safari/537.36";
+
+export interface WebSearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+/**
+ * Parse DuckDuckGo HTML results into a list of {title, url, snippet}.
+ * DDG wraps real URLs in a redirect (`uddg` query param); we unwrap them.
+ */
+export function parseDdgResults(html: string): WebSearchResult[] {
+  const results: WebSearchResult[] = [];
+  // Each result is an <a class="result__a"> whose href points at the redirect.
+  const linkRe = /<a\b[^>]*class="[^"]*\bresult__a\b[^"]*"[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/gi;
+  // Snippets live in <a class="result__snippet"> ... </a>.
+  const snippetRe = /<a\b[^>]*class="[^"]*\bresult__snippet\b[^"]*"[^>]*>([\s\S]*?)<\/a>/gi;
+
+  const rawSnippets: string[] = [];
+  let sm: RegExpExecArray | null;
+  while ((sm = snippetRe.exec(html)) !== null) {
+    rawSnippets.push(stripTags(sm[1] ?? ""));
+  }
+
+  let idx = 0;
+  let lm: RegExpExecArray | null;
+  while ((lm = linkRe.exec(html)) !== null) {
+    const href = lm[1] ?? "";
+    const title = stripTags(lm[2] ?? "").trim();
+    if (!title) continue;
+    const url = unwrapRedirect(href);
+    if (!url) continue;
+    const snippet = rawSnippets[idx] ?? "";
+    results.push({ title, url, snippet });
+    idx++;
+  }
+  return results;
+}
+
+function stripTags(s: string): string {
+  return s
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&amp;/g, "&")
+    .replace(/&lt;/g, "<")
+    .replace(/&gt;/g, ">")
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;|&apos;/g, "'")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function unwrapRedirect(href: string): string {
+  // DDG wraps real URLs in a redirect like:
+  //   //duckduckgo.com/l/?uddg=https%3A%2F%2Fexample.com%2Fpage&amp;rut=...
+  // The real destination is the `uddg` query param. The hostname can vary
+  // (html.duckduckgo.com or duckduckgo.com) and the link may be protocol-
+  // relative, so we key off the /l/ path and the uddg param instead.
+  try {
+    const u = new URL(href, "https://html.duckduckgo.com/");
+    if (u.pathname === "/l/") {
+      const target = u.searchParams.get("uddg");
+      if (target) return decodeURIComponent(target);
+    }
+  } catch {
+    // fall through
+  }
+  // Some results are absolute URLs directly.
+  if (/^https?:\/\//i.test(href)) return href;
+  return "";
+}
+
+export function makeWebSearchTool(): { def: ToolDef; execute: (args: Record<string, any>) => Promise<string> } {
+  return {
+    def: {
+      name: "WebSearch",
+      description:
+        "Search the web for current information. Returns titles, URLs, and snippets. Use for recent events or facts not in the project.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "the search query" },
+          maxResults: { type: "number", default: 5, description: "max number of results to return" },
+        },
+        required: ["query"],
+      },
+    },
+    execute: async (args) => {
+      const query = String(args.query ?? "").trim();
+      if (!query) return "ERROR: query is required";
+      const maxResults = Math.max(1, Math.min(20, Number(args.maxResults) || 5));
+
+      let res: Response;
+      try {
+        const url = `${DDG_URL}?${new URLSearchParams({ q: query }).toString()}`;
+        res = await fetch(url, {
+          method: "GET",
+          headers: { "User-Agent": USER_AGENT, "Accept": "text/html" },
+        });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return `ERROR: WebSearch network failure: ${message}`;
+      }
+
+      if (!res.ok) {
+        return `ERROR: WebSearch failed: HTTP ${res.status}`;
+      }
+
+      let html = "";
+      try {
+        html = await res.text();
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return `ERROR: WebSearch failed to read response: ${message}`;
+      }
+
+      const parsed = parseDdgResults(html).slice(0, maxResults);
+      if (parsed.length === 0) {
+        return "No matches found";
+      }
+      return parsed
+        .map((r, i) => `${i + 1}. ${r.title} - ${r.url}\n   ${r.snippet}`)
+        .join("\n\n");
+    },
+  };
+}