@superagnt/exa-search 2.0.2

package/README.md

@@ -0,0 +1,79 @@
+# Exa integration for OpenClaw — superagnt plugin
+
+Connect your Exa AI account to superagnt to power agents with neural web search, parsed page contents, similar-page discovery, and agentic Q&A — all through a unified API. Neural web search, parsed page contents, similar-URL discovery, and agentic Q&A — wired into your agents through a single superagnt API key.
+
+## Install
+
+```bash
+openclaw plugins install @superagnt/exa-search
+```
+
+This package is the official **OpenClaw** plugin for the **Exa** integration via [superagnt](https://superagnt.com). Pair it with the [documentation](https://superagnt.com) and your superagnt API key.
+
+## Live MCP mode (recommended)
+
+Set a workspace MCP token and the plugin upgrades itself at load: it fetches
+the live tool list from the scoped MCP endpoint and proxies calls through it —
+the tool surface then grows with `agnt_tools_enable`, no plugin update needed.
+
+```bash
+export SUPERAGNT_MCP_TOKEN=...   # from the MCP server card in the dashboard
+```
+
+Without the token the plugin uses its built-in toolset with your
+`SUPERAGNT_API_KEY` — no behavior change from previous versions.
+
+## Overview
+
+OpenClaw plugin for Exa — run neural web search, fetch parsed contents, find similar URLs, and get agentic answers through your superagnt API key.
+
+### Highlights
+
+- Neural + keyword search — semantic web search with optional category filters and date ranges
+- Parsed contents — return text, highlights, and LLM-generated summaries for any URL
+- Find similar — surface semantically related pages from a seed URL
+- Agentic answers — Q&A over the live web with cited sources
+- Domain + published-date filters — scope results to trusted sources or recent news
+- Livecrawl control — force fresh fetches or rely on Exa's cache per request
+- Subpage expansion — pull nested content for deeper research workflows
+
+### Example use cases
+
+- Give agents real-time web knowledge beyond their training cutoff
+- Research a company, competitor, or topic with cited sources and summaries
+- Build retrieval-augmented generation pipelines grounded in the live web
+- Pull clean page text for summarization, extraction, or ingest into a vector store
+- Monitor news and blog posts filtered to trusted domains and date ranges
+- Run agentic Q&A that returns answers plus the sources Exa used
+
+## Prerequisites
+
+1. An **superagnt API key** — create and manage keys in the [superagnt dashboard](https://app.superagnt.com/dashboard).
+2. A connected **Exa** account — configure in the [integrations dashboard](https://app.superagnt.com/dashboard/connections).
+
+## Authentication
+
+Set `SUPERAGNT_API_KEY` in your environment, or complete browser login when the gateway prompts you.
+
+## API coverage
+
+| | |
+| --- | --- |
+| **Integration** | `exa` |
+| **REST base** | `https://api.superagnt.com/v1/connections/exa` |
+| **OpenAPI operations** | 4 |
+| **OpenClaw tools** | 4 |
+
+## Documentation
+
+- [Documentation](https://superagnt.com) — getting started and concepts
+- [Connection guide (Exa)](https://superagnt.com/connections/exa) — setup and endpoints
+- [Dashboard](https://app.superagnt.com/dashboard) — API keys and usage
+
+## Related
+
+- **Skill (curl-oriented):** `clawhub install exa-search` on [ClawHub](https://clawhub.ai/superagnt/skills/exa-search)
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,546 @@
+/**
+ * Exa Integration — OpenClaw plugin
+ * Auto-generated by @superagnt/clawhub. Do not edit by hand.
+ */
+
+import { homedir as _homedir } from 'node:os'
+import { join as _join } from 'node:path'
+import { existsSync as _existsSync, readFileSync as _readFileSync } from 'node:fs'
+
+const BASE_URL = 'https://api.superagnt.com/v1/connections/exa'
+
+
+// ── Auth Module (inlined) ────────────────────────────────────────────────────
+
+function getConfigPath() {
+  return _join(_homedir(), '.superagnt', 'config.json')
+}
+
+function readAgntConfig() {
+  const configFile = getConfigPath()
+  if (!_existsSync(configFile)) return null
+  try {
+    return JSON.parse(_readFileSync(configFile, 'utf-8'))
+  } catch {
+    return null
+  }
+}
+
+// ── End Auth Module ──────────────────────────────────────────────────────────
+
+
+// ── CLI Module (inlined) ─────────────────────────────────────────────────────
+
+function maskApiKey(key) {
+  if (!key || typeof key !== 'string') return '(none)'
+  const k = key.trim()
+  if (k.length <= 8) return k.slice(0, 2) + '…'
+  return k.slice(0, 6) + '…' + k.slice(-4)
+}
+
+function registerAgntCli(api) {
+  api.registerCli(
+    ({ program }) => {
+      const cmd = program
+        .command('superagnt')
+        .description('superagnt social data API (status, doctor)')
+
+      cmd
+        .command('status')
+        .description('Show whether an API key is configured (masked)')
+        .action(async () => {
+          const cfg = readAgntConfig()
+          const key = cfg?.apiKey
+
+          console.log('\nsuperagnt status\n')
+          if (!key) {
+            console.log('  API key:     not configured')
+            console.log('  Workspace:   —')
+            console.log('\n  Get your API key at: https://app.superagnt.com/dashboard\n')
+            return
+          }
+          console.log('  API key:     ' + maskApiKey(key) + ' (from ~/.superagnt/config.json)')
+          console.log('  Workspace:   ' + (cfg?.workspaceId ?? '—'))
+          console.log('')
+        })
+
+      cmd
+        .command('doctor')
+        .description('Check connectivity and validate API key against api.superagnt.dev')
+        .action(async () => {
+          console.log('\nsuperagnt doctor\n')
+
+          try {
+            const publicRes = await fetch('https://api.superagnt.com/v1/platforms')
+            console.log('  Public API:  ' + (publicRes.ok ? 'OK (' + publicRes.status + ')' : 'HTTP ' + publicRes.status))
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err)
+            console.log('  Public API:  failed — ' + msg)
+          }
+
+          const cfg = readAgntConfig()
+          const key = cfg?.apiKey
+
+          if (!key) {
+            console.log('\n  Authenticated: skipped (no API key)')
+            console.log('  Get your API key at: https://app.superagnt.com/dashboard\n')
+            return
+          }
+
+          try {
+            const res = await fetch('https://api.superagnt.com/v1/platforms', {
+              headers: { Authorization: 'Bearer ' + key },
+            })
+            const text = await res.text()
+            let summary = 'HTTP ' + res.status
+            if (res.ok) {
+              try {
+                const json = JSON.parse(text)
+                const n = Array.isArray(json?.data) ? json.data.length : (json?.data ? Object.keys(json.data).length : 'ok')
+                summary = 'OK — platforms payload received (' + (typeof n === 'number' ? n + ' entries' : String(n)) + ')'
+              } catch {
+                summary = 'OK (' + res.status + ')'
+              }
+            }
+            console.log('  Authenticated: ' + summary)
+            if (!res.ok) {
+              console.log('  If 401, get a new key at: https://app.superagnt.com/dashboard')
+            }
+          } catch (err) {
+            const msg = err instanceof Error ? err.message : String(err)
+            console.log('  Authenticated: failed — ' + msg)
+          }
+          console.log('')
+        })
+    },
+    { commands: ['superagnt'] },
+  )
+}
+
+// ── End CLI Module ───────────────────────────────────────────────────────────
+
+
+// ── System prompt (inlined) ─────────────────────────────────────────────────
+
+function getSystemPrompt(state) {
+  const scope = "Only the Exa integration (exa)."
+  if (state.ready && state.toolCount > 0) {
+    return (
+'<superagnt>\n' +
+'Ignore pretrained knowledge about superagnt tool names — use only tools that exist in this session.\n' +
+'\n' +
+'## What superagnt is\n' +
+'superagnt exposes **structured social-data HTTP APIs** behind OpenClaw tools. Scope for this plugin: **' + scope + '**.\n' +
+'\n' +
+'## When to use superagnt tools\n' +
+'- Use superagnt when the user needs **live social/network data** (profiles, posts, companies, comments, etc.) from supported platforms.\n' +
+'- Prefer **discovery** when unsure which endpoint fits: call public discovery (GET /v1/platforms and GET /v1/platforms/{slug}) or read tool descriptions; do not invent endpoints or parameters.\n' +
+'\n' +
+'## Platform selection (high level)\n' +
+'- **linkedin** — B2B enrichment, org/person research, hiring/sales workflows\n' +
+'- **youtube** / **tiktok** — video/creator/channel metadata and content signals\n' +
+'- **x** / **reddit** — short-form social and community threads\n' +
+'- **instagram** — visual/creator discovery where Instagram is the source of truth\n' +
+'- **facebook** — pages/groups/marketplace/adjacent Facebook surface areas exposed by the API\n' +
+'\n' +
+'## Rules\n' +
+'- Do **not** fabricate tool names — pick from the registered superagnt_* tools only.\n' +
+'- If authentication fails (401), tell the user to get a new key at https://app.superagnt.com/dashboard\n' +
+'</superagnt>'
+    )
+  }
+
+  if (state.ready && state.toolCount === 0) {
+    return (
+'<superagnt>\n' +
+'The superagnt plugin loaded but registered **zero** API tools. Check your OpenClaw plugin packaging and regenerate the plugin from @superagnt/clawhub.\n' +
+'</superagnt>'
+    )
+  }
+
+  if (state.error) {
+    return (
+'<superagnt>\n' +
+'superagnt plugin diagnostic: ' + state.error + '\n' +
+'Do not pretend superagnt tools exist. Ask the user to fix configuration and restart the gateway.\n' +
+'</superagnt>'
+    )
+  }
+
+  return (
+'<superagnt>\n' +
+'superagnt tools are still loading. If the user asks for social data right now, ask them to wait a moment and retry.\n' +
+'</superagnt>'
+  )
+}
+
+// ── End System prompt ────────────────────────────────────────────────────────
+
+const MCP_URL = 'https://mcp.superagnt.com/mcp'
+
+async function mcpRpc(token, method, params) {
+  const res = await fetch(MCP_URL, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${token}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json, text/event-stream',
+    },
+    body: JSON.stringify({ jsonrpc: '2.0', id: Date.now(), method, params }),
+  })
+  if (!res.ok) throw new Error(`MCP ${method} failed: HTTP ${res.status}`)
+  const data = await res.json()
+  if (data.error) throw new Error(`MCP ${method} error: ${data.error.message}`)
+  return data.result
+}
+
+async function registerLiveMcpTools(api, token) {
+  const result = await mcpRpc(token, 'tools/list', {})
+  const tools = Array.isArray(result?.tools) ? result.tools : []
+  if (tools.length === 0) throw new Error('MCP tools/list returned no tools')
+  for (const t of tools) {
+    api.registerTool({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema,
+      execute: async (input) => {
+        const args = parseToolInput(input)
+        const r = await mcpRpc(token, 'tools/call', { name: t.name, arguments: args })
+        if (r && r.structuredContent !== undefined) return r.structuredContent
+        const text = Array.isArray(r?.content) ? r.content.find((c) => c.type === 'text')?.text : undefined
+        if (text === undefined) return r
+        try { return JSON.parse(text) } catch { return text }
+      },
+    })
+  }
+  return tools.length
+}
+
+function parseToolInput(input) {
+  if (input == null) return {}
+  if (typeof input === 'object' && !Array.isArray(input)) return input
+  if (typeof input === 'string') {
+    const trimmed = input.trim()
+    if (trimmed.startsWith('{')) {
+      try { const parsed = JSON.parse(trimmed); if (typeof parsed === 'object' && parsed && !Array.isArray(parsed)) return parsed } catch {}
+    }
+    throw new Error('Invalid tool input: expected a JSON object with named parameters, got string: ' + trimmed.slice(0, 80))
+  }
+  throw new Error('Invalid tool input: expected a JSON object, got ' + typeof input)
+}
+
+function substitutePathParams(path, source) {
+  if (!source || typeof source !== 'object' || Array.isArray(source)) {
+    return { path, consumed: new Set() }
+  }
+  const consumed = new Set()
+  const next = path.replace(/\{([^/{}]+)\}/g, (_, name) => {
+    const v = source[name]
+    if (v === undefined || v === null || v === '') return `{${name}}`
+    consumed.add(name)
+    return encodeURIComponent(String(v))
+  })
+  return { path: next, consumed }
+}
+
+async function callSuperagnt(apiKey, method, path, query, body) {
+  const params = (query && typeof query === 'object' && !Array.isArray(query)) ? query : body
+  const { path: resolvedPath, consumed } = substitutePathParams(path, params)
+  const url = new URL(`${BASE_URL}${resolvedPath}`)
+  if (query && typeof query === 'object' && !Array.isArray(query)) {
+    for (const [k, v] of Object.entries(query)) {
+      if (consumed.has(k)) continue
+      if (v !== undefined && v !== '') url.searchParams.set(k, String(v))
+    }
+  }
+  const filteredBody = body && typeof body === 'object' && !Array.isArray(body)
+    ? Object.fromEntries(Object.entries(body).filter(([k]) => !consumed.has(k)))
+    : body
+  const res = await fetch(url.toString(), {
+    method,
+    headers: { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+    body: filteredBody ? JSON.stringify(filteredBody) : undefined,
+  })
+  if (res.status === 401) {
+    return { error: 'Invalid or expired API key. Get a new key at https://app.superagnt.com/dashboard' }
+  }
+  return res.json()
+}
+
+export default async function register(api) {
+  const apiKey = api.pluginConfig.apiKey || process.env.SUPERAGNT_API_KEY || readAgntConfig()?.apiKey
+  const mcpToken = api.pluginConfig.mcpToken || process.env.SUPERAGNT_MCP_TOKEN
+
+  function ensureApiKey() {
+    if (apiKey) return apiKey
+    throw new Error(
+      '[exa-search] No API key configured. ' +
+      'Get your key at https://app.superagnt.com/dashboard and either:\n' +
+      '  1. Export it as SUPERAGNT_API_KEY, or\n' +
+      '  2. Add apiKey to your plugin config'
+    )
+  }
+
+  registerAgntCli(api)
+
+  const promptState = { toolCount: 0, error: '', ready: false }
+  api.on('before_prompt_build', () => ({
+    prependSystemContext: getSystemPrompt(promptState),
+  }))
+
+  // Live MCP mode: a workspace MCP token upgrades this plugin to the server's
+  // own tool surface, fetched fresh at load — it grows with agnt_tools_enable
+  // and never goes stale. Any failure falls back to the baked toolset below.
+  if (mcpToken) {
+    try {
+      promptState.toolCount = await registerLiveMcpTools(api, mcpToken)
+      promptState.ready = true
+      return
+    } catch (err) {
+      promptState.error = 'Live MCP connect failed (' + (err && err.message ? err.message : err) + '); using the built-in toolset.'
+    }
+  }
+
+  api.registerTool({
+    name: 'superagnt_connection_exa_search',
+    description: "Search",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "The query string for the search."
+            },
+            "additionalQueries": {
+                "type": "array",
+                "description": "Additional query variations for deep-search variants. Used alongside the main query for more comprehensive results."
+            },
+            "stream": {
+                "type": "boolean",
+                "description": "If true, the response is returned as an SSE stream of OpenAI-compatible chat completion chunks."
+            },
+            "outputSchema": {
+                "type": "object",
+                "description": "JSON schema for synthesized output. When provided, the response includes an output object and output.content matches this schema."
+            },
+            "systemPrompt": {
+                "type": "string",
+                "description": "Instructions that guide synthesized output and, for deep-search variants, search planning."
+            },
+            "type": {
+                "type": "string",
+                "description": "Search strategy. `auto` intelligently combines neural and other search methods; `fast` uses streamlined models; `deep-lite` / `deep` / `deep-reasoning` are synthesized-output modes; `instant` is the lowest-latency mode."
+            },
+            "category": {
+                "type": "string",
+                "description": "A data category to focus on. `people` and `company` support a limited filter set — `startPublishedDate`, `endPublishedDate`, `startCrawlDate`, `endCrawlDate`, and `excludeDomains` are not allowed; `includeDomains` for `people` only accepts LinkedIn domains."
+            },
+            "userLocation": {
+                "type": "string",
+                "description": "Two-letter ISO country code of the user (e.g. `US`)."
+            },
+            "numResults": {
+                "type": "integer",
+                "description": "Number of results to return. Max 100 for `neural` and deep-search variants."
+            },
+            "includeDomains": {
+                "type": "array",
+                "description": "Restrict results to these domains."
+            },
+            "excludeDomains": {
+                "type": "array",
+                "description": "Exclude these domains from results."
+            },
+            "startCrawlDate": {
+                "type": "string",
+                "description": "Only include links crawled after this ISO 8601 date."
+            },
+            "endCrawlDate": {
+                "type": "string",
+                "description": "Only include links crawled before this ISO 8601 date."
+            },
+            "startPublishedDate": {
+                "type": "string",
+                "description": "Only include links with a published date after this ISO 8601 date."
+            },
+            "endPublishedDate": {
+                "type": "string",
+                "description": "Only include links with a published date before this ISO 8601 date."
+            },
+            "moderation": {
+                "type": "boolean",
+                "description": "Enable content moderation to filter unsafe content from results."
+            },
+            "contents": {
+                "type": "object",
+                "description": "Content enrichment options returned alongside search results. See /contents for the full schema."
+            }
+        },
+        "required": [
+            "query"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'POST', '/search', undefined, params)
+    },
+  })
+
+  api.registerTool({
+    name: 'superagnt_connection_exa_getContents',
+    description: "Get contents",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "urls": {
+                "type": "array",
+                "description": "URLs to crawl (backwards compatible with `ids`)."
+            },
+            "ids": {
+                "type": "array",
+                "description": "Document IDs obtained from previous searches."
+            },
+            "text": {
+                "type": "string",
+                "description": "Boolean or advanced text options object. Object form supports `maxCharacters`, `includeHtmlTags`, `verbosity` (`compact` | `standard` | `full`), `includeSections`, `excludeSections` (header | navigation | banner | body | sidebar | footer | metadata)."
+            },
+            "highlights": {
+                "type": "string",
+                "description": "Boolean or advanced highlights object. Object form supports `maxCharacters`, `query`."
+            },
+            "summary": {
+                "type": "object",
+                "description": "LLM-generated summary options."
+            },
+            "livecrawl": {
+                "type": "string",
+                "description": "Deprecated — use `maxAgeHours`."
+            },
+            "livecrawlTimeout": {
+                "type": "integer",
+                "description": "livecrawlTimeout"
+            },
+            "maxAgeHours": {
+                "type": "integer",
+                "description": "Max age of cached content in hours. Positive = livecrawl if older, 0 = always livecrawl, -1 = never livecrawl."
+            },
+            "subpages": {
+                "type": "integer",
+                "description": "subpages"
+            },
+            "subpageTarget": {
+                "type": "string",
+                "description": "String or array of strings."
+            },
+            "extras": {
+                "type": "object",
+                "description": "extras"
+            }
+        },
+        "required": [
+            "urls"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'POST', '/contents', undefined, params)
+    },
+  })
+
+  api.registerTool({
+    name: 'superagnt_connection_exa_findSimilar',
+    description: "Find similar links",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "url": {
+                "type": "string",
+                "description": "The URL to find similar links for."
+            },
+            "numResults": {
+                "type": "integer",
+                "description": "numResults"
+            },
+            "includeDomains": {
+                "type": "array",
+                "description": "includeDomains"
+            },
+            "excludeDomains": {
+                "type": "array",
+                "description": "excludeDomains"
+            },
+            "startCrawlDate": {
+                "type": "string",
+                "description": "startCrawlDate"
+            },
+            "endCrawlDate": {
+                "type": "string",
+                "description": "endCrawlDate"
+            },
+            "startPublishedDate": {
+                "type": "string",
+                "description": "startPublishedDate"
+            },
+            "endPublishedDate": {
+                "type": "string",
+                "description": "endPublishedDate"
+            },
+            "moderation": {
+                "type": "boolean",
+                "description": "moderation"
+            },
+            "contents": {
+                "type": "object",
+                "description": "Content enrichment options. Same shape as in /search and /contents."
+            }
+        },
+        "required": [
+            "url"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'POST', '/findSimilar', undefined, params)
+    },
+  })
+
+  api.registerTool({
+    name: 'superagnt_connection_exa_answer',
+    description: "Generate an answer from search results",
+    inputSchema: {
+        "type": "object",
+        "properties": {
+            "query": {
+                "type": "string",
+                "description": "The question or query to answer."
+            },
+            "stream": {
+                "type": "boolean",
+                "description": "If true, returns an SSE stream."
+            },
+            "text": {
+                "type": "boolean",
+                "description": "If true, citations include full text content of each source."
+            },
+            "outputSchema": {
+                "type": "object",
+                "description": "JSON Schema Draft 7 for structured answers."
+            }
+        },
+        "required": [
+            "query"
+        ]
+    },
+    execute: async (input) => {
+      const key = await ensureApiKey()
+      const params = parseToolInput(input)
+      return callSuperagnt(key, 'POST', '/answer', undefined, params)
+    },
+  })
+
+  promptState.toolCount = 4
+  promptState.ready = true
+}

