@aria-cli/tools 1.0.0

package/src/__tests__/web-tools.test.ts

@@ -0,0 +1,619 @@
+/**
+ * @aria/tools - Web tool tests (web_search + browse)
+ *
+ * Tests for the web_search (SearchProviderRouter) and browse (Readability+Turndown) tool executors.
+ * All external calls (search providers, fetch) are mocked -- no real network traffic.
+ */
+
+import * as dns from "node:dns";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import type { ToolContext } from "../types.js";
+import { executeWebSearch, executeBrowse } from "../executors/web.js";
+import { isPrivateAddress } from "../security/ssrf.js";
+import { searchCache, browseCache } from "../cache/web-cache.js";
+
+vi.mock("node:dns", () => ({
+  promises: {
+    lookup: vi.fn(),
+  },
+}));
+
+// Helper to create a minimal ToolContext
+const createContext = (env: Record<string, string> = {}): ToolContext => ({
+  workingDir: "/tmp/test",
+  env,
+  confirm: async () => true,
+});
+
+describe("web_search", () => {
+  let originalFetch: typeof global.fetch;
+
+  beforeEach(() => {
+    originalFetch = global.fetch;
+    searchCache.clear();
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  it("uses DuckDuckGo fallback when no API keys are set", async () => {
+    // With SearchProviderRouter, DuckDuckGo is always available as fallback.
+    // No longer requires TAVILY_API_KEY to be set.
+    const savedKey = process.env.TAVILY_API_KEY;
+    delete process.env.TAVILY_API_KEY;
+
+    // Mock fetch to respond as DuckDuckGo would
+    const mockFetch = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ results: [] }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+    vi.stubGlobal("fetch", mockFetch);
+
+    try {
+      const ctx = createContext({});
+      const result = await executeWebSearch({ query: "test" }, ctx);
+
+      // Should succeed via DuckDuckGo fallback, or fail with search error (not missing key)
+      if (result.success) {
+        expect(result.data).toHaveProperty("query", "test");
+      } else {
+        expect(result.message).toContain("Web search failed");
+      }
+    } finally {
+      if (savedKey !== undefined) {
+        process.env.TAVILY_API_KEY = savedKey;
+      }
+    }
+  });
+
+  it("returns formatted results from mocked Tavily provider", async () => {
+    const tavilyResponse = {
+      results: [
+        {
+          title: "TypeScript Handbook",
+          url: "https://www.typescriptlang.org/docs/handbook",
+          content: "The TypeScript Handbook is the official guide to TypeScript.",
+          score: 0.95,
+        },
+        {
+          title: "TypeScript Tutorial",
+          url: "https://www.typescriptlang.org/docs/tutorial",
+          content: "Learn TypeScript from scratch with this tutorial.",
+          score: 0.88,
+        },
+      ],
+    };
+
+    const mockFetch = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify(tavilyResponse), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+    vi.stubGlobal("fetch", mockFetch);
+
+    const ctx = createContext({ TAVILY_API_KEY: "tvly-test-key-123" });
+    const result = await executeWebSearch({ query: "typescript guide" }, ctx);
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain("2 results");
+    expect(result.message).toContain("typescript guide");
+
+    const data = result.data as {
+      query: string;
+      results: Array<{ title: string; url: string; content: string }>;
+    };
+    expect(data.query).toBe("typescript guide");
+    expect(data.results).toHaveLength(2);
+    expect(data.results[0]).toMatchObject({
+      title: "TypeScript Handbook",
+      url: "https://www.typescriptlang.org/docs/handbook",
+      content: expect.stringContaining("TypeScript Handbook"),
+    });
+    expect(data.results[1]).toMatchObject({
+      title: "TypeScript Tutorial",
+      url: "https://www.typescriptlang.org/docs/tutorial",
+    });
+  });
+
+  it("routes through Tavily provider when TAVILY_API_KEY is set", async () => {
+    const mockFetch = vi.fn().mockResolvedValue(
+      new Response(JSON.stringify({ results: [] }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      }),
+    );
+    vi.stubGlobal("fetch", mockFetch);
+
+    const ctx = createContext({ TAVILY_API_KEY: "tvly-key" });
+    await executeWebSearch({ query: "test query", limit: 3 }, ctx);
+
+    // Verify the Tavily API was called (through the provider)
+    expect(mockFetch).toHaveBeenCalledWith(
+      "https://api.tavily.com/search",
+      expect.objectContaining({
+        method: "POST",
+        body: expect.any(String),
+      }),
+    );
+
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.api_key).toBe("tvly-key");
+    expect(body.query).toBe("test query");
+    expect(body.max_results).toBe(3);
+  });
+
+  it("defaults limit to 10 when not specified", async () => {
+    const mockFetch = vi
+      .fn()
+      .mockResolvedValue(new Response(JSON.stringify({ results: [] }), { status: 200 }));
+    vi.stubGlobal("fetch", mockFetch);
+
+    const ctx = createContext({ TAVILY_API_KEY: "tvly-key" });
+    await executeWebSearch({ query: "test" }, ctx);
+
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.max_results).toBe(10);
+  });
+
+  it("handles provider API error response", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response("Unauthorized", {
+          status: 401,
+          statusText: "Unauthorized",
+        }),
+      ),
+    );
+
+    const ctx = createContext({ TAVILY_API_KEY: "tvly-bad-key" });
+    const result = await executeWebSearch({ query: "test" }, ctx);
+
+    // With SearchProviderRouter, a 401 from Tavily triggers fallback to DuckDuckGo.
+    // DuckDuckGo also gets the 401 mock, so all providers fail.
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("Web search failed");
+  });
+
+  it("handles network error from all providers", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("Network unreachable")));
+
+    const ctx = createContext({ TAVILY_API_KEY: "tvly-key" });
+    const result = await executeWebSearch({ query: "test" }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("Web search failed");
+  });
+
+  it("merges ctx.env API keys into process.env for providers", async () => {
+    const mockFetch = vi
+      .fn()
+      .mockResolvedValue(new Response(JSON.stringify({ results: [] }), { status: 200 }));
+    vi.stubGlobal("fetch", mockFetch);
+
+    // ctx.env should be preferred — SearchProviderRouter reads from process.env,
+    // but executeWebSearch merges ctx.env into process.env temporarily
+    const ctx = createContext({ TAVILY_API_KEY: "ctx-key" });
+    await executeWebSearch({ query: "test" }, ctx);
+
+    const body = JSON.parse(mockFetch.mock.calls[0][1].body);
+    expect(body.api_key).toBe("ctx-key");
+  });
+
+  it("handles context abort as cancellation", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation((_url: string, options?: RequestInit) => {
+        return new Promise((_resolve, reject) => {
+          const signal = options?.signal;
+          if (signal) {
+            signal.addEventListener("abort", () => {
+              const abortError = new Error("The operation was aborted");
+              abortError.name = "AbortError";
+              reject(abortError);
+            });
+          }
+        });
+      }),
+    );
+
+    const ctx = createContext({ TAVILY_API_KEY: "tvly-key" });
+    const abortController = new AbortController();
+    const ctxWithAbort = { ...ctx, abortSignal: abortController.signal };
+
+    // Abort immediately to trigger the cancellation path
+    setTimeout(() => abortController.abort(), 10);
+    const result = await executeWebSearch({ query: "test" }, ctxWithAbort);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("cancelled");
+  });
+});
+
+describe("browse", () => {
+  let originalFetch: typeof global.fetch;
+
+  beforeEach(() => {
+    originalFetch = global.fetch;
+    browseCache.clear();
+    // Default DNS mock: resolve to a public IP
+    vi.mocked(dns.promises.lookup).mockResolvedValue({
+      address: "93.184.216.34",
+      family: 4,
+    });
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  it("returns text content from a valid HTML page", async () => {
+    const html = `
+      <html>
+        <head><title>Example Page</title></head>
+        <body>
+          <h1>Hello World</h1>
+          <p>This is a test page with some content.</p>
+        </body>
+      </html>
+    `;
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response(html, {
+          status: 200,
+          headers: { "Content-Type": "text/html" },
+        }),
+      ),
+    );
+
+    const ctx = createContext();
+    const result = await executeBrowse({ url: "https://example.com" }, ctx);
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain("Browsed");
+
+    const data = result.data as { url: string; title: string; content: string };
+    expect(data.url).toBe("https://example.com");
+    expect(data.title).toBe("Example Page");
+    expect(data.content).toContain("Hello World");
+    expect(data.content).toContain("test page");
+    // Should not contain HTML tags
+    expect(data.content).not.toContain("<h1>");
+    expect(data.content).not.toContain("<p>");
+  });
+
+  it("strips script and style blocks from HTML via Readability+Turndown", async () => {
+    const html = `
+      <html>
+        <head>
+          <title>Test</title>
+          <style>body { color: red; }</style>
+        </head>
+        <body>
+          <script>alert('xss');</script>
+          <p>Visible content only</p>
+          <script type="text/javascript">console.log('hidden');</script>
+        </body>
+      </html>
+    `;
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response(html, {
+          status: 200,
+          headers: { "Content-Type": "text/html" },
+        }),
+      ),
+    );
+
+    const ctx = createContext();
+    const result = await executeBrowse({ url: "https://example.com" }, ctx);
+
+    expect(result.success).toBe(true);
+    const data = result.data as { content: string };
+    // Content is now wrapped with external content boundary markers
+    expect(data.content).toContain("Visible content only");
+    expect(data.content).not.toContain("alert(");
+    expect(data.content).not.toContain("console.log(");
+    expect(data.content).not.toContain("color: red");
+  });
+
+  it("returns error for invalid URL", async () => {
+    const ctx = createContext();
+    const result = await executeBrowse({ url: "not-a-valid-url" }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("Invalid URL");
+  });
+
+  it("returns error for missing URL", async () => {
+    const ctx = createContext();
+    const result = await executeBrowse({ url: "" }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("URL is required");
+  });
+
+  it("returns error for non-http protocols", async () => {
+    const ctx = createContext();
+    const result = await executeBrowse({ url: "ftp://files.example.com/doc" }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("protocol");
+  });
+
+  it("returns error on HTTP error response", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response("Not Found", {
+          status: 404,
+          statusText: "Not Found",
+        }),
+      ),
+    );
+
+    const ctx = createContext();
+    const result = await executeBrowse({ url: "https://example.com/missing" }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("404");
+  });
+
+  it("handles timeout", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockImplementation((_url: string, options?: RequestInit) => {
+        return new Promise((_resolve, reject) => {
+          const signal = options?.signal;
+          if (signal) {
+            signal.addEventListener("abort", () => {
+              const abortError = new Error("The operation was aborted");
+              abortError.name = "AbortError";
+              reject(abortError);
+            });
+          }
+        });
+      }),
+    );
+
+    const ctx = createContext();
+    const result = await executeBrowse({ url: "https://slow.example.com", timeoutMs: 50 }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("timed out");
+  });
+
+  it("handles network error", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("Connection refused")));
+
+    const ctx = createContext();
+    const result = await executeBrowse({ url: "https://unreachable.example.com" }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("Connection refused");
+  });
+
+  it("truncates long content to 50000 characters", async () => {
+    const longText = "A".repeat(60_000);
+    const html = `<html><head><title>Big</title></head><body><p>${longText}</p></body></html>`;
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response(html, {
+          status: 200,
+          headers: { "Content-Type": "text/html" },
+        }),
+      ),
+    );
+
+    const ctx = createContext();
+    const result = await executeBrowse({ url: "https://example.com/long" }, ctx);
+
+    expect(result.success).toBe(true);
+    const data = result.data as { content: string };
+    // Content is now truncated at 50K + wrapped with external content boundary
+    // The boundary markers add ~100 chars, truncation notice adds ~20 chars
+    expect(data.content).toContain("[Content truncated]");
+  });
+
+  it("marks content as truncated when response exceeds byte limit", async () => {
+    const longText = "A".repeat(2 * 1024 * 1024 + 4096);
+    const html = `<html><head><title>Huge</title></head><body><p>${longText}</p></body></html>`;
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(
+        new Response(html, {
+          status: 200,
+          headers: { "Content-Type": "text/html" },
+        }),
+      ),
+    );
+
+    const ctx = createContext();
+    const result = await executeBrowse({ url: "https://example.com/huge-truncated" }, ctx);
+
+    expect(result.success).toBe(true);
+    const data = result.data as { content: string };
+    expect(data.content).toContain("[Content truncated]");
+  });
+
+  it("decodes HTML entities", async () => {
+    const html = `
+      <html>
+        <head><title>Entities</title></head>
+        <body>
+          <p>Tom &amp; Jerry &lt;3 &gt; &quot;friends&quot; &#39;forever&#39;</p>
+        </body>
+      </html>
+    `;
+
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response(html, { status: 200 })));
+
+    const ctx = createContext();
+    const result = await executeBrowse({ url: "https://example.com/entities" }, ctx);
+
+    expect(result.success).toBe(true);
+    const data = result.data as { content: string };
+    // Depending on extraction path, content may be decoded text or raw HTML fallback.
+    expect(data.content).toMatch(/Tom\s+(?:&|&amp;)\s+Jerry/);
+    expect(data.content).toMatch(/(?:<3|&lt;3)/);
+    expect(data.content).toMatch(/(?:"friends"|&quot;friends&quot;)/);
+    expect(data.content).toMatch(/(?:'forever'|&#39;forever&#39;)/);
+  });
+
+  it("returns empty title when no <title> tag present", async () => {
+    const html = "<html><body><p>No title here</p></body></html>";
+
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(new Response(html, { status: 200 })));
+
+    const ctx = createContext();
+    const result = await executeBrowse({ url: "https://example.com/notitle" }, ctx);
+
+    expect(result.success).toBe(true);
+    const data = result.data as { title: string };
+    expect(data.title).toBe("");
+  });
+
+  it("rejects URLs that resolve to private IP addresses", async () => {
+    vi.mocked(dns.promises.lookup).mockResolvedValue({
+      address: "127.0.0.1",
+      family: 4,
+    });
+
+    const ctx = createContext();
+    const result = await executeBrowse({ url: "https://internal.example.com" }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("private network");
+  });
+});
+
+describe("isPrivateAddress", () => {
+  it("blocks IPv4 loopback (127.x.x.x)", () => {
+    expect(isPrivateAddress("127.0.0.1")).toBe(true);
+    expect(isPrivateAddress("127.255.255.255")).toBe(true);
+  });
+
+  it("blocks AWS metadata endpoint (169.254.169.254)", () => {
+    expect(isPrivateAddress("169.254.169.254")).toBe(true);
+    expect(isPrivateAddress("169.254.0.1")).toBe(true);
+  });
+
+  it("blocks RFC 1918 10.x.x.x", () => {
+    expect(isPrivateAddress("10.0.0.1")).toBe(true);
+    expect(isPrivateAddress("10.255.255.255")).toBe(true);
+  });
+
+  it("blocks RFC 1918 172.16-31.x.x", () => {
+    expect(isPrivateAddress("172.16.0.1")).toBe(true);
+    expect(isPrivateAddress("172.31.255.255")).toBe(true);
+    // 172.15.x and 172.32.x are NOT private
+    expect(isPrivateAddress("172.15.0.1")).toBe(false);
+    expect(isPrivateAddress("172.32.0.1")).toBe(false);
+  });
+
+  it("blocks RFC 1918 192.168.x.x", () => {
+    expect(isPrivateAddress("192.168.1.1")).toBe(true);
+    expect(isPrivateAddress("192.168.0.0")).toBe(true);
+  });
+
+  it("blocks IPv6 loopback (::1)", () => {
+    expect(isPrivateAddress("::1")).toBe(true);
+  });
+
+  it("blocks IPv6 private (fc00::/7)", () => {
+    expect(isPrivateAddress("fc00::1")).toBe(true);
+    expect(isPrivateAddress("fd12:3456:789a::1")).toBe(true);
+  });
+
+  it("blocks unspecified addresses", () => {
+    expect(isPrivateAddress("0.0.0.0")).toBe(true);
+    expect(isPrivateAddress("::")).toBe(true);
+    expect(isPrivateAddress("[::]")).toBe(true);
+  });
+
+  it("allows public IP addresses", () => {
+    expect(isPrivateAddress("8.8.8.8")).toBe(false);
+    expect(isPrivateAddress("93.184.216.34")).toBe(false);
+    expect(isPrivateAddress("1.1.1.1")).toBe(false);
+  });
+});
+
+describe("SSRF protection", () => {
+  let originalFetch: typeof global.fetch;
+
+  beforeEach(() => {
+    originalFetch = global.fetch;
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+    vi.restoreAllMocks();
+  });
+
+  const privateIPs = [
+    { ip: "127.0.0.1", label: "loopback", family: 4 },
+    { ip: "169.254.169.254", label: "AWS metadata", family: 4 },
+    { ip: "10.0.0.1", label: "RFC 1918 (10.x)", family: 4 },
+    { ip: "192.168.1.1", label: "RFC 1918 (192.168.x)", family: 4 },
+    { ip: "172.16.0.1", label: "RFC 1918 (172.16.x)", family: 4 },
+    { ip: "::1", label: "IPv6 loopback", family: 6 },
+  ];
+
+  for (const { ip, label, family } of privateIPs) {
+    it(`browse rejects hostname resolving to ${label} (${ip})`, async () => {
+      vi.mocked(dns.promises.lookup).mockResolvedValue({
+        address: ip,
+        family,
+      });
+
+      const ctx = createContext();
+      const result = await executeBrowse({ url: "https://attacker.example.com" }, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toContain("private network");
+      expect(result.message).toContain(ip);
+    });
+  }
+
+  it("browse allows hostname resolving to public IP", async () => {
+    vi.mocked(dns.promises.lookup).mockResolvedValue({
+      address: "8.8.8.8",
+      family: 4,
+    });
+
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue(new Response("<html><body>OK</body></html>", { status: 200 })),
+    );
+
+    const ctx = createContext();
+    const result = await executeBrowse({ url: "https://safe.example.com" }, ctx);
+
+    expect(result.success).toBe(true);
+  });
+
+  it("browse returns error when DNS resolution fails", async () => {
+    vi.mocked(dns.promises.lookup).mockRejectedValue(
+      new Error("getaddrinfo ENOTFOUND bad.example.com"),
+    );
+
+    const ctx = createContext();
+    const result = await executeBrowse({ url: "https://bad.example.com" }, ctx);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("DNS resolution failed");
+  });
+});

