@frockbot/plugin-web 0.0.0 → 0.1.1

package/README.md

@@ -1,3 +1,73 @@
 # @frockbot/plugin-web
 
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.
+The Web Package. It contributes one runtime Contribution (`./agent`) carrying
+one tool, **`web_fetch`**, and one provider-neutral contract (`./contract`) that
+a search provider Package implements.
+
+Row 47 of the parity register (`docs/research/grokbot-computer.md`) names web
+search, web fetch and image generation as first-class tools, but cites a section
+that is not in the register: **no input schema, bound, or error shape was ever
+measured** for any of them. Everything here is FrockBot's own contract, defined
+from first principles. No schema parity is claimed.
+
+## `web_fetch`
+
+|                |                                                                        |
+| -------------- | ---------------------------------------------------------------------- |
+| Capability     | `web-fetch`, kind `tool`, `connectionTypes: []`                        |
+| Input          | `url`, `max_bytes` ≤ 1 MiB, `format: "text" \| "markdown"`             |
+| Durable result | `{"url","finalUrl","status","contentType","bytes","truncated","text"}` |
+| Refusal        | `isError: true` with a stable reason code                              |
+| Effect class   | read-only, `idempotent: true`                                          |
+| Turn types     | all four (manifest v4 `admission`)                                     |
+
+`web_fetch` needs no Connection: reading a public page needs no credential. The
+Assignment is still the fence — the Contribution mounts nothing without an
+enabled Assignment of `web-fetch`.
+
+It is a plain outbound request, so it works while the User's Computer is
+hibernated and never wakes it. A page that needs a real browser is the
+Computer's job, not this tool's.
+
+## The outbound trust boundary
+
+The Bot's Durable Object can reach anything workerd can reach. `./ssrf.ts` is a
+pure classifier — a string in, a verdict out — and it runs before every hop and
+again on every redirect target:
+
+1. `https:` only. No `http:`, `data:`, `file:`, `blob:`, `ftp:`.
+2. The default port, or `443` stated explicitly.
+3. No `localhost`, `*.localhost`, `*.internal`, or bare label with no dot.
+4. No IP literal outside the public ranges. Literals are **normalized first**,
+   so `0177.0.0.1`, `2130706433`, `0x7f000001`, `127.1` and `::ffff:127.0.0.1`
+   are the same refusal as `127.0.0.1`. `169.254.169.254` — the cloud metadata
+   address — is inside `169.254.0.0/16`.
+5. No credentials in the URL. A fixed `User-Agent` and `Accept`; no `Cookie`,
+   no `Authorization`, and no header the model chose.
+6. `redirect: "manual"`, at most three hops, rules 1–5 re-run on each one.
+7. The response must declare a media type on the allow list (`text/html`,
+   `text/plain`, `text/markdown`, `application/json`,
+   `application/xhtml+xml`), and a declared length over `max_bytes` is refused
+   outright; the body is then read under a streaming cap and reports
+   `truncated` when it was cut short.
+8. A refusal carries a stable reason code — `ssrf-blocked-private-address`,
+   `web-fetch-blocked-content-type`, … — and **never names what a host resolved
+   to**.
+
+### Known limitation: DNS rebinding
+
+workerd exposes no resolve-then-connect hook, so a hostname cannot be pinned to
+the address the request will actually reach. A name that resolves to a public
+address at classification time and to `127.0.0.1` at connection time defeats
+every rule above. Classification is therefore exact for IP literals and for the
+known-internal name shapes, and best-effort for everything else. Closing the gap
+needs a platform primitive FrockBot does not have; it is recorded here rather
+than papered over.
+
+## `./contract` — `WebSearchV1`
+
+The `web_search` tool definition, its bounds, its DTO and its decoder live here
+so that a provider Package contributes the tool by supplying transport alone.
+`@frockbot/plugin-provider-ollama-cloud` is the first implementation
+(`POST {apiBaseUrl}/api/web_search`); this Package holds no transport and
+depends on no provider.

package/frockbot.json

@@ -0,0 +1,26 @@
+{
+  "schemaVersion": 4,
+  "id": "web",
+  "displayName": "Web",
+  "version": "0.0.1",
+  "compatibility": { "frockbot": ">=0.0.1" },
+  "contributions": {
+    "runtime": { "entry": "./agent" }
+  },
+  "permissions": ["network:web"],
+  "configuration": {
+    "settings": [],
+    "connectionTypes": [],
+    "capabilities": [
+      {
+        "id": "web-fetch",
+        "kind": "tool",
+        "connectionTypes": [],
+        "admission": {
+          "turnTypes": ["chat", "automation", "subagent"],
+          "subagentRoles": ["executor"]
+        }
+      }
+    ]
+  }
+}

package/package.json

