@specstream/openclaw-plugin 0.0.0-stage → 0.1.0

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,94 @@
-# Temporary Holding Version
+# @specstream/openclaw-plugin
 
-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.
+Ask your OpenClaw agent for a list and get the whole list back. "Dental clinics in Lisbon with online booking, with their website and phone." Every row comes from the live web with the page it was read from, so you can open it and look. You pay per match, and a search that finds nothing costs nothing.
+
+[SpecStream](https://specstream.ai) is the live web data engine for teams and agents. This plugin gives OpenClaw two tools for it and, if you want the full conversation with SpecStream, four skills.
+
+## Install
+
+From ClawHub:
+
+```sh
+openclaw plugins install clawhub:@specstream/openclaw-plugin
+```
+
+Or from npm:
+
+```sh
+openclaw plugins install @specstream/openclaw-plugin
+```
+
+Needs OpenClaw 2026.10.3 or newer.
+
+## Set it up
+
+Create an API key under **Agents & API** in your [SpecStream workspace](https://specstream.ai/workspace). New accounts start with $10 of work free for 30 days, no card.
+
+The plugin reads the key from `SPECSTREAM_API_KEY`. To keep it in your OpenClaw config instead, store a SecretRef that points at the variable:
+
+```sh
+openclaw config set plugins.entries.specstream.config.apiKey \
+  '{"source":"env","provider":"default","id":"SPECSTREAM_API_KEY"}' --strict-json
+```
+
+Then set the most one list may cost. This is the number that lets you hand the agent a tool that spends money:
+
+```sh
+openclaw config set plugins.entries.specstream.config.maxPriceUsd 5
+```
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `apiKey` | `SPECSTREAM_API_KEY` | Your SpecStream API key, or a SecretRef |
+| `maxPriceUsd` | `5` | The price ceiling for one list, in US dollars |
+| `waitSeconds` | `300` | How long a find waits for a running list before it returns the rows so far |
+
+Give the key only what the task needs: its scope, projects, an expiry and a spending limit.
+
+## The tools
+
+### `specstream_find_list`
+
+| Input | |
+| --- | --- |
+| `request` | The list in plain words: what to find, where, what every row must meet, and the facts to bring back |
+| `max_results` | How many rows, 1 to 1000. Default 25 |
+| `max_price_usd` | Optional. A lower ceiling for this call |
+
+The tool reads the request, gets the price, and starts the run only if the quoted maximum is within your ceiling. The agent can ask for a lower ceiling on a call and can never raise yours. If the price is above the ceiling, nothing runs and the agent is told so. Results cost 10 cents, 30 cents or $1 each depending on the list, plus 10 cents for a person's email and 25 cents for a phone number, and nothing when nothing matches.
+
+It waits for the list, then returns JSON: `state`, `list_id`, `list_link` and `rows`. Each row has its columns plus `source_url` and `checked_at`. A retry of the same request with the same limits within the hour reaches the run it already started, so a flaky turn does not buy the list twice.
+
+### `specstream_get_list_rows`
+
+Reads every row of a list you already own, by `list_id`. Free. Use it when a big list was still running at the end of the wait.
+
+## Skills and the SpecStream server (optional)
+
+The plugin ships four skills: `specstream-compile` (read the request back), `specstream-review-work` (get the price), `specstream-approve-work` (approve it) and `specstream-continue-work` (read the rows, send them to Sheets, Notion, HubSpot and more, keep them current). They use the hosted SpecStream server and stay hidden until you add it:
+
+```sh
+openclaw mcp set specstream '{"url":"https://api.specstream.ai/mcp","transport":"streamable-http","auth":"oauth"}'
+openclaw mcp login specstream
+```
+
+The tools above work without it.
+
+## Example
+
+> Find food banks in Texas with their annual revenue. Keep it under $3.
+
+The agent calls `specstream_find_list` with `max_price_usd: 3`, and you get a table of food banks, each row with the page it came from, plus a link to open the list in your workspace.
+
+## Develop
+
+```sh
+npm ci
+npm run check            # tsc, source and tests
+npm test                 # vitest, fetch mocked
+npm run plugin:validate  # OpenClaw's own manifest validator
+```
+
+## License
+
+MIT

package/dist/client.js

@@ -0,0 +1,234 @@
+/** The SpecStream REST calls the tools share: read a request, price it, start it within a maximum, read its rows. */
+export const BASE_URL = "https://api.specstream.ai";
+export const USER_AGENT = "@specstream/openclaw-plugin/0.1.0";
+/** A list runs for up to about five minutes, so the default wait is just under that. */
+export const DEFAULT_WAIT_SECONDS = 300;
+export const DEFAULT_POLL_INTERVAL_SECONDS = 3;
+export const DEFAULT_LOCALE = "en-US";
+export const MAX_RESULTS = 1000;
+const REQUEST_TIMEOUT_MS = 150_000;
+const FINISHED = new Set(["completed", "partial"]);
+const STOPPED = new Set(["failed", "cancelled", "canceled", "expired"]);
+/** Fields every row carries. A list column with one of these names is renamed so it cannot overwrite them. */
+const RESERVED = new Set(["list_id", "list_link", "position", "source_url", "checked_at"]);
+/** SpecStream refused a call or answered with something this plugin cannot read. */
+export class SpecStreamError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SpecStreamError";
+    }
+}
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function dollars(cents) {
+    return `$${(cents / 100).toFixed(2)}`;
+}
+export function listLink(findId) {
+    return `https://specstream.ai/workspace/collections/${encodeURIComponent(findId)}`;
+}
+/** Flattens one record into a row: each column label maps to what the list shows, plus where the row was read. */
+export function flattenRow(findId, record) {
+    const row = { list_id: findId, position: record.ordinal ?? null };
+    let source = null;
+    const cells = record.details?.length ? record.details : (record.cells ?? []);
+    for (const cell of cells) {
+        let label = String(cell.label || cell.column_id || "").trim();
+        if (!label)
+            continue;
+        if (RESERVED.has(label))
+            label = `${label} (column)`;
+        if (cell.absence)
+            row[label] = "";
+        else if (cell.display != null)
+            row[label] = cell.display;
+        else
+            row[label] = cell.value ?? "";
+        const provenance = cell.provenance || {};
+        if (source === null && String(provenance.source_url || "").startsWith("http"))
+            source = provenance;
+    }
+    row.source_url = source ? (source.source_url ?? "") : "";
+    row.checked_at = source ? (source.observed_at ?? "") : "";
+    row.list_link = listLink(findId);
+    return row;
+}
+async function sha256Hex(text) {
+    const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function errorMessage(response, raw) {
+    let payload = {};
+    try {
+        payload = JSON.parse(raw || "{}");
+    }
+    catch {
+        payload = {};
+    }
+    const detail = isObject(payload) ? payload.error : undefined;
+    const message = isObject(detail) ? detail.message : typeof detail === "string" ? detail : undefined;
+    return `SpecStream answered ${response.status}: ${message || response.statusText}`;
+}
+export class SpecStreamClient {
+    baseUrl;
+    apiKey;
+    fetchImpl;
+    sleep;
+    now;
+    constructor(options) {
+        this.apiKey = options.apiKey.trim();
+        this.baseUrl = (options.baseUrl ?? BASE_URL).replace(/\/+$/, "");
+        this.fetchImpl = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+        this.sleep = options.sleep ?? wait;
+        this.now = options.now ?? Date.now;
+    }
+    async request(method, path, body, options = {}) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(new Error("timed out")), REQUEST_TIMEOUT_MS);
+        const outer = options.abortSignal;
+        const onAbort = () => controller.abort(outer?.reason);
+        if (outer?.aborted)
+            onAbort();
+        else
+            outer?.addEventListener("abort", onAbort, { once: true });
+        let response;
+        let raw;
+        try {
+            response = await this.fetchImpl(this.baseUrl + path, {
+                method,
+                body: body === undefined ? undefined : JSON.stringify(body),
+                headers: {
+                    Authorization: /^bearer /i.test(this.apiKey) ? this.apiKey : `Bearer ${this.apiKey}`,
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                    "User-Agent": USER_AGENT,
+                },
+                signal: controller.signal,
+            });
+            raw = await response.text();
+        }
+        catch (error) {
+            if (outer?.aborted)
+                throw error;
+            const reason = error instanceof Error ? (error.cause instanceof Error ? error.cause.message : error.message) : String(error);
+            throw new SpecStreamError(`Could not reach SpecStream: ${reason}`);
+        }
+        finally {
+            clearTimeout(timer);
+            outer?.removeEventListener("abort", onAbort);
+        }
+        if (!response.ok) {
+            if (options.allow404 && response.status === 404)
+                return null;
+            throw new SpecStreamError(errorMessage(response, raw));
+        }
+        let payload;
+        try {
+            payload = JSON.parse(raw || "{}");
+        }
+        catch {
+            payload = null;
+        }
+        const data = isObject(payload) ? payload.data : undefined;
+        if (!isObject(data))
+            throw new SpecStreamError("SpecStream returned a response this plugin could not read.");
+        return data;
+    }
+    /** Every row found so far for a list, following the pages. Reading is free. */
+    async results(findId, abortSignal) {
+        const rows = [];
+        let cursor = null;
+        let state = "running";
+        for (;;) {
+            const query = new URLSearchParams({ limit: "100", ...(cursor ? { cursor } : {}) });
+            const page = (await this.request("GET", `/v1/finds/${encodeURIComponent(findId)}/rows?${query}`, undefined, { abortSignal })) ?? {};
+            state = typeof page.status === "string" && page.status ? page.status : state;
+            for (const record of Array.isArray(page.rows) ? page.rows : [])
+                rows.push(flattenRow(findId, record));
+            const next = typeof page.next_cursor === "string" && page.next_cursor ? page.next_cursor : null;
+            if (!next || next === cursor)
+                break;
+            cursor = next;
+        }
+        return { list_id: findId, state, list_link: listLink(findId), row_count: rows.length, rows };
+    }
+    /** Reads the request, prices it, and runs it only if the most it can cost is within `maxPriceUsd`. */
+    async findList(request, options) {
+        const q = (request ?? "").trim();
+        if (!q)
+            throw new Error("Describe the list to find.");
+        const { maxResults, abortSignal } = options;
+        if (!Number.isInteger(maxResults) || maxResults < 1 || maxResults > MAX_RESULTS) {
+            throw new Error(`max_results must be a whole number from 1 to ${MAX_RESULTS}.`);
+        }
+        const maxCents = Math.round(Number(options.maxPriceUsd) * 100);
+        if (!(maxCents > 0))
+            throw new Error("The price ceiling must be greater than 0.");
+        // The key covers the hour, so an agent that retries a step reaches the run it already started and never buys the
+        // list twice. The previous hour is checked too, so a retry across the turn of the hour still finds that run.
+        const keyFor = async (at) => {
+            const hour = new Date(at).toISOString().slice(0, 13);
+            return `openclaw-${(await sha256Hex(`${q}|${maxResults}|${maxCents}|${hour}`)).slice(0, 32)}`;
+        };
+        const at = this.now();
+        const requestKey = await keyFor(at);
+        let existing = null;
+        for (const candidate of [requestKey, await keyFor(at - 3_600_000)]) {
+            existing = await this.request("GET", `/v1/capacity/requests/${encodeURIComponent(candidate)}`, undefined, {
+                allow404: true,
+                abortSignal,
+            });
+            if (existing?.find_id)
+                break;
+        }
+        let findId;
+        let maximumCents;
+        if (existing?.find_id) {
+            findId = String(existing.find_id);
+            maximumCents = Math.trunc(Number(existing.maximum_cents)) || maxCents;
+        }
+        else {
+            const reading = (await this.request("POST", "/v1/parse", { q, locale: options.locale ?? DEFAULT_LOCALE }, { abortSignal })) ?? {};
+            if (reading.status !== "runnable") {
+                const readAs = reading.canonical_sentence || q;
+                return {
+                    state: "needs_edit",
+                    request: q,
+                    message: `SpecStream needs a clearer request before it can price it. It read: "${readAs}". Add the place or what every row must meet.`,
+                };
+            }
+            const quote = (await this.request("POST", "/v1/capacity/quotes", { ast_hash: reading.ast_hash, operation: "find", requested_units: maxResults }, { abortSignal })) ?? {};
+            maximumCents = Math.trunc(Number(quote.maximum_cents)) || 0;
+            if (maximumCents > maxCents) {
+                return {
+                    state: "over_maximum",
+                    request: q,
+                    maximum_price_usd: maximumCents / 100,
+                    message: `Nothing ran: this list can cost up to ${dollars(maximumCents)}, above the ceiling of ${dollars(maxCents)}. Ask for fewer results, or tell the user the list needs a higher ceiling.`,
+                };
+            }
+            const run = (await this.request("POST", "/v1/capacity/executions", { quote_id: quote.quote_id, quote_hash: quote.quote_hash, confirm_max_cents: maximumCents, idempotency_key: requestKey }, { abortSignal })) ?? {};
+            if (!run.find_id)
+                throw new SpecStreamError("SpecStream returned a response this plugin could not read.");
+            findId = String(run.find_id);
+        }
+        const waitMs = Math.max(0, options.waitSeconds ?? DEFAULT_WAIT_SECONDS) * 1000;
+        const pollMs = Math.max(0, options.pollIntervalSeconds ?? DEFAULT_POLL_INTERVAL_SECONDS) * 1000;
+        const deadline = this.now() + waitMs;
+        let result;
+        for (;;) {
+            result = await this.results(findId, abortSignal);
+            if (FINISHED.has(result.state) || STOPPED.has(result.state) || this.now() >= deadline)
+                break;
+            if (abortSignal?.aborted)
+                throw abortSignal.reason ?? new Error("aborted");
+            await this.sleep(pollMs);
+        }
+        const found = { ...result, request: q, maximum_price_usd: maximumCents / 100 };
+        if (!FINISHED.has(result.state) && !STOPPED.has(result.state)) {
+            found.message = "Still running. Call specstream_get_list_rows with this list_id for the rest. Reading is free.";
+        }
+        return found;
+    }
+}

