opencode-search-plugin 2.1.1 → 3.0.0

package/plugins/deepseek-search.ts

@@ -112,8 +112,12 @@ type SearchResult = ReturnType<typeof toResult>
 //
 //   DEEPSEEK_CACHE_TTL   ms to reuse a response for the same query (0 disables)
 //   DEEPSEEK_COUNT       results per search, clamped to 1-50
-//   DEEPSEEK_API_KEY     required; from https://platform.deepseek.com
+//   DEEPSEEK_TIMEOUT     ms to wait before failing (0 removes the deadline)
+//   OSP_DEEPSEEK_API_KEY     required; from https://platform.deepseek.com
 const CACHE_TTL = envInt("DEEPSEEK_CACHE_TTL", 600_000)
+// OpenCode's own providers each bounded themselves at 25s, and the host adds
+// no deadline of its own around `execute`, so this is the only one that exists.
+const SEARCH_TIMEOUT = envInt("DEEPSEEK_TIMEOUT", 25_000)
 const COUNT = Math.min(Math.max(envInt("DEEPSEEK_COUNT", 10), 1), 50)
 
 const CACHE_LIMIT = 200
@@ -138,6 +142,14 @@ function writeCache(queryKey: string, results: SearchResult[]): void {
   }
 }
 
+// A hung upstream must not hang the agent: the deadline bounds it, and the
+// thunk's signal carries host cancellation into the socket. `timeout <= 0`
+// removes the deadline but never the cancellation, because
+// `AbortSignal.timeout(0)` aborts instantly rather than "never".
+function timedSignal(signal: AbortSignal, timeout: number): AbortSignal {
+  return timeout > 0 ? AbortSignal.any([signal, AbortSignal.timeout(timeout)]) : signal
+}
+
 export const effect = (ctx: Plugin.Context) =>
   Effect.gen(function* () {
     // Make "DeepSeek" show up in /connect with an API-key method.
@@ -151,7 +163,7 @@ export const effect = (ctx: Plugin.Context) =>
       })
       editor.method.update({
         integrationID: ID,
-        method: { type: "env", names: ["DEEPSEEK_API_KEY"] },
+        method: { type: "env", names: ["OSP_DEEPSEEK_API_KEY"] },
       })
     })
 
@@ -171,7 +183,7 @@ export const effect = (ctx: Plugin.Context) =>
         const credential = connection
           ? yield* soften(ctx.integration.connection.resolve(connection))
           : undefined
-        return credential?.type === "key" ? credential.key : process.env.DEEPSEEK_API_KEY
+        return credential?.type === "key" ? credential.key : process.env.OSP_DEEPSEEK_API_KEY
       })
 
     // DeepSeek is bound to websearch only while a key exists. Deleting the key
