crewly 1.11.5 → 1.12.0

package/packages/crewly-agent/src/runtime/web-search.tool.test.ts

@@ -0,0 +1,131 @@
+/**
+ * Tests for the web_search tool.
+ *
+ * @module services/agent/crewly-agent/web-search.tool.test
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { createWebSearchTool, formatAsMarkdown } from './web-search.tool.js';
+import { CloudNotLoggedInError, type CloudConfig } from './cloud-config.js';
+
+const config: CloudConfig = {
+  cloudUrl: 'https://api.crewlyai.com',
+  token: 'fake-jwt',
+};
+
+function jsonResponse(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'Content-Type': 'application/json' },
+  });
+}
+
+describe('formatAsMarkdown', () => {
+  it('returns just the answer when there are no sources', () => {
+    expect(formatAsMarkdown('hello\n', [])).toBe('hello');
+  });
+
+  it('appends a numbered Sources list', () => {
+    const out = formatAsMarkdown('Some answer.', [
+      { title: 'Title A', url: 'https://a.com', snippet: '' },
+      { title: 'Title B', url: 'https://b.com', snippet: '' },
+    ]);
+    expect(out).toBe(
+      'Some answer.\n\nSources:\n[1] Title A — https://a.com\n[2] Title B — https://b.com',
+    );
+  });
+
+  it('falls back to url when title is missing', () => {
+    const out = formatAsMarkdown('a', [{ title: '', url: 'https://x.com', snippet: '' }]);
+    expect(out.endsWith('[1] https://x.com — https://x.com')).toBe(true);
+  });
+});
+
+describe('createWebSearchTool', () => {
+  it('returns CloudNotLoggedInError as a structured failure (does not throw)', async () => {
+    const tool = createWebSearchTool({
+      loadConfig: () => Promise.reject(new CloudNotLoggedInError()),
+    });
+    const result = (await tool.execute({ query: 'hi' })) as { success: boolean; error?: string };
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/Crewly Cloud is not connected/);
+  });
+
+  it('sends the query + bearer token to the configured endpoint', async () => {
+    const fetchSpy = vi.fn().mockResolvedValue(
+      jsonResponse({
+        success: true,
+        answer: 'answer text',
+        sources: [{ title: 'A', url: 'https://a.com', snippet: '' }],
+      }),
+    );
+    const tool = createWebSearchTool({
+      loadConfig: () => Promise.resolve(config),
+      fetchImpl: fetchSpy as unknown as typeof fetch,
+    });
+
+    const result = (await tool.execute({ query: 'what is X', max_results: 3 })) as {
+      success: boolean;
+      result?: string;
+    };
+
+    expect(fetchSpy).toHaveBeenCalledTimes(1);
+    const [url, init] = fetchSpy.mock.calls[0]!;
+    expect(url).toBe('https://api.crewlyai.com/api/v1/search');
+    expect(init.method).toBe('POST');
+    expect(init.headers.Authorization).toBe('Bearer fake-jwt');
+    expect(JSON.parse(init.body)).toEqual({ query: 'what is X', max_results: 3 });
+
+    expect(result.success).toBe(true);
+    expect(result.result).toContain('answer text');
+    expect(result.result).toContain('[1] A — https://a.com');
+  });
+
+  it('omits max_results from body when not provided', async () => {
+    const fetchSpy = vi.fn().mockResolvedValue(
+      jsonResponse({ success: true, answer: 'ok', sources: [] }),
+    );
+    const tool = createWebSearchTool({
+      loadConfig: () => Promise.resolve(config),
+      fetchImpl: fetchSpy as unknown as typeof fetch,
+    });
+    await tool.execute({ query: 'hi' });
+    expect(JSON.parse(fetchSpy.mock.calls[0]![1].body)).toEqual({ query: 'hi' });
+  });
+
+  it('returns a structured error on non-2xx response', async () => {
+    const fetchSpy = vi.fn().mockResolvedValue(
+      jsonResponse({ success: false, error: 'bad query' }, 400),
+    );
+    const tool = createWebSearchTool({
+      loadConfig: () => Promise.resolve(config),
+      fetchImpl: fetchSpy as unknown as typeof fetch,
+    });
+    const result = (await tool.execute({ query: 'hi' })) as { success: boolean; error?: string };
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/Search backend returned 400.*bad query/);
+  });
+
+  it('returns a structured error on fetch failure', async () => {
+    const tool = createWebSearchTool({
+      loadConfig: () => Promise.resolve(config),
+      fetchImpl: (() => Promise.reject(new Error('network down'))) as unknown as typeof fetch,
+    });
+    const result = (await tool.execute({ query: 'hi' })) as { success: boolean; error?: string };
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/network down/);
+  });
+
+  it('reports when the backend returns success:false', async () => {
+    const fetchSpy = vi.fn().mockResolvedValue(
+      jsonResponse({ success: false, error: 'quota exhausted' }, 200),
+    );
+    const tool = createWebSearchTool({
+      loadConfig: () => Promise.resolve(config),
+      fetchImpl: fetchSpy as unknown as typeof fetch,
+    });
+    const result = (await tool.execute({ query: 'hi' })) as { success: boolean; error?: string };
+    expect(result.success).toBe(false);
+    expect(result.error).toMatch(/quota exhausted/);
+  });
+});

package/packages/crewly-agent/src/runtime/web-search.tool.ts

@@ -0,0 +1,140 @@
+/**
+ * `web_search` tool — Crewly cloud-backed web search.
+ *
+ * Models like DeepSeek that lack a built-in search capability call this tool
+ * to delegate the search to the Crewly cloud service, which hits Gemini +
+ * Google Search and returns a synthesized answer with cited sources. The
+ * tool formats the response as markdown with a numbered Sources footer so
+ * the model can naturally inline citations like [1][2].
+ *
+ * Claude Code / Gemini CLI / Codex runtimes have their own search and won't
+ * be wired through this — this tool only ships in the Crewly agent runtime.
+ *
+ * @module services/agent/crewly-agent/web-search.tool
+ */
+
+import { z } from 'zod';
+import type { ToolDefinition } from './types.js';
+import { loadCloudConfig, CloudNotLoggedInError, type CloudConfig } from './cloud-config.js';
+
+const SEARCH_PATH = '/api/v1/search';
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+interface SearchSource {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+interface SearchResponse {
+  success: boolean;
+  answer?: string;
+  sources?: SearchSource[];
+  error?: string;
+}
+
+/** Injectable IO for tests. */
+export interface WebSearchDeps {
+  loadConfig?: () => Promise<CloudConfig>;
+  fetchImpl?: typeof fetch;
+  timeoutMs?: number;
+}
+
+export function createWebSearchTool(deps: WebSearchDeps = {}): ToolDefinition {
+  const loadConfig = deps.loadConfig ?? (() => loadCloudConfig());
+  const fetchImpl = deps.fetchImpl ?? fetch;
+  const timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+
+  return {
+    description:
+      'Search the web. Returns a synthesized answer plus a numbered list of cited sources. Use it whenever the user asks about current events, third-party documentation, package versions, or anything that may have changed since training. Inline-cite sources as [1][2] in your reply.',
+    inputSchema: z.object({
+      query: z.string().min(1).describe('The search query in natural language.'),
+      max_results: z
+        .number()
+        .int()
+        .min(1)
+        .max(10)
+        .optional()
+        .describe('Maximum number of cited sources to return (1-10, default 5).'),
+    }),
+    execute: async (args) => {
+      const { query, max_results } = args as { query: string; max_results?: number };
+
+      let config: CloudConfig;
+      try {
+        config = await loadConfig();
+      } catch (err) {
+        if (err instanceof CloudNotLoggedInError) {
+          return { success: false, error: err.message };
+        }
+        throw err;
+      }
+
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      let resp: Response;
+      try {
+        resp = await fetchImpl(`${config.cloudUrl}${SEARCH_PATH}`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${config.token}`,
+          },
+          body: JSON.stringify(
+            max_results !== undefined ? { query, max_results } : { query },
+          ),
+          signal: controller.signal,
+        });
+      } catch (err) {
+        clearTimeout(timer);
+        const message = err instanceof Error ? err.message : String(err);
+        return { success: false, error: `Search request failed: ${message}` };
+      }
+      clearTimeout(timer);
+
+      if (!resp.ok) {
+        let body: SearchResponse | null = null;
+        try {
+          body = (await resp.json()) as SearchResponse;
+        } catch {
+          /* not JSON — fall through */
+        }
+        const detail = body?.error || resp.statusText;
+        return { success: false, error: `Search backend returned ${resp.status}: ${detail}` };
+      }
+
+      const body = (await resp.json()) as SearchResponse;
+      if (!body.success || typeof body.answer !== 'string') {
+        return { success: false, error: body.error || 'Search returned no answer.' };
+      }
+
+      const sources = Array.isArray(body.sources) ? body.sources : [];
+      return {
+        success: true,
+        result: formatAsMarkdown(body.answer, sources),
+        sourceCount: sources.length,
+      };
+    },
+  };
+}
+
+/**
+ * Format `answer` + `sources` as a single markdown block ready to drop into
+ * the model's context: synthesized answer followed by a numbered Sources
+ * section. The model can inline [1][2] back-references.
+ *
+ * Exported for unit testing.
+ */
+export function formatAsMarkdown(answer: string, sources: readonly SearchSource[]): string {
+  if (sources.length === 0) return answer.trim();
+
+  const numbered = sources
+    .map((s, i) => {
+      const title = s.title?.trim() || s.url;
+      return `[${i + 1}] ${title} — ${s.url}`;
+    })
+    .join('\n');
+
+  return `${answer.trim()}\n\nSources:\n${numbered}`;
+}