@open-mercato/web-research-exa 0.7.1-develop.7194.1.ab4fc81f82

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+[build:web-research-tavily] found 2 entry points
+[build:web-research-tavily] built successfully

package/build.mjs

@@ -0,0 +1,10 @@
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { buildPackage } from '../../scripts/build-package.mjs'
+
+const packageDir = dirname(fileURLToPath(import.meta.url))
+
+await buildPackage(packageDir, {
+  name: 'web-research-tavily',
+  entryPoints: 'src/**/*.ts',
+})

package/dist/adapter.js

@@ -0,0 +1,154 @@
+import {
+  CONTRACT_VERSION,
+  READY,
+  defineAdapterModule,
+  notReady,
+  searchOk,
+  stripTrailingSlashes,
+  toOutcomeFailure
+} from "@open-mercato/web-research";
+import { z } from "zod";
+const SEARCH_TYPES = ["instant", "fast", "auto", "deep-lite", "deep", "deep-reasoning"];
+const exaOptionsSchema = z.object({
+  apiKey: z.string().min(1).optional(),
+  baseUrl: z.url().optional(),
+  searchType: z.enum(SEARCH_TYPES).optional(),
+  /** Return page text inline, sparing the engine a follow-up fetch per result. */
+  includeContent: z.boolean().optional(),
+  /** Cap on inline text per result; Exa's own ceiling is 10000. */
+  maxCharacters: z.number().int().min(200).max(1e4).optional(),
+  timeoutMs: z.number().int().min(1e3).max(12e4).optional()
+});
+const DEFAULT_BASE_URL = "https://api.exa.ai";
+const DEFAULT_TIMEOUT_MS = 2e4;
+const DEFAULT_MAX_CHARACTERS = 4e3;
+const responseSchema = z.object({
+  results: z.array(
+    z.object({
+      url: z.string().nullish(),
+      title: z.string().nullish(),
+      text: z.string().nullish(),
+      highlights: z.array(z.string()).nullish(),
+      summary: z.string().nullish(),
+      publishedDate: z.string().nullish(),
+      score: z.number().nullish()
+    })
+  ).nullish(),
+  costDollars: z.object({ total: z.number().nullish() }).nullish()
+});
+const FRESHNESS_DAYS = {
+  day: 1,
+  week: 7,
+  month: 31,
+  year: 365
+};
+function publishedAfter(request, now) {
+  const days = request.freshness ? FRESHNESS_DAYS[request.freshness] : void 0;
+  if (days === void 0) return null;
+  return new Date(now - days * 864e5).toISOString();
+}
+function parseJson(body) {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return null;
+  }
+}
+function createExaAdapter(options) {
+  const apiKey = options.apiKey?.trim() ?? "";
+  const baseUrl = stripTrailingSlashes(options.baseUrl ?? DEFAULT_BASE_URL);
+  const searchType = options.searchType ?? "auto";
+  const includeContent = options.includeContent ?? false;
+  const maxCharacters = options.maxCharacters ?? DEFAULT_MAX_CHARACTERS;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  return {
+    id: "exa",
+    kind: "api",
+    capabilities: {
+      search: true,
+      fetch: false,
+      snippets: true,
+      content: includeContent,
+      freshness: true,
+      siteFilter: true,
+      cost: "metered"
+    },
+    /** `free` — inspects the configured key. */
+    probeCost: "free",
+    readiness: () => apiKey.length > 0 ? READY : notReady("Exa API key is not set"),
+    async search(request, context) {
+      if (apiKey.length === 0) return { status: "unavailable", reason: "Exa API key is not set" };
+      try {
+        const startPublishedDate = publishedAfter(request, Date.now());
+        const response = await context.http.request(`${baseUrl}/search`, {
+          method: "POST",
+          headers: { "x-api-key": apiKey, "content-type": "application/json" },
+          body: JSON.stringify({
+            query: request.query,
+            type: searchType,
+            numResults: request.limit,
+            // Native domain filtering rather than folding `site:` into the query:
+            // Exa's index is embeddings-based, so an operator directive inside the
+            // query text competes with the semantics instead of constraining them.
+            ...request.site ? { includeDomains: [request.site] } : {},
+            ...startPublishedDate ? { startPublishedDate } : {},
+            contents: {
+              highlights: true,
+              ...includeContent ? { text: { maxCharacters } } : {}
+            }
+          }),
+          accept: ["application/json"],
+          timeoutMs,
+          signal: context.signal
+        });
+        const parsed = responseSchema.safeParse(parseJson(response.body));
+        if (!parsed.success) {
+          return { status: "error", reason: "Exa returned an unrecognized response shape", retriable: false };
+        }
+        const results = [];
+        for (const item of parsed.data.results ?? []) {
+          if (!item.url) continue;
+          const snippet = item.highlights?.filter(Boolean).join(" \u2026 ") || item.summary || null;
+          results.push({
+            url: item.url,
+            title: item.title ?? null,
+            snippet,
+            content: item.text ?? null,
+            publishedAt: item.publishedDate ?? null,
+            score: item.score ?? null
+          });
+          if (results.length >= request.limit) break;
+        }
+        const cost = parsed.data.costDollars?.total;
+        context.report(
+          "ok",
+          `Exa returned ${results.length} result(s)${typeof cost === "number" ? ` for $${cost.toFixed(4)}` : ""}`,
+          { resultCount: results.length }
+        );
+        return searchOk(results);
+      } catch (error) {
+        return toOutcomeFailure(error);
+      }
+    },
+    /**
+     * Deliberately configuration-only: Exa bills per search, and this runs for
+     * every installed adapter whenever an operator opens the settings page.
+     */
+    async healthCheck() {
+      return apiKey.length > 0 ? { ok: true, detail: `key set; ${searchType} mode` } : { ok: false, detail: "Exa API key is not set" };
+    }
+  };
+}
+const exaAdapterModule = defineAdapterModule({
+  id: "exa",
+  kind: "api",
+  contractVersion: CONTRACT_VERSION,
+  optionsSchema: exaOptionsSchema,
+  createAdapter: createExaAdapter
+});
+export {
+  createExaAdapter,
+  exaAdapterModule,
+  exaOptionsSchema
+};
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/adapter.ts"],
+  "sourcesContent": ["import {\n  CONTRACT_VERSION,\n  READY,\n  defineAdapterModule,\n  notReady,\n  searchOk,\n  stripTrailingSlashes,\n  toOutcomeFailure,\n  type RawResult,\n  type SearchAdapter,\n  type SearchOutcome,\n  type SearchRequest,\n} from '@open-mercato/web-research'\nimport { z } from 'zod'\n\n/**\n * Exa's retrieval modes, cheapest first. `auto` lets Exa pick between its\n * embeddings index and keyword search, which is the right default for a general\n * agent; the `deep*` modes run an agentic loop and cost several times more per\n * call, so choosing one is deliberate.\n */\nconst SEARCH_TYPES = ['instant', 'fast', 'auto', 'deep-lite', 'deep', 'deep-reasoning'] as const\n\nexport const exaOptionsSchema = z.object({\n  apiKey: z.string().min(1).optional(),\n  baseUrl: z.url().optional(),\n  searchType: z.enum(SEARCH_TYPES).optional(),\n  /** Return page text inline, sparing the engine a follow-up fetch per result. */\n  includeContent: z.boolean().optional(),\n  /** Cap on inline text per result; Exa's own ceiling is 10000. */\n  maxCharacters: z.number().int().min(200).max(10_000).optional(),\n  timeoutMs: z.number().int().min(1000).max(120_000).optional(),\n})\n\nexport type ExaOptions = z.infer<typeof exaOptionsSchema>\n\nconst DEFAULT_BASE_URL = 'https://api.exa.ai'\nconst DEFAULT_TIMEOUT_MS = 20_000\nconst DEFAULT_MAX_CHARACTERS = 4_000\n\nconst responseSchema = z.object({\n  results: z\n    .array(\n      z.object({\n        url: z.string().nullish(),\n        title: z.string().nullish(),\n        text: z.string().nullish(),\n        highlights: z.array(z.string()).nullish(),\n        summary: z.string().nullish(),\n        publishedDate: z.string().nullish(),\n        score: z.number().nullish(),\n      }),\n    )\n    .nullish(),\n  costDollars: z.object({ total: z.number().nullish() }).nullish(),\n})\n\nconst FRESHNESS_DAYS: Readonly<Record<string, number>> = {\n  day: 1,\n  week: 7,\n  month: 31,\n  year: 365,\n}\n\n/** Exa filters by publication date natively, which beats a `site:`-style hint. */\nfunction publishedAfter(request: SearchRequest, now: number): string | null {\n  const days = request.freshness ? FRESHNESS_DAYS[request.freshness] : undefined\n  if (days === undefined) return null\n  return new Date(now - days * 86_400_000).toISOString()\n}\n\nfunction parseJson(body: string): unknown {\n  try {\n    return JSON.parse(body)\n  } catch {\n    return null\n  }\n}\n\nexport function createExaAdapter(options: ExaOptions): SearchAdapter {\n  const apiKey = options.apiKey?.trim() ?? ''\n  const baseUrl = stripTrailingSlashes(options.baseUrl ?? DEFAULT_BASE_URL)\n  const searchType = options.searchType ?? 'auto'\n  const includeContent = options.includeContent ?? false\n  const maxCharacters = options.maxCharacters ?? DEFAULT_MAX_CHARACTERS\n  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS\n\n  return {\n    id: 'exa',\n    kind: 'api',\n    capabilities: {\n      search: true,\n      fetch: false,\n      snippets: true,\n      content: includeContent,\n      freshness: true,\n      siteFilter: true,\n      cost: 'metered',\n    },\n    /** `free` \u2014 inspects the configured key. */\n    probeCost: 'free' as const,\n    readiness: () => (apiKey.length > 0 ? READY : notReady('Exa API key is not set')),\n\n    async search(request, context): Promise<SearchOutcome> {\n      if (apiKey.length === 0) return { status: 'unavailable', reason: 'Exa API key is not set' }\n      try {\n        const startPublishedDate = publishedAfter(request, Date.now())\n        const response = await context.http.request(`${baseUrl}/search`, {\n          method: 'POST',\n          headers: { 'x-api-key': apiKey, 'content-type': 'application/json' },\n          body: JSON.stringify({\n            query: request.query,\n            type: searchType,\n            numResults: request.limit,\n            // Native domain filtering rather than folding `site:` into the query:\n            // Exa's index is embeddings-based, so an operator directive inside the\n            // query text competes with the semantics instead of constraining them.\n            ...(request.site ? { includeDomains: [request.site] } : {}),\n            ...(startPublishedDate ? { startPublishedDate } : {}),\n            contents: {\n              highlights: true,\n              ...(includeContent ? { text: { maxCharacters } } : {}),\n            },\n          }),\n          accept: ['application/json'],\n          timeoutMs,\n          signal: context.signal,\n        })\n\n        const parsed = responseSchema.safeParse(parseJson(response.body))\n        if (!parsed.success) {\n          return { status: 'error', reason: 'Exa returned an unrecognized response shape', retriable: false }\n        }\n\n        const results: RawResult[] = []\n        for (const item of parsed.data.results ?? []) {\n          if (!item.url) continue\n          // Highlights are the passages Exa judged most relevant, so they make a\n          // better snippet than the head of the page text.\n          const snippet = item.highlights?.filter(Boolean).join(' \u2026 ') || item.summary || null\n          results.push({\n            url: item.url,\n            title: item.title ?? null,\n            snippet,\n            content: item.text ?? null,\n            publishedAt: item.publishedDate ?? null,\n            score: item.score ?? null,\n          })\n          if (results.length >= request.limit) break\n        }\n\n        // Exa prices per call and reports it, so the operator can see what a\n        // search actually cost instead of inferring it from an invoice.\n        const cost = parsed.data.costDollars?.total\n        context.report(\n          'ok',\n          `Exa returned ${results.length} result(s)${typeof cost === 'number' ? ` for $${cost.toFixed(4)}` : ''}`,\n          { resultCount: results.length },\n        )\n        return searchOk(results)\n      } catch (error) {\n        return toOutcomeFailure(error)\n      }\n    },\n\n    /**\n     * Deliberately configuration-only: Exa bills per search, and this runs for\n     * every installed adapter whenever an operator opens the settings page.\n     */\n    async healthCheck() {\n      return apiKey.length > 0\n        ? { ok: true, detail: `key set; ${searchType} mode` }\n        : { ok: false, detail: 'Exa API key is not set' }\n    },\n  }\n}\n\nexport const exaAdapterModule = defineAdapterModule({\n  id: 'exa',\n  kind: 'api',\n  contractVersion: CONTRACT_VERSION,\n  optionsSchema: exaOptionsSchema,\n  createAdapter: createExaAdapter,\n})\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/index.js

@@ -0,0 +1,9 @@
+import { createExaAdapter, exaAdapterModule, exaOptionsSchema } from "./adapter.js";
+import { exaAdapterModule as exaAdapterModule2 } from "./adapter.js";
+export {
+  createExaAdapter,
+  exaAdapterModule2 as default,
+  exaAdapterModule,
+  exaOptionsSchema
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["export { createExaAdapter, exaAdapterModule, exaOptionsSchema, type ExaOptions } from './adapter'\n\nexport { exaAdapterModule as default } from './adapter'\n"],
+  "mappings": "AAAA,SAAS,kBAAkB,kBAAkB,wBAAyC;AAEtF,SAA6B,oBAApBA,yBAAmC;",
+  "names": ["exaAdapterModule"]
+}

package/jest.config.cjs

@@ -0,0 +1,28 @@
+/** @type {import('jest').Config} */
+const base = require('../../jest.config.base.cjs')
+
+module.exports = {
+  ...base,
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  watchman: false,
+  rootDir: '.',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
+  moduleNameMapper: {
+    '^@open-mercato/web-research/(.*)$': '<rootDir>/../web-research/src/$1',
+    '^@open-mercato/web-research$': '<rootDir>/../web-research/src/index.ts',
+  },
+  transform: {
+    '^.+\\.(t|j)sx?$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          rootDir: '.',
+          ignoreDeprecations: '6.0',
+        },
+      },
+    ],
+  },
+  testMatch: ['<rootDir>/src/**/__tests__/**/*.test.(ts|tsx)'],
+  passWithNoTests: true,
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@open-mercato/web-research-exa",
+  "version": "0.7.1-develop.7194.1.ab4fc81f82",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "openMercato": {
+    "webResearchAdapter": {
+      "id": "exa"
+    }
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "watch": "node watch.mjs",
+    "test": "jest --config jest.config.cjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./*.ts": {
+      "types": "./src/*.ts",
+      "default": "./dist/*.js"
+    },
+    "./*": {
+      "types": [
+        "./src/*.ts"
+      ],
+      "default": "./dist/*.js"
+    }
+  },
+  "peerDependencies": {
+    "@open-mercato/web-research": "^0.6.0"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@open-mercato/web-research": "0.7.1-develop.7194.1.ab4fc81f82",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.0.1",
+    "esbuild": "^0.28.1",
+    "glob": "^13.0.6",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-mercato/open-mercato",
+    "directory": "packages/web-research-exa"
+  },
+  "stableVersion": "0.7.0"
+}

