@frockbot/plugin-provider-ollama-cloud 0.0.0 → 0.1.0

package/README.md

@@ -1,3 +1,117 @@
 # @frockbot/plugin-provider-ollama-cloud
 
-Placeholder reserving this name. See https://github.com/timoconnellaus/frockbot.
+The Ollama model provider Package. It contributes:
+
+- a **User backend Contribution** (`./user`) that owns the `ollama-cloud-account`
+  Connection type: it admits `connection/*` commands durably, validates and
+  stores the API key, discovers the account's model catalog, refreshes that
+  catalog on a durable alarm, resolves models the catalog does not list, and
+  leases the credential for a Turn;
+- a **runtime Contribution** (`./runtime`) that registers the `ollama-cloud`
+  provider behind the kernel's model interface, translating a normalized model
+  request onto Ollama's OpenAI-compatible `/v1/chat/completions` endpoint;
+- the **`web_search` tool** (`./web-search`), a second Capability over the same
+  Connection.
+
+## The `ollama-cloud-web-search` Capability
+
+`POST /api/web_search` authenticates with the _same_ key as `/api/chat` — see
+`docs/research/ollama-cloud-auth.md` — and a credential is openable only by the
+Package that owns its Connection. So the search transport lives here, beside the
+model provider, rather than in a Package that would have to be handed a key it
+does not own. `plugin-composio` is the precedent for a Connection-backed tool
+Capability.
+
+The _contract_ is not provider-specific. `@frockbot/plugin-web/contract` owns the
+`WebSearchV1` interface, the result DTO, its decoder and the `web_search` tool
+definition; this Package supplies transport and the credential, and a second
+search provider satisfies the same contract with no change here and none in the
+kernel.
+
+|                |                                                                                     |
+| -------------- | ----------------------------------------------------------------------------------- |
+| Capability     | `ollama-cloud-web-search`, kind `tool`, `connectionTypes: ["ollama-cloud-account"]` |
+| Endpoint       | `POST {apiBaseUrl}/api/web_search` — the same resolved root chat uses               |
+| Input          | `query` 1–400 chars, `max_results` 1–10 (default 5)                                 |
+| Response bound | 256 KiB, snippets trimmed to 1 000 characters                                       |
+| Durable result | `{"query", "results":[{"title","url","snippet"}]}`                                  |
+| Effect class   | read-only, `idempotent: true`                                                       |
+| Turn types     | all four (manifest v4 `admission`)                                                  |
+
+**Authority.** The tool mounts only for an enabled Assignment of
+`ollama-cloud-web-search` bound to a ready Connection. There is no
+unauthenticated fallback: a Bot without the Assignment is never offered the
+tool. The key is leased per durable `effectId`, opened inside this Package, used
+and settled, so it never reaches a tool argument, a tool result, or the event
+log.
+
+## The `api-base-url` Connection setting
+
+A Connection is not pinned to `https://ollama.com`. Its User may point it at any
+Ollama-compatible endpoint — a self-hosted gateway, a colleague's GPU box, or a
+local Ollama server at `http://127.0.0.1:11434`.
+
+The endpoint is a **Connection-scoped setting**: it belongs to one Connection,
+not to the User or the Bot, so a User may hold a Cloud Connection and a local
+Connection side by side and assign either to a Bot.
+
+The manifest declares it in `configuration.settings` as `api-base-url` — the
+kernel requires lowercase kebab-case Contribution ids — and it is carried on the
+Connection settings bag under the key **`api-base-url`**:
+
+```json
+{
+  "id": "api-base-url",
+  "schemaVersion": 1,
+  "scopes": ["connection"],
+  "schema": { "type": "string", "minLength": 1, "maxLength": 2048 }
+}
+```
+
+### Setting it
+
+Supply it when the Connection is created, on the
+`connection/create-api-key` command:
+
+```jsonc
+POST /api/connections
+{
+  "schemaVersion": 1,
+  "type": "connection/create-api-key",
+  "commandId": "<idempotency key>",
+  "packageId": "provider-ollama-cloud",
+  "connectionTypeId": "ollama-cloud-account",
+  "label": "Workstation Ollama",
+  "apiKey": "<key>",
+  "settings": { "api-base-url": "http://127.0.0.1:11434" }
+}
+```
+
+Omit `settings` entirely for Ollama Cloud. In the WebUI the same value is the
+optional **API base URL** field on the Connect form; leaving it empty sends no
+`settings` field at all.
+
+The value is the **endpoint root**, with no `/api` or `/v1` path segment: the
+Package appends `/api/...` for catalog and probe calls and `/v1` for chat
+completions. It must be an absolute `http:` or `https:` URL carrying no
+credentials, query, or fragment; a trailing slash is stripped. Anything else is
+refused at the seam, and the command fails with a visible reason on the
+Connection rather than silently falling back to the default.
+
+Every provider call for a Connection uses that Connection's endpoint: the
+creation catalog read, the key-validation probe, the periodic catalog refresh,
+exact model resolution, and chat completions.
+
+The setting is durable state on the Connection and is visible in
+`GET /api/settings` under the Connection's `settings` bag.
+
+### The key is still proven
+
+Pointing a Connection elsewhere does not relax key validation. Measured against
+`https://ollama.com` and recorded in `docs/research/ollama-cloud-auth.md`,
+`GET /api/tags`, `GET /v1/models`, and `POST /api/show` all answer 200 for a
+valid key, a garbage key, and no key at all — so no catalog read can validate a
+key. `POST /api/chat` does authenticate. Creating or rotating a key therefore
+runs a real one-token inference probe against **whatever endpoint the Connection
+is configured with**, and a Connection whose endpoint rejects the key ends
+`failed` with the provider's reason, never `ready`.