package/src/ask-user-interaction.ts

@@ -0,0 +1,33 @@
+export interface AskUserQuestion {
+  question: string;
+  options?: string[];
+}
+
+const ASK_USER_PAUSE_REQUIRED_CODE = "ASK_USER_PAUSE_REQUIRED" as const;
+
+export class AskUserPauseRequiredError extends Error {
+  readonly code = ASK_USER_PAUSE_REQUIRED_CODE;
+  readonly questions: AskUserQuestion[];
+
+  constructor(
+    questions: AskUserQuestion[],
+    message = "ask_user requires additional answers before this run can continue.",
+  ) {
+    super(message);
+    this.name = "AskUserPauseRequiredError";
+    this.questions = questions.map((question) => ({
+      question: question.question,
+      ...(Array.isArray(question.options) ? { options: [...question.options] } : {}),
+    }));
+  }
+}
+
+export function isAskUserPauseRequiredError(error: unknown): error is AskUserPauseRequiredError {
+  if (error instanceof AskUserPauseRequiredError) return true;
+  if (!error || typeof error !== "object") return false;
+  const candidate = error as { code?: unknown; name?: unknown; questions?: unknown };
+  return (
+    candidate.code === ASK_USER_PAUSE_REQUIRED_CODE ||
+    (candidate.name === "AskUserPauseRequiredError" && Array.isArray(candidate.questions))
+  );
+}