@@ -195,12 +207,12 @@ export const effect = (ctx: Plugin.Context) =>
             const key = yield* resolveKey()
             if (!key) {
               return yield* Effect.fail(
-                new Error("Connect DeepSeek in /connect, or set DEEPSEEK_API_KEY"),
+                new Error("Connect DeepSeek in /connect, or set OSP_DEEPSEEK_API_KEY"),
               )
             }
 
             const response = yield* Effect.tryPromise({
-              try: () =>
+              try: (signal) =>
                 fetch("https://api.deepseek.com/v1/tools/search", {
                   method: "POST",
                   headers: {
@@ -212,8 +224,14 @@ export const effect = (ctx: Plugin.Context) =>
                     query: queryKey,
                     count: COUNT,
                   }),
+                  signal: timedSignal(signal, SEARCH_TIMEOUT),
                 }),
-              catch: (error) => new Error("DeepSeek request failed: " + String(error)),
+              // A timeout is its own failure: naming it stops the user hunting
+              // for a key problem that was never there.
+              catch: (error) =>
+                error instanceof Error && error.name === "TimeoutError"
+                  ? new Error("DeepSeek search timed out after " + SEARCH_TIMEOUT + "ms")
+                  : new Error("DeepSeek request failed: " + String(error)),
             })
 
             if (!response.ok) {

package/plugins/jina-search.ts

@@ -77,13 +77,24 @@ function envStr(name: string): string {
 //   JINA_GL              country code for results, e.g. "us", "cn"
 //   JINA_HL              language code for results, e.g. "en", "zh-cn"
 //   JINA_LOCATION        city-level origin to simulate, e.g. "Berlin"
-//   JINA_API_KEY         required; free key at https://jina.ai/?sui=apikey
+//   JINA_TIMEOUT         ms to wait before failing (0 removes the deadline).
+//                        Defaults to 25000, or 60000 when JINA_INCLUDE_CONTENT
+//                        is on, because whole-page fetches legitimately take
+//                        far longer than a snippet search
+//   OSP_JINA_API_KEY         required; free key at https://jina.ai/?sui=apikey
 const CACHE_TTL = envInt("JINA_CACHE_TTL", 600_000)
 const INCLUDE_CONTENT = envStr("JINA_INCLUDE_CONTENT") === "true"
 const SEARCH_SIZE = Math.min(Math.max(envInt("JINA_NUM", 0), 0), 100)
 const GL = envStr("JINA_GL")
 const HL = envStr("JINA_HL")
 const LOCATION = envStr("JINA_LOCATION")
+// OpenCode's own providers each bounded themselves at 25s, and the host adds
+// no deadline of its own around `execute`, so this is the only one that exists.
+// Jina is the one provider whose default has to vary: asking for page content
+// turns a snippet search into a crawl, and a shared budget would either cut
+// that off or be padded so high that a genuine hang takes a minute to surface.
+const DEFAULT_TIMEOUT = INCLUDE_CONTENT ? 60_000 : 25_000
+const SEARCH_TIMEOUT = envInt("JINA_TIMEOUT", DEFAULT_TIMEOUT)
 
 const CACHE_LIMIT = 200
 const cache = new Map<string, { at: number; results: SearchResult[] }>()
@@ -107,6 +118,14 @@ function writeCache(queryKey: string, results: SearchResult[]): void {
   }
 }
 
+// A hung upstream must not hang the agent: the deadline bounds it, and the
+// thunk's signal carries host cancellation into the socket. `timeout <= 0`
+// removes the deadline but never the cancellation, because
+// `AbortSignal.timeout(0)` aborts instantly rather than "never".
+function timedSignal(signal: AbortSignal, timeout: number): AbortSignal {
+  return timeout > 0 ? AbortSignal.any([signal, AbortSignal.timeout(timeout)]) : signal
+}
+
 export const effect = (ctx: Plugin.Context) =>
   Effect.gen(function* () {
     // Make "Jina" show up in /connect with an API-key method.
@@ -120,7 +139,7 @@ export const effect = (ctx: Plugin.Context) =>
       })
       editor.method.update({
         integrationID: ID,
-        method: { type: "env", names: ["JINA_API_KEY"] },
+        method: { type: "env", names: ["OSP_JINA_API_KEY"] },
       })
     })
 
@@ -140,7 +159,7 @@ export const effect = (ctx: Plugin.Context) =>
         const credential = connection
           ? yield* soften(ctx.integration.connection.resolve(connection))
           : undefined
-        return credential?.type === "key" ? credential.key : process.env.JINA_API_KEY
+        return credential?.type === "key" ? credential.key : process.env.OSP_JINA_API_KEY
       })
 
     // Jina is bound to websearch only while a key exists. Deleting the key
