feat: default serpapi tools to markdown output, add md/json format setting

[galetahub]

Summary

SerpApi now supports markdown output via the output=md parameter — an LLM-optimized rendering that consumes significantly fewer tokens than raw JSON.

This PR makes markdown the default response format for all 30 specialized serpapi_* tools, with two escape hatches:

• Config: plugins.entries.serpapi.config.webSearch.format — "md" (default) or "json"
• Per call: every tool accepts an output argument ("md" / "json")

Changes

• src/config.ts — resolveSerpApiFormat() reads the format setting. Defaults to "md", case-insensitive; invalid values throw instead of silently falling back.
• src/markdown.ts (new) — limitResultTable(), a line-based port of hermes-plugin's markdown.py: truncates the results table under a named heading (e.g. "News Results") to the requested count rows while leaving front-matter, pagination, and other sections untouched.
• src/serpapi-client.ts — callSerpApi returns Record<string, unknown> | string: sends output=md and returns raw text for markdown; JSON path unchanged. Response text is redacted of the API key. Markdown payloads are wrapped under __serpapi_markdown for the record-based shared cache; the cache key includes the format, so md/json entries can't poison each other.
• src/utils.ts — serpApiResult(): markdown responses are wrapped with wrapWebContent (the SDK's untrusted-content security markers) and returned under a single markdown field; JSON keeps the previous structured shape.
• All 30 tools — accept the output override; the five tools with count (news, jobs, maps, scholar, shopping) truncate the markdown results table to count rows.
• web_search provider — hardcoded to output: "json". Its contract (results[], count/maxResults) is structured, so markdown does not apply — same as hermes-plugin's provider.
• openclaw.plugin.json — configSchema (enum: ["md", "json"], default: "md") and uiHints for the new setting.
• README / SKILL.md — document the setting and the breaking change.
• Version — bumped to 0.2.0.

Breaking change

serpapi_* tools now return { markdown: "..." } by default instead of the structured fields. Set format: "json" (or pass output: "json" per call) to restore the previous behavior.

[Copilot]

Pull request overview

This PR updates the SerpApi OpenClaw plugin to default specialized serpapi_* tools to SerpApi’s markdown output (output=md) to reduce token usage, while preserving a JSON escape hatch via config and per-call overrides.

Changes:

• Add webSearch.format config (md default / json) plus per-tool output override parsing.
• Update SerpApi client + result shaping to support markdown responses (including cache isolation and API-key redaction) and return { markdown: ... } by default for specialized tools.
• Add limitResultTable() to truncate markdown result tables for tools that accept count.

Reviewed changes

Copilot reviewed 39 out of 39 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
src/config.ts	Adds SerpApiOutputFormat and resolves default format (md/json) from plugin config.
src/markdown.ts	New helper to truncate markdown tables under a named heading.
src/serpapi-client.ts	Adds md/json output selection, md-aware caching, and API key redaction in returned text/errors.
src/utils.ts	Adds readOutputArg() and serpApiResult() to standardize md/json tool outputs and apply markdown truncation + wrapping.
src/serpapi-search-provider.ts	Forces web_search provider to always request structured JSON (output: "json").
src/tools/amazon.ts	Adds output override support and routes responses through serpApiResult().
src/tools/amazon-product.ts	Adds output override support and routes responses through serpApiResult().
src/tools/autocomplete.ts	Adds output override support and routes responses through serpApiResult().
src/tools/bing.ts	Adds output override support and routes responses through serpApiResult().
src/tools/duckduckgo.ts	Adds output override support and routes responses through serpApiResult().
src/tools/ebay.ts	Adds output override support and routes responses through serpApiResult().
src/tools/ebay-product.ts	Adds output override support and routes responses through serpApiResult().
src/tools/events.ts	Adds output override support and routes responses through serpApiResult().
src/tools/facebook-profile.ts	Adds output override support and routes responses through serpApiResult().
src/tools/finance.ts	Adds output override support and routes responses through serpApiResult().
src/tools/flights.ts	Adds output override support and routes responses through serpApiResult().
src/tools/hotels.ts	Adds output override support and routes responses through serpApiResult().
src/tools/immersive-product.ts	Adds output override support and routes responses through serpApiResult().
src/tools/instagram-profile.ts	Adds output override support and routes responses through serpApiResult().
src/tools/jobs.ts	Adds output override + truncates markdown results table to count.
src/tools/lens.ts	Adds output override support and routes responses through serpApiResult().
src/tools/maps.ts	Adds output override + truncates markdown results table to count.
src/tools/maps-reviews.ts	Adds output override support and routes responses through serpApiResult().
src/tools/news.ts	Adds output override + truncates markdown results table to count.
src/tools/scholar.ts	Adds output override + truncates markdown results table to count.
src/tools/shopping.ts	Adds output override + truncates markdown results table to count.
src/tools/trends.ts	Adds output override support and routes responses through serpApiResult().
src/tools/tripadvisor.ts	Adds output override support and routes responses through serpApiResult().
src/tools/walmart.ts	Adds output override support and routes responses through serpApiResult().
src/tools/walmart-product.ts	Adds output override support and routes responses through serpApiResult().
src/tools/weather.ts	Adds output override support and routes responses through serpApiResult().
src/tools/yahoo.ts	Adds output override support and routes responses through serpApiResult().
src/tools/youtube.ts	Adds output override support and routes responses through serpApiResult().
src/tools/youtube-video.ts	Adds output override support and routes responses through serpApiResult().
src/tools/youtube-transcript.ts	Adds output override support and routes responses through serpApiResult().
skills/serpapi/SKILL.md	Documents the new default markdown behavior and override options.
README.md	Documents the response format setting and breaking change.
openclaw.plugin.json	Adds schema + UI hints for webSearch.format.
package.json	Bumps version to 0.2.0.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.