denchclaw 2.4.6 → 2.5.1

package/extensions/exa-search/index.ts

@@ -0,0 +1,363 @@
+import type { AnyAgentTool, OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+export const id = "exa-search";
+
+const DEFAULT_GATEWAY_URL = "https://gateway.merseoriginals.com";
+
+type UnknownRecord = Record<string, unknown>;
+
+function asRecord(value: unknown): UnknownRecord | undefined {
+  return value && typeof value === "object" ? (value as UnknownRecord) : undefined;
+}
+
+function readTrimmedString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function readStringList(value: unknown): string[] | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const items = value
+    .map((item) => readTrimmedString(item))
+    .filter((item): item is string => Boolean(item));
+  return items.length > 0 ? items : undefined;
+}
+
+function resolveGatewayUrl(config: unknown): string {
+  const root = asRecord(config);
+  const pluginEntries = asRecord(asRecord(root?.plugins)?.entries);
+  const gatewayConfig = asRecord(asRecord(pluginEntries?.["dench-ai-gateway"])?.config);
+  return (
+    readTrimmedString(gatewayConfig?.gatewayUrl) ||
+    process.env.DENCH_GATEWAY_URL?.trim() ||
+    DEFAULT_GATEWAY_URL
+  );
+}
+
+function resolveApiKey(config: unknown): string | undefined {
+  const root = asRecord(config);
+  const providers = asRecord(asRecord(asRecord(root?.models)?.providers));
+  const provider = asRecord(providers?.["dench-cloud"]);
+  return (
+    readTrimmedString(provider?.apiKey) ||
+    process.env.DENCH_CLOUD_API_KEY?.trim() ||
+    process.env.DENCH_API_KEY?.trim() ||
+    undefined
+  );
+}
+
+function jsonResult(payload: unknown) {
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(payload, null, 2) }],
+    details: payload,
+  };
+}
+
+const SEARCH_TYPES = [
+  "auto",
+  "neural",
+  "fast",
+  "deep",
+  "deep-reasoning",
+  "instant",
+] as const;
+const SEARCH_CATEGORIES = [
+  "company",
+  "research paper",
+  "news",
+  "personal site",
+  "financial report",
+  "people",
+] as const;
+
+const ExaSearchParameters = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    query: { type: "string", description: "Search query." },
+    searchType: { type: "string", enum: [...SEARCH_TYPES], description: "Exa search type." },
+    category: { type: "string", enum: [...SEARCH_CATEGORIES], description: "Exa search category." },
+    numResults: { type: "number", description: "Maximum number of results." },
+    includeDomains: { type: "array", items: { type: "string" }, description: "Only search these domains." },
+    excludeDomains: { type: "array", items: { type: "string" }, description: "Exclude these domains." },
+    startPublishedDate: { type: "string", description: "ISO date lower bound for published date." },
+    endPublishedDate: { type: "string", description: "ISO date upper bound for published date." },
+    text: { type: "boolean", description: "Include extracted page text." },
+    textMaxCharacters: { type: "number", description: "Maximum characters of extracted text." },
+    highlights: { type: "boolean", description: "Include highlights." },
+    highlightsMaxCharacters: { type: "number", description: "Maximum characters in highlights." },
+    summary: { type: "boolean", description: "Include a summary." },
+    summaryQuery: { type: "string", description: "Summary query prompt to send upstream." },
+  },
+  required: ["query"],
+};
+
+const ExaContentsParameters = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    urls: { type: "array", items: { type: "string" }, description: "URLs to fetch content for." },
+    text: { type: "boolean", description: "Include extracted page text." },
+    textMaxCharacters: { type: "number", description: "Maximum characters of extracted text." },
+    highlights: { type: "boolean", description: "Include highlights." },
+    highlightsMaxCharacters: { type: "number", description: "Maximum characters in highlights." },
+    summary: { type: "boolean", description: "Include a summary." },
+    summaryQuery: { type: "string", description: "Summary query prompt to send upstream." },
+  },
+  required: ["urls"],
+};
+
+const ExaAnswerParameters = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    query: { type: "string", description: "Question to answer." },
+    text: { type: "boolean", description: "Include extra answer text fields." },
+  },
+  required: ["query"],
+};
+
+function buildTextOption(params: Record<string, unknown>) {
+  if (typeof params.textMaxCharacters === "number") {
+    return { maxCharacters: params.textMaxCharacters };
+  }
+  if (params.text === true) {
+    return true;
+  }
+  return undefined;
+}
+
+function buildHighlightsOption(params: Record<string, unknown>) {
+  if (typeof params.highlightsMaxCharacters === "number") {
+    return { maxCharacters: params.highlightsMaxCharacters };
+  }
+  if (params.highlights === true) {
+    return true;
+  }
+  return undefined;
+}
+
+function buildSummaryOption(params: Record<string, unknown>) {
+  const query = readTrimmedString(params.summaryQuery);
+  if (query) {
+    return { query };
+  }
+  if (params.summary === true) {
+    return {};
+  }
+  return undefined;
+}
+
+function buildSearchBody(params: Record<string, unknown>) {
+  const body: Record<string, unknown> = {
+    query: params.query,
+  };
+  const searchType = readTrimmedString(params.searchType);
+  const category = readTrimmedString(params.category);
+  const includeDomains = readStringList(params.includeDomains);
+  const excludeDomains = readStringList(params.excludeDomains);
+  const startPublishedDate = readTrimmedString(params.startPublishedDate);
+  const endPublishedDate = readTrimmedString(params.endPublishedDate);
+  const text = buildTextOption(params);
+  const highlights = buildHighlightsOption(params);
+  const summary = buildSummaryOption(params);
+  const contents: Record<string, unknown> = {};
+
+  if (searchType) {
+    body.type = searchType;
+  }
+  if (category) {
+    body.category = category;
+  }
+  if (typeof params.numResults === "number") {
+    body.numResults = params.numResults;
+  }
+  if (includeDomains) {
+    body.includeDomains = includeDomains;
+  }
+  if (excludeDomains) {
+    body.excludeDomains = excludeDomains;
+  }
+  if (startPublishedDate) {
+    body.startPublishedDate = startPublishedDate;
+  }
+  if (endPublishedDate) {
+    body.endPublishedDate = endPublishedDate;
+  }
+  if (text !== undefined) {
+    contents.text = text;
+  }
+  if (highlights !== undefined) {
+    contents.highlights = highlights;
+  }
+  if (summary !== undefined) {
+    contents.summary = summary;
+  }
+  if (Object.keys(contents).length > 0) {
+    body.contents = contents;
+  }
+
+  return body;
+}
+
+function buildContentsBody(params: Record<string, unknown>) {
+  const urls = readStringList(params.urls);
+  const body: Record<string, unknown> = {
+    urls: urls ?? [],
+  };
+  const text = buildTextOption(params);
+  const highlights = buildHighlightsOption(params);
+  const summary = buildSummaryOption(params);
+
+  if (text !== undefined) {
+    body.text = text;
+  }
+  if (highlights !== undefined) {
+    body.highlights = highlights;
+  }
+  if (summary !== undefined) {
+    body.summary = summary;
+  }
+
+  return body;
+}
+
+async function parseResponse(response: Response) {
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    return response.json();
+  }
+  return response.text();
+}
+
+async function postJson(params: {
+  gatewayUrl: string;
+  apiKey: string;
+  path: string;
+  body: Record<string, unknown>;
+}) {
+  const response = await fetch(`${params.gatewayUrl}${params.path}`, {
+    method: "POST",
+    headers: {
+      "content-type": "application/json",
+      authorization: `Bearer ${params.apiKey}`,
+    },
+    body: JSON.stringify(params.body),
+  });
+
+  if (!response.ok) {
+    const detail = await parseResponse(response).catch(() => "");
+    return jsonResult({
+      error: `Search request failed (HTTP ${response.status}).`,
+      detail: detail || undefined,
+    });
+  }
+
+  return jsonResult(await parseResponse(response));
+}
+
+function createExaSearchTool(gatewayUrl: string, apiKey: string): AnyAgentTool {
+  return {
+    name: "exa_search",
+    label: "Exa Search",
+    description:
+      "Search the web through Exa via the Dench Cloud gateway, with optional text extraction, highlights, and summary generation.",
+    parameters: ExaSearchParameters,
+    execute: async (_toolCallId: string, params: Record<string, unknown>) => {
+      try {
+        return await postJson({
+          gatewayUrl,
+          apiKey,
+          path: "/v1/search",
+          body: buildSearchBody(params),
+        });
+      } catch (err) {
+        return jsonResult({
+          error: "Search request failed.",
+          detail: err instanceof Error ? err.message : String(err),
+        });
+      }
+    },
+  } as AnyAgentTool;
+}
+
+function createExaContentsTool(gatewayUrl: string, apiKey: string): AnyAgentTool {
+  return {
+    name: "exa_get_contents",
+    label: "Exa Get Contents",
+    description:
+      "Fetch page contents for one or more URLs through Exa via the Dench Cloud gateway.",
+    parameters: ExaContentsParameters,
+    execute: async (_toolCallId: string, params: Record<string, unknown>) => {
+      try {
+        const urls = readStringList(params.urls);
+        if (!urls) {
+          return jsonResult({ error: "At least one URL is required." });
+        }
+        return await postJson({
+          gatewayUrl,
+          apiKey,
+          path: "/v1/search/contents",
+          body: buildContentsBody({ ...params, urls }),
+        });
+      } catch (err) {
+        return jsonResult({
+          error: "Contents request failed.",
+          detail: err instanceof Error ? err.message : String(err),
+        });
+      }
+    },
+  } as AnyAgentTool;
+}
+
+function createExaAnswerTool(gatewayUrl: string, apiKey: string): AnyAgentTool {
+  return {
+    name: "exa_answer",
+    label: "Exa Answer",
+    description:
+      "Ask Exa for a citation-backed answer through the Dench Cloud gateway.",
+    parameters: ExaAnswerParameters,
+    execute: async (_toolCallId: string, params: Record<string, unknown>) => {
+      try {
+        return await postJson({
+          gatewayUrl,
+          apiKey,
+          path: "/v1/search/answer",
+          body: {
+            query: params.query,
+            ...(params.text === true ? { text: true } : {}),
+          },
+        });
+      } catch (err) {
+        return jsonResult({
+          error: "Answer request failed.",
+          detail: err instanceof Error ? err.message : String(err),
+        });
+      }
+    },
+  } as AnyAgentTool;
+}
+
+export default function register(api: OpenClawPluginApi) {
+  const rootConfig = asRecord(api.config);
+  const pluginEntries = asRecord(asRecord(rootConfig?.plugins)?.entries);
+  const pluginConfig = asRecord(asRecord(pluginEntries?.[id])?.config);
+  if (pluginConfig?.enabled === false) {
+    return;
+  }
+
+  const gatewayUrl = resolveGatewayUrl(api.config);
+  const apiKey = resolveApiKey(api.config);
+
+  if (!apiKey) {
+    api.logger?.info?.(
+      "[exa-search] No Dench Cloud API key found; tools will not be registered.",
+    );
+    return;
+  }
+
+  api.registerTool(createExaSearchTool(gatewayUrl, apiKey));
+  api.registerTool(createExaContentsTool(gatewayUrl, apiKey));
+  api.registerTool(createExaAnswerTool(gatewayUrl, apiKey));
+}