package/dist/config.js

@@ -0,0 +1,32 @@
+import { DEFAULT_WAIT_SECONDS, MAX_RESULTS } from "./client.js";
+export const DEFAULT_MAX_PRICE_USD = 5;
+export const DEFAULT_MAX_RESULTS = 25;
+export const MISSING_KEY_MESSAGE = "SpecStream has no API key. Set plugins.entries.specstream.config.apiKey (a SecretRef works) or the SPECSTREAM_API_KEY environment variable. " +
+    "Create a key under Agents & API in your SpecStream workspace.";
+/** Reads the plugin config, falling back to SPECSTREAM_API_KEY for the key. Throws when no key is set. */
+export function resolveConfig(config, env = process.env) {
+    const fromConfig = typeof config?.apiKey === "string" ? config.apiKey.trim() : "";
+    const apiKey = fromConfig || (env.SPECSTREAM_API_KEY ?? "").trim();
+    if (!apiKey)
+        throw new Error(MISSING_KEY_MESSAGE);
+    const maxPriceUsd = config?.maxPriceUsd ?? DEFAULT_MAX_PRICE_USD;
+    if (!Number.isFinite(maxPriceUsd) || maxPriceUsd <= 0) {
+        throw new Error("plugins.entries.specstream.config.maxPriceUsd must be greater than 0.");
+    }
+    return { apiKey, maxPriceUsd, waitSeconds: config?.waitSeconds ?? DEFAULT_WAIT_SECONDS };
+}
+/**
+ * The ceiling for one call. The model may ask for a lower ceiling than the configured one and never a higher one,
+ * because the configured value is the limit the person agreed to.
+ */
+export function effectiveCeiling(configuredUsd, requestedUsd) {
+    if (requestedUsd === undefined || !Number.isFinite(requestedUsd) || requestedUsd <= 0)
+        return configuredUsd;
+    return Math.min(configuredUsd, requestedUsd);
+}
+export function clampResults(requested) {
+    const whole = Math.trunc(Number(requested ?? DEFAULT_MAX_RESULTS));
+    if (!Number.isFinite(whole) || whole < 1)
+        return DEFAULT_MAX_RESULTS;
+    return Math.min(whole, MAX_RESULTS);
+}