package/src/__tests__/exa.test.ts

@@ -0,0 +1,149 @@
+import { createStubHttpClient, createTestContext, describeAdapterContract } from '@open-mercato/web-research/testing'
+import { describeOptionsSchema } from '@open-mercato/web-research'
+import { createExaAdapter, exaAdapterModule } from '../adapter'
+
+const BODY = JSON.stringify({
+  results: [
+    {
+      url: 'https://a.com/1',
+      title: 'Alpha',
+      highlights: ['first passage', 'second passage'],
+      text: 'Full alpha page text',
+      publishedDate: '2026-05-01T00:00:00.000Z',
+      score: 0.9,
+    },
+    { url: 'https://b.com/2', title: 'Beta', summary: 'Beta summary' },
+    { title: 'No url at all' },
+  ],
+  costDollars: { total: 0.007 },
+})
+
+type SentRequest = { headers?: Record<string, string>; body?: Record<string, unknown> }
+
+function recordingClient(body = BODY) {
+  const sent: SentRequest[] = []
+  const http = createStubHttpClient((_url, init) => {
+    sent.push({
+      headers: init?.headers as Record<string, string>,
+      body: init?.body ? (JSON.parse(init.body) as Record<string, unknown>) : undefined,
+    })
+    return { body }
+  })
+  return { http, sent }
+}
+
+describe('exa adapter', () => {
+  it('is unavailable without a key and makes no call', async () => {
+    const { http } = recordingClient()
+    const outcome = await createExaAdapter({}).search({ query: 'x', limit: 5 }, createTestContext({ http }))
+    expect(outcome).toMatchObject({ status: 'unavailable' })
+    expect(http.calls).toHaveLength(0)
+  })
+
+  it('maps results and prefers highlights as the snippet', async () => {
+    // Highlights are the passages Exa judged relevant; the head of the page text
+    // is what every other source already gives us.
+    const { http } = recordingClient()
+    const outcome = await createExaAdapter({ apiKey: 'k' }).search(
+      { query: 'x', limit: 5 },
+      createTestContext({ http }),
+    )
+    expect(outcome.status).toBe('ok')
+    if (outcome.status !== 'ok') return
+    expect(outcome.results[0]).toMatchObject({
+      url: 'https://a.com/1',
+      snippet: 'first passage … second passage',
+      publishedAt: '2026-05-01T00:00:00.000Z',
+      score: 0.9,
+    })
+    expect(outcome.results[1]?.snippet).toBe('Beta summary')
+  })
+
+  it('drops a result with no url rather than emitting a broken citation', async () => {
+    const { http } = recordingClient()
+    const outcome = await createExaAdapter({ apiKey: 'k' }).search(
+      { query: 'x', limit: 10 },
+      createTestContext({ http }),
+    )
+    if (outcome.status !== 'ok') throw new Error('expected ok')
+    expect(outcome.results).toHaveLength(2)
+  })
+
+  it('sends the key in x-api-key and respects the limit', async () => {
+    const { http, sent } = recordingClient()
+    await createExaAdapter({ apiKey: 'secret' }).search({ query: 'q', limit: 3 }, createTestContext({ http }))
+    expect(sent[0]?.headers?.['x-api-key']).toBe('secret')
+    expect(sent[0]?.body?.numResults).toBe(3)
+  })
+
+  it('filters by domain natively instead of folding site: into the query', async () => {
+    // The index is embeddings-based, so an operator directive inside the query
+    // text competes with the semantics rather than constraining them.
+    const { http, sent } = recordingClient()
+    await createExaAdapter({ apiKey: 'k' }).search(
+      { query: 'pricing', limit: 5, site: 'example.com' },
+      createTestContext({ http }),
+    )
+    expect(sent[0]?.body?.includeDomains).toEqual(['example.com'])
+    expect(sent[0]?.body?.query).toBe('pricing')
+  })
+
+  it('turns a freshness window into a published-after bound', async () => {
+    const { http, sent } = recordingClient()
+    await createExaAdapter({ apiKey: 'k' }).search(
+      { query: 'q', limit: 5, freshness: 'week' },
+      createTestContext({ http }),
+    )
+    const bound = Date.parse(sent[0]?.body?.startPublishedDate as string)
+    const ageDays = (Date.now() - bound) / 86_400_000
+    expect(ageDays).toBeGreaterThan(6.5)
+    expect(ageDays).toBeLessThan(7.5)
+  })
+
+  it('asks for page text only when content is enabled', async () => {
+    const { http: lean, sent: leanSent } = recordingClient()
+    await createExaAdapter({ apiKey: 'k' }).search({ query: 'q', limit: 5 }, createTestContext({ http: lean }))
+    expect((leanSent[0]?.body?.contents as Record<string, unknown>).text).toBeUndefined()
+
+    const { http: full, sent: fullSent } = recordingClient()
+    const adapter = createExaAdapter({ apiKey: 'k', includeContent: true, maxCharacters: 1234 })
+    const outcome = await adapter.search({ query: 'q', limit: 5 }, createTestContext({ http: full }))
+    expect((fullSent[0]?.body?.contents as Record<string, { maxCharacters: number }>).text.maxCharacters).toBe(1234)
+    expect(adapter.capabilities.content).toBe(true)
+    if (outcome.status !== 'ok') throw new Error('expected ok')
+    expect(outcome.results[0]?.content).toBe('Full alpha page text')
+  })
+
+  it('reports a malformed payload as an error rather than crashing', async () => {
+    const http = createStubHttpClient(() => ({ body: 'not json at all' }))
+    const outcome = await createExaAdapter({ apiKey: 'k' }).search(
+      { query: 'q', limit: 5 },
+      createTestContext({ http }),
+    )
+    expect(outcome).toMatchObject({ status: 'error', retriable: false })
+  })
+
+  it('answers a health check without spending a search', async () => {
+    // This runs for every installed adapter whenever the settings page is opened,
+    // and Exa bills per call.
+    const { http } = recordingClient()
+    const health = await createExaAdapter({ apiKey: 'k' }).healthCheck?.(createTestContext({ http }))
+    expect(health?.ok).toBe(true)
+    expect(http.calls).toHaveLength(0)
+  })
+
+  it('names its credential so the settings form masks it', async () => {
+    const apiKeyField = describeOptionsSchema(exaAdapterModule).find((field) => field.name === 'apiKey')
+    expect(apiKeyField?.secret).toBe(true)
+  })
+})
+
+describeAdapterContract(
+  exaAdapterModule,
+  {
+    unconfiguredOptions: {},
+    configuredOptions: { apiKey: 'test-key' },
+    context: () => createTestContext({ http: createStubHttpClient(() => ({ body: BODY })) }),
+  },
+  { describe, it, expect: expect as never },
+)

