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

package/src/web-search.test.ts

@@ -0,0 +1,383 @@
+import { describe, expect, test } from "bun:test";
+import { Context, Service } from "cordis";
+import { ToolRegistry } from "@frockbot/plugin-tools/agent";
+import type { ToolExecutionContext } from "@frockbot/kernel-contracts";
+import type { CredentialLeaseV1 } from "@frockbot/connection-core";
+import {
+  createConfiguredOllamaWebSearchRuntimeContribution,
+  ollamaWebSearchUrl,
+  OllamaCloudWebSearchClient,
+} from "./web-search.ts";
+
+const CONNECTION_ID = "connection-1";
+const GENERATION = "generation-1";
+const API_KEY = "ollama-test-key";
+
+const ASSIGNMENT = {
+  packageId: "provider-ollama-cloud",
+  capabilityId: "ollama-cloud-web-search",
+  connectionId: CONNECTION_ID,
+  state: "enabled",
+} as const;
+
+interface Recorded {
+  url: string;
+  init: RequestInit | undefined;
+}
+
+function lease(effectId: string): CredentialLeaseV1 {
+  return {
+    schemaVersion: 1,
+    leaseId: `lease-${effectId}`,
+    connectionId: CONNECTION_ID,
+    effectId,
+    credentialGeneration: GENERATION,
+    expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    // The lease carries the sealed credential; only the Credential Store may
+    // open it, and this test's opener never looks inside.
+    envelope: {
+      schemaVersion: 1,
+      algorithm: "AES-GCM",
+      keyId: "primary",
+      credentialGeneration: GENERATION,
+      nonce: "bm9uY2U",
+      ciphertext: "Y2lwaGVy",
+      createdAt: new Date(0).toISOString(),
+    },
+  };
+}
+
+/** The credential-store service the Bot Durable Object mounts for real. */
+class FakeCredentialLease extends Service {
+  opened: string[] = [];
+  constructor(ctx: Context) {
+    super(ctx, "credentialLease");
+  }
+  open(input: {
+    packageId: string;
+    lease: CredentialLeaseV1;
+  }): Promise<string> {
+    this.opened.push(input.packageId);
+    return Promise.resolve(API_KEY);
+  }
+}
+
+function toolContext(effectId = "effect-1"): ToolExecutionContext {
+  return {
+    botId: "bot",
+    agentId: "bot",
+    sessionId: "session",
+    compositionGenerationId: "generation",
+    effectId,
+    turnType: "chat",
+    signal: new AbortController().signal,
+  };
+}
+
+async function mount(options: {
+  respond: (recorded: Recorded) => Response;
+  apiBaseUrl?: string;
+  maxResults?: number;
+}) {
+  const recorded: Recorded[] = [];
+  const leased: string[] = [];
+  const settled: string[] = [];
+  const root = new Context();
+  await root.plugin(ToolRegistry);
+  await root.plugin(FakeCredentialLease);
+  const plugin = createConfiguredOllamaWebSearchRuntimeContribution({
+    assignment: ASSIGNMENT,
+    accountId: "user-1",
+    connectionId: CONNECTION_ID,
+    connectionGeneration: GENERATION,
+    ...(options.apiBaseUrl === undefined
+      ? {}
+      : { apiBaseUrl: options.apiBaseUrl }),
+    ...(options.maxResults === undefined
+      ? {}
+      : { maxResults: options.maxResults }),
+    leaseCredential: (effectId) => {
+      leased.push(effectId);
+      return Promise.resolve(lease(effectId));
+    },
+    settleCredential: (effectId) => {
+      settled.push(effectId);
+      return Promise.resolve();
+    },
+    fetch: (input, init) => {
+      const entry = { url: String(input), init };
+      recorded.push(entry);
+      return Promise.resolve(options.respond(entry));
+    },
+  });
+  expect(plugin).toBeDefined();
+  await root.plugin(plugin!);
+  return { root, recorded, leased, settled };
+}
+
+describe("the Ollama Cloud web_search Capability", () => {
+  test("composes the endpoint from the Connection's own base URL", () => {
+    expect(ollamaWebSearchUrl()).toBe("https://ollama.com/api/web_search");
+    expect(ollamaWebSearchUrl("http://127.0.0.1:11434")).toBe(
+      "http://127.0.0.1:11434/api/web_search",
+    );
+    expect(ollamaWebSearchUrl("https://proxy.example/")).toBe(
+      "https://proxy.example/api/web_search",
+    );
+  });
+
+  test("posts the bounded request shape with the leased key", async () => {
+    const { root, recorded, leased, settled } = await mount({
+      respond: () =>
+        Response.json({
+          results: [
+            {
+              title: "A result",
+              url: "https://example.test/a",
+              content: "  a  snippet\n over lines ",
+            },
+            { title: "no url", content: "dropped" },
+          ],
+        }),
+    });
+
+    const prepared = await root.tools.prepare(
+      { id: "call-1", name: "web_search", input: { query: "frockbot" } },
+      toolContext(),
+    );
+    expect(prepared.kind).toBe("ready");
+    if (prepared.kind !== "ready") return;
+    const result = await root.tools.executePrepared(prepared, toolContext());
+
+    expect(result.isError).toBe(false);
+    expect(JSON.parse(result.content)).toEqual({
+      query: "frockbot",
+      results: [
+        {
+          title: "A result",
+          url: "https://example.test/a",
+          snippet: "a snippet over lines",
+        },
+      ],
+    });
+    const call = recorded[0]!;
+    expect(call.url).toBe("https://ollama.com/api/web_search");
+    expect(call.init?.method).toBe("POST");
+    expect(new Headers(call.init?.headers).get("authorization")).toBe(
+      `Bearer ${API_KEY}`,
+    );
+    expect(JSON.parse(String(call.init?.body))).toEqual({
+      query: "frockbot",
+      max_results: 5,
+    });
+    // The credential is leased per durable effect and settled afterwards, so
+    // no key outlives the tool call that opened it.
+    expect(leased).toEqual(["effect-1"]);
+    expect(settled).toEqual(["effect-1"]);
+    // And it never reaches the durable result.
+    expect(result.content).not.toContain(API_KEY);
+    await root.fiber.dispose();
+  });
+
+  test("carries max_results through and trims the answer to it", async () => {
+    const { root, recorded } = await mount({
+      respond: () =>
+        Response.json({
+          results: Array.from({ length: 8 }, (_value, index) => ({
+            title: `r${index}`,
+            url: `https://example.test/${index}`,
+            content: "x",
+          })),
+        }),
+    });
+    const call = {
+      id: "c",
+      name: "web_search",
+      input: { query: "q", max_results: 2 },
+    };
+    const prepared = await root.tools.prepare(call, toolContext());
+    if (prepared.kind !== "ready") throw new Error("not ready");
+    const result = await root.tools.executePrepared(prepared, toolContext());
+    expect(JSON.parse(String(recorded[0]?.init?.body)).max_results).toBe(2);
+    expect(
+      (JSON.parse(result.content) as { results: unknown[] }).results.length,
+    ).toBe(2);
+    await root.fiber.dispose();
+  });
+
+  test("caps the request at the Package-level setting the User chose", async () => {
+    const { root, recorded } = await mount({
+      maxResults: 2,
+      respond: () =>
+        Response.json({
+          results: Array.from({ length: 8 }, (_value, index) => ({
+            title: `r${index}`,
+            url: `https://example.test/${index}`,
+            content: "x",
+          })),
+        }),
+    });
+    const prepared = await root.tools.prepare(
+      {
+        id: "c",
+        name: "web_search",
+        // The model asks for the contract's maximum; the User's ceiling wins.
+        input: { query: "q", max_results: 10 },
+      },
+      toolContext(),
+    );
+    if (prepared.kind !== "ready") throw new Error("not ready");
+    const result = await root.tools.executePrepared(prepared, toolContext());
+    // The ceiling is applied before the provider is asked, so the extra
+    // results are never fetched, let alone recorded on the Turn.
+    expect(JSON.parse(String(recorded[0]?.init?.body)).max_results).toBe(2);
+    expect(
+      (JSON.parse(result.content) as { results: unknown[] }).results.length,
+    ).toBe(2);
+    await root.fiber.dispose();
+  });
+
+  test("leaves a request already under the ceiling alone", async () => {
+    const { root, recorded } = await mount({
+      maxResults: 8,
+      respond: () => Response.json({ results: [] }),
+    });
+    const prepared = await root.tools.prepare(
+      { id: "c", name: "web_search", input: { query: "q", max_results: 3 } },
+      toolContext(),
+    );
+    if (prepared.kind !== "ready") throw new Error("not ready");
+    await root.tools.executePrepared(prepared, toolContext());
+    expect(JSON.parse(String(recorded[0]?.init?.body)).max_results).toBe(3);
+    await root.fiber.dispose();
+  });
+
+  test("refuses arguments outside the contract's bounds", async () => {
+    const { root } = await mount({
+      respond: () => Response.json({ results: [] }),
+    });
+    for (const input of [
+      {},
+      { query: "" },
+      { query: "q", max_results: 0 },
+      { query: "q", max_results: 11 },
+      { query: "q", max_results: 1.5 },
+      { query: "x".repeat(401) },
+    ]) {
+      const prepared = await root.tools.prepare(
+        { id: "c", name: "web_search", input },
+        toolContext(),
+      );
+      expect({ input, kind: prepared.kind }).toEqual({ input, kind: "denied" });
+    }
+    await root.fiber.dispose();
+  });
+
+  test("reports a revoked key as a visible tool error", async () => {
+    const { root, settled } = await mount({
+      respond: () =>
+        new Response(JSON.stringify({ error: "Unauthorized" }), {
+          status: 401,
+          headers: { "content-type": "application/json" },
+        }),
+    });
+    const prepared = await root.tools.prepare(
+      { id: "c", name: "web_search", input: { query: "q" } },
+      toolContext(),
+    );
+    if (prepared.kind !== "ready") throw new Error("not ready");
+    const result = await root.tools.executePrepared(prepared, toolContext());
+    expect(result.isError).toBe(true);
+    const body = JSON.parse(result.content) as {
+      error: string;
+      message: string;
+    };
+    expect(body.error).toBe("web-search-failed");
+    expect(body.message).toContain("401");
+    // The lease is settled even when the call fails.
+    expect(settled).toEqual(["effect-1"]);
+    await root.fiber.dispose();
+  });
+
+  test("refuses a provider answer larger than the response bound", async () => {
+    const { root } = await mount({
+      respond: () =>
+        Response.json({
+          results: [
+            {
+              title: "big",
+              url: "https://example.test/big",
+              content: "x".repeat(300 * 1024),
+            },
+          ],
+        }),
+    });
+    const prepared = await root.tools.prepare(
+      { id: "c", name: "web_search", input: { query: "q" } },
+      toolContext(),
+    );
+    if (prepared.kind !== "ready") throw new Error("not ready");
+    const result = await root.tools.executePrepared(prepared, toolContext());
+    expect(result.isError).toBe(true);
+    expect(result.content).toContain("too large");
+    await root.fiber.dispose();
+  });
+
+  test("is offered on every turn type the manifest admits", async () => {
+    const { root } = await mount({
+      respond: () => Response.json({ results: [] }),
+    });
+    for (const turnType of ["chat", "automation", "subagent"] as const) {
+      expect({
+        turnType,
+        names: root.tools.schemas({ turnType }).map((schema) => schema.name),
+      }).toEqual({ turnType, names: ["web_search"] });
+    }
+    await root.fiber.dispose();
+  });
+
+  test("mounts nothing without an enabled Assignment bound to the Connection", () => {
+    const base = {
+      accountId: "user-1",
+      connectionId: CONNECTION_ID,
+      connectionGeneration: GENERATION,
+      leaseCredential: () => Promise.resolve(lease("e")),
+      settleCredential: () => Promise.resolve(),
+    };
+    expect(
+      createConfiguredOllamaWebSearchRuntimeContribution({
+        ...base,
+        assignment: { ...ASSIGNMENT, state: "disabled" },
+      }),
+    ).toBeUndefined();
+    expect(
+      createConfiguredOllamaWebSearchRuntimeContribution({
+        ...base,
+        assignment: { ...ASSIGNMENT, capabilityId: "ollama-cloud-models" },
+      }),
+    ).toBeUndefined();
+    expect(
+      createConfiguredOllamaWebSearchRuntimeContribution({
+        ...base,
+        assignment: { ...ASSIGNMENT, connectionId: "other" },
+      }),
+    ).toBeUndefined();
+  });
+
+  test("bounds the provider response before it is parsed", async () => {
+    const client = new OllamaCloudWebSearchClient({
+      fetch: () =>
+        Promise.resolve(
+          new Response("{}", {
+            headers: {
+              "content-type": "application/json",
+              "content-length": String(512 * 1024),
+            },
+          }),
+        ),
+    });
+    await expect(
+      client.search(API_KEY, { query: "q", maxResults: 5 }),
+    ).rejects.toThrow("too large");
+  });
+});