package/dist/index.js

@@ -0,0 +1,81 @@
+import { Type } from "typebox";
+import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";
+import { SpecStreamClient, MAX_RESULTS } from "./client.js";
+import { clampResults, effectiveCeiling, resolveConfig, DEFAULT_MAX_PRICE_USD } from "./config.js";
+const configSchema = Type.Object({
+    apiKey: Type.Optional(Type.Union([Type.String(), Type.Record(Type.String(), Type.Unknown())], {
+        description: "SpecStream API key, or a SecretRef. Falls back to the SPECSTREAM_API_KEY environment variable.",
+    })),
+    maxPriceUsd: Type.Optional(Type.Number({
+        exclusiveMinimum: 0,
+        description: `The most one list may cost, in US dollars. Defaults to ${DEFAULT_MAX_PRICE_USD}. The model can lower it per call and never raise it.`,
+    })),
+    waitSeconds: Type.Optional(Type.Integer({ minimum: 10, maximum: 900, description: "How long specstream_find_list waits for a running list. Defaults to 300." })),
+}, { additionalProperties: false });
+export default defineToolPlugin({
+    id: "specstream",
+    name: "SpecStream",
+    description: "Ask for any list in plain words and get every matching row from the live web, each with its source page, priced per match.",
+    activation: { onStartup: false },
+    configSchema,
+    tools: (tool) => [
+        tool({
+            name: "specstream_find_list",
+            label: "Find a list",
+            description: [
+                "Find a list of real things on the live web and return every matching row, each with the page it was read from.",
+                "Use it when the answer is many things that meet conditions: companies in a city, local businesses with a service, funding filings, open grants, tenders, clinical trials, repositories, people in a role.",
+                "For one fact or a summary of one page, use a search tool instead.",
+                "It is priced per match. Rows that could not be confirmed are left out and not charged. The run starts only if the quoted maximum is within the user's price ceiling.",
+                "Returns JSON with state, list_id, list_link and rows (one object per match: its columns, source_url and checked_at).",
+                'state "over_maximum" means nothing ran because the price was above the ceiling: ask for fewer rows or tell the user.',
+                'state "needs_edit" means the request was too vague to price: add the place or the conditions.',
+                "If the list is still running, call specstream_get_list_rows with its list_id for the rest.",
+            ].join(" "),
+            parameters: Type.Object({
+                request: Type.String({
+                    minLength: 1,
+                    description: "The list in plain words: what to find, where, what every row must meet, and the facts to bring back. " +
+                        'Example: "Dental clinics in Lisbon with online booking, with their website and phone".',
+                }),
+                max_results: Type.Optional(Type.Integer({
+                    minimum: 1,
+                    maximum: MAX_RESULTS,
+                    description: "How many rows to find, 1 to 1000. Defaults to 25. Ask for what the task needs, because the price grows with the matches.",
+                })),
+                max_price_usd: Type.Optional(Type.Number({
+                    exclusiveMinimum: 0,
+                    description: "A lower price ceiling for this call, in US dollars. A value above the user's configured ceiling is ignored.",
+                })),
+            }),
+            execute: async ({ request, max_results, max_price_usd }, config, { signal }) => {
+                const settings = resolveConfig(config);
+                const client = new SpecStreamClient({ apiKey: settings.apiKey });
+                return client.findList(request, {
+                    maxResults: clampResults(max_results),
+                    maxPriceUsd: effectiveCeiling(settings.maxPriceUsd, max_price_usd),
+                    waitSeconds: settings.waitSeconds,
+                    abortSignal: signal,
+                });
+            },
+        }),
+        tool({
+            name: "specstream_get_list_rows",
+            label: "Read list rows",
+            description: [
+                "Read every row found so far for a SpecStream list the user already owns, such as one that was still running. Reading is free.",
+                "Returns JSON with state, list_id, list_link and rows, each with its columns, source_url and checked_at.",
+            ].join(" "),
+            parameters: Type.Object({
+                list_id: Type.String({
+                    minLength: 1,
+                    description: 'The list_id that specstream_find_list returned, like "fnd_gk5y3d0r97bvyz0t08zzh75kr6".',
+                }),
+            }),
+            execute: async ({ list_id }, config, { signal }) => {
+                const settings = resolveConfig(config);
+                return new SpecStreamClient({ apiKey: settings.apiKey }).results(list_id.trim(), signal);
+            },
+        }),
+    ],
+});