package/frockbot.json

@@ -0,0 +1,79 @@
+{
+  "schemaVersion": 4,
+  "id": "provider-ollama-cloud",
+  "displayName": "Ollama Cloud",
+  "version": "0.0.1",
+  "compatibility": { "frockbot": ">=0.0.1" },
+  "dependencies": {
+    "credentials": ">=0.0.1",
+    "settings": ">=0.0.1",
+    "web": ">=0.0.1"
+  },
+  "contributions": {
+    "backend": [{ "entry": "./user", "host": "user" }],
+    "runtime": { "entry": "./runtime" }
+  },
+  "permissions": [
+    "connections:manage",
+    "models:invoke",
+    "tools:execute",
+    "network:ollama-cloud"
+  ],
+  "configuration": {
+    "settings": [
+      {
+        "id": "web-search-max-results",
+        "schemaVersion": 1,
+        "scopes": ["user"],
+        "schema": {
+          "type": "integer",
+          "title": "Web search results",
+          "description": "The most results web_search returns, whatever the model asks for. Absent means the tool's own default of 5.",
+          "minimum": 1,
+          "maximum": 10
+        }
+      }
+    ],
+    "connectionTypes": [
+      {
+        "id": "ollama-cloud-account",
+        "displayName": "Ollama Cloud account",
+        "allowMultiple": true,
+        "authorization": { "kind": "api-key", "driverId": "ollama-cloud" },
+        "capabilities": ["ollama-cloud-models", "ollama-cloud-web-search"],
+        "settings": [
+          {
+            "id": "api-base-url",
+            "schemaVersion": 1,
+            "schema": {
+              "type": "string",
+              "title": "API base URL",
+              "description": "Root URL of the Ollama-compatible endpoint, without a trailing slash. Absent means https://ollama.com; use http://127.0.0.1:11434 for a local Ollama server.",
+              "minLength": 1,
+              "maxLength": 2048
+            }
+          }
+        ]
+      }
+    ],
+    "capabilities": [
+      {
+        "id": "ollama-cloud-models",
+        "kind": "model",
+        "connectionTypes": ["ollama-cloud-account"],
+        "admission": {
+          "turnTypes": ["chat", "automation", "subagent"]
+        }
+      },
+      {
+        "id": "ollama-cloud-web-search",
+        "kind": "tool",
+        "connectionTypes": ["ollama-cloud-account"],
+        "admission": {
+          "turnTypes": ["chat", "automation", "subagent"],
+          "subagentRoles": ["executor"]
+        }
+      }
+    ]
+  }
+}

package/package.json

@@ -1,14 +1,47 @@
 {
   "name": "@frockbot/plugin-provider-ollama-cloud",
-  "version": "0.0.0",
-  "description": "Placeholder reserving this name for trusted publishing. Superseded by the first release.",
-  "license": "UNLICENSED",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./runtime": "./src/runtime.ts",
+    "./user": "./src/user.ts",
+    "./manifest": "./src/manifest.ts",
+    "./frockbot.json": "./frockbot.json",
+    "./package.json": "./package.json",
+    "./web-search": "./src/web-search.ts"
+  },
+  "frockbot": {
+    "manifest": "./frockbot.json"
+  },
+  "scripts": {
+    "test": "bun test src",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@frockbot/configuration-core": "0.1.0",
+    "@frockbot/connection-core": "0.1.0",
+    "@frockbot/kernel-agent-loop": "0.1.0",
+    "@frockbot/kernel-contracts": "0.1.0",
+    "@frockbot/plugin-credentials": "0.1.0",
+    "@frockbot/plugin-models": "0.1.0",
+    "@frockbot/plugin-settings": "0.1.0",
+    "@frockbot/plugin-web": "0.1.0",
+    "@frockbot/provider-openai-compatible": "0.1.0",
+    "cordis": "4.0.0-rc.8"
+  },
+  "devDependencies": {
+    "@frockbot/plugin-tools": "0.1.0",
+    "@types/bun": "1.3.6",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/timoconnellaus/frockbot.git",
     "directory": "packages/plugin-provider-ollama-cloud"
-  },
-  "publishConfig": {
-    "access": "public"
   }
 }