package/extensions/exa-search/openclaw.plugin.json

@@ -0,0 +1,16 @@
+{
+  "id": "exa-search",
+  "name": "Exa Search",
+  "version": "1.0.0",
+  "description": "Registers agent tools for Exa web search, content extraction, and answer generation via the Dench Cloud gateway.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": {
+        "type": "boolean",
+        "default": true
+      }
+    }
+  }
+}

package/extensions/exa-search/package.json

@@ -0,0 +1,8 @@
+{
+  "name": "@denchclaw/exa-search",
+  "version": "1.0.0",
+  "private": true,
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  }
+}

package/extensions/posthog-analytics/lib/build-env.js

@@ -1,3 +1,3 @@
 export const POSTHOG_KEY = "phc_Nt8s1Ny8062TY9aKT8LWiB4nBuoHNYQXRU9MypWfQCW";
-export const DENCHCLAW_VERSION = "2.4.6";
+export const DENCHCLAW_VERSION = "2.5.1";
 export const OPENCLAW_VERSION = "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "denchclaw",
-  "version": "2.4.6",
+  "version": "2.5.1",
   "description": "Fully Managed OpenClaw Framework for managing your CRM, Sales Automation and Outreach agents. The only local productivity tool you need.",
   "keywords": [],
   "homepage": "https://github.com/DenchHQ/DenchClaw#readme",
