opencode-specstream 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpecStream SAS
+
+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

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# opencode-specstream
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+SpecStream plugin for [OpenCode](https://opencode.ai). SpecStream is the live web data engine for teams and agents: describe a list in plain words ("roofing companies in Columbus, Ohio with their website and phone") and get every matching row, each with the page it came from. You see the price first, you approve a ceiling, and You pay for each result delivered. A search that finds nothing costs nothing.
+
+The plugin does two things when OpenCode starts:
+
+- adds the hosted SpecStream MCP server, `https://api.specstream.ai/mcp`, to your config as `specstream`
+- adds four agent skills: `compile` (read the request back), `review-work` (get the price), `approve-work` (approve it) and `continue-work` (read the rows, send them on, keep them current)
+
+## Install
+
+OpenCode 1.18.29 or newer, and OpenCode 2:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-specstream"]
+}
+```
+
+In OpenCode 2 the key is `plugins`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["opencode-specstream"]
+}
+```
+
+OpenCode installs the package on the next launch.
+
+## Sign in
+
+The server uses OAuth, so you do not paste a key. Run:
+
+```sh
+opencode mcp auth specstream
+```
+
+Your browser opens, you sign in to SpecStream, and OpenCode keeps the token. New accounts start with $10 of work free for 30 days, no card.
+
+To use an API key instead, for example on a machine with no browser, create one under **Agents & API** in the [workspace](https://specstream.ai/workspace) and set it where OpenCode starts:
+
+```sh
+export SPECSTREAM_API_KEY="ss_live_..."
+```
+
+With the variable set, the plugin sends it as a bearer header and turns the browser sign-in off. Give the key only what the task needs: its scope, projects, an expiry and a spending limit.
+
+## Use it
+
+Ask for a list:
+
+> Find food banks in Texas, with their annual revenue.
+
+The agent reads the request back, shows the quoted ceiling, and starts only after you say yes. Rows come back with their source pages, ready to export as CSV, Excel or JSON or to send to Google Sheets, Notion, Airtable, HubSpot or Salesforce.
+
+## Options
+
+Both parts are on by default. Turn either off with plugin options:
+
+```json
+{
+  "plugin": [["opencode-specstream", { "skills": false }]]
+}
+```
+
+| Option | Default | Effect |
+| --- | --- | --- |
+| `mcp` | `true` | `false` leaves the MCP server out |
+| `skills` | `true` | `false` leaves the four skills out |
+
+A `specstream` entry you already wrote under `mcp` is never replaced.
+
+## Develop
+
+```sh
+npm ci
+npm run check   # tsc --noEmit
+npm test
+```
+
+The skills in `skills/` are copies of the repository's [`skills/`](../../skills); a test fails when they drift. The package ships its TypeScript source, as OpenCode runs plugins directly.
+
+Docs: https://specstream.ai/docs/mcp. Licensed MIT.

package/index.ts

@@ -0,0 +1,5 @@
+import { server } from "./v1.ts";
+import { v2 } from "./v2.ts";
+
+// One entrypoint for both hosts: OpenCode 1 calls `server()`, OpenCode 2 reads `id` and `setup()`.
+export default { ...v2, server };

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "opencode-specstream",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "SpecStream plugin for OpenCode: adds the SpecStream MCP server and four agent skills, so your agent can ask for a list in plain words and get every matching row with its source.",
+  "type": "module",
+  "main": "index.ts",
+  "files": [
+    "index.ts",
+    "v1.ts",
+    "v2.ts",
+    "shared.ts",
+    "skills",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "specstream",
+    "mcp",
+    "lead-lists",
+    "web-data",
+    "web-search",
+    "agent-skills"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/specstream/specstream-tools.git",
+    "directory": "integrations/opencode"
+  },
+  "homepage": "https://specstream.ai/docs/mcp",
+  "author": {
+    "name": "SpecStream",
+    "url": "https://specstream.ai"
+  },
+  "engines": {
+    "opencode": "^1.18.29 || ^2.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --experimental-strip-types --disable-warning=ExperimentalWarning --test test/plugin.test.ts"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.18.34",
+    "@opencode/plugin": "^2.0.23",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}

package/shared.ts

@@ -0,0 +1,54 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const MCP_NAME = "specstream";
+export const MCP_URL = "https://api.specstream.ai/mcp";
+
+export const skillsDir = join(dirname(fileURLToPath(import.meta.url)), "skills");
+
+export type Options = { mcp?: boolean; skills?: boolean };
+
+export type RemoteServer = {
+  type: "remote";
+  url: string;
+  headers?: Record<string, string>;
+  oauth?: false;
+};
+
+/** Reads a plugin option that defaults to on. Only an explicit `false` turns it off. */
+export function enabled(options: unknown, key: keyof Options): boolean {
+  if (typeof options !== "object" || options === null) return true;
+  return (options as Options)[key] !== false;
+}
+
+/**
+ * The hosted server signs people in through the browser (OAuth), so no key is needed.
+ * A SPECSTREAM_API_KEY in the environment switches to a bearer header, for machines with no browser.
+ */
+export function remoteServer(env: Record<string, string | undefined> = process.env): RemoteServer {
+  const key = env.SPECSTREAM_API_KEY?.trim();
+  if (!key) return { type: "remote", url: MCP_URL };
+  return { type: "remote", url: MCP_URL, headers: { Authorization: `Bearer ${key}` }, oauth: false };
+}
+
+export type Skill = { id: string; name: string; description: string; path: string; content: string };
+
+/** Reads one skill file: single-line `name` and `description` frontmatter, then the body. */
+export function parseSkill(file: string): Skill {
+  const raw = readFileSync(file, "utf8");
+  const fence = raw.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!fence) throw new Error(`${file} has no frontmatter`);
+  const field = (key: string) =>
+    fence[1].match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1]?.trim().replace(/^(["'])(.*)\1$/, "$2") ?? "";
+  const name = field("name");
+  if (!name) throw new Error(`${file} has no name`);
+  return { id: name, name, description: field("description"), path: file, content: raw.slice(fence[0].length).trim() };
+}
+
+export function bundledSkills(root: string = skillsDir): Skill[] {
+  return readdirSync(root, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => parseSkill(join(root, entry.name, "SKILL.md")))
+    .sort((a, b) => a.name.localeCompare(b.name));
+}

package/skills/approve-work/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: approve-work
+description: Approve an exact price, up to the maximum the person set. This starts paid work.
+---
+
+# Approve a price
+
+SpecStream is the live web data engine for teams and agents. Use the configured MCP server at `https://api.specstream.ai/mcp`.
+
+`authorize_capacity_work` starts paid work, so treat it as a write. It needs the reviewed `quote_id` and `quote_hash`, the approved maximum as an integer in `confirm_max_cents`, and a stable `idempotency_key`. A standing project or agent authority must cover this exact scope and limit. A funded account is not enough.
+
+Save the same key before you send the call. If the response is unclear, recover the same work with `get_capacity_request` or `get_capacity_quote`. Never create a new key, price or run just to recover a lost response. A price that expired or changed needs a new approval.
+
+Do not top up, subscribe, add a seat or open a payment page. If the balance or the authority is missing, say exactly what is missing and keep the request.
+
+Use `get_find` for progress. Rows appear while the run works, and a run can be stopped and keeps what it found. Only delivered matches are charged. Unsure results stay unsure.

package/skills/compile/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: compile
+description: Read a plain-English request back to the person before anything runs. No price, no work.
+---
+
+# Read the request
+
+SpecStream is the live web data engine for teams and agents. Use the configured MCP server at `https://api.specstream.ai/mcp`.
+
+Use `compile` to read the person's request. Say back what it found: the kind of thing, the conditions, the details to bring back and the quantity. Separate the conditions that must hold from the details that are nice to have. Use `edit_spec` for a deliberate change. Never drop a hard condition quietly, and never treat missing evidence as a no. Reading a request does not start any work.
+
+Suggest requests that work well: local businesses with ratings, companies from registries, grants, tenders, clinical trials, papers, datasets, regulations, vulnerabilities, apps, repositories, packages, podcasts and books. Companies that use a tool, funding and new-executive signals, US nonprofits and UK financial firms by FCA status also work. If someone asks for people by job title, say that results may be few. `list_request_templates` returns requests that already work for each kind.
+
+The same saved request can be revised, branched, compared and shared, in the workspace or through this agent. Never ask for an API key in chat. Use the connector's own sign-in.

package/skills/continue-work/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: continue-work
+description: Read the finished rows with the page behind each fact, send them where the person works, and start new work only on purpose.
+---
+
+# Read, send and continue
+
+SpecStream is the live web data engine for teams and agents. Use the configured MCP server at `https://api.specstream.ai/mcp`.
+
+Read `list_find_rows` and follow each `next_cursor` through the `cursor` argument until it is null. The first page is not the whole result. Open `get_find_decisions` to show each condition check with the value observed, its source and the time it was read. Never invent links or fill in unknown facts. Keep the original read times and do not call reused evidence fresh.
+
+When the person asks, `send_to_destination` sends selected results to Google Sheets, Excel, Notion, Airtable, HubSpot, Salesforce or an Outlook draft. An Outlook draft lands in the person's own Drafts folder and is never sent. `export_find` makes a download link as CSV, Excel, JSON or HTML. Reading, exporting and sharing cost nothing.
+
+Finding more, adding facts or rechecking is new work with its own reviewed price. A recheck costs half the rate for a row that changed and 1 cent for a row that did not.
+
+`create_capacity_schedule` sets up a monitor and is a write. It needs a scope, a cadence, a validity period and limits per run and per period. A monitor reruns on its schedule and labels each change: still matches, no longer matches, unresolved or unavailable. Creating one does not fund it. A blocked or missed run is not an unchanged result and is not bought later. Pause or revoke a monitor when the owner says so.
+
+The workspace is the place to explore the full history. Do not present a small result widget as the whole workspace.

package/skills/review-work/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: review-work
+description: Get the real price for the exact request. Nothing runs.
+---
+
+# See the price
+
+SpecStream is the live web data engine for teams and agents. Use the configured MCP server at `https://api.specstream.ai/mcp`.
+
+Call `quote_capacity_work` with the `ast_hash` from `compile`, the operation, the number of results wanted, the useful minimum, and the original `parent_find_id`, `project_id` or `revision_id` when one applies. Asking for more uses `extend`, adding facts uses `add_facts` and rechecking uses `refresh`.
+
+Say the scope, the conditions, the maximum price and the expiry in text. Results cost 5 cents, 15 cents or $1 each, plus 5 cents for a person's email and 15 cents for a phone, and nothing when nothing matches. A price lasts 30 minutes. The price does not spend any balance and does not start a job.
+
+Use `get_capacity_balance` to read the balance. A balance is not permission to spend. Do not copy the maximum into an approval unless the person said to, or an existing bounded task already allows it. Plans and top-ups live in the person's account, not in chat.

package/v1.ts

@@ -0,0 +1,21 @@
+import type { Plugin } from "@opencode-ai/plugin";
+import { MCP_NAME, enabled, remoteServer, skillsDir } from "./shared.ts";
+
+/** OpenCode 1: the config hook adds the MCP server and the skills folder. Anything the user already set wins. */
+export const server: Plugin = async (_input, options) => {
+  return {
+    async config(input) {
+      if (enabled(options, "mcp")) {
+        input.mcp ??= {};
+        input.mcp[MCP_NAME] ??= remoteServer();
+      }
+      if (enabled(options, "skills")) {
+        // The V1 SDK's Config type does not declare skills.paths yet; OpenCode reads it.
+        const config = input as typeof input & { skills?: { paths?: string[] } };
+        config.skills ??= {};
+        config.skills.paths ??= [];
+        if (!config.skills.paths.includes(skillsDir)) config.skills.paths.push(skillsDir);
+      }
+    },
+  };
+};

package/v2.ts

@@ -0,0 +1,28 @@
+import type { Plugin } from "@opencode/plugin";
+import { MCP_NAME, bundledSkills, enabled, remoteServer } from "./shared.ts";
+
+/**
+ * OpenCode 2: the same two additions, through the MCP and skill transforms.
+ * Type-only import: OpenCode 1 loads this file too and has no `@opencode/plugin` to resolve.
+ */
+export const v2: Plugin.Plugin = {
+  id: "specstream",
+  async setup(ctx) {
+    if (enabled(ctx.options, "mcp")) {
+      await ctx.mcp.transform((editor) => {
+        if (!editor.get(MCP_NAME)) {
+          // The config schema classes are structural; a plain object is accepted at runtime.
+          editor.set(MCP_NAME, remoteServer() as never);
+        }
+      });
+    }
+    if (enabled(ctx.options, "skills")) {
+      const skills = bundledSkills();
+      await ctx.skill.transform((editor) => {
+        for (const skill of skills) {
+          if (!editor.get(skill.id)) editor.add(skill as never);
+        }
+      });
+    }
+  },
+};