package/src/adapter.ts

@@ -0,0 +1,184 @@
+import {
+  CONTRACT_VERSION,
+  READY,
+  defineAdapterModule,
+  notReady,
+  searchOk,
+  stripTrailingSlashes,
+  toOutcomeFailure,
+  type RawResult,
+  type SearchAdapter,
+  type SearchOutcome,
+  type SearchRequest,
+} from '@open-mercato/web-research'
+import { z } from 'zod'
+
+/**
+ * Exa's retrieval modes, cheapest first. `auto` lets Exa pick between its
+ * embeddings index and keyword search, which is the right default for a general
+ * agent; the `deep*` modes run an agentic loop and cost several times more per
+ * call, so choosing one is deliberate.
+ */
+const SEARCH_TYPES = ['instant', 'fast', 'auto', 'deep-lite', 'deep', 'deep-reasoning'] as const
+
+export const exaOptionsSchema = z.object({
+  apiKey: z.string().min(1).optional(),
+  baseUrl: z.url().optional(),
+  searchType: z.enum(SEARCH_TYPES).optional(),
+  /** Return page text inline, sparing the engine a follow-up fetch per result. */
+  includeContent: z.boolean().optional(),
+  /** Cap on inline text per result; Exa's own ceiling is 10000. */
+  maxCharacters: z.number().int().min(200).max(10_000).optional(),
+  timeoutMs: z.number().int().min(1000).max(120_000).optional(),
+})
+
+export type ExaOptions = z.infer<typeof exaOptionsSchema>
+
+const DEFAULT_BASE_URL = 'https://api.exa.ai'
+const DEFAULT_TIMEOUT_MS = 20_000
+const DEFAULT_MAX_CHARACTERS = 4_000
+
+const responseSchema = z.object({
+  results: z
+    .array(
+      z.object({
+        url: z.string().nullish(),
+        title: z.string().nullish(),
+        text: z.string().nullish(),
+        highlights: z.array(z.string()).nullish(),
+        summary: z.string().nullish(),
+        publishedDate: z.string().nullish(),
+        score: z.number().nullish(),
+      }),
+    )
+    .nullish(),
+  costDollars: z.object({ total: z.number().nullish() }).nullish(),
+})
+
+const FRESHNESS_DAYS: Readonly<Record<string, number>> = {
+  day: 1,
+  week: 7,
+  month: 31,
+  year: 365,
+}
+
+/** Exa filters by publication date natively, which beats a `site:`-style hint. */
+function publishedAfter(request: SearchRequest, now: number): string | null {
+  const days = request.freshness ? FRESHNESS_DAYS[request.freshness] : undefined
+  if (days === undefined) return null
+  return new Date(now - days * 86_400_000).toISOString()
+}
+
+function parseJson(body: string): unknown {
+  try {
+    return JSON.parse(body)
+  } catch {
+    return null
+  }
+}
+
+export function createExaAdapter(options: ExaOptions): SearchAdapter {
+  const apiKey = options.apiKey?.trim() ?? ''
+  const baseUrl = stripTrailingSlashes(options.baseUrl ?? DEFAULT_BASE_URL)
+  const searchType = options.searchType ?? 'auto'
+  const includeContent = options.includeContent ?? false
+  const maxCharacters = options.maxCharacters ?? DEFAULT_MAX_CHARACTERS
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS
+
+  return {
+    id: 'exa',
+    kind: 'api',
+    capabilities: {
+      search: true,
+      fetch: false,
+      snippets: true,
+      content: includeContent,
+      freshness: true,
+      siteFilter: true,
+      cost: 'metered',
+    },
+    /** `free` — inspects the configured key. */
+    probeCost: 'free' as const,
+    readiness: () => (apiKey.length > 0 ? READY : notReady('Exa API key is not set')),
+
+    async search(request, context): Promise<SearchOutcome> {
+      if (apiKey.length === 0) return { status: 'unavailable', reason: 'Exa API key is not set' }
+      try {
+        const startPublishedDate = publishedAfter(request, Date.now())
+        const response = await context.http.request(`${baseUrl}/search`, {
+          method: 'POST',
+          headers: { 'x-api-key': apiKey, 'content-type': 'application/json' },
+          body: JSON.stringify({
+            query: request.query,
+            type: searchType,
+            numResults: request.limit,
+            // Native domain filtering rather than folding `site:` into the query:
+            // Exa's index is embeddings-based, so an operator directive inside the
+            // query text competes with the semantics instead of constraining them.
+            ...(request.site ? { includeDomains: [request.site] } : {}),
+            ...(startPublishedDate ? { startPublishedDate } : {}),
+            contents: {
+              highlights: true,
+              ...(includeContent ? { text: { maxCharacters } } : {}),
+            },
+          }),
+          accept: ['application/json'],
+          timeoutMs,
+          signal: context.signal,
+        })
+
+        const parsed = responseSchema.safeParse(parseJson(response.body))
+        if (!parsed.success) {
+          return { status: 'error', reason: 'Exa returned an unrecognized response shape', retriable: false }
+        }
+
+        const results: RawResult[] = []
+        for (const item of parsed.data.results ?? []) {
+          if (!item.url) continue
+          // Highlights are the passages Exa judged most relevant, so they make a
+          // better snippet than the head of the page text.
+          const snippet = item.highlights?.filter(Boolean).join(' … ') || item.summary || null
+          results.push({
+            url: item.url,
+            title: item.title ?? null,
+            snippet,
+            content: item.text ?? null,
+            publishedAt: item.publishedDate ?? null,
+            score: item.score ?? null,
+          })
+          if (results.length >= request.limit) break
+        }
+
+        // Exa prices per call and reports it, so the operator can see what a
+        // search actually cost instead of inferring it from an invoice.
+        const cost = parsed.data.costDollars?.total
+        context.report(
+          'ok',
+          `Exa returned ${results.length} result(s)${typeof cost === 'number' ? ` for $${cost.toFixed(4)}` : ''}`,
+          { resultCount: results.length },
+        )
+        return searchOk(results)
+      } catch (error) {
+        return toOutcomeFailure(error)
+      }
+    },
+
+    /**
+     * Deliberately configuration-only: Exa bills per search, and this runs for
+     * every installed adapter whenever an operator opens the settings page.
+     */
+    async healthCheck() {
+      return apiKey.length > 0
+        ? { ok: true, detail: `key set; ${searchType} mode` }
+        : { ok: false, detail: 'Exa API key is not set' }
+    },
+  }
+}
+
+export const exaAdapterModule = defineAdapterModule({
+  id: 'exa',
+  kind: 'api',
+  contractVersion: CONTRACT_VERSION,
+  optionsSchema: exaOptionsSchema,
+  createAdapter: createExaAdapter,
+})

package/src/index.ts

@@ -0,0 +1,3 @@
+export { createExaAdapter, exaAdapterModule, exaOptionsSchema, type ExaOptions } from './adapter'
+
+export { exaAdapterModule as default } from './adapter'

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/__tests__/**"]
+}

package/watch.mjs

@@ -0,0 +1,7 @@
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { watch } from '../../scripts/watch.mjs'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+watch(__dirname)