@@ -47,7 +47,7 @@
     "prepack": "pnpm build:plugin-env && pnpm build && pnpm web:build && pnpm web:prepack",
     "start": "node denchclaw.mjs",
     "test": "pnpm test:cli && pnpm --dir apps/web test",
-    "test:cli": "vitest run --config vitest.unit.config.ts src/cli/run-main.test.ts src/cli/bootstrap-external.test.ts src/cli/bootstrap-external.bootstrap-command.test.ts src/cli/dench-cloud.test.ts src/cli/workspace-seed.test.ts src/cli/web-runtime.test.ts src/cli/web-runtime-command.test.ts src/cli/flatten-standalone-deps.test.ts",
+    "test:cli": "vitest run --config vitest.unit.config.ts src/cli/run-main.test.ts src/cli/bootstrap-external.test.ts src/cli/bootstrap-external.bootstrap-command.test.ts src/cli/dench-cloud.test.ts src/cli/workspace-seed.test.ts src/cli/web-runtime.test.ts src/cli/web-runtime-command.test.ts src/cli/flatten-standalone-deps.test.ts && vitest run --config extensions/vitest.config.ts extensions/dench-identity/index.test.ts extensions/dench-identity/composio-cheat-sheet.test.ts extensions/dench-ai-gateway/index.test.ts",
     "test:web": "pnpm --dir apps/web test",
     "web:build": "pnpm --dir apps/web build",
     "web:dev": "pnpm --dir apps/web dev",

