@stratusagent/tool-web 0.6.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,76 @@
+# @stratusagent/tool-web
+
+`web.fetch`: retrieve a URL and get back the text a reader would keep. No
+browser, no JavaScript, no Chromium — this is what an agent reaches for
+twenty times for every once it needs `browser.*`.
+
+## Install and enable
+
+```bash
+npm install @stratusagent/tool-web
+```
+
+```jsonc
+// ~/.stratus/config.json — a trusted config only
+{
+  "plugins": {
+    "@stratusagent/tool-web": { "enabled": true }
+  }
+}
+```
+
+Then the agent's soul decides, per identity:
+
+```markdown
+---
+id: ava
+tools: [web.fetch]
+---
+```
+
+## Risk model
+
+| Tool | Risk | What approval mode does |
+| --- | --- | --- |
+| `web.fetch` | `gated` | `interactive` asks at the terminal, `remote` asks in Slack, `headless` refuses. It reaches a service outside Stratus at an address the agent chose, which is the line 03 draws. |
+
+Approval decides *whether*; the address policy decides *where*, and it is
+not the same question. An approver looking at `https://example.com/report`
+has approved that URL — not the redirect it answers with.
+
+## Settings
+
+| Key | Default | What |
+| --- | --- | --- |
+| `allowedHosts` | none | Hosts exempt from the address check, by name or literal address. The narrow override: one internal service an agent is meant to reach. |
+| `allowPrivateAddresses` | `false` | Reach any non-global address. The trusted-workstation posture — it turns the SSRF protection off rather than adjusting it. |
+| `maxBytes` | `400000` | Stop reading here; the result says `truncated`. |
+| `timeoutMs` | `20000` | Give up on the whole exchange. |
+| `maxRedirects` | `5` | Hops to follow before refusing. |
+| `userAgent` | `StratusAgent/0.5 …` | What to send. |
+
+All of them can be set per agent under `agents`, and `allowedHosts` in
+particular should be: an exemption written once at the top level is an
+exemption every agent gets.
+
+## What it refuses, and where
+
+The address policy is `@stratusagent/egress`, **the same module
+`@stratusagent/tool-browser` uses** — not a copy of it. A second
+implementation would not drift into a style difference; the stale one would
+be an SSRF hole. Both packs are tested against the same table of hostile
+URLs, which is what fails if the module is ever forked.
+
+- **Schemes**: `http:` and `https:`. `file:`, `data:`, and `javascript:` are
+  refused before anything is fetched — this process can read the files a
+  `file:` URL names.
+- **Addresses**: every non-global address in both families — loopback,
+  RFC 1918, carrier-NAT, link-local (where cloud instance metadata lives),
+  IPv6 unique-local and link-local, multicast, and the IPv4-mapped, NAT64,
+  and 6to4 forms that write the same addresses a different way.
+- **Every hop**: redirects are followed one at a time and each one faces the
+  policy from scratch, so a public URL that answers `302 Location:
+  http://169.254.169.254/` is a refusal rather than a fetch.
+- **The connection itself**: the socket's own DNS resolution is the one that
+  gets checked. Resolving a name to validate it and letting the client
+  resolve it again to connect is DNS rebinding with extra steps.

package/dist/index.d.ts

@@ -0,0 +1,51 @@
+import type { JsonObject, Plugin } from '@stratusagent/core';
+import { type EgressPolicy } from '@stratusagent/egress';
+export { decodeEntities, extractTitle, htmlToText } from './readability.ts';
+export interface WebPluginConfig extends JsonObject {
+    /** Reach addresses that are not globally routable. See the README. */
+    allowPrivateAddresses?: boolean;
+    /** Hosts exempt from the address check, by name or literal address. */
+    allowedHosts?: string[];
+    maxBytes?: number;
+    timeoutMs?: number;
+    maxRedirects?: number;
+    userAgent?: string;
+}
+/**
+ * Fetch a URL, following redirects **one validated hop at a time**.
+ *
+ * The loop is here rather than in the HTTP client for one reason: every hop
+ * is a new request to a new host, and a client that followed redirects for
+ * us would resolve and connect to hosts nothing checked. An approved public
+ * URL that answers `302 Location: http://169.254.169.254/` is exactly the
+ * attack, and it is defeated by the second hop facing the policy the same
+ * way the first one did.
+ */
+export declare const fetchThroughPolicy: (rawUrl: string, options?: {
+    policy?: EgressPolicy;
+    maxBytes?: number;
+    timeoutMs?: number;
+    maxRedirects?: number;
+    userAgent?: string;
+    signal?: AbortSignal;
+}) => Promise<{
+    url: string;
+    status: number;
+    contentType: string;
+    body: string;
+    truncated: boolean;
+    hops: string[];
+}>;
+/**
+ * The `web` toolset: one tool, deliberately.
+ *
+ * This is the capability an agent reaches for twenty times for every once
+ * it needs a browser, and paying Chromium's startup and memory for it is
+ * the wrong trade. Search is not here and is not coming: every backend
+ * needs a vendor key and a commercial relationship, so `web.search` belongs
+ * to the ecosystem.
+ */
+export declare const createWebPlugin: (config?: JsonObject) => Plugin;
+/** The loader's ABI. See `docs/architecture/plugins.md`. */
+export declare const createPlugin: (config?: JsonObject) => Plugin;
+//# 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,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAiB,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAGL,KAAK,YAAY,EAClB,MAAM,sBAAsB,CAAC;AAK9B,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAO5E,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,sEAAsE;IACtE,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA8BD;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,MAAM,EACd,UAAS;IACP,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACjB,KACL,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CAmChH,CAAC;AAkDF;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,SAAQ,UAAe,KAAG,MAKxD,CAAC;AAEH,4DAA4D;AAC5D,eAAO,MAAM,YAAY,YARe,UAAU,KAAQ,MAQf,CAAC"}

