@stratusagent/search 0.11.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stratus Labs
+
+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,271 @@
+# @stratusagent/search
+
+**`web.search`: the contract, not a backend.** One tool name, one option
+meaning, one result shape — so two independently written search plugins are
+interchangeable behind one soul allowlist, and swapping vendors changes no
+soul, no skill, and no result shape.
+
+This package ships **no backend and reaches no vendor.** Every backend needs
+an API key and a commercial relationship, so core ships `web.fetch` and the
+ecosystem ships `web.search` ([`plugins.md`](../../docs/architecture/plugins.md)).
+What has to be first-party is the half that makes the other half worth
+anything.
+
+## For an operator
+
+You need a backend plugin. Install it, enable it in a trusted config, and
+store the key:
+
+```bash
+npm install -g stratus-plugin-somesearch
+printf %s "$SEARCH_KEY" | stratus credential set search.apiKey
+```
+
+```jsonc
+// ~/.stratus/config.json — a trusted config only
+{
+  "plugins": {
+    "stratus-plugin-somesearch": { "enabled": true, "maxSearchesPerDay": 200 }
+  }
+}
+```
+
+Then each agent's soul opts in, on both gates — the tool and the credential:
+
+```markdown
+---
+id: ava
+tools: [web.fetch, web.search]
+credentials: [search.apiKey]
+---
+```
+
+`tools: [web.*]` picks up search too, with no soul edit, which is the reason
+the glob exists. The `credentials:` line is separate and is **not** optional:
+without it every call answers "Agent ava is not allowed to access credential:
+search.apiKey".
+
+**Two backends cannot be enabled at once.** Both contribute `web.search`, and
+a tool name is unique per install, so that is a load-time error naming both
+packages. A deployment that genuinely needs two backends wants two daemons.
+
+### Settings every backend accepts
+
+A backend's manifest must declare these in its `config` schema, because they
+are read by the shared tool rather than by the backend's own code. All of
+them take a per-agent override in the `agents` sub-block.
+
+| Key | Default | What |
+| --- | --- | --- |
+| `maxSearchesPerDay` | `200` | Calls one agent may make in a UTC day. A query acts on nothing, but a metered API costs money and an agent in a loop can spend it. `0` refuses every call, which is how you turn one agent's search off without editing its soul. There is deliberately no "uncapped" — set a large number if that is what you mean. |
+| `allowedHosts` | none | Hosts exempt from the address check. What a self-hosted backend on `localhost` needs. |
+| `allowPrivateAddresses` | `false` | Reach any non-global address. Turns the SSRF protection off rather than adjusting it. |
+
+The cap is **kept in the daemon's process**, so a restart forgives the count.
+That is stated rather than hidden: its job is to stop a runaway loop, and a
+loop lives inside one daemon's lifetime.
+
+### The credential is one name, whatever the vendor
+
+`search.apiKey`. Always. A Brave adapter asking for `BRAVE_API_KEY` and a
+Tavily adapter asking for `TAVILY_API_KEY` would mean swapping backends edits
+**every soul in the fleet**, even though the `web.search` allowlist entry
+never moved.
+
+Two corollaries. Something that is *not* secret — a Google CSE engine id, a
+SearXNG base URL — goes in the plugin's config block, which is not
+soul-scoped. And a backend needing **no** credential is legitimate: a
+self-hosted instance never calls `get`, and is conforming rather than broken.
+
+A key belongs in the credential store, never as a literal in the config
+block — a key in `stratus.config.json` is a key in a file people commit.
+
+## For a backend author
+
+Implement one method. Everything else — the tool name, the schema, the
+option parsing, the filtering, the envelope, the credential seam, the address
+policy — is this package's, which is what makes your backend swappable with
+somebody else's.
+
+```ts
+import {
+  createWebSearchTool,
+  defineSearchProvider,
+  SEARCH_CREDENTIAL_NAME,
+} from '@stratusagent/search';
+import { requestThroughPolicy } from '@stratusagent/egress';
+import type { JsonObject, Plugin } from '@stratusagent/core';
+
+const createBackend = (config: JsonObject) => defineSearchProvider({
+  name: 'somesearch',
+  async search(query, options, context) {
+    const key = await context.credentials.get(SEARCH_CREDENTIAL_NAME);
+    const url = new URL('https://api.somesearch.example/v1/search');
+    url.searchParams.set('q', query);          // literal text — see below
+    url.searchParams.set('count', String(options.count));
+    if (options.site) url.searchParams.set('host', options.site);
+    if (options.freshness) url.searchParams.set('since', options.freshness.since);
+
+    // Every request through the policy you were handed. Never derive one.
+    const response = await requestThroughPolicy(url.href, {
+      policy: context.policy,
+      headers: { 'x-api-key': key },
+      ...(context.signal ? { signal: context.signal } : {}),
+    });
+    if (response.status !== 200) {
+      throw new Error(`The somesearch API answered ${response.status}.`);
+    }
+    return (JSON.parse(response.body).results ?? []).map((row) => ({
+      title: row.title,
+      url: row.url,
+      snippet: row.description,
+      publishedAt: row.published,
+    }));
+  },
+});
+
+export const createPlugin = (config: JsonObject): Plugin => ({
+  name: 'stratus-plugin-somesearch',
+  setup(context) {
+    context.tools.register(createWebSearchTool({
+      provider: createBackend(config),
+      config,
+      ...(context.credentials ? { credentials: context.credentials } : {}),
+      // The daemon's log records that a search ran and against which
+      // provider — never the query, which is user content.
+      onSearch: (record) => context.log?.(`web.search via ${record.provider} — ${record.results} result(s)`),
+    }));
+  },
+});
+```
+
+Your `package.json` manifest declares the tool and the credential:
+
+```jsonc
+"stratus": {
+  "pluginVersion": 1,
+  "contributes": { "tools": [{ "name": "web.search", "risk": "safe" }] },
+  "credentials": ["search.apiKey"],
+  "config": {
+    "type": "object",
+    "properties": {
+      "maxSearchesPerDay": { "type": "integer" },
+      "allowedHosts": { "type": "array", "items": { "type": "string" } },
+      "allowPrivateAddresses": { "type": "boolean" }
+    },
+    "additionalProperties": false
+  }
+}
+```
+
+Declare `risk: "safe"` if you like — **it will register `gated` anyway.**
+`safe` means "run this unattended, with nobody watching", and that is not a
+claim the code being judged gets to make about itself; the third-party floor
+applies to `web.*` exactly as it does everywhere else.
+
+### The options, pinned
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `query` | `string`, required, non-empty | **Literal text.** Do whatever your provider requires — escaping, quoting, a literal-search parameter — so the upstream searches for the characters given rather than parsing operators out of them. An unbalanced quote is a search for a quote character, not a syntax error. |
+| `count` | `integer`, 1–50, default 10 | A **maximum**. Returning fewer is normal; returning more is a contract violation, and this package truncates. |
+| `site` | one normalized hostname | Matches that host and anything under it, on label boundaries: `example.com` matches `docs.example.com` and **not** `notexample.com`. Already lower-cased, trailing dot removed, IDN in A-label form. Not a query operator — never splice `site:` into the query. |
+| `freshness` | `{ duration, ms, since }` | An age, resolved to an instant once per call. `since` is the oldest a result may be. |
+
+A call carrying any **other** field is refused naming it. The caller is a
+model writing JSON, so `freshnes: "P7D"` is a realistic mistake — and read as
+"no freshness filter" it runs an unrestricted search that *succeeds*, after
+which the agent says the answer is recent. A dropped option is a silently
+ignored one arriving a step earlier, and this table is strict for that reason
+throughout.
+
+### What `publishedAt` may be
+
+An **ISO 8601 instant**, and the shape is checked before anything is parsed
+— because `new Date(value)` is not a validator. It reads `03/04/2026` as
+4 March without ever saying whether the backend meant March or April, and it
+silently *corrects* `2026-02-30` into 2 March. A lenient parse therefore does
+not fail to date a result, it **invents** a date, and a `freshness` filter
+then keeps or drops the result on the strength of it.
+
+| Accepted | Read as |
+| --- | --- |
+| `2026-09-01T09:00:00Z` | itself |
+| `2026-09-01T11:00:00+02:00`, `…+0200` | the same instant, in UTC |
+| `2026-09-01` | UTC midnight |
+
+Everything else becomes absent, which under `freshness` means the result is
+dropped: a locale-formatted date, a day that does not exist, and a
+**zone-less** `2026-09-01T10:00:00` — that last one is *local* time to
+whatever machine parses it, so the same string is two different instants on
+two daemons, which is the disagreement this package exists to remove. Convert
+your vendor's format; that is the one job a backend cannot hand back.
+
+A date with no time is accepted rather than refused because plenty of
+backends only have a day, and refusing them would silently empty every
+`freshness` search against such a backend. Reading it as midnight errs
+towards calling a page slightly older than it is, which is the safe
+direction.
+
+Results older than `freshness` are excluded, **and so are results with no
+known date** — which is the case every backend produces without being asked.
+Leaving that unsaid would let two conforming adapters return different sets
+for identical calls. The agent asked for recent results and will say the
+answer is recent, and "we could not determine a date" is not evidence that it
+is. The exclusion applies *only* when `freshness` is set.
+
+**Refuse rather than approximate.** A backend that silently ignores an option
+is worse than one that fails. Declare what you cannot honor and the call is
+refused naming it, before a request is spent:
+
+```ts
+defineSearchProvider({ name: 'somesearch', unsupported: ['freshness'], search })
+```
+
+Omitting `unsupported` means you honor everything, which fails towards the
+contract: you opt out deliberately rather than being quietly excused.
+
+### What you do not have to get right
+
+The shared tool applies `count`, `site`, and `freshness` to whatever you
+return, validates every result URL against the address policy, strips markup
+from snippets, and turns `publishedAt` into a UTC instant (dropping anything
+that will not parse, rather than guessing).
+
+Pass your vendor's decorated snippet straight through — highlight markup is
+expected. Inline formatting is **removed**, not replaced with a space,
+because vendors highlight the matched *substring*: `un<strong>expected</strong>`
+reads back as `unexpected`, and `<strong>kettle</strong>.` keeps its full
+stop attached. Anything that is not inline formatting becomes a space
+instead, so two table cells never fuse into `AlphaBeta`. Send the options upstream anyway
+where your vendor supports them — native filtering ranks better than a filter
+applied afterwards — but the guarantee does not rest on your having done so.
+
+Freshness is fixed-length only: `P7D`, `P4W`, `PT12H`, `PT30M`. `P1M` and
+`P1Y` are refused, because a month from 31 March and a year from 29 February
+each have more than one defensible answer, and an adapter that converted to
+30 or 365 days would disagree with one that did not — at boundaries,
+intermittently. The rejection is **positional**: `PT30M` is thirty minutes
+and is fine.
+
+## The result envelope
+
+```jsonc
+{
+  "query": "kettles",
+  "provider": "somesearch",
+  "results": [
+    { "title": "…", "url": "https://…", "snippet": "…", "publishedAt": "2026-09-01T09:00:00.000Z" }
+  ],
+  "untrusted": true,
+  "untrustedNote": "Titles and snippets below were written by the pages that own them…"
+}
+```
+
+Snippets are attacker-controlled text: written by whoever owns the page,
+selected by a third-party ranker, and handed to a model that is about to
+decide what to do next. **This does not solve prompt injection** and does not
+claim to — it marks the boundary, because doing so is nearly free here and a
+retrofit across every tool that returns third-party text is not. Whether the
+marking should become a kernel concept that `web.fetch` and the MCP bridge
+share is [13](../../docs/roadmap/13-search.md)'s open question, still open.