package/skills/composio-apps/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: composio-apps
+description: Connected app tool recipes for Composio integrations (Gmail, Slack, GitHub, Notion, Google Calendar, Linear)
+---
+
+# Composio connected apps
+
+Use **Composio tools** only. In DenchClaw these may already appear directly as tool names like `GMAIL_FETCH_EMAILS`; call those directly when present.
+
+Do **not** use:
+- `gog`
+- shell CLIs for Gmail / Calendar / Drive / Slack / GitHub / Notion / Linear
+- `curl`
+- raw `/v1/composio/*` gateway calls
+- direct Composio REST calls
+
+If the user mentions Composio, rube, map, MCP, or says an app is already connected, Composio is the only allowed integration path. If the Composio tools are unavailable in the current session, stop and report repair guidance instead of bypassing them.
+
+The workspace may contain `composio-tool-index.json` with the exact tool names and hints for **your** connected apps — prefer that file when present. If the exact tool is not obvious, call `composio_resolve_tool` first to get the correct tool name, argument shape, and default args.
+
+## General rules
+
+- Tool names are **uppercase** with underscores (e.g. `GMAIL_FETCH_EMAILS`).
+- Pass **JSON-shaped** arguments as the tool schema requires: arrays are arrays, not comma-separated strings.
+- If a call fails on argument shape, fix the types and retry once before escalating.
+- Never fall back to `gog`, curl, or raw gateway HTTP for a connected app task unless the user explicitly asks for that non-Composio path.
+
+## Gmail
+
+| Intent | Tool | Defaults / notes |
+|--------|------|------------------|
+| List / read recent mail | `GMAIL_FETCH_EMAILS` | `label_ids`: `["INBOX"]`, `max_results`: `10` |
+| Read one message | `GMAIL_FETCH_MESSAGE_BY_MESSAGE_ID` | `message_id` from list results |
+| Send mail | `GMAIL_SEND_EMAIL` | `to`, `subject`, `body` (use schema field names) |
+
+**Gotcha:** `label_ids` must be an array like `["INBOX"]`, never a single string.
+
+## Slack
+
+| Intent | Tool | Defaults / notes |
+|--------|------|------------------|
+| Send a message | `SLACK_SEND_MESSAGE` | `channel`, `text` |
+| List channels / DMs | `SLACK_LIST_CONVERSATIONS` | Use schema filters if needed |
+
+**Gotcha:** `channel` is usually a channel ID (often starts with `C`), not the display name.
+
+## GitHub
+
+| Intent | Tool | Defaults / notes |
+|--------|------|------------------|
+| List repos for user | `GITHUB_LIST_REPOSITORIES_FOR_THE_AUTHENTICATED_USER` | Pagination per schema |
+| Find / search pull requests | `GITHUB_FIND_PULL_REQUESTS` | Best first path for "recent PRs" or broad PR search |
+| List pull requests in a repo | `GITHUB_LIST_PULL_REQUESTS` | Requires `owner` and `repo` |
+| Get one pull request | `GITHUB_GET_A_PULL_REQUEST` | `owner`, `repo`, `pull_number` |
+| Repo metadata | `GITHUB_GET_A_REPOSITORY` | `owner`, `repo` |
+| Create issue | `GITHUB_CREATE_AN_ISSUE` | `owner`, `repo`, `title`, `body` |
+
+## Notion
+
+| Intent | Tool | Defaults / notes |
+|--------|------|------------------|
+| Search | `NOTION_SEARCH` | Query string per schema |
+| Read page | `NOTION_GET_PAGE` | Page ID |
+| Create page | `NOTION_CREATE_PAGE` | Parent object per schema |
+
+## Google Calendar
+
+| Intent | Tool | Defaults / notes |
+|--------|------|------------------|
+| List calendars | `GOOGLE_CALENDAR_CALENDAR_LIST` | Optional params per schema |
+| Upcoming events | `GOOGLE_CALENDAR_EVENTS_LIST` | Prefer a clear time window when possible |
+| List events | `GOOGLE_CALENDAR_EVENTS_LIST` | `calendar_id`, time range (`time_min` / `time_max` as RFC3339) |
+| Find event | `GOOGLE_CALENDAR_EVENTS_LIST` | Use search text / date window fields supported by the schema |
+| Create event | `GOOGLE_CALENDAR_CREATE_EVENT` | Calendar id + event payload per schema |
+
+**Gotcha:** Datetimes should be RFC3339 strings.
+
+## Linear
+
+| Intent | Tool | Defaults / notes |
+|--------|------|------------------|
+| List issues | `LINEAR_LIST_ISSUES` | Filters per schema |
+| Get issue | `LINEAR_GET_ISSUE` | Issue id |
+| Create issue | `LINEAR_CREATE_ISSUE` | Team id, title, description per schema |
+
+## Subagent handoff
+
+When delegating, include: which app, the exact tool name, and the argument object you intend (copy shapes from the tool schema, `composio_resolve_tool`, or `composio-tool-index.json`).