package/openclaw.plugin.json

@@ -0,0 +1,80 @@
+{
+  "id": "specstream",
+  "name": "SpecStream",
+  "description": "Ask for any list in plain words and get every matching row from the live web, each with its source page, priced per match.",
+  "categories": [
+    "data-analytics"
+  ],
+  "version": "0.1.0",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "apiKey": {
+        "anyOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "object",
+            "patternProperties": {
+              "^.*$": {}
+            }
+          }
+        ],
+        "description": "SpecStream API key, or a SecretRef. Falls back to the SPECSTREAM_API_KEY environment variable."
+      },
+      "maxPriceUsd": {
+        "type": "number",
+        "exclusiveMinimum": 0,
+        "description": "The most one list may cost, in US dollars. Defaults to 5. The model can lower it per call and never raise it."
+      },
+      "waitSeconds": {
+        "type": "integer",
+        "minimum": 10,
+        "maximum": 900,
+        "description": "How long specstream_find_list waits for a running list. Defaults to 300."
+      }
+    },
+    "additionalProperties": false
+  },
+  "activation": {
+    "onStartup": false
+  },
+  "skills": [
+    "./skills"
+  ],
+  "uiHints": {
+    "apiKey": {
+      "label": "SpecStream API key",
+      "help": "Create a key under Agents & API in your SpecStream workspace. Falls back to the SPECSTREAM_API_KEY environment variable.",
+      "sensitive": true,
+      "placeholder": "ss_live_..."
+    },
+    "maxPriceUsd": {
+      "label": "Price ceiling per list (USD)",
+      "help": "A list runs only if its quoted maximum is at or below this. The model can lower it per call and never raise it. Default 5."
+    },
+    "waitSeconds": {
+      "label": "Wait for a running list (seconds)",
+      "help": "How long a find waits before returning the rows so far. Default 300.",
+      "advanced": true
+    }
+  },
+  "configContracts": {
+    "secretInputs": {
+      "paths": [
+        {
+          "path": "apiKey",
+          "expected": "string",
+          "ownerKind": "capability"
+        }
+      ]
+    }
+  },
+  "contracts": {
+    "tools": [
+      "specstream_find_list",
+      "specstream_get_list_rows"
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@specstream/openclaw-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "SpecStream plugin for OpenClaw: ask for any list in plain words and get every matching row from the live web, each with its source page, priced per match.",
+  "type": "module",
+  "files": [
+    "dist",
+    "skills",
+    "assets",
+    "openclaw.plugin.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "specstream",
+    "lead-lists",
+    "web-data",
+    "live-web",
+    "agent-tools",
+    "mcp"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Specstreamai/specstream-tools.git",
+    "directory": "integrations/openclaw"
+  },
+  "homepage": "https://specstream.ai/docs/mcp",
+  "author": {
+    "name": "SpecStream",
+    "url": "https://specstream.ai"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "plugin:build": "npm run build && openclaw plugins build --entry ./dist/index.js",
+    "plugin:validate": "npm run build && openclaw plugins validate --entry ./dist/index.js",
+    "prepack": "npm run plugin:build"
+  },
+  "dependencies": {
+    "typebox": "1.3.34"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.10.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "openclaw": "2026.10.3",
+    "typescript": "5.9.3",
+    "vitest": "^3.2.0"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.10.3"
+    },
+    "build": {
+      "openclawVersion": "2026.10.3"
+    }
+  }
+}

package/skills/specstream-approve-work/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: specstream-approve-work
+description: Approve an exact price, up to the maximum the person set. This starts paid work.
+metadata: { "openclaw": { "requires": { "config": ["mcp.servers.specstream"] } } }
+---
+
+# 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/specstream-compile/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: specstream-compile
+description: Read a plain-English request back to the person before anything runs. No price, no work.
+metadata: { "openclaw": { "requires": { "config": ["mcp.servers.specstream"] } } }
+---
+
+# 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/specstream-continue-work/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: specstream-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.
+metadata: { "openclaw": { "requires": { "config": ["mcp.servers.specstream"] } } }
+---
+
+# 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. Rechecks cost half.
+
+`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/specstream-review-work/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: specstream-review-work
+description: Get the real price for the exact request. Nothing runs.
+metadata: { "openclaw": { "requires": { "config": ["mcp.servers.specstream"] } } }
+---
+
+# 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 10 cents, 30 cents or $1 each, plus 10 cents for a person's email and 25 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.