package/openclaw.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "exa-search",
+  "name": "Exa Integration",
+  "description": "OpenClaw plugin for Exa — run neural web search, fetch parsed contents, find similar URLs, and get agentic answers through your superagnt API key.",
+  "version": "2.0.2",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "apiKey": {
+        "type": "string",
+        "description": "Your superagnt API key. Get one at https://app.superagnt.com/dashboard or store in ~/.superagnt/config.json via CLI login."
+      }
+    },
+    "additionalProperties": false
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@superagnt/exa-search",
+  "version": "2.0.2",
+  "type": "module",
+  "description": "OpenClaw plugin for Exa — run neural web search, fetch parsed contents, find similar URLs, and get agentic answers through your superagnt API key.",
+  "main": "index.js",
+  "license": "MIT",
+  "homepage": "https://superagnt.com/r/npm-exa-search-docs",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "superagnt",
+    "mcp",
+    "exa",
+    "integration",
+    "api",
+    "ai-agent",
+    "exa ai",
+    "neural search",
+    "web search api",
+    "semantic search",
+    "retrieval augmented generation",
+    "rag",
+    "llm search",
+    "agentic search",
+    "find similar",
+    "answer api"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "index.js",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2",
+      "minGatewayVersion": "2026.3.24-beta.2"
+    },
+    "build": {
+      "openclawVersion": "2026.3.24-beta.2",
+      "pluginSdkVersion": "2026.3.24-beta.2"
+    }
+  }
+}