package/src/web-search.ts

@@ -0,0 +1,299 @@
+// Ollama Cloud's implementation of the provider-neutral `WebSearchV1`.
+//
+// WHY A NON-MODEL TOOL LIVES IN A MODEL PROVIDER PACKAGE. `/api/web_search`
+// authenticates with the *same* key as `/api/chat` (measured, and recorded in
+// `docs/research/ollama-cloud-auth.md`), and a credential is openable only by
+// the Package that owns its Connection: `credentialLease.open` is called with
+// this Package's id and the User Durable Object refuses any other. Putting the
+// search transport anywhere else would mean either a second credential for the
+// same account or a Package opening a Connection it does not own. The
+// precedent is `plugin-composio`, whose tools are likewise a Connection-backed
+// Capability. The tool's *contract* is not provider-specific: it lives in
+// `@frockbot/plugin-web/contract`, and a second provider satisfies it with no
+// change here and none in the kernel.
+//
+// AUTHORITY. `web_search` needs an enabled Assignment of the
+// `ollama-cloud-web-search` Capability bound to a ready `ollama-cloud-account`
+// Connection. Without one this module mounts nothing and the tool is simply
+// absent from the catalog, which is what "fail visibly" means for a tool: the
+// model is never offered a capability the Bot does not hold.
+//
+// EFFECT CLASS. Read-only, `idempotent: true`. A search records no intent and
+// recovers by re-running.
+import {
+  decodeWebSearchResponseV1,
+  createWebSearchToolDefinitionV1,
+  type WebSearchExecutionV1,
+  type WebSearchRequestV1,
+  type WebSearchResponseV1,
+  type WebSearchV1,
+} from "@frockbot/plugin-web/contract";
+import type { CredentialLeaseV1 } from "@frockbot/connection-core";
+// The `credentialLease` service is declared once, by `./runtime.ts`; this
+// module consumes that augmentation rather than restating it.
+import type {} from "./runtime.js";
+import type { Plugin } from "cordis";
+import {
+  DEFAULT_OLLAMA_API_BASE_URL,
+  decodeOllamaApiBaseUrl,
+  type OllamaFetch,
+} from "./client.js";
+
+/** The provider answer is bounded before it is parsed, as chat's is. */
+const MAX_SEARCH_RESPONSE_BYTES = 256 * 1024;
+
+/**
+ * Compose the web-search endpoint from a Connection's endpoint root — the
+ * *same* resolved base chat uses, so a Connection pointed at a local Ollama or
+ * an Ollama-compatible host searches there too rather than silently reaching
+ * `https://ollama.com` with that host's key.
+ */
+export function ollamaWebSearchUrl(apiBaseUrl?: string): string {
+  return `${decodeOllamaApiBaseUrl(apiBaseUrl ?? DEFAULT_OLLAMA_API_BASE_URL)}/api/web_search`;
+}
+
+async function boundedJson(
+  response: Response,
+  maximum: number,
+): Promise<unknown> {
+  const declaredLength = Number(response.headers.get("content-length"));
+  if (Number.isFinite(declaredLength) && declaredLength > maximum) {
+    throw new Error("Ollama Cloud web search response is too large");
+  }
+  const chunks: Uint8Array[] = [];
+  let length = 0;
+  const reader = response.body?.getReader();
+  if (reader) {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      length += chunk.value.byteLength;
+      if (length > maximum) {
+        await reader.cancel().catch(() => undefined);
+        throw new Error("Ollama Cloud web search response is too large");
+      }
+      chunks.push(chunk.value);
+    }
+  }
+  const bytes = new Uint8Array(length);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  try {
+    return JSON.parse(new TextDecoder().decode(bytes)) as unknown;
+  } catch {
+    throw new Error("Ollama Cloud web search returned invalid JSON");
+  }
+}
+
+export interface OllamaWebSearchClientConfig {
+  apiBaseUrl?: string;
+  fetch?: OllamaFetch;
+}
+
+/** The transport, and nothing else: no authority, no credential of its own. */
+export class OllamaCloudWebSearchClient {
+  private readonly endpoint: string;
+  private readonly fetcher: OllamaFetch;
+
+  constructor(config: OllamaWebSearchClientConfig = {}) {
+    this.endpoint = ollamaWebSearchUrl(config.apiBaseUrl);
+    // Workerd rejects a detached global `fetch`, so the default forwards.
+    this.fetcher =
+      config.fetch ?? ((input, init) => globalThis.fetch(input, init));
+  }
+
+  async search(
+    apiKey: string,
+    request: WebSearchRequestV1,
+    signal?: AbortSignal,
+  ): Promise<WebSearchResponseV1> {
+    const response = await this.fetcher(this.endpoint, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${apiKey}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({
+        query: request.query,
+        max_results: request.maxResults,
+      }),
+      ...(signal ? { signal } : {}),
+    });
+    if (!response.ok) {
+      await response.body?.cancel().catch(() => undefined);
+      if (response.status === 401 || response.status === 403) {
+        throw new Error(
+          "Ollama Cloud rejected the key for web search (HTTP " +
+            `${response.status})`,
+        );
+      }
+      throw new Error(`Ollama Cloud web search failed (${response.status})`);
+    }
+    return decodeWebSearchResponseV1(
+      await boundedJson(response, MAX_SEARCH_RESPONSE_BYTES),
+      request,
+    );
+  }
+}
+
+interface CredentialLeaseOpener {
+  open(input: {
+    accountId: string;
+    connectionId: string;
+    packageId: string;
+    lease: CredentialLeaseV1;
+  }): Promise<string>;
+}
+
+export interface OllamaWebSearchRuntimeConfig {
+  accountId: string;
+  connectionId: string;
+  connectionGeneration: string;
+  packageId: "provider-ollama-cloud";
+  /** The endpoint root carried on the Connection's own settings bag. */
+  apiBaseUrl?: string;
+  /**
+   * The Package-level `web-search-max-results` setting: the User's ceiling on
+   * how many results one search returns, whatever the model asked for. Absent
+   * leaves the model's own request — bounded by the contract — untouched.
+   */
+  maxResults?: number;
+  leaseCredential(
+    effectId: string,
+    expectedGeneration?: string,
+  ): Promise<CredentialLeaseV1>;
+  settleCredential(effectId: string): Promise<void>;
+  fetch?: OllamaFetch;
+  now?: () => number;
+}
+
+/**
+ * The credential is leased per tool call, keyed by the call's durable
+ * `effectId`, opened inside this Package, used, and settled — the same shape
+ * the model path uses. The key never reaches a tool argument, a tool result,
+ * or the event log.
+ */
+class ConnectionBackedWebSearch implements WebSearchV1 {
+  constructor(
+    private readonly config: OllamaWebSearchRuntimeConfig,
+    private readonly credentialLease: CredentialLeaseOpener,
+    private readonly client: OllamaCloudWebSearchClient,
+  ) {}
+
+  /** The request, capped by the Package-level setting when the User set one. */
+  private bound(request: WebSearchRequestV1): WebSearchRequestV1 {
+    const ceiling = this.config.maxResults;
+    if (ceiling === undefined || request.maxResults <= ceiling) return request;
+    return { ...request, maxResults: ceiling };
+  }
+
+  async search(
+    request: WebSearchRequestV1,
+    execution: WebSearchExecutionV1,
+  ): Promise<WebSearchResponseV1> {
+    const effectId = execution.effectId;
+    // The User's ceiling is applied before the provider is asked, so a model
+    // that requests more than the User allows never causes the extra results
+    // to be fetched, let alone recorded on the Turn.
+    const bounded = this.bound(request);
+    const lease = await this.config.leaseCredential(
+      effectId,
+      this.config.connectionGeneration,
+    );
+    try {
+      if (
+        lease.effectId !== effectId ||
+        lease.connectionId !== this.config.connectionId ||
+        lease.credentialGeneration !== this.config.connectionGeneration ||
+        Date.parse(lease.expiresAt) <= (this.config.now ?? Date.now)()
+      ) {
+        throw new Error("Ollama Cloud credential lease is invalid");
+      }
+      const apiKey = await this.credentialLease.open({
+        accountId: this.config.accountId,
+        connectionId: this.config.connectionId,
+        packageId: this.config.packageId,
+        lease,
+      });
+      return await this.client.search(apiKey, bounded, execution.signal);
+    } finally {
+      await this.config.settleCredential(effectId).catch(() => undefined);
+    }
+  }
+}
+
+/** Mount `web_search` for one authorized Connection. */
+export function createOllamaWebSearchRuntimePlugin(
+  config: OllamaWebSearchRuntimeConfig,
+): Plugin.Function {
+  const plugin: Plugin.Function = (ctx) => {
+    const client = new OllamaCloudWebSearchClient({
+      ...(config.apiBaseUrl === undefined
+        ? {}
+        : { apiBaseUrl: config.apiBaseUrl }),
+      ...(config.fetch ? { fetch: config.fetch } : {}),
+    });
+    const definition = createWebSearchToolDefinitionV1(
+      new ConnectionBackedWebSearch(config, ctx.credentialLease, client),
+    );
+    return ctx.tools.register(definition, {
+      admissionCeiling: ["chat", "automation", "subagent"],
+      subagentRoleCeiling: ["executor"],
+    });
+  };
+  plugin.inject = ["tools", "credentialLease"];
+  return plugin;
+}
+
+/**
+ * The Assignment fence (D3): `web_search` exists for a Bot only through an
+ * enabled Assignment of `ollama-cloud-web-search` bound to a Connection. There
+ * is no unauthenticated fallback provider.
+ */
+export function createConfiguredOllamaWebSearchRuntimeContribution(config: {
+  assignment: {
+    packageId: string;
+    capabilityId: string;
+    connectionId?: string;
+    state: string;
+  };
+  accountId: string;
+  connectionId: string;
+  connectionGeneration: string;
+  apiBaseUrl?: string;
+  /** `web-search-max-results`, when this User set it on the Package. */
+  maxResults?: number;
+  leaseCredential(
+    effectId: string,
+    expectedGeneration?: string,
+  ): Promise<CredentialLeaseV1>;
+  settleCredential(effectId: string): Promise<void>;
+  fetch?: OllamaFetch;
+}): Plugin.Function | undefined {
+  if (
+    config.assignment.packageId !== "provider-ollama-cloud" ||
+    config.assignment.capabilityId !== "ollama-cloud-web-search" ||
+    config.assignment.state !== "enabled" ||
+    config.assignment.connectionId !== config.connectionId
+  ) {
+    return undefined;
+  }
+  return createOllamaWebSearchRuntimePlugin({
+    accountId: config.accountId,
+    connectionId: config.connectionId,
+    connectionGeneration: config.connectionGeneration,
+    packageId: "provider-ollama-cloud",
+    ...(config.apiBaseUrl === undefined
+      ? {}
+      : { apiBaseUrl: config.apiBaseUrl }),
+    ...(config.maxResults === undefined
+      ? {}
+      : { maxResults: config.maxResults }),
+    leaseCredential: config.leaseCredential,
+    settleCredential: config.settleCredential,
+    ...(config.fetch ? { fetch: config.fetch } : {}),
+  });
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "lib": ["ES2023", "DOM"],
+    "types": ["bun"]
+  },
+  "include": ["src/**/*.ts"]
+}