@@ -1,14 +1,39 @@
 {
   "name": "@frockbot/plugin-web",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./agent": "./src/agent.ts",
+    "./contract": "./src/contract.ts",
+    "./ssrf": "./src/ssrf.ts",
+    "./manifest": "./src/manifest.ts",
+    "./frockbot.json": "./frockbot.json",
+    "./package.json": "./package.json"
+  },
+  "frockbot": {
+    "manifest": "./frockbot.json"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/kernel-contracts": "0.1.1",
+    "cordis": "4.0.0-rc.8"
+  },
+  "devDependencies": {
+    "@frockbot/plugin-tools": "0.1.1",
+    "@types/bun": "1.4.0",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/plugin-web"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/agent.test.ts

@@ -0,0 +1,265 @@
+import { describe, expect, test } from "bun:test";
+import { Context } from "cordis";
+import { ToolRegistry } from "@frockbot/plugin-tools/agent";
+import type { ToolExecutionContext } from "@frockbot/kernel-contracts";
+import {
+  createConfiguredWebFetchRuntimeContribution,
+  createWebFetchToolDefinitionV1,
+  executeWebFetchV1,
+  extractReadableTextV1,
+  WEB_FETCH_MAX_BYTES_V1,
+  type WebFetchFn,
+  type WebFetchResultV1,
+} from "./agent.ts";
+
+const ENABLED_ASSIGNMENT = {
+  packageId: "web",
+  capabilityId: "web-fetch",
+  state: "enabled",
+} as const;
+
+function toolContext(): ToolExecutionContext {
+  return {
+    botId: "bot",
+    agentId: "bot",
+    sessionId: "session",
+    compositionGenerationId: "generation",
+    effectId: "effect-1",
+    turnType: "chat",
+    signal: new AbortController().signal,
+  };
+}
+
+/** A fetch that answers a script of responses and records what it was asked. */
+function fakeFetch(
+  answers: Array<{
+    status?: number;
+    headers?: Record<string, string>;
+    body?: string;
+  }>,
+): { fetch: WebFetchFn; calls: string[] } {
+  const calls: string[] = [];
+  let index = 0;
+  const fetch: WebFetchFn = (input) => {
+    calls.push(input);
+    const answer = answers[Math.min(index, answers.length - 1)] ?? {};
+    index += 1;
+    return Promise.resolve(
+      new Response(answer.body ?? "", {
+        status: answer.status ?? 200,
+        headers: answer.headers ?? { "content-type": "text/html" },
+      }),
+    );
+  };
+  return { fetch, calls };
+}
+
+function parsed(content: string): Record<string, unknown> {
+  return JSON.parse(content) as Record<string, unknown>;
+}
+
+describe("web_fetch", () => {
+  test("returns the durable JSON shape for a readable page", async () => {
+    const { fetch, calls } = fakeFetch([
+      {
+        headers: { "content-type": "text/html; charset=utf-8" },
+        body: "<html><head><title>t</title><style>a{}</style></head><body><h1>Title</h1><p>Body &amp; more</p><script>evil()</script></body></html>",
+      },
+    ]);
+    const result = await executeWebFetchV1(
+      { url: "https://example.test/page", maxBytes: 65536, format: "text" },
+      { fetch },
+    );
+
+    expect(result.isError).toBe(false);
+    const body = parsed(result.content) as unknown as WebFetchResultV1;
+    expect(body.url).toBe("https://example.test/page");
+    expect(body.finalUrl).toBe("https://example.test/page");
+    expect(body.status).toBe(200);
+    expect(body.contentType).toBe("text/html");
+    expect(body.truncated).toBe(false);
+    expect(body.text).toContain("Title");
+    expect(body.text).toContain("Body & more");
+    // Script and style content is dropped whole, never handed to the model.
+    expect(body.text).not.toContain("evil()");
+    expect(body.text).not.toContain("a{}");
+    expect(calls).toEqual(["https://example.test/page"]);
+  });
+
+  test("sends a fixed identity and no credential of the Bot's", async () => {
+    let sent: Headers | undefined;
+    const fetch: WebFetchFn = (_input, init) => {
+      sent = new Headers(init?.headers);
+      return Promise.resolve(
+        new Response("<p>ok</p>", { headers: { "content-type": "text/html" } }),
+      );
+    };
+    await executeWebFetchV1(
+      { url: "https://example.test/", maxBytes: 65536, format: "text" },
+      { fetch },
+    );
+    expect(sent?.get("user-agent")).toContain("FrockBot");
+    expect(sent?.get("authorization")).toBeNull();
+    expect(sent?.get("cookie")).toBeNull();
+  });
+
+  test("truncates a body that runs past max_bytes and says so", async () => {
+    const { fetch } = fakeFetch([
+      {
+        headers: { "content-type": "text/plain" },
+        body: "x".repeat(20_000),
+      },
+    ]);
+    const result = await executeWebFetchV1(
+      { url: "https://example.test/big", maxBytes: 4096, format: "text" },
+      { fetch },
+    );
+    const body = parsed(result.content) as unknown as WebFetchResultV1;
+    expect(result.isError).toBe(false);
+    expect(body.bytes).toBe(4096);
+    expect(body.truncated).toBe(true);
+    expect(body.text.length).toBe(4096);
+  });
+
+  test("refuses a body whose declared length is already over the cap", async () => {
+    const { fetch } = fakeFetch([
+      {
+        headers: {
+          "content-type": "text/plain",
+          "content-length": String(WEB_FETCH_MAX_BYTES_V1 + 1),
+        },
+        body: "small",
+      },
+    ]);
+    const result = await executeWebFetchV1(
+      {
+        url: "https://example.test/huge",
+        maxBytes: WEB_FETCH_MAX_BYTES_V1,
+        format: "text",
+      },
+      { fetch },
+    );
+    expect(result.isError).toBe(true);
+    expect(parsed(result.content).error).toBe("web-fetch-response-too-large");
+  });
+
+  test("refuses a content type outside the allow list", async () => {
+    const { fetch } = fakeFetch([
+      { headers: { "content-type": "application/pdf" }, body: "%PDF-1.4" },
+    ]);
+    const result = await executeWebFetchV1(
+      { url: "https://example.test/doc.pdf", maxBytes: 65536, format: "text" },
+      { fetch },
+    );
+    expect(result.isError).toBe(true);
+    expect(parsed(result.content).error).toBe("web-fetch-blocked-content-type");
+  });
+
+  test("re-validates every redirect and refuses one into private space", async () => {
+    const { fetch, calls } = fakeFetch([
+      {
+        status: 302,
+        headers: { location: "https://169.254.169.254/latest/meta-data" },
+      },
+    ]);
+    const result = await executeWebFetchV1(
+      { url: "https://example.test/go", maxBytes: 65536, format: "text" },
+      { fetch },
+    );
+    expect(result.isError).toBe(true);
+    expect(parsed(result.content).error).toBe("ssrf-blocked-private-address");
+    // The private hop is never requested: the classifier runs before the fetch.
+    expect(calls).toEqual(["https://example.test/go"]);
+  });
+
+  test("follows at most three redirects", async () => {
+    const { fetch, calls } = fakeFetch([
+      { status: 302, headers: { location: "/next" } },
+    ]);
+    const result = await executeWebFetchV1(
+      { url: "https://example.test/a", maxBytes: 65536, format: "text" },
+      { fetch },
+    );
+    expect(parsed(result.content).error).toBe("web-fetch-too-many-redirects");
+    expect(calls.length).toBe(4);
+  });
+
+  test("refuses a non-https url without making a request", async () => {
+    const { fetch, calls } = fakeFetch([{}]);
+    const result = await executeWebFetchV1(
+      {
+        url: "http://169.254.169.254/latest/meta-data",
+        maxBytes: 65536,
+        format: "text",
+      },
+      { fetch },
+    );
+    expect(result.isError).toBe(true);
+    expect(parsed(result.content).error).toBe("ssrf-blocked-scheme");
+    expect(calls).toEqual([]);
+  });
+
+  test("renders markdown when the call asks for it", () => {
+    const markdown = extractReadableTextV1(
+      '<h2>Heading</h2><ul><li>one</li></ul><p><a href="https://example.test/x">link</a></p>',
+      "text/html",
+      "markdown",
+    );
+    expect(markdown).toContain("## Heading");
+    expect(markdown).toContain("- one");
+    expect(markdown).toContain("[link](https://example.test/x)");
+  });
+
+  test("declares itself idempotent, so recovery re-runs rather than guesses", () => {
+    expect(createWebFetchToolDefinitionV1().idempotent).toBe(true);
+  });
+
+  test("rejects arguments the schema does not admit", async () => {
+    const definition = createWebFetchToolDefinitionV1();
+    expect(definition.validate?.({ url: 42 })).toBe(false);
+    expect(
+      definition.validate?.({ url: "https://a.test/", format: "pdf" }),
+    ).toBe(false);
+    expect(definition.validate?.({ url: "https://a.test/" })).toBe(true);
+    const result = await definition.execute({ url: "" }, toolContext());
+    expect(result.isError).toBe(true);
+  });
+});
+
+describe("the web-fetch Capability Assignment", () => {
+  test("mounts nothing without an enabled Assignment naming it", () => {
+    expect(
+      createConfiguredWebFetchRuntimeContribution({
+        assignment: { ...ENABLED_ASSIGNMENT, state: "disabled" },
+      }),
+    ).toBeUndefined();
+    expect(
+      createConfiguredWebFetchRuntimeContribution({
+        assignment: { ...ENABLED_ASSIGNMENT, capabilityId: "something-else" },
+      }),
+    ).toBeUndefined();
+    expect(
+      createConfiguredWebFetchRuntimeContribution({
+        assignment: ENABLED_ASSIGNMENT,
+      }),
+    ).toBeDefined();
+  });
+
+  test("offers web_fetch on every turn type its manifest admits", async () => {
+    const root = new Context();
+    await root.plugin(ToolRegistry);
+    const plugin = createConfiguredWebFetchRuntimeContribution({
+      assignment: ENABLED_ASSIGNMENT,
+    });
+    expect(plugin).toBeDefined();
+    await root.plugin(plugin!);
+
+    for (const turnType of ["chat", "automation", "subagent"] as const) {
+      expect({
+        turnType,
+        names: root.tools.schemas({ turnType }).map((schema) => schema.name),
+      }).toEqual({ turnType, names: ["web_fetch"] });
+    }
+    await root.fiber.dispose();
+  });
+});