package/dist/index.js

@@ -0,0 +1,135 @@
+import { assertRequestAllowed, requestThroughPolicy, } from '@stratusagent/egress';
+import { resolvePluginAgentConfig } from '@stratusagent/plugins';
+import { extractTitle, htmlToText } from "./readability.js";
+export { decodeEntities, extractTitle, htmlToText } from "./readability.js";
+const DEFAULT_MAX_BYTES = 400_000;
+const DEFAULT_TIMEOUT_MS = 20_000;
+const DEFAULT_MAX_REDIRECTS = 5;
+const DEFAULT_USER_AGENT = 'StratusAgent/0.5 (+https://github.com/stratuslabs/agent)';
+const asNumber = (value, fallback) => typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : fallback;
+const settingsFor = (config, session) => {
+    // Per call, from the session: an agent allowed to reach an internal host
+    // is a decision about that agent, and closing over it at setup would
+    // give the exemption to everyone.
+    const resolved = resolvePluginAgentConfig(config, session.agent.id);
+    const policy = {
+        ...(resolved.allowPrivateAddresses === true ? { allowPrivateAddresses: true } : {}),
+        ...(Array.isArray(resolved.allowedHosts)
+            ? { allowedHosts: resolved.allowedHosts.filter((entry) => typeof entry === 'string') }
+            : {}),
+    };
+    return {
+        policy,
+        maxBytes: asNumber(resolved.maxBytes, DEFAULT_MAX_BYTES),
+        timeoutMs: asNumber(resolved.timeoutMs, DEFAULT_TIMEOUT_MS),
+        maxRedirects: asNumber(resolved.maxRedirects, DEFAULT_MAX_REDIRECTS),
+        userAgent: typeof resolved.userAgent === 'string' ? resolved.userAgent : DEFAULT_USER_AGENT,
+    };
+};
+const isRedirect = (status) => status >= 300 && status < 400;
+const contentTypeOf = (headers) => String(headers['content-type'] ?? '').toLowerCase();
+/**
+ * Fetch a URL, following redirects **one validated hop at a time**.
+ *
+ * The loop is here rather than in the HTTP client for one reason: every hop
+ * is a new request to a new host, and a client that followed redirects for
+ * us would resolve and connect to hosts nothing checked. An approved public
+ * URL that answers `302 Location: http://169.254.169.254/` is exactly the
+ * attack, and it is defeated by the second hop facing the policy the same
+ * way the first one did.
+ */
+export const fetchThroughPolicy = async (rawUrl, options = {}) => {
+    const maxRedirects = options.maxRedirects ?? DEFAULT_MAX_REDIRECTS;
+    const hops = [];
+    let current = assertRequestAllowed(rawUrl, options.policy ?? {}).href;
+    for (let hop = 0; hop <= maxRedirects; hop += 1) {
+        hops.push(current);
+        const response = await requestThroughPolicy(current, {
+            ...(options.policy ? { policy: options.policy } : {}),
+            headers: { 'user-agent': options.userAgent ?? DEFAULT_USER_AGENT, accept: 'text/html,text/plain;q=0.9,*/*;q=0.5' },
+            ...(options.maxBytes === undefined ? {} : { maxBytes: options.maxBytes }),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            ...(options.signal ? { signal: options.signal } : {}),
+        });
+        const location = response.headers.location;
+        if (isRedirect(response.status) && typeof location === 'string' && location.length > 0) {
+            // Resolved against the current URL, then checked from scratch — a
+            // relative redirect is still a new destination.
+            const next = new URL(location, current).href;
+            current = assertRequestAllowed(next, options.policy ?? {}).href;
+            continue;
+        }
+        return {
+            url: current,
+            status: response.status,
+            contentType: contentTypeOf(response.headers),
+            body: response.body,
+            truncated: response.truncated,
+            hops,
+        };
+    }
+    throw new Error(`Too many redirects (${maxRedirects}) starting at ${rawUrl}`);
+};
+const createFetchTool = (config) => ({
+    name: 'web.fetch',
+    description: 'Retrieve a URL and return its readable text. No browser, no JavaScript.',
+    // Gated: it reaches a service outside Stratus, on an address an agent
+    // chose. The address policy decides *where*; approval decides *whether*.
+    risk: 'gated',
+    parameters: {
+        type: 'object',
+        properties: {
+            url: { type: 'string' },
+            maxBytes: { type: 'number' },
+            raw: { type: 'boolean', description: 'Return the body as received, without text extraction.' },
+        },
+        required: ['url'],
+    },
+    async execute(input, session, context) {
+        const url = typeof input.url === 'string' ? input.url : '';
+        if (!url) {
+            throw new Error('url is required.');
+        }
+        const settings = settingsFor(config, session);
+        const response = await fetchThroughPolicy(url, {
+            policy: settings.policy,
+            maxBytes: asNumber(input.maxBytes, settings.maxBytes),
+            timeoutMs: settings.timeoutMs,
+            maxRedirects: settings.maxRedirects,
+            userAgent: settings.userAgent,
+            ...(context?.signal ? { signal: context.signal } : {}),
+        });
+        const html = response.contentType.includes('html');
+        const text = input.raw === true || !html ? response.body : htmlToText(response.body);
+        const title = html ? extractTitle(response.body) : undefined;
+        return {
+            url: response.url,
+            status: response.status,
+            contentType: response.contentType,
+            ...(title ? { title } : {}),
+            // Named `redirects` rather than left implicit: an agent that followed
+            // a link somewhere else should be able to say where it ended up.
+            ...(response.hops.length > 1 ? { redirects: response.hops } : {}),
+            text,
+            truncated: response.truncated,
+        };
+    },
+});
+/**
+ * The `web` toolset: one tool, deliberately.
+ *
+ * This is the capability an agent reaches for twenty times for every once
+ * it needs a browser, and paying Chromium's startup and memory for it is
+ * the wrong trade. Search is not here and is not coming: every backend
+ * needs a vendor key and a commercial relationship, so `web.search` belongs
+ * to the ecosystem.
+ */
+export const createWebPlugin = (config = {}) => ({
+    name: '@stratusagent/tool-web',
+    setup(context) {
+        context.tools.register(createFetchTool(config));
+    },
+});
+/** The loader's ABI. See `docs/architecture/plugins.md`. */
+export const createPlugin = createWebPlugin;
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/readability.d.ts

