@kagan-sh/opensearch 0.1.0 → 0.2.0

package/CONTRIBUTING.md

@@ -70,7 +70,7 @@ This repo uses `semantic-release` on `main`.
 
 - Prefer Conventional Commits for merge commits and direct commits to `main`
 - Run `bun run release:dry-run` locally if you want to preview the next release
-- npm publishing is configured for GitHub Actions trusted publishing via OIDC for `@kagan-sh/opensearch`
+- npm publishing now uses GitHub Actions trusted publishing via OIDC for `@kagan-sh/opensearch`
 - The npm package must be linked to this repository under the `kagan_sh` publisher account before the first release
 - Local `semantic-release --dry-run` still fails auth checks unless GitHub and npm credentials are present; the OIDC npm path is validated in GitHub Actions, not in a regular local shell
 
@@ -95,7 +95,7 @@ This repo uses `semantic-release` on `main`.
 - CI workflow: `.github/workflows/ci.yml`
 - Release workflow: `.github/workflows/release.yml`
 - GitHub releases are automated with `semantic-release`
-- npm publishing is ready for trusted publishing via OIDC once the package is configured on npm
+- npm publishing is configured to publish through OIDC without a long-lived npm token
 
 ## Pull requests
 

package/README.md

@@ -1,11 +1,12 @@
 <p align="center">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kagan-sh/opensearch/main/.github/assets/logo-dark.svg">
-    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/kagan-sh/opensearch/main/.github/assets/logo-light.svg">
-    <img alt="OpenSearch — evidence-backed search for OpenCode" src="https://raw.githubusercontent.com/kagan-sh/opensearch/main/.github/assets/logo-dark.svg" width="100%">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/kagan-sh/opensearch/main/.github/assets/mark-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/kagan-sh/opensearch/main/.github/assets/mark-light.svg">
+    <img alt="OpenSearch — evidence-backed search for OpenCode" src="https://raw.githubusercontent.com/kagan-sh/opensearch/main/.github/assets/mark-dark.svg" width="100%">
   </picture>
 </p>
 <p align="center">
+  <a href="https://www.npmjs.com/package/@kagan-sh/opensearch"><img src="https://img.shields.io/npm/v/%40kagan-sh%2Fopensearch?style=for-the-badge" alt="npm"></a>
   <a href="https://github.com/kagan-sh/opensearch/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/kagan-sh/opensearch/ci.yml?style=for-the-badge&label=CI" alt="CI"></a>
   <a href="https://kagan-sh.github.io/opensearch/"><img src="https://img.shields.io/badge/docs-github%20pages-181717?style=for-the-badge&logo=github" alt="Docs"></a>
   <a href="https://opensource.org/license/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge" alt="License: MIT"></a>
@@ -14,8 +15,9 @@
 <h3 align="center">
   <a href="https://kagan-sh.github.io/opensearch/">Docs</a> ·
   <a href="https://kagan-sh.github.io/opensearch/quickstart/">Quickstart</a> ·
-  <a href="https://kagan-sh.github.io/opensearch/reference/result-contract/">Result Contract</a> ·
-  <a href="https://github.com/kagan-sh/opensearch/issues/new?template=feature-request.yml">Feature Requests</a>
+  <a href="https://kagan-sh.github.io/opensearch/guides/searxng/">SearXNG Setup</a> ·
+  <a href="https://kagan-sh.github.io/opensearch/reference/result-contract/">Reference</a> ·
+  <a href="https://raw.githubusercontent.com/kagan-sh/opensearch/main/SKILL.md">LLM Quick Reference</a>
 </h3>
 
 ---
@@ -35,56 +37,20 @@ Add the plugin to `opencode.json`:
 
 OpenCode installs npm plugins automatically at startup.
 