@@ -164,12 +183,12 @@ export const effect = (ctx: Plugin.Context) =>
             const key = yield* resolveKey()
             if (!key) {
               return yield* Effect.fail(
-                new Error("Connect Jina in /connect, or set JINA_API_KEY"),
+                new Error("Connect Jina in /connect, or set OSP_JINA_API_KEY"),
               )
             }
 
             const response = yield* Effect.tryPromise({
-              try: () =>
+              try: (signal) =>
                 fetch("https://s.jina.ai/", {
                   method: "POST",
                   headers: {
@@ -188,8 +207,14 @@ export const effect = (ctx: Plugin.Context) =>
                     ...(HL ? { hl: HL } : {}),
                     ...(LOCATION ? { location: LOCATION } : {}),
                   }),
+                  signal: timedSignal(signal, SEARCH_TIMEOUT),
                 }),
-              catch: (error) => new Error("Jina request failed: " + String(error)),
+              // A timeout is its own failure: naming it stops the user hunting
+              // for a key problem that was never there.
+              catch: (error) =>
+                error instanceof Error && error.name === "TimeoutError"
+                  ? new Error("Jina search timed out after " + SEARCH_TIMEOUT + "ms")
+                  : new Error("Jina request failed: " + String(error)),
             })
 
             if (!response.ok) {

package/plugins/keenable-search.ts

@@ -122,8 +122,12 @@ function envStr(name: string): string {
 //                         leave unset and the organization's default applies
 //   KEENABLE_TITLE        app name sent as X-Keenable-Title, which the keyless
 //                         endpoint requires to attribute traffic (max 256 chars)
-//   KEENABLE_API_KEY      optional; keyless access works without it
+//   KEENABLE_TIMEOUT      ms to wait before failing (0 removes the deadline)
+//   OSP_KEENABLE_API_KEY      optional; keyless access works without it
 const CACHE_TTL = envInt("KEENABLE_CACHE_TTL", 600_000)
+// OpenCode's own providers each bounded themselves at 25s, and the host adds
+// no deadline of its own around `execute`, so this is the only one that exists.
+const SEARCH_TIMEOUT = envInt("KEENABLE_TIMEOUT", 25_000)
 const SEARCH_SIZE = Math.min(Math.max(envInt("KEENABLE_MAX_RESULTS", 10), 1), 50)
 const MODE = envStr("KEENABLE_MODE")
 const TITLE = (envStr("KEENABLE_TITLE") || "opencode-search-plugin").slice(0, 256)
@@ -153,6 +157,14 @@ function writeCache(queryKey: string, results: SearchResult[]): void {
   }
 }
 
+// A hung upstream must not hang the agent: the deadline bounds it, and the
+// thunk's signal carries host cancellation into the socket. `timeout <= 0`
+// removes the deadline but never the cancellation, because
+// `AbortSignal.timeout(0)` aborts instantly rather than "never".
+function timedSignal(signal: AbortSignal, timeout: number): AbortSignal {
+  return timeout > 0 ? AbortSignal.any([signal, AbortSignal.timeout(timeout)]) : signal
+}
+
 // Unlike the key-requiring providers in this repo, Keenable never gates on
 // `bound`: keyless access is a first-class mode, so the provider is always in
 // the pool. The key is still read per call, which is why no credential-event
@@ -171,7 +183,7 @@ export const effect = (ctx: Plugin.Context) =>
       })
       editor.method.update({
         integrationID: ID,
-        method: { type: "env", names: ["KEENABLE_API_KEY"] },
+        method: { type: "env", names: ["OSP_KEENABLE_API_KEY"] },
       })
     })
 
@@ -200,7 +212,7 @@ export const effect = (ctx: Plugin.Context) =>
               ? yield* soften(ctx.integration.connection.resolve(connection))
               : undefined
             const key =