package/dist/contract.d.ts

@@ -0,0 +1,171 @@
+/**
+ * What a search backend implements, and what it is handed per call.
+ *
+ * Published from this repository, implemented outside it. Every backend
+ * needs a vendor key and a commercial relationship, so the backends belong
+ * to the ecosystem — but the *shape* has to be first-party or the ecosystem
+ * is worth nothing: two independently written plugins are interchangeable
+ * only if a soul allowlisting `web.search` gets the same tool, the same
+ * options, and the same results whichever one is installed.
+ */
+import type { ScopedCredentials } from '@stratusagent/core';
+import type { EgressPolicy } from '@stratusagent/egress';
+/** The tool name, in the `web` namespace on purpose — see the README. */
+export declare const WEB_SEARCH_TOOL_NAME = "web.search";
+/**
+ * The one credential name every backend asks for, whatever vendor is
+ * behind it.
+ *
+ * This is not tidiness. A soul's `credentials` list is enforced by the
+ * `CredentialResolver`, so a Brave adapter asking for `BRAVE_API_KEY` and a
+ * Tavily adapter asking for `TAVILY_API_KEY` would mean swapping backends
+ * edits every soul in the fleet — even though the `web.search` allowlist
+ * entry never moved. One name is what makes the swap free.
+ *
+ * A backend needing something that is not secret (a Google CSE engine id, a
+ * SearXNG base URL) puts it in the plugin's config block, which is not
+ * soul-scoped. A backend needing no credential at all never calls `get`,
+ * and is conforming rather than broken.
+ */
+export declare const SEARCH_CREDENTIAL_NAME = "search.apiKey";
+/**
+ * The options a backend may refuse by name.
+ *
+ * `count` is absent on purpose: it is a maximum, and this package truncates
+ * to it after the fact, so every backend honors it whether or not its
+ * vendor has a parameter for it.
+ */
+export type SearchOptionName = 'site' | 'freshness';
+/**
+ * An age, resolved once per call so every part of the request agrees on
+ * what "now" was.
+ *
+ * All three forms are given because backends need different ones: some take
+ * a coarse enum, some take a date range, and the filter this package
+ * applies afterwards needs the instant.
+ */
+export interface SearchFreshness {
+    /** The ISO 8601 duration as the caller wrote it, normalized to upper case (`P7D`). */
+    duration: string;
+    /** That duration in milliseconds. Always a fixed length — see `parseFreshnessDuration`. */
+    ms: number;
+    /** The oldest instant a result may carry, as a UTC ISO 8601 instant. */
+    since: string;
+}
+/**
+ * One call's options, already parsed, validated, and normalized. A backend
+ * never sees the agent's raw input — that is the point of the shape.
+ */
+export interface SearchOptions {
+    /**
+     * A **maximum**. Returning fewer is normal; returning more is a contract
+     * violation, and this package truncates rather than trusting.
+     */
+    count: number;
+    /**
+     * One normalized hostname — lower case, no trailing dot, IDN in its
+     * A-label form. Matches that host and anything under it on label
+     * boundaries: `example.com` matches `docs.example.com` and never
+     * `notexample.com`.
+     *
+     * Not a query operator. A backend without native site filtering must not
+     * splice `site:` into the query — the query is literal text — and can
+     * leave the filtering to this package, which applies it either way.
+     */
+    site?: string;
+    /**
+     * Results older than this are excluded, **and so are results with no
+     * known date**. A backend that cannot honor it declares `freshness` in
+     * `unsupported` rather than ignoring it: an agent that asked for recent
+     * results will say the answer is recent.
+     */
+    freshness?: SearchFreshness;
+}
+/**
+ * What one search call is handed besides the query.
+ *
+ * The third parameter is what makes per-agent keys possible at all.
+ * `CredentialResolver.resolve` takes an `AgentDefinition`, so a
+ * `search(query, options)` seam would leave one shared adapter instance no
+ * way to reach the calling agent's key except a factory outside the
+ * contract or mutable global state.
+ */
+export interface SearchContext {
+    /**
+     * Already bound to the calling agent, and `get(name)` is the whole
+     * surface. An adapter has no way to *name* another agent, so it has no
+     * way to reach another agent's key — where handing it an
+     * `AgentDefinition` and a resolver would make agent isolation something
+     * every third-party backend author has to not get wrong.
+     */
+    credentials: ScopedCredentials;
+    /**
+     * The address policy every request this call makes must go through,
+     * resolved for the calling agent. Backends do not derive it: pass it
+     * straight to `requestThroughPolicy` from `@stratusagent/egress`. A
+     * self-hosted backend on `http://localhost:8888` is a legitimate
+     * configuration and a deliberate allowance, which is exactly the
+     * decision this policy already carries.
+     */
+    policy: EgressPolicy;
+    /**
+     * The turn's. A cancelled turn must stop the HTTP request, not merely
+     * stop waiting on it.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * One result, after the backend has reshaped whatever its vendor returned.
+ *
+ * A backend's raw payload never reaches the agent. This is the whole value
+ * of specifying the step: a provider that reshapes its JSON must not
+ * reshape what every soul and skill in the fleet was written against.
+ */
+export interface SearchResult {
+    title: string;
+    /** Absolute, `http`/`https` only. Validated against the address policy before an agent sees it. */
+    url: string;
+    /** Plain text. Markup is stripped by this package, so a backend may pass its vendor's decorated string through. */
+    snippet?: string;
+    /**
+     * An ISO 8601 instant in UTC when the backend has one, and absent when it
+     * does not — never a guess, never a locale-formatted date. Anything that
+     * will not parse as an instant is treated as absent, which under
+     * `freshness` means the result is dropped.
+     */
+    publishedAt?: string;
+}
+export interface SearchProvider {
+    /**
+     * What this backend is, for the daemon's log and the result envelope —
+     * `brave`, `tavily`, `searxng`. Not a URL and not a secret: it is written
+     * to a log an operator shares.
+     */
+    readonly name: string;
+    /**
+     * Options this backend cannot honor. A call using one is refused naming
+     * it, before a request is made.
+     *
+     * Omitted means "all of them", which is the right default because it
+     * fails towards the contract: a backend opts *out* deliberately rather
+     * than being quietly excused for having forgotten. Refusing beats
+     * approximating — a backend that silently ignored `freshness` would be
+     * worse than one that failed, because the agent's next sentence states
+     * the result is recent.
+     */
+    readonly unsupported?: readonly SearchOptionName[];
+    search(query: string, options: SearchOptions, context: SearchContext): Promise<SearchResult[]>;
+}
+export interface SearchProviderDefinition {
+    name: string;
+    unsupported?: readonly SearchOptionName[];
+    search(query: string, options: SearchOptions, context: SearchContext): Promise<SearchResult[]>;
+}
+/**
+ * Canonicalize a backend definition. The conditional spread is not
+ * decoration: `exactOptionalPropertyTypes` means an absent `unsupported`
+ * and one explicitly set to `undefined` are different types, and only the
+ * first one means "honors everything".
+ */
+export declare const defineSearchProvider: (definition: SearchProviderDefinition) => SearchProvider;
+//# sourceMappingURL=contract.d.ts.map

package/dist/contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.d.ts","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEzD,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,sBAAsB,kBAAkB,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,WAAW,CAAC;AAEpD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,sFAAsF;IACtF,QAAQ,EAAE,MAAM,CAAC;IACjB,2FAA2F;IAC3F,EAAE,EAAE,MAAM,CAAC;IACX,wEAAwE;IACxE,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;;OASG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,WAAW,EAAE,iBAAiB,CAAC;IAC/B;;;;;;;OAOG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,mGAAmG;IACnG,GAAG,EAAE,MAAM,CAAC;IACZ,mHAAmH;IACnH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACnD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAChG;AAED,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;IAC1C,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;CAChG;AAED;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAAI,YAAY,wBAAwB,KAAG,cAI1E,CAAC"}

package/dist/contract.js

@@ -0,0 +1,40 @@
+/**
+ * What a search backend implements, and what it is handed per call.
+ *
+ * Published from this repository, implemented outside it. Every backend
+ * needs a vendor key and a commercial relationship, so the backends belong
+ * to the ecosystem — but the *shape* has to be first-party or the ecosystem
+ * is worth nothing: two independently written plugins are interchangeable
+ * only if a soul allowlisting `web.search` gets the same tool, the same
+ * options, and the same results whichever one is installed.
+ */
+/** The tool name, in the `web` namespace on purpose — see the README. */
+export const WEB_SEARCH_TOOL_NAME = 'web.search';
+/**
+ * The one credential name every backend asks for, whatever vendor is
+ * behind it.
+ *
+ * This is not tidiness. A soul's `credentials` list is enforced by the
+ * `CredentialResolver`, so a Brave adapter asking for `BRAVE_API_KEY` and a
+ * Tavily adapter asking for `TAVILY_API_KEY` would mean swapping backends
+ * edits every soul in the fleet — even though the `web.search` allowlist
+ * entry never moved. One name is what makes the swap free.
+ *
+ * A backend needing something that is not secret (a Google CSE engine id, a
+ * SearXNG base URL) puts it in the plugin's config block, which is not
+ * soul-scoped. A backend needing no credential at all never calls `get`,
+ * and is conforming rather than broken.
+ */
+export const SEARCH_CREDENTIAL_NAME = 'search.apiKey';
+/**
+ * Canonicalize a backend definition. The conditional spread is not
+ * decoration: `exactOptionalPropertyTypes` means an absent `unsupported`
+ * and one explicitly set to `undefined` are different types, and only the
+ * first one means "honors everything".
+ */
+export const defineSearchProvider = (definition) => ({
+    name: definition.name,
+    ...(definition.unsupported !== undefined ? { unsupported: definition.unsupported } : {}),
+    search: definition.search,
+});
+//# sourceMappingURL=contract.js.map

package/dist/contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract.js","sourceRoot":"","sources":["../src/contract.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,yEAAyE;AACzE,MAAM,CAAC,MAAM,oBAAoB,GAAG,YAAY,CAAC;AAEjD;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,eAAe,CAAC;AA8ItD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,UAAoC,EAAkB,EAAE,CAAC,CAAC;IAC7F,IAAI,EAAE,UAAU,CAAC,IAAI;IACrB,GAAG,CAAC,UAAU,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACxF,MAAM,EAAE,UAAU,CAAC,MAAM;CAC1B,CAAC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `web.search`: the contract the ecosystem implements.
+ *
+ * The backends stay outside this repository — every one of them needs a
+ * vendor key and a commercial relationship, so core ships `web.fetch` and
+ * the ecosystem ships `web.search`. What has to be first-party is the half
+ * that makes the other half worth anything: a fixed tool name and a fixed
+ * result shape, so a soul or a skill written against search keeps working
+ * when the operator changes vendor.
+ *
+ * The contract is specified in `docs/roadmap/13-search.md` and summarized
+ * in this package's README; the code here is what enforces it.
+ */
+export { defineSearchProvider, SEARCH_CREDENTIAL_NAME, WEB_SEARCH_TOOL_NAME, type SearchContext, type SearchFreshness, type SearchOptionName, type SearchOptions, type SearchProvider, type SearchProviderDefinition, type SearchResult, } from './contract.ts';
+export { hostMatchesSite, normalizeSearchSite, parseFreshnessDuration, parseSearchCall, SearchOptionError, SEARCH_COUNT_DEFAULT, SEARCH_COUNT_MAX, type ParsedSearchCall, } from './options.ts';
+export { normalizePublishedAt, normalizeSearchResults, plainSnippet, } from './results.ts';
+export { createWebSearchTool, DEFAULT_MAX_SEARCHES_PER_DAY, UNTRUSTED_RESULT_NOTE, type SearchLogRecord, type WebSearchToolOptions, } from './tool.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,EACpB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,wBAAwB,EAC7B,KAAK,YAAY,GAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,KAAK,gBAAgB,GACtB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,GACb,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,mBAAmB,EACnB,4BAA4B,EAC5B,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,oBAAoB,GAC1B,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * `web.search`: the contract the ecosystem implements.
+ *
+ * The backends stay outside this repository — every one of them needs a
+ * vendor key and a commercial relationship, so core ships `web.fetch` and
+ * the ecosystem ships `web.search`. What has to be first-party is the half
+ * that makes the other half worth anything: a fixed tool name and a fixed
+ * result shape, so a soul or a skill written against search keeps working
+ * when the operator changes vendor.
+ *
+ * The contract is specified in `docs/roadmap/13-search.md` and summarized
+ * in this package's README; the code here is what enforces it.
+ */
+export { defineSearchProvider, SEARCH_CREDENTIAL_NAME, WEB_SEARCH_TOOL_NAME, } from "./contract.js";
+export { hostMatchesSite, normalizeSearchSite, parseFreshnessDuration, parseSearchCall, SearchOptionError, SEARCH_COUNT_DEFAULT, SEARCH_COUNT_MAX, } from "./options.js";
+export { normalizePublishedAt, normalizeSearchResults, plainSnippet, } from "./results.js";
+export { createWebSearchTool, DEFAULT_MAX_SEARCHES_PER_DAY, UNTRUSTED_RESULT_NOTE, } from "./tool.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,GAQrB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,eAAe,EACf,mBAAmB,EACnB,sBAAsB,EACtB,eAAe,EACf,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,GAEjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,YAAY,GACb,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,mBAAmB,EACnB,4BAA4B,EAC5B,qBAAqB,GAGtB,MAAM,WAAW,CAAC"}