@@ -0,0 +1,19 @@
+/**
+ * HTML to the text a reader would keep.
+ *
+ * Not a parser and not trying to be one: an agent asked for a page's
+ * content, and what it must not receive is fifty kilobytes of navigation,
+ * script, and styling with three sentences somewhere inside. So the
+ * elements that never carry the article are dropped whole, block
+ * boundaries become newlines, and everything else collapses to text.
+ *
+ * A real DOM would do better on a hostile page. It would also be a
+ * dependency, a parse of untrusted markup, and a second answer to what a
+ * page "is" — for a fetcher whose output is fed to a model as prose, this
+ * trade is the right one, and the failure mode is a worse extraction
+ * rather than an incorrect one.
+ */
+export declare const decodeEntities: (value: string) => string;
+export declare const extractTitle: (html: string) => string | undefined;
+export declare const htmlToText: (html: string) => string;
+//# sourceMappingURL=readability.d.ts.map

package/dist/readability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readability.d.ts","sourceRoot":"","sources":["../src/readability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAuCH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,MAW3C,CAAC;AAEL,eAAO,MAAM,YAAY,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,SAGpD,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,MAAM,MAAM,KAAG,MAwBzC,CAAC"}

package/dist/readability.js

@@ -0,0 +1,87 @@
+/**
+ * HTML to the text a reader would keep.
+ *
+ * Not a parser and not trying to be one: an agent asked for a page's
+ * content, and what it must not receive is fifty kilobytes of navigation,
+ * script, and styling with three sentences somewhere inside. So the
+ * elements that never carry the article are dropped whole, block
+ * boundaries become newlines, and everything else collapses to text.
+ *
+ * A real DOM would do better on a hostile page. It would also be a
+ * dependency, a parse of untrusted markup, and a second answer to what a
+ * page "is" — for a fetcher whose output is fed to a model as prose, this
+ * trade is the right one, and the failure mode is a worse extraction
+ * rather than an incorrect one.
+ */
+const DROPPED_ELEMENTS = [
+    'script',
+    'style',
+    'noscript',
+    'template',
+    'svg',
+    'canvas',
+    'iframe',
+    'nav',
+    'header',
+    'footer',
+    'aside',
+    'form',
+];
+const BLOCK_ELEMENTS = [
+    'p', 'div', 'section', 'article', 'main', 'br', 'hr',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+    'ul', 'ol', 'table', 'tr', 'blockquote', 'pre',
+];
+const NAMED_ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'",
+    nbsp: ' ',
+    mdash: '—',
+    ndash: '–',
+    hellip: '…',
+    rsquo: '’',
+    lsquo: '‘',
+    ldquo: '“',
+    rdquo: '”',
+};
+export const decodeEntities = (value) => value.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (match, entity) => {
+    if (entity.startsWith('#x') || entity.startsWith('#X')) {
+        const code = Number.parseInt(entity.slice(2), 16);
+        return Number.isFinite(code) ? String.fromCodePoint(code) : match;
+    }
+    if (entity.startsWith('#')) {
+        const code = Number.parseInt(entity.slice(1), 10);
+        return Number.isFinite(code) ? String.fromCodePoint(code) : match;
+    }
+    return NAMED_ENTITIES[entity.toLowerCase()] ?? match;
+});
+export const extractTitle = (html) => {
+    const match = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html);
+    return match?.[1] ? decodeEntities(match[1]).trim() : undefined;
+};
+export const htmlToText = (html) => {
+    let text = html.replace(/<!--[\s\S]*?-->/g, '');
+    for (const element of DROPPED_ELEMENTS) {
+        text = text.replace(new RegExp(`<${element}\\b[^>]*>[\\s\\S]*?</${element}>`, 'gi'), ' ');
+        // Unclosed or self-closing forms of the same elements.
+        text = text.replace(new RegExp(`<${element}\\b[^>]*/?>`, 'gi'), ' ');
+    }
+    text = text.replace(/<head\b[^>]*>[\s\S]*?<\/head>/gi, ' ');
+    text = text.replace(/<li\b[^>]*>/gi, '\n- ');
+    for (const element of BLOCK_ELEMENTS) {
+        text = text.replace(new RegExp(`</?${element}\\b[^>]*>`, 'gi'), '\n');
+    }
+    text = text.replace(/<[^>]+>/g, ' ');
+    text = decodeEntities(text);
+    return text
+        .split('\n')
+        .map((line) => line.replace(/[ \t ]+/g, ' ').trim())
+        .filter((line, index, lines) => line.length > 0 || (lines[index - 1] ?? '').length > 0)
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+};
+//# sourceMappingURL=readability.js.map

