GooDAnDReaDY/dsh-grok-xsearch

dsh-grok-xsearch is a native plugin built specifically for the DeepSeek Harness runtime, distributed through npm under the @goodandready scope and installed with the single command dsh plugin --profile web add @goodandready/dsh-grok-xsearch from a profile-scoped terminal. It targets the upstream xAI Responses API endpoint that exposes the x_search tool type, routing every agent request through a SuperGrok OAuth PKCE session so DSH agents can read live breaking news, developer sentiment, Community Notes fact-checking, author timelines, and viral trends without paying for premium per-query X API tiers. The package requires Node.js 20 or newer, exposes management surfaces over a dedicated set of HTTP routes including /dsh-grok-xsearch/config, /dsh-grok-xsearch/cache/clear, /oauth/start, /oauth/callback, /oauth/complete, and /logout, and registers a structured settings card directly inside the DSH web profile interface for live cache inspection and one-click cache flushing.

Inside ctx.tools the plugin registers six purpose-built tools: x_search for natural-language post and thread queries with comma-separated allowed_x_handles/excluded_x_handles filters (up to ten each), from_date/to_date ISO date ranges, only_original_posts, has_media, and has_links toggles; x_author_profile for stance and timeline summaries; x_trending_topics for live trending discovery; x_fact_check_notes for Community Notes fact verification; x_thread_reader for reconstructing thread context; and x_find_experts for targeted expert discovery. Every call first traverses an in-memory TTL cache, and misses are normalized through a multimodal filter, deduplicated, canonicalized to https://x.com/<handle>/status/<id> URLs with tracking parameters such as utm_*, ?s=, ?t=, and ref_src stripped, and then persisted back to cache for a five-minute window. The intended users are researchers, investigative journalists, social-listening operators, and quant traders who want live X intelligence injected directly into DSH reasoning loops without bespoke integration code.

Dependencies are limited to a valid SuperGrok OAuth subscription tied to the installing user's xAI account, and runtime hardening includes a single-flight mutex on the refresh token path, automatic HTTP 401 retry-after-refresh, exponential backoff for transient 5xx and network errors, capacity-bounded proactive cache pruning for both SEARCH_CACHE and MODELS_CACHE, and a graceful Grok 4.5 fallback when the upstream x_search endpoint returns HTTP 429 rate-limit responses. First-run operators must authenticate once via Settings → Plugins → Grok X Search & Intelligence Suite inside the DSH web profile before any tool call will succeed; standalone operators can alternatively complete the PKCE flow by visiting /oauth/start, pasting the redirected URL into /oauth/complete, and clearing their session at any time through /logout. The plugin is released under the permissive MIT license at no cost, although downstream usage volume is ultimately bounded by the user's own SuperGrok subscription quotas and the xAI model's published rate limits.