-              credential?.type === "key" ? credential.key : process.env.KEENABLE_API_KEY
+              credential?.type === "key" ? credential.key : process.env.OSP_KEENABLE_API_KEY
 
             const headers: Record<string, string> = {
               Accept: "application/json",
@@ -213,7 +225,7 @@ export const effect = (ctx: Plugin.Context) =>
             if (key) headers["X-API-Key"] = key
 
             const response = yield* Effect.tryPromise({
-              try: () =>
+              try: (signal) =>
                 fetch(key ? SEARCH_URL : PUBLIC_URL, {
                   method: "POST",
                   headers,
@@ -222,8 +234,14 @@ export const effect = (ctx: Plugin.Context) =>
                     max_results: SEARCH_SIZE,
                     ...(MODE ? { mode: MODE } : {}),
                   }),
+                  signal: timedSignal(signal, SEARCH_TIMEOUT),
                 }),
-              catch: (error) => new Error("Keenable request failed: " + String(error)),
+              // A timeout is its own failure: naming it stops the user hunting
+              // for a key problem that was never there.
+              catch: (error) =>
+                error instanceof Error && error.name === "TimeoutError"
+                  ? new Error("Keenable search timed out after " + SEARCH_TIMEOUT + "ms")
+                  : new Error("Keenable request failed: " + String(error)),
             })
 
             if (!response.ok) {
@@ -235,7 +253,7 @@ export const effect = (ctx: Plugin.Context) =>
                   new Error(
                     "Keenable credits exhausted (HTTP 402): the free monthly " +
                       "allowance of 100,000 requests is spent. Connect Keenable " +
-                      "in /connect or set KEENABLE_API_KEY to buy credits, or " +
+                      "in /connect or set OSP_KEENABLE_API_KEY to buy credits, or " +
                       "wait for the allowance to reset.",
                   ),
                 )
@@ -249,7 +267,7 @@ export const effect = (ctx: Plugin.Context) =>
                       (key
                         ? ""
                         : ". The keyless pool allows 1,000 requests an hour and " +
-                          "10 a second per IP; set KEENABLE_API_KEY to spend your " +
+                          "10 a second per IP; set OSP_KEENABLE_API_KEY to spend your " +
                           "own 100,000-request monthly allowance instead."),
                   ),
                 )

package/plugins/linkup-search.ts

@@ -54,8 +54,12 @@ function envStr(name: string): string {
 //                        vendor's recommended default for agents), "standard"
 //                        (single agentic pass) or "deep" (several iterations)
 //   LINKUP_MAX_RESULTS   results per search, clamped to 1-100
-//   LINKUP_API_KEY       required; from https://app.linkup.so
+//   LINKUP_TIMEOUT       ms to wait before failing (0 removes the deadline)
+//   OSP_LINKUP_API_KEY       required; from https://app.linkup.so
 const CACHE_TTL = envInt("LINKUP_CACHE_TTL", 600_000)
+// OpenCode's own providers each bounded themselves at 25s, and the host adds
+// no deadline of its own around `execute`, so this is the only one that exists.
+const SEARCH_TIMEOUT = envInt("LINKUP_TIMEOUT", 25_000)
 const SEARCH_SIZE = Math.min(Math.max(envInt("LINKUP_MAX_RESULTS", 10), 1), 100)
 const DEPTH = ["flash", "fast", "standard", "deep"].includes(envStr("LINKUP_DEPTH"))
   ? envStr("LINKUP_DEPTH")
@@ -83,6 +87,14 @@ function writeCache(queryKey: string, results: SearchResult[]): void {
   }
 }
 
+// A hung upstream must not hang the agent: the deadline bounds it, and the
+// thunk's signal carries host cancellation into the socket. `timeout <= 0`
+// removes the deadline but never the cancellation, because
+// `AbortSignal.timeout(0)` aborts instantly rather than "never".
+function timedSignal(signal: AbortSignal, timeout: number): AbortSignal {
+  return timeout > 0 ? AbortSignal.any([signal, AbortSignal.timeout(timeout)]) : signal
+}
+
 export const effect = (ctx: Plugin.Context) =>
   Effect.gen(function* () {
     // Make "Linkup" show up in /connect with an API-key method.
@@ -96,7 +108,7 @@ export const effect = (ctx: Plugin.Context) =>
       })
       editor.method.update({
         integrationID: ID,
-        method: { type: "env", names: ["LINKUP_API_KEY"] },
+        method: { type: "env", names: ["OSP_LINKUP_API_KEY"] },
       })
     })
 
@@ -116,7 +128,7 @@ export const effect = (ctx: Plugin.Context) =>
         const credential = connection
           ? yield* soften(ctx.integration.connection.resolve(connection))
           : undefined