package/dist/readability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"readability.js","sourceRoot":"","sources":["../src/readability.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@stratusagent/tool-web",
+  "version": "0.6.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.13 <23 || >=23.4"
+  },
+  "dependencies": {
+    "@stratusagent/core": "0.6.0",
+    "@stratusagent/egress": "0.6.0",
+    "@stratusagent/plugins": "0.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.0",
+    "typescript": "^5.9.3"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stratuslabs/agent.git",
+    "directory": "packages/tool-web"
+  },
+  "description": "Web fetching for Stratus agents: retrieve a URL as readable text, with no browser and a shared address policy",
+  "keywords": [
+    "stratus",
+    "agent",
+    "ai",
+    "llm",
+    "stratus-plugin",
+    "tools",
+    "web"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "stratus": {
+    "pluginVersion": 1,
+    "contributes": {
+      "tools": [
+        {
+          "name": "web.fetch",
+          "risk": "gated"
+        }
+      ]
+    },
+    "config": {
+      "type": "object",
+      "properties": {
+        "allowPrivateAddresses": {
+          "type": "boolean"
+        },
+        "allowedHosts": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "maxBytes": {
+          "type": "integer"
+        },
+        "timeoutMs": {
+          "type": "integer"
+        },
+        "maxRedirects": {
+          "type": "integer"
+        },
+        "userAgent": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "typecheck": "tsc --noEmit --project tsconfig.test.json",
+    "test": "node --test --experimental-strip-types"
+  }
+}