package/src/client.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, test } from "bun:test";
+import { OllamaCloudClient } from "./client.js";
+
+describe("Ollama Cloud client", () => {
+  test("discovers account models and normalizes provider capabilities", async () => {
+    const requests: Request[] = [];
+    const client = new OllamaCloudClient({
+      fetch: async (input, init) => {
+        const request = new Request(input, init);
+        requests.push(request);
+        if (request.url.endsWith("/tags")) {
+          return Response.json({ models: [{ model: "glm-5.3-flash:cloud" }] });
+        }
+        return Response.json({
+          capabilities: ["completion", "tools", "thinking"],
+          model_info: { "glm.context_length": 1_048_576 },
+        });
+      },
+    });
+
+    expect(await client.listModels("account-key")).toEqual([
+      {
+        providerModelId: "glm-5.3-flash:cloud",
+        displayName: "glm-5.3-flash",
+        contextWindow: 1_048_576,
+        capabilities: { tools: true, vision: false, reasoning: true },
+        source: "discovered",
+      },
+    ]);
+    expect(requests).toHaveLength(2);
+    expect(
+      requests.every(
+        (request) =>
+          request.headers.get("authorization") === "Bearer account-key",
+      ),
+    ).toBe(true);
+  });
+
+  test("rejects provider model metadata outside the catalog contract", async () => {
+    let requests = 0;
+    const client = new OllamaCloudClient({
+      fetch: (input) => {
+        requests += 1;
+        return Promise.resolve(
+          String(input).endsWith("/tags")
+            ? Response.json({ models: [{ model: "x".repeat(257) }] })
+            : Response.json({ capabilities: [] }),
+        );
+      },
+    });
+
+    await expect(client.listModels("account-key")).rejects.toThrow(
+      "Ollama Cloud model id is invalid",
+    );
+    expect(requests).toBe(1);
+  });
+
+  test("truncates oversized advisory catalogs before detail fanout", async () => {
+    let requests = 0;
+    const client = new OllamaCloudClient({
+      fetch: (input) => {
+        requests += 1;
+        return Promise.resolve(
+          String(input).endsWith("/tags")
+            ? Response.json({
+                models: Array.from({ length: 101 }, (_, index) => ({
+                  model: `model-${index}:cloud`,
+                })),
+              })
+            : Response.json({ capabilities: [] }),
+        );
+      },
+    });
+
+    const models = await client.listModels("account-key");
+
+    expect(models).toHaveLength(100);
+    expect(models.at(-1)?.providerModelId).toBe("model-99:cloud");
+    expect(requests).toBe(101);
+  });
+
+  test("limits concurrent model detail lookups", async () => {
+    const fourStarted = Promise.withResolvers<void>();
+    const release = Promise.withResolvers<void>();
+    let active = 0;
+    let maximumActive = 0;
+    let detailRequests = 0;
+    const client = new OllamaCloudClient({
+      fetch: async (input) => {
+        if (String(input).endsWith("/tags")) {
+          return Response.json({
+            models: Array.from({ length: 8 }, (_, index) => ({
+              model: `model-${index}:cloud`,
+            })),
+          });
+        }
+        detailRequests += 1;
+        active += 1;
+        maximumActive = Math.max(maximumActive, active);
+        if (active === 4) fourStarted.resolve();
+        await release.promise;
+        active -= 1;
+        return Response.json({ capabilities: [] });
+      },
+    });
+
+    const models = client.listModels("account-key");
+    await fourStarted.promise;
+    await Promise.resolve();
+    expect(detailRequests).toBe(4);
+    release.resolve();
+
+    expect(await models).toHaveLength(8);
+    expect(maximumActive).toBe(4);
+  });
+
+  test("rejects oversized provider responses", async () => {
+    const client = new OllamaCloudClient({
+      fetch: () =>
+        Promise.resolve(Response.json({ padding: "x".repeat(512 * 1024) })),
+    });
+
+    await expect(client.listModels("account-key")).rejects.toThrow(
+      "Ollama Cloud response is too large",
+    );
+  });
+
+  test("does not expose provider response bodies in errors", async () => {
+    const client = new OllamaCloudClient({
+      fetch: () =>
+        Promise.resolve(
+          new Response("credential=do-not-leak", { status: 401 }),
+        ),
+    });
+
+    await expect(client.listModels("secret")).rejects.toThrow(
+      "Ollama Cloud request failed (401)",
+    );
+  });
+});