package/dist/options.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Every option pinned to a meaning.
+ *
+ * Naming the options is not specifying them: two adapters can both satisfy
+ * `{ search(query, options) }` while accepting incompatible calls, which
+ * defeats the one criterion this package exists for. So the parsing lives
+ * here, once, in front of every backend — a call that means one thing on
+ * Brave means the same thing on SearXNG because neither of them parsed it.
+ */
+import type { JsonObject } from '@stratusagent/core';
+import { type SearchOptions } from './contract.ts';
+export declare const SEARCH_COUNT_DEFAULT = 10;
+export declare const SEARCH_COUNT_MAX = 50;
+/**
+ * A call this contract refuses. Exported because a backend throws it too:
+ * an option it declared `unsupported` and a value its vendor rejects are
+ * the same kind of answer to the agent.
+ */
+export declare class SearchOptionError extends Error {
+    constructor(message: string);
+}
+/**
+ * An ISO 8601 duration of fixed length, in milliseconds.
+ *
+ * **Fixed-length only, because `P1M` and `P1Y` are not one length.**
+ * Calendar arithmetic is where two conforming adapters part company:
+ * subtracting a month from 31 March, or a year from 29 February, has more
+ * than one defensible answer, and an adapter that converts to 30 or 365
+ * days instead disagrees with one that does not — at boundaries,
+ * intermittently, which is the worst way for a difference to show up.
+ * Rejecting the two ambiguous designators costs nothing a caller wants:
+ * `P30D` and `P365D` say what someone asking for "a month" or "a year" of
+ * search results actually means, and say it identically everywhere.
+ *
+ * `M` means two things and only one of them is rejected. ISO 8601 uses the
+ * same letter for months in the date portion and minutes after the `T`, so
+ * "reject `M`" would throw out `PT30M`, which is fixed-length and perfectly
+ * well defined.
+ */
+export declare const parseFreshnessDuration: (raw: string) => number;
+/**
+ * One hostname, normalized so two adapters compare the same string.
+ *
+ * **Hostname with label-boundary matching, not "registrable domain".** A
+ * registrable domain is the public-suffix-plus-one form, so
+ * `docs.example.com` is not one — an adapter enforcing that term would
+ * reject it or widen it up to `example.com`, silently broadening a search
+ * another adapter would keep narrow. This needs no public-suffix list,
+ * which is a dependency worth not acquiring. The two-label minimum is what
+ * stops `site: com`.
+ */
+export declare const normalizeSearchSite: (raw: string) => string;
+/**
+ * Whether one result's host is inside a `site` filter.
+ *
+ * On label boundaries, which is the whole rule: `notexample.com` ends with
+ * `example.com` as a string and is a different company.
+ */
+export declare const hostMatchesSite: (host: string, site: string) => boolean;
+export interface ParsedSearchCall {
+    query: string;
+    options: SearchOptions;
+}
+/**
+ * One tool call's input, turned into the options a backend receives.
+ *
+ * The query is passed through as **literal text**. "Verbatim" was the wrong
+ * word for it and the two halves could not both be true: most search APIs
+ * parse their own operators out of the query field, so handing the string
+ * over untouched is precisely what lets the upstream reinterpret `site:`,
+ * `OR`, a minus sign, or a quote — while a backend that escapes them is no
+ * longer passing anything verbatim. What is required is the *meaning*: the
+ * query is literal, and each backend does whatever its provider needs to
+ * make that true. An unbalanced quote is a search for a quote character,
+ * not a syntax error.
+ */
+export declare const parseSearchCall: (input: JsonObject, now: Date) => ParsedSearchCall;
+//# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,EAA8C,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AAE/F,eAAO,MAAM,oBAAoB,KAAK,CAAC;AACvC,eAAO,MAAM,gBAAgB,KAAK,CAAC;AAEnC;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAoBD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,sBAAsB,GAAI,KAAK,MAAM,KAAG,MAsBpD,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,mBAAmB,GAAI,KAAK,MAAM,KAAG,MA0BjD,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,EAAE,MAAM,MAAM,KAAG,OAG5D,CAAC;AAkBF,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,aAAa,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,UAAU,EAAE,KAAK,IAAI,KAAG,gBA6C9D,CAAC"}