-        return credential?.type === "key" ? credential.key : process.env.LINKUP_API_KEY
+        return credential?.type === "key" ? credential.key : process.env.OSP_LINKUP_API_KEY
       })
 
     // Linkup is bound to websearch only while a key exists. Deleting the key
@@ -140,12 +152,12 @@ export const effect = (ctx: Plugin.Context) =>
             const key = yield* resolveKey()
             if (!key) {
               return yield* Effect.fail(
-                new Error("Connect Linkup in /connect, or set LINKUP_API_KEY"),
+                new Error("Connect Linkup in /connect, or set OSP_LINKUP_API_KEY"),
               )
             }
 
             const response = yield* Effect.tryPromise({
-              try: () =>
+              try: (signal) =>
                 fetch("https://api.linkup.so/v1/search", {
                   method: "POST",
                   headers: {
@@ -159,8 +171,14 @@ export const effect = (ctx: Plugin.Context) =>
                     outputType: "searchResults",
                     maxResults: SEARCH_SIZE,
                   }),
+                  signal: timedSignal(signal, SEARCH_TIMEOUT),
                 }),
-              catch: (error) => new Error("Linkup request failed: " + String(error)),
+              // A timeout is its own failure: naming it stops the user hunting
+              // for a key problem that was never there.
+              catch: (error) =>
+                error instanceof Error && error.name === "TimeoutError"
+                  ? new Error("Linkup search timed out after " + SEARCH_TIMEOUT + "ms")
+                  : new Error("Linkup request failed: " + String(error)),
             })
 
             if (!response.ok) {

package/plugins/metaso-search.ts

@@ -111,8 +111,12 @@ type SearchResult = ReturnType<typeof toResult>
 //   METASO_INCLUDE_RAW_CONTENT  true returns the full source text of every hit: same
 //                               search cost, far more context tokens. Only worth it
 //                               when you would otherwise webfetch those hits anyway.
-//   METASO_API_KEY              required; from https://metaso.cn
+//   METASO_TIMEOUT              ms to wait before failing (0 removes the deadline)
+//   OSP_METASO_API_KEY              required; from https://metaso.cn
 const CACHE_TTL = envInt("METASO_CACHE_TTL", 600_000)
+// OpenCode's own providers each bounded themselves at 25s, and the host adds
+// no deadline of its own around `execute`, so this is the only one that exists.
+const SEARCH_TIMEOUT = envInt("METASO_TIMEOUT", 25_000)
 const SEARCH_SIZE = Math.min(Math.max(envInt("METASO_SEARCH_SIZE", 20), 1), 100)
 const INCLUDE_RAW_CONTENT = envStr("METASO_INCLUDE_RAW_CONTENT") === "true"
 
@@ -138,6 +142,14 @@ function writeCache(queryKey: string, results: SearchResult[]): void {
   }
 }
 
+// A hung upstream must not hang the agent: the deadline bounds it, and the
+// thunk's signal carries host cancellation into the socket. `timeout <= 0`
+// removes the deadline but never the cancellation, because
+// `AbortSignal.timeout(0)` aborts instantly rather than "never".
+function timedSignal(signal: AbortSignal, timeout: number): AbortSignal {
+  return timeout > 0 ? AbortSignal.any([signal, AbortSignal.timeout(timeout)]) : signal
+}
+
 export const effect = (ctx: Plugin.Context) =>
   Effect.gen(function* () {
     // Make "Metaso" show up in /connect with an API-key method.
@@ -151,7 +163,7 @@ export const effect = (ctx: Plugin.Context) =>
       })
       editor.method.update({
         integrationID: ID,
-        method: { type: "env", names: ["METASO_API_KEY"] },
+        method: { type: "env", names: ["OSP_METASO_API_KEY"] },
       })
     })
 
@@ -171,7 +183,7 @@ export const effect = (ctx: Plugin.Context) =>
         const credential = connection
           ? yield* soften(ctx.integration.connection.resolve(connection))
           : undefined