-Full docs: **[kagan-sh.github.io/opensearch](https://kagan-sh.github.io/opensearch/)**.
+Full docs: **[kagan-sh.github.io/opensearch](https://kagan-sh.github.io/opensearch/)**. Web search uses a self-hosted `SearXNG` instance; setup lives in the docs.
 
-## Configuration
-
-Control runtime behavior with environment variables:
-
-- `OPENSEARCH_SYNTH=true|false`
-- `OPENSEARCH_DEPTH=quick|thorough`
-- `OPENSEARCH_SOURCE_SESSION=true|false`
-- `OPENSEARCH_SOURCE_WEB=true|false`
-- `OPENSEARCH_SOURCE_CODE=true|false`
-- `OPENSEARCH_WEB_KEY=<exa_api_key>`
-- `EXA_API_KEY=<exa_api_key>`
-
-`OPENSEARCH_WEB_KEY` takes precedence over `EXA_API_KEY`. Web search is skipped when neither key is set.
-
-## Tool
-
-The plugin exposes a single tool: `opensearch`.
-
-Arguments:
-
-- `query: string`
-- `sources?: ("session" | "web" | "code")[]`
-- `depth?: "quick" | "thorough"`
-
-The tool returns strict JSON with `status`, `answer`, `confidence`, `evidence[]`, `sources[]`, `followups[]`, and `meta`.
-
-`meta` includes:
-
-- `sources_requested`
-- `sources_queried`
-- `sources_yielded`
-- `sources_unavailable[]`
-- `source_errors[]`
-
-Invalid plugin config is reported explicitly instead of being ignored.
-
-## Contributing
-
-For local source development, validation commands, and release workflow details, see `CONTRIBUTING.md`.
-
-## Documentation
-
-Published docs live at `https://kagan-sh.github.io/opensearch/`. MkDocs source lives in `docs/` with site config in `mkdocs.yml`.
-
-## Skill
+## License
 
-The repo includes `SKILL.md` for agent environments that support installable skills. It increases the chance that agents reach for `opensearch` on research-heavy prompts, but it does not force tool selection.
+[MIT](LICENSE)
 
-## License
+---
 
-MIT
+<p align="center">
+  <a href="https://www.star-history.com/#kagan-sh/opensearch&type=date">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=kagan-sh/opensearch&type=date&theme=dark" />
+      <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=kagan-sh/opensearch&type=date" />
+      <img alt="Star History" src="https://api.star-history.com/svg?repos=kagan-sh/opensearch&type=date" width="600" />
+    </picture>
+  </a>
+</p>

package/SKILL.md

@@ -2,7 +2,7 @@
 name: opensearch
 description: Use OpenSearch for broad, evidence-backed investigation across session history, the web, and public code when a user asks to search, research, compare sources, or gather official docs and examples.
 license: MIT
-compatibility: Requires OpenCode with @kagan-sh/opensearch installed. Web results need OPENSEARCH_WEB_KEY or EXA_API_KEY.
+compatibility: Requires OpenCode with @kagan-sh/opensearch installed. The current web provider is SearXNG, so web results need OPENSEARCH_WEB_URL.
 metadata:
   version: 0.0.1
 ---

package/dist/config.js

@@ -26,7 +26,7 @@ export function defaultConfig() {
             session: parseBoolean("OPENSEARCH_SOURCE_SESSION", process.env.OPENSEARCH_SOURCE_SESSION, true),
             web: {
                 enabled: parseBoolean("OPENSEARCH_SOURCE_WEB", process.env.OPENSEARCH_SOURCE_WEB, true),
-                key: process.env.OPENSEARCH_WEB_KEY ?? process.env.EXA_API_KEY,
+                url: process.env.OPENSEARCH_WEB_URL,
             },
             code: parseBoolean("OPENSEARCH_SOURCE_CODE", process.env.OPENSEARCH_SOURCE_CODE, true),
         },
@@ -50,7 +50,7 @@ export function isSourceAvailable(config, source) {
     if (source === "session")
         return config.sources.session;
     if (source === "web") {
-        return config.sources.web.enabled && Boolean(config.sources.web.key);
+        return config.sources.web.enabled && Boolean(config.sources.web.url);
     }
     return config.sources.code;
 }

package/dist/index.js

@@ -4,6 +4,19 @@ import { noResultsResult, noSourcesResult, rawResultsResult, runSourceSearches,
 import { DEPTHS, ResultSchema, SOURCE_IDS, } from "./schema";
 import { synthesize } from "./synth";
 const BRAND = "OpenSearch";
+const TAGLINE = "evidence-backed search";
+function sourceBadge(source) {
+    if (source === "session")
+        return "SESSION";
+    if (source === "web")
+        return "WEB";
+    return "CODE";
+}
+function sourceBadges(sources) {
+    if (sources.length === 0)
+        return ["OFFLINE"];
+    return sources.map(sourceBadge);
+}
 function serialize(result) {
     return JSON.stringify(result, null, 2);
 }
@@ -22,28 +35,32 @@ function describeSources(sources) {
     return "session + web + code";
 }
 function runningTitle(sources) {
-    return `${BRAND} · searching ${describeSources(sources)}`;
+    return `${BRAND} // scanning ${describeSources(sources)}`;
 }
 function doneTitle(result) {
     if (result.status === "no_sources")
-        return `${BRAND} · unavailable`;
+        return `${BRAND} // unavailable`;
     if (result.status === "no_results")
-        return `${BRAND} · no matches`;
+        return `${BRAND} // no matches`;
     if (result.status === "raw") {
-        return `${BRAND} · ${result.meta.sources_yielded} raw result${result.meta.sources_yielded === 1 ? "" : "s"}`;
+        return `${BRAND} // ${result.meta.sources_yielded} raw result${result.meta.sources_yielded === 1 ? "" : "s"}`;
     }
     if (result.status === "raw_fallback")
-        return `${BRAND} · evidence fallback`;
-    return `${BRAND} · ${result.meta.sources_yielded} result${result.meta.sources_yielded === 1 ? "" : "s"}`;
+        return `${BRAND} // evidence fallback`;
+    return `${BRAND} // ${result.meta.sources_yielded} result${result.meta.sources_yielded === 1 ? "" : "s"}`;
 }
 function toolMetadata(input) {
     return {
         brand: BRAND,
+        brand_tagline: TAGLINE,
+        brand_origin: "@kagan-sh/opensearch",
+        brand_surface: "plugin",
         phase: input.phase,
         query: previewQuery(input.query),
         depth: input.depth,
         sources: input.sources,
         source_summary: describeSources(input.sources),
+        source_badges: sourceBadges(input.sources),
         ...(input.result
             ? {
                 status: input.result.status,
@@ -84,7 +101,7 @@ export const OpensearchPlugin = async (ctx) => {
             if (input.toolID !== "opensearch")
                 return;
             output.description =
-                "OpenSearch: use for broad investigation when the user asks to search, compare evidence, gather official docs, or combine session, web, and code results.";
+                "OpenSearch // evidence-backed search across session history, SearXNG web search, and public code. Use it for broad investigation, comparison, docs gathering, and cross-source research.";
         },
         "tool.execute.after": async (input, output) => {
             if (input.tool !== "opensearch")
@@ -110,7 +127,7 @@ export const OpensearchPlugin = async (ctx) => {
         },
         tool: {
             opensearch: tool({
-                description: "Universal intelligent search. Queries session history, web, and code in parallel. Returns structured evidence-backed answer.",
+                description: "OpenSearch // evidence-backed search. Queries session history, SearXNG web search, and public code in parallel, then returns a structured answer with explicit status and source metadata.",
                 args: {
                     query: tool.schema.string().describe("What to search for"),
                     sources: tool.schema
@@ -185,7 +202,7 @@ export const OpensearchPlugin = async (ctx) => {
                     }
                     if (cfg.synth) {
                         context.metadata({
-                            title: `${BRAND} · synthesizing evidence`,
+                            title: `${BRAND} // assembling evidence`,
                             metadata: {
                                 ...toolMetadata({
                                     phase: "synthesizing",
@@ -194,6 +211,7 @@ export const OpensearchPlugin = async (ctx) => {
                                     sources: resolved.sources,
                                 }),
                                 raw_results: search.raw.length,
+                                status_note: "assembling evidence",
                             },
                         });
                         try {

package/dist/orchestrator.js

@@ -43,7 +43,7 @@ export async function runSourceSearches(input) {
             return searchSessions(input.client, input.directory, input.query, input.depth);
         }
         if (source === "web") {
-            return searchWeb(input.query, input.config.sources.web.key, input.depth);
+            return searchWeb(input.query, input.config.sources.web.url, input.depth);
         }
         return searchCode(input.query, input.depth);
     }));
@@ -61,7 +61,7 @@ export function noSourcesResult(input) {
         sources: [],
         followups: [
             "Enable at least one search source in opensearch config",
-            "Set OPENSEARCH_WEB_KEY or EXA_API_KEY to enable web search",
+            "Set OPENSEARCH_WEB_URL to enable web search",
         ],
         meta: resultMeta({
             query: input.query,

package/dist/schema.d.ts

@@ -346,27 +346,27 @@ export declare const ConfigSchema: z.ZodObject<{
         session: z.ZodBoolean;
         web: z.ZodObject<{
             enabled: z.ZodBoolean;
-            key: z.ZodOptional<z.ZodString>;
+            url: z.ZodOptional<z.ZodString>;
         }, "strict", z.ZodTypeAny, {
             enabled: boolean;
-            key?: string | undefined;
+            url?: string | undefined;
         }, {
             enabled: boolean;
-            key?: string | undefined;
+            url?: string | undefined;
         }>;
         code: z.ZodBoolean;
     }, "strict", z.ZodTypeAny, {
         session: boolean;
         web: {
             enabled: boolean;
-            key?: string | undefined;
+            url?: string | undefined;
         };
         code: boolean;
     }, {
         session: boolean;
         web: {
             enabled: boolean;
-            key?: string | undefined;
+            url?: string | undefined;
         };
         code: boolean;
     }>;
@@ -377,7 +377,7 @@ export declare const ConfigSchema: z.ZodObject<{
         session: boolean;
         web: {
             enabled: boolean;
-            key?: string | undefined;
+            url?: string | undefined;
         };
         code: boolean;
     };
@@ -388,7 +388,7 @@ export declare const ConfigSchema: z.ZodObject<{
         session: boolean;
         web: {
             enabled: boolean;
-            key?: string | undefined;
+            url?: string | undefined;
         };
         code: boolean;
     };

package/dist/schema.js

@@ -82,7 +82,7 @@ export const ConfigSchema = z
         web: z
             .object({
             enabled: z.boolean(),
-            key: z.string().optional(),
+            url: z.string().url().optional(),
         })
             .strict(),
         code: z.boolean(),

package/dist/sources/web.d.ts

@@ -1,3 +1,3 @@
 import type { Depth } from "../schema";
 import { type SourceSearchOutcome } from "./shared";
-export declare function searchWeb(query: string, key: string | undefined, depth: Depth): Promise<SourceSearchOutcome>;
+export declare function searchWeb(query: string, baseUrl: string | undefined, depth: Depth): Promise<SourceSearchOutcome>;

package/dist/sources/web.js

@@ -1,46 +1,38 @@
 import { failure, messageFromError } from "./shared";
-export async function searchWeb(query, key, depth) {
+export async function searchWeb(query, baseUrl, depth) {
     const source = "web";
-    if (!key) {
-        return failure(source, "unavailable", "Web source requires OPENSEARCH_WEB_KEY or EXA_API_KEY.");
+    if (!baseUrl) {
+        return failure(source, "unavailable", "Web source requires OPENSEARCH_WEB_URL.");
     }
     try {
-        const res = await fetch("https://api.exa.ai/search", {
-            method: "POST",
+        const url = new URL("search", baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`);
+        url.searchParams.set("q", query);
+        url.searchParams.set("format", "json");
+        const res = await fetch(url, {
             headers: {
-                "x-api-key": key,
-                "Content-Type": "application/json",
+                Accept: "application/json",
             },
-            body: JSON.stringify({
-                query,
-                numResults: depth === "quick" ? 5 : 10,
-                type: "auto",
-                contents: {
-                    text: {
-                        maxCharacters: 1000,
-                    },
-                },
-            }),
         });
         if (!res.ok) {
-            return failure(source, "request_failed", `Exa search failed with status ${res.status}.`);
+            return failure(source, "request_failed", res.status === 403
+                ? "SearXNG search failed with status 403. Enable JSON output on the instance."
+                : `SearXNG search failed with status ${res.status}.`);
         }
         const body = (await res.json());
         if (!Array.isArray(body.results)) {
-            return failure(source, "invalid_response", "Exa search returned an invalid payload.");
+            return failure(source, "invalid_response", "SearXNG search returned an invalid payload.");
         }
-        const list = body.results;
+        const limit = depth === "quick" ? 5 : 10;
+        const list = body.results.slice(0, limit);
         return {
             source,
             results: list.map((item, i) => ({
-                id: item.id ?? `web-${i}`,
+                id: `web-${i}`,
                 type: source,
                 title: item.title ?? item.url ?? "Untitled",
-                snippet: (item.text ?? "").slice(0, 700),
+                snippet: (item.content ?? item.url ?? "").slice(0, 700),
                 url: item.url,
-                relevance: typeof item.score === "number"
-                    ? Math.min(1, Math.max(0, item.score))
-                    : 0.5,
+                relevance: Math.max(0.1, 1 - i / Math.max(1, list.length)),
                 timestamp: item.publishedDate
                     ? Date.parse(item.publishedDate) || undefined
                     : undefined,
@@ -48,6 +40,6 @@ export async function searchWeb(query, key, depth) {
         };
     }
     catch (error) {
-        return failure(source, "request_failed", `Exa search failed: ${messageFromError(error)}`);
+        return failure(source, "request_failed", `SearXNG search failed: ${messageFromError(error)}`);
     }
 }

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@kagan-sh/opensearch",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "OpenCode plugin that combines session, web, and code search",
+  "license": "MIT",
   "homepage": "https://kagan-sh.github.io/opensearch/",
   "repository": {
     "type": "git",