@kagan-sh/opensearch 0.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,104 @@
+# Contributing to @kagan-sh/opensearch
+
+Keep the published README end-user facing. Put local setup, source-based plugin loading, and maintainer workflow details here.
+
+## Requirements
+
+- Bun 1.2+
+- Node 20+
+- OpenCode CLI (`opencode`)
+
+## Local setup
+
+```bash
+bun install
+npm install -g opencode-ai
+```
+
+## Run the plugin from source
+
+For local development, point `opencode.json` at the source entrypoint:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["file:///absolute/path/to/opensearch/src/index.ts"]
+}
+```
+
+This keeps the published package path in `README.md` while still giving contributors a zero-publish development loop.
+
+## Validate changes
+
+Run the full validation pipeline before opening a pull request:
+
+```bash
+bun run check
+```
+
+That runs:
+
+1. `bun run typecheck`
+2. `bun run test`
+3. `bun run build`
+
+Acceptance tests are integration-heavy and boot a real OpenCode server process.
+
+## Docs
+
+Install docs dependencies:
+
+```bash
+python3 -m pip install -r requirements-docs.txt
+```
+
+Run the local docs server:
+
+```bash
+mkdocs serve
+```
+
+Build docs with strict link validation:
+
+```bash
+mkdocs build --strict
+```
+
+## Release automation
+
+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`
+- 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
+
+## Project structure
+
+- `src/index.ts` plugin entrypoint, source selection, and response assembly
+- `src/schema.ts` zod schemas and JSON schema export
+- `src/sources/*` source adapters for session, web, and code search
+- `src/synth.ts` structured synthesis through `session.prompt`
+- `tests/*` vitest coverage for schema and end-to-end plugin behavior
+- `SKILL.md` optional skill guidance that nudges agent workflows toward `opensearch` for broad research tasks
+
+## Testing policy
+
+- Prefer acceptance-first coverage for behavior changes
+- Test observable outcomes instead of internal wiring
+- Avoid tautological tests and unnecessary mocks
+- Mock only when the real contract cannot be exercised in runtime tests
+
+## Release workflow
+
+- 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
+
+## Pull requests
+
+- Keep changes small and focused
+- Add or update tests for behavior changes
+- Keep `README.md` user-facing and keep contributor workflow details in `CONTRIBUTING.md`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+<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%">
+  </picture>
+</p>
+<p align="center">
+  <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>
+  <a href="https://github.com/kagan-sh/opensearch/stargazers"><img src="https://img.shields.io/github/stars/kagan-sh/opensearch?style=for-the-badge" alt="Stars"></a>
+</p>
+<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>
+</h3>
+
+---
+
+`@kagan-sh/opensearch` is an OpenCode plugin for broad investigation. It searches session history, the live web, and public code in parallel, then returns a structured evidence-backed response your agent can act on.
+
+## Install
+
+Add the plugin to `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@kagan-sh/opensearch"]
+}
+```
+
+OpenCode installs npm plugins automatically at startup.
+
+Full docs: **[kagan-sh.github.io/opensearch](https://kagan-sh.github.io/opensearch/)**.
+
+## 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
+
+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.
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,53 @@
+---
+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.
+metadata:
+  version: 0.0.1
+---
+
+# OpenSearch Skill
+
+Use this skill when the task is primarily about finding, comparing, and synthesizing evidence rather than editing code immediately.
+
+## When to Use It
+
+- The user says `search`, `look up`, `research`, `investigate`, or `find examples`
+- The answer should combine project context, official docs, and public code patterns
+- The task needs contradictory-source checking before implementation
+- The user wants official references, best practices, or GitHub examples
+
+## When Not to Use It
+
+- A local `read`, `grep`, or `glob` is enough to answer the question
+- The task is a straightforward edit in a known file
+- The user explicitly wants a pure code change with no research step
+
+## Default Workflow
+
+1. Call `opensearch` first for broad or ambiguous research questions.
+2. Prefer `depth: "thorough"` for broad or ambiguous research; keep `quick` for focused lookups.
+3. Use all sources when external context matters; narrow sources only when the user asks for repo-local or session-local evidence.
+4. Summarize what the tool found, highlight contradictions or gaps, then continue with implementation or recommendation.
+
+## Query Patterns
+
+- Official docs and examples:
+  - `React Server Components caching behavior official docs GitHub examples`
+- Repo plus external evidence:
+  - `OpenCode plugin loading order project behavior official docs`
+- Contradiction check:
+  - `semantic-release trusted publishing npm GitHub Actions official guidance 2026`
+
+## Source Selection Guide
+
+- `session` for prior decisions, earlier runs, and local conversation history
+- `web` for official docs, changelogs, and current vendor guidance
+- `code` for public implementation examples and real usage patterns
+
+## Output Expectations
+
+- Return the strongest evidence first
+- Call out missing or unavailable sources explicitly
+- Keep citations grounded in the tool response instead of guessing

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+import type { Config, SourceId } from "./schema";
+export declare function defaultConfig(): Config;
+export declare function parsePluginConfig(input: unknown): Config | undefined;
+export declare function isSourceAvailable(config: Config, source: SourceId): boolean;
+export declare function resolveSources(config: Config, requested?: SourceId[]): {
+    requested: ("session" | "web" | "code")[];
+    sources: ("session" | "web" | "code")[];
+    unavailable: ("session" | "web" | "code")[];
+};

package/dist/config.js

@@ -0,0 +1,66 @@
+import { ConfigSchema, SOURCE_IDS } from "./schema";
+function parseBoolean(name, value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    throw new Error(`Invalid value for ${name}: expected true or false, got ${value}`);
+}
+function parseDepth(value) {
+    if (value === undefined || value === "quick")
+        return "quick";
+    if (value === "thorough")
+        return "thorough";
+    throw new Error(`Invalid value for OPENSEARCH_DEPTH: expected quick or thorough, got ${value}`);
+}
+function formatIssuePath(path) {
+    if (path.length === 0)
+        return "opensearch";
+    return `opensearch.${path.join(".")}`;
+}
+export function defaultConfig() {
+    return {
+        sources: {
+            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,
+            },
+            code: parseBoolean("OPENSEARCH_SOURCE_CODE", process.env.OPENSEARCH_SOURCE_CODE, true),
+        },
+        depth: parseDepth(process.env.OPENSEARCH_DEPTH),
+        synth: parseBoolean("OPENSEARCH_SYNTH", process.env.OPENSEARCH_SYNTH, true),
+    };
+}
+export function parsePluginConfig(input) {
+    if (!input || typeof input !== "object" || !("opensearch" in input)) {
+        return undefined;
+    }
+    const parsed = ConfigSchema.safeParse(input.opensearch);
+    if (parsed.success)
+        return parsed.data;
+    const issues = parsed.error.issues
+        .map((issue) => `${formatIssuePath(issue.path)} ${issue.message}`)
+        .join("; ");
+    throw new Error(`Invalid opensearch config: ${issues}`);
+}
+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.code;
+}
+export function resolveSources(config, requested) {
+    const requestedSources = Array.from(new Set(requested ?? SOURCE_IDS));
+    const sources = requestedSources.filter((source) => isSourceAvailable(config, source));
+    const unavailable = requestedSources.filter((source) => !isSourceAvailable(config, source));
+    return {
+        requested: requestedSources,
+        sources,
+        unavailable,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from "@opencode-ai/plugin";
+export declare const OpensearchPlugin: Plugin;
+export default OpensearchPlugin;

package/dist/index.js

@@ -0,0 +1,276 @@
+import { tool } from "@opencode-ai/plugin";
+import { defaultConfig, parsePluginConfig, resolveSources } from "./config";
+import { noResultsResult, noSourcesResult, rawResultsResult, runSourceSearches, synthesizedResult, } from "./orchestrator";
+import { DEPTHS, ResultSchema, SOURCE_IDS, } from "./schema";
+import { synthesize } from "./synth";
+const BRAND = "OpenSearch";
+function serialize(result) {
+    return JSON.stringify(result, null, 2);
+}
+function previewQuery(query, max = 64) {
+    if (query.length <= max)
+        return query;
+    return `${query.slice(0, max - 1)}...`;
+}
+function describeSources(sources) {
+    if (sources.length === 0)
+        return "no sources";
+    if (sources.length === 1)
+        return `${sources[0]} only`;
+    if (sources.length === 2)
+        return `${sources[0]} + ${sources[1]}`;
+    return "session + web + code";
+}
+function runningTitle(sources) {
+    return `${BRAND} · searching ${describeSources(sources)}`;
+}
+function doneTitle(result) {
+    if (result.status === "no_sources")
+        return `${BRAND} · unavailable`;
+    if (result.status === "no_results")
+        return `${BRAND} · no matches`;
+    if (result.status === "raw") {
+        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"}`;
+}
+function toolMetadata(input) {
+    return {
+        brand: BRAND,
+        phase: input.phase,
+        query: previewQuery(input.query),
+        depth: input.depth,
+        sources: input.sources,
+        source_summary: describeSources(input.sources),
+        ...(input.result
+            ? {
+                status: input.result.status,
+                answer: input.result.answer,
+                duration_ms: input.result.meta.duration,
+                sources_requested: input.result.meta.sources_requested,
+                sources_queried: input.result.meta.sources_queried,
+                sources_yielded: input.result.meta.sources_yielded,
+                source_errors: input.result.meta.source_errors.length,
+                sources_unavailable: input.result.meta.sources_unavailable,
+            }
+            : {}),
+    };
+}
+function parseResultOutput(output) {
+    try {
+        const parsed = ResultSchema.safeParse(JSON.parse(output));
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseRequestedSources(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    return value.filter((source) => typeof source === "string" && SOURCE_IDS.includes(source));
+}
+export const OpensearchPlugin = async (ctx) => {
+    let cfg = defaultConfig();
+    return {
+        async config(input) {
+            const next = parsePluginConfig(input);
+            if (next)
+                cfg = next;
+        },
+        "tool.definition": async (input, output) => {
+            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.";
+        },
+        "tool.execute.after": async (input, output) => {
+            if (input.tool !== "opensearch")
+                return;
+            const result = parseResultOutput(output.output);
+            if (!result)
+                return;
+            const requested = parseRequestedSources(input.args?.sources);
+            const resolved = resolveSources(cfg, requested);
+            output.title = doneTitle(result);
+            output.metadata = {
+                ...(output.metadata ?? {}),
+                ...toolMetadata({
+                    phase: "completed",
+                    query: result.meta.query,
+                    depth: input.args && typeof input.args.depth === "string"
+                        ? input.args.depth
+                        : cfg.depth,
+                    sources: requested ?? resolved.sources,
+                    result,
+                }),
+            };
+        },
+        tool: {
+            opensearch: tool({
+                description: "Universal intelligent search. Queries session history, web, and code in parallel. Returns structured evidence-backed answer.",
+                args: {
+                    query: tool.schema.string().describe("What to search for"),
+                    sources: tool.schema
+                        .array(tool.schema.enum(SOURCE_IDS))
+                        .optional()
+                        .describe("Sources to query. Defaults to all enabled."),
+                    depth: tool.schema
+                        .enum(DEPTHS)
+                        .optional()
+                        .describe("Search depth. Default: quick"),
+                },
+                async execute(args, context) {
+                    const start = Date.now();
+                    const searchDepth = args.depth ?? cfg.depth;
+                    const resolved = resolveSources(cfg, args.sources);
+                    context.metadata({
+                        title: runningTitle(resolved.sources),
+                        metadata: toolMetadata({
+                            phase: "searching",
+                            query: args.query,
+                            depth: searchDepth,
+                            sources: resolved.sources,
+                        }),
+                    });
+                    if (resolved.sources.length === 0) {
+                        const result = noSourcesResult({
+                            query: args.query,
+                            start,
+                            requested: resolved.requested,
+                            unavailable: resolved.unavailable,
+                        });
+                        context.metadata({
+                            title: doneTitle(result),
+                            metadata: toolMetadata({
+                                phase: "completed",
+                                query: args.query,
+                                depth: searchDepth,
+                                sources: resolved.sources,
+                                result,
+                            }),
+                        });
+                        return serialize(result);
+                    }
+                    const search = await runSourceSearches({
+                        client: ctx.client,
+                        directory: context.directory,
+                        config: cfg,
+                        query: args.query,
+                        depth: searchDepth,
+                        sources: resolved.sources,
+                    });
+                    if (search.raw.length === 0) {
+                        const result = noResultsResult({
+                            query: args.query,
+                            start,
+                            requested: resolved.requested,
+                            queried: resolved.sources,
+                            unavailable: resolved.unavailable,
+                            sourceErrors: search.sourceErrors,
+                        });
+                        context.metadata({
+                            title: doneTitle(result),
+                            metadata: toolMetadata({
+                                phase: "completed",
+                                query: args.query,
+                                depth: searchDepth,
+                                sources: resolved.sources,
+                                result,
+                            }),
+                        });
+                        return serialize(result);
+                    }
+                    if (cfg.synth) {
+                        context.metadata({
+                            title: `${BRAND} · synthesizing evidence`,
+                            metadata: {
+                                ...toolMetadata({
+                                    phase: "synthesizing",
+                                    query: args.query,
+                                    depth: searchDepth,
+                                    sources: resolved.sources,
+                                }),
+                                raw_results: search.raw.length,
+                            },
+                        });
+                        try {
+                            const synthesis = await synthesize(ctx.client, context.directory, search.raw, args.query);
+                            const result = synthesizedResult({
+                                query: args.query,
+                                start,
+                                requested: resolved.requested,
+                                queried: resolved.sources,
+                                unavailable: resolved.unavailable,
+                                sourceErrors: search.sourceErrors,
+                                raw: search.raw,
+                                synthesis,
+                            });
+                            context.metadata({
+                                title: doneTitle(result),
+                                metadata: toolMetadata({
+                                    phase: "completed",
+                                    query: args.query,
+                                    depth: searchDepth,
+                                    sources: resolved.sources,
+                                    result,
+                                }),
+                            });
+                            return serialize(result);
+                        }
+                        catch {
+                            const result = rawResultsResult({
+                                query: args.query,
+                                start,
+                                requested: resolved.requested,
+                                queried: resolved.sources,
+                                unavailable: resolved.unavailable,
+                                sourceErrors: search.sourceErrors,
+                                raw: search.raw,
+                                status: "raw_fallback",
+                            });
+                            context.metadata({
+                                title: doneTitle(result),
+                                metadata: {
+                                    ...toolMetadata({
+                                        phase: "completed",
+                                        query: args.query,
+                                        depth: searchDepth,
+                                        sources: resolved.sources,
+                                        result,
+                                    }),
+                                    fallback: "synthesis_error",
+                                },
+                            });
+                            return serialize(result);
+                        }
+                    }
+                    const result = rawResultsResult({
+                        query: args.query,
+                        start,
+                        requested: resolved.requested,
+                        queried: resolved.sources,
+                        unavailable: resolved.unavailable,
+                        sourceErrors: search.sourceErrors,
+                        raw: search.raw,
+                        status: "raw",
+                    });
+                    context.metadata({
+                        title: doneTitle(result),
+                        metadata: toolMetadata({
+                            phase: "completed",
+                            query: args.query,
+                            depth: searchDepth,
+                            sources: resolved.sources,
+                            result,
+                        }),
+                    });
+                    return serialize(result);
+                },
+            }),
+        },
+    };
+};
+export default OpensearchPlugin;

package/dist/orchestrator.d.ts

@@ -0,0 +1,60 @@
+import type { createOpencodeClient } from "@opencode-ai/sdk";
+import type { Config, RawResult, Result, Source, SourceError, SourceId, Synthesis } from "./schema";
+export declare function normalize(raw: RawResult): Source;
+export declare function runSourceSearches(input: {
+    client: ReturnType<typeof createOpencodeClient>;
+    directory: string;
+    config: Config;
+    query: string;
+    depth: Config["depth"];
+    sources: SourceId[];
+}): Promise<{
+    raw: {
+        id: string;
+        type: "session" | "web" | "code";
+        title: string;
+        snippet: string;
+        relevance: number;
+        url?: string | undefined;
+        timestamp?: number | undefined;
+    }[];
+    sourceErrors: {
+        code: "unavailable" | "request_failed" | "invalid_response";
+        message: string;
+        source: "session" | "web" | "code";
+    }[];
+}>;
+export declare function noSourcesResult(input: {
+    query: string;
+    start: number;
+    requested: SourceId[];
+    unavailable: SourceId[];
+}): Result;
+export declare function noResultsResult(input: {
+    query: string;
+    start: number;
+    requested: SourceId[];
+    queried: SourceId[];
+    unavailable: SourceId[];
+    sourceErrors: SourceError[];
+}): Result;
+export declare function rawResultsResult(input: {
+    query: string;
+    start: number;
+    requested: SourceId[];
+    queried: SourceId[];
+    unavailable: SourceId[];
+    sourceErrors: SourceError[];
+    raw: RawResult[];
+    status: "raw" | "raw_fallback";
+}): Result;
+export declare function synthesizedResult(input: {
+    query: string;
+    start: number;
+    requested: SourceId[];
+    queried: SourceId[];
+    unavailable: SourceId[];
+    sourceErrors: SourceError[];
+    raw: RawResult[];
+    synthesis: Synthesis;
+}): Result;