-        return credential?.type === "key" ? credential.key : process.env.METASO_API_KEY
+        return credential?.type === "key" ? credential.key : process.env.OSP_METASO_API_KEY
       })
 
     // Metaso is bound to websearch only while a key exists. Deleting the key
@@ -195,12 +207,12 @@ export const effect = (ctx: Plugin.Context) =>
             const key = yield* resolveKey()
             if (!key) {
               return yield* Effect.fail(
-                new Error("Connect Metaso in /connect, or set METASO_API_KEY"),
+                new Error("Connect Metaso in /connect, or set OSP_METASO_API_KEY"),
               )
             }
 
             const response = yield* Effect.tryPromise({
-              try: () =>
+              try: (signal) =>
                 fetch("https://metaso.cn/api/v1/search", {
                   method: "POST",
                   headers: {
@@ -216,8 +228,14 @@ export const effect = (ctx: Plugin.Context) =>
                     includeRawContent: INCLUDE_RAW_CONTENT,
                     conciseSnippet: true,
                   }),
+                  signal: timedSignal(signal, SEARCH_TIMEOUT),
                 }),
-              catch: (error) => new Error("Metaso request failed: " + String(error)),
+              // A timeout is its own failure: naming it stops the user hunting
+              // for a key problem that was never there.
+              catch: (error) =>
+                error instanceof Error && error.name === "TimeoutError"
+                  ? new Error("Metaso search timed out after " + SEARCH_TIMEOUT + "ms")
+                  : new Error("Metaso request failed: " + String(error)),
             })
 
             if (!response.ok) {

package/plugins/ollama-search.ts

@@ -0,0 +1,253 @@
+import { Plugin } from "@opencode/plugin/effect"
+import { Effect, Schema, Stream } from "effect"
+
+// Ollama's hosted search answers with the flattest envelope in this package:
+// `results` carries the hits, each a title, a URL and the page's own markdown
+// -- hundreds to tens of thousands of characters, because `content` is the
+// fetched page, not a snippet -- with no wrapper fields and, unlike every
+// other provider here, no dates. Every field but the URL is optional, and a
+// missing one means "Ollama provided none", not an error.
+const OllamaResponse = Schema.Struct({
+  results: Schema.optional(
+    Schema.Array(
+      Schema.Struct({
+        title: Schema.optional(Schema.String),
+        url: Schema.String,
+        content: Schema.optional(Schema.String),
+      }),
+    ),
+  ),
+})
+
+// The /connect integration ID, and the websearch provider ID it binds to.
+// The `osp-` prefix is this package's namespace: OpenCode's built-ins and a
+// vendor plugin's own entry are bare vendor names, and OpenCode's own `ollama`
+// model provider already registers one, so the bare name is spoken for -- the
+// prefix is what keeps this websearch entry and its /connect row distinct from
+// that model provider, and from the opencode.db row keyed by integration ID.
+const ID = "osp-ollama"
+
+// Ollama returns no publication date, so results carry an empty time record.
+function toResult(item: {
+  title?: string | undefined
+  url: string
+  content?: string | undefined
+}) {
+  return {
+    url: item.url,
+    // The URL is the one field the schema insists on, so it is also the one
+    // thing a title can fall back to rather than leave the result untitled.
+    title: item.title || item.url,
+    content: item.content ?? "",
+    time: {},
+  }
+}
+
+type SearchResult = ReturnType<typeof toResult>
+
+function envInt(name: string, fallback: number): number {
+  const raw = (process.env[name] ?? "").trim()
+  if (raw === "") return fallback
+  const value = Number(raw)
+  return Number.isFinite(value) && value >= 0 ? value : fallback
+}
+
+function envStr(name: string): string {
+  return (process.env[name] ?? "").trim()
+}
+
+// Web search rides on an Ollama account: the API is hosted at ollama.com, not
+// served by the local model runner (the official SDKs hardcode that host, and
+// the local server neither proxies this endpoint nor reads this key). A
+// generous free tier covers individual use, and the API caps a search at 10
+// results, which is the clamp below. Knobs are read once at load time, so
+// restart after changing them.
+//
+//   OLLAMA_CACHE_TTL     ms to reuse a response for the same query (0 disables)
+//   OLLAMA_MAX_RESULTS   results per search, clamped to 1-10 (the API's range).
+//                        `content` is a whole page of markdown, not a snippet,
+//                        so the default of 5 already means thousands of
+//                        characters of context per search
+//   OLLAMA_TIMEOUT       ms to wait before failing (0 removes the deadline)
+//   OSP_OLLAMA_API_KEY   required; from https://ollama.com/settings/keys.
+//                        Namespaced away from the vendor-canonical
+//                        OLLAMA_API_KEY, which other tools -- and OpenCode's
+//                        own config examples -- also read, sometimes holding
+//                        a bearer token for an Ollama-compatible proxy
+//                        rather than an account key. A /connect credential
+//                        still outranks this variable.
+const CACHE_TTL = envInt("OLLAMA_CACHE_TTL", 600_000)
+// OpenCode's own providers each bounded themselves at 25s, and the host adds
+// no deadline of its own around `execute`, so this is the only one that exists.
+const SEARCH_TIMEOUT = envInt("OLLAMA_TIMEOUT", 25_000)
+const MAX_RESULTS = Math.min(Math.max(envInt("OLLAMA_MAX_RESULTS", 5), 1), 10)
+
+const SEARCH_URL = "https://ollama.com/api/web_search"
+
+const CACHE_LIMIT = 200
+const cache = new Map<string, { at: number; results: SearchResult[] }>()
+
+function cacheKey(query: string): string {
+  return query.trim().replace(/\s+/g, " ")
+}
+
+function readCache(queryKey: string): SearchResult[] | undefined {
+  if (CACHE_TTL <= 0) return undefined
+  const hit = cache.get(queryKey)
+  return hit && Date.now() - hit.at < CACHE_TTL ? hit.results : undefined
+}
+
+function writeCache(queryKey: string, results: SearchResult[]): void {
+  if (CACHE_TTL <= 0) return
+  cache.set(queryKey, { at: Date.now(), results })
+  if (cache.size > CACHE_LIMIT) {
+    const oldest = cache.keys().next().value
+    if (oldest !== undefined) cache.delete(oldest)
+  }
+}
+
+// A hung upstream must not hang the agent: the deadline bounds it, and the
+// thunk's signal carries host cancellation into the socket. `timeout <= 0`
+// removes the deadline but never the cancellation, because
+// `AbortSignal.timeout(0)` aborts instantly rather than "never".
+function timedSignal(signal: AbortSignal, timeout: number): AbortSignal {
+  return timeout > 0 ? AbortSignal.any([signal, AbortSignal.timeout(timeout)]) : signal
+}
+
+export const effect = (ctx: Plugin.Context) =>
+  Effect.gen(function* () {
+    // Make "Ollama" show up in /connect with an API-key method.
+    yield* ctx.integration.transform((editor) => {
+      editor.update(ID, (integration) => {
+        integration.name = "Ollama Search (osp)"
+      })
+      editor.method.update({
+        integrationID: ID,
+        method: { type: "key", label: "Ollama API key" },
+      })
+      editor.method.update({
+        integrationID: ID,
+        method: { type: "env", names: ["OSP_OLLAMA_API_KEY"] },
+      })
+    })
+
+    // The host instantiates this API's failure channel as `unknown`, which would
+    // make the whole plugin effect unrunnable. A credential read must never take
+    // the plugin down: a failed read degrades to "no stored key", and the
+    // environment fallback below applies exactly as it does when the credential
+    // simply does not exist.
+    const soften = <A>(read: Effect.Effect<A, unknown>): Effect.Effect<A | undefined, never> =>
+      read.pipe(Effect.catch(() => Effect.succeed(undefined)))
+
+    // The key comes from the /connect credential, falling back to the
+    // environment. Resolved per call so a rotated key needs no restart.
+    const resolveKey = () =>
+      Effect.gen(function* () {
+        const connection = yield* soften(ctx.integration.connection.active(ID))
+        const credential = connection
+          ? yield* soften(ctx.integration.connection.resolve(connection))
+          : undefined
+        return credential?.type === "key" ? credential.key : process.env.OSP_OLLAMA_API_KEY
+      })
+
+    // Web search requires an Ollama account, so the provider binds only while
+    // a key exists. Deleting the key unbinds it, and `random` can never pick a
+    // keyless Ollama. The transform replays on reload and reads `bound` as it
+    // stands then.
+    let bound = Boolean(yield* resolveKey())
+
+    yield* ctx.websearch.transform((editor) => {
+      if (!bound) return
+      editor.add({
+        id: ID,
+        name: "Ollama Search",
+        execute: ({ query }) =>
+          Effect.gen(function* () {
+            const queryKey = cacheKey(query)
+            const cached = readCache(queryKey)
+            if (cached) return cached
+
+            // Rechecked per call: binding can lag a key deletion by the
+            // event round-trip, so this keeps that window explicit.
+            const key = yield* resolveKey()
+            if (!key) {
+              return yield* Effect.fail(
+                new Error("Connect Ollama in /connect, or set OSP_OLLAMA_API_KEY"),
+              )
+            }
+
+            const response = yield* Effect.tryPromise({
+              try: (signal) =>
+                fetch(SEARCH_URL, {
+                  method: "POST",
+                  headers: {
+                    Accept: "application/json",
+                    "Content-Type": "application/json",
+                    Authorization: "Bearer " + key,
+                  },
+                  body: JSON.stringify({
+                    query: queryKey,
+                    max_results: MAX_RESULTS,
+                  }),
+                  signal: timedSignal(signal, SEARCH_TIMEOUT),
+                }),
+              // A timeout is its own failure: naming it stops the user hunting
+              // for a key problem that was never there.
+              catch: (error) =>
+                error instanceof Error && error.name === "TimeoutError"
+                  ? new Error("Ollama search timed out after " + SEARCH_TIMEOUT + "ms")
+                  : new Error("Ollama request failed: " + String(error)),
+            })
+
+            if (!response.ok) {
+              // A bad key answers 401 with `{"error":"Unauthorized"}` (checked
+              // against the live API); the body rides along verbatim, so any
+              // shape Ollama adds later is reported rather than mistranslated.
+              const detail = yield* Effect.tryPromise({
+                try: () => response.text(),
+                catch: () => new Error("response body unavailable"),
+              })
+              return yield* Effect.fail(
+                new Error("Ollama API error " + response.status + ": " + detail),
+              )
+            }
+
+            const json = yield* Effect.tryPromise({
+              try: () => response.json(),
+              catch: (error) => new Error("Invalid Ollama response: " + String(error)),
+            })
+
+            const body = yield* Schema.decodeUnknownEffect(OllamaResponse)(json)
+            const results = (body.results ?? []).map(toResult)
+
+            writeCache(queryKey, results)
+            return results
+          }),
+      })
+    })
+
+    // Rebind on credential changes: connect, delete, or rotate a key and the
+    // provider joins or leaves the websearch pool without a restart. Env-var
+    // keys cannot change under a running process, so they bind at startup.
+    yield* Effect.forkScoped(
+      ctx.event.subscribe().pipe(
+        Stream.filter(
+          (event) =>
+            event.type === "credential.updated" ||
+            event.type === "credential.switched" ||
+            event.type === "integration.updated",
+        ),
+        Stream.mapEffect(() =>
+          Effect.gen(function* () {
+            const next = Boolean(yield* resolveKey())
+            if (next === bound) return
+            bound = next
+            yield* ctx.websearch.reload()
+          }),
+        ),
+        Stream.runDrain,
+      ),
+    )
+  })
+
+export default Plugin.define({ id: "ollama-search", effect })