Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 68 additions & 6 deletions packages/core/src/tool/plugin/websearch.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,8 @@ export * as WebSearchTool from "./websearch.js"
import type { Context } from "@opencode/plugin/effect/plugin"
import type { SessionHooks } from "@opencode/plugin/effect/session"
import { ToolFailure } from "@opencode/ai/effect"
import { Effect, Schema, Semaphore } from "effect"
import { isRecord } from "@opencode/util/record"
import { Effect, Option, Schema, Semaphore, type JsonSchema } from "effect"
import { HttpClientError } from "effect/http"
import { Config } from "../../config.js"
import { ConfigEntryObserver } from "../../config/plugin/entry-observer.js"
Expand All @@ -22,10 +23,15 @@ const httpErrors = new Map([

export const description = `Search the web using the user's selected search integration. Use this for current information beyond knowledge cutoff.

Pass \`providerID\` to pick the search provider for this call; the accepted values are listed in that parameter. Omit it to use the user's saved or random provider, and put the provider there rather than in the query text.

The current year is ${new Date().getFullYear()}. Use this year when searching for recent information or current events.`

export const Input = Schema.Struct({
query: Schema.String.annotate({ description: "Websearch query" }),
providerID: Schema.optionalKey(WebSearch.ID).annotate({
description: "Search provider for this call. Omit to use the user's saved or random provider.",
}),
})

const Output = Schema.Array(
Expand Down Expand Up @@ -56,13 +62,43 @@ export const Plugin = {
output: Output,
execute: (input, context) =>
Effect.gen(function* () {
yield* permission.assert({
const requested = input.providerID
const approval = {
action: name,
resources: [input.query],
save: ["*"],
metadata: input,
...Permission.invocation(context),
})
}
let needsConsent = false
if (requested !== undefined) {
const providers = (yield* ctx.websearch.providers()).data
// A bad ID fails before the approval prompt so it cannot record a saved permission, but a policy
// deny still outranks it: `assertNotDenied` evaluates the rules without asking the user.
if (!providers.some((provider) => provider.id === requested)) {
yield* permission.assertNotDenied(approval)
return yield* new ToolFailure({
message: `Unknown web search provider "${requested}". Available: ${providers.map((provider) => provider.id).join(", ") || "none"}.`,
})
}
// A saved "disabled" choice outranks a per-call provider; no saved choice still needs consent.
const saved = yield* websearch.default().pipe(Effect.option)
if (Option.isNone(saved)) {
yield* permission.assertNotDenied(approval)
return yield* new WebSearch.DisabledError()
}
needsConsent = saved.value === undefined

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When the user has saved a specific provider ("Choose another provider" in the form, or a provider set in config), a pinned providerID still overrides it for that call. A user who picked a provider for cost, privacy or account reasons loses that control, and the model decides instead. Before this change, the tool always used the user's selection. Should a pinned provider only be honoured when the saved choice is random/unset, or should this be confirmed as the intended product behaviour first?

Copy link
Copy Markdown
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Taken — I adopted the conservative option.

With a specific saved provider, that choice wins: providerID must match it, and a different id is refused with Web search is pinned to "<saved>" by the user. Omit providerID or pass "<saved>". Only "random" (or no choice yet) lets the model pick. The refusal happens before the search and before any approval prompt, so it costs no provider call and leaves no saved permission.

WebSearch.selection() is now exposed on the service so the tool can read the saved choice without guessing from default() (which cannot tell "random" from a specific id). Test: saved exa + request parallel fails with the message and runs zero queries; saved random + request parallel still searches with parallel. Docs updated on websearch.mdx. See 6083d36.

// A provider the user saved outranks a per-call request: only `random` (or no choice yet) leaves the
// routing to the model. Otherwise the request has to agree with the user's choice.
const pinned = yield* websearch.selection()
if (pinned !== undefined && pinned !== false && pinned !== "random" && pinned !== requested) {
yield* permission.assertNotDenied(approval)
return yield* new ToolFailure({
message: `Web search is pinned to "${pinned}" by the user. Omit providerID or pass "${pinned}".`,
})
}
}
yield* permission.assert(approval)
const search = (providerID?: WebSearch.ID) =>
websearch.query(
{ ...input, providerID },
Expand All @@ -71,7 +107,11 @@ export const Plugin = {
onProvider: (provider) => context.progress({ provider: provider.id }),
},
)
const result = yield* search().pipe(
// A pinned provider is used as-is: no failover, and consent never overrides it.
const attempt: Effect.Effect<WebSearch.Response, WebSearch.Error> = needsConsent
? Effect.fail(new WebSearch.ProviderRequiredError())
: search(requested)
const result = yield* attempt.pipe(
Effect.catchTag("WebSearch.ProviderRequired", () => {
return providerSelectionLock
.withPermit(
Expand Down Expand Up @@ -150,7 +190,8 @@ export const Plugin = {
duration: "1 minute",
orElse: () => Effect.fail(new Error("Web search cancelled")),
}),
Effect.flatMap(search),
// Consent never overrides the provider the model pinned for this call.
Effect.flatMap((providerID) => search(requested ?? providerID)),
)
}),
)
Expand All @@ -174,6 +215,8 @@ export const Plugin = {
return { output, content, metadata: { provider: result.providerID } }
}).pipe(
Effect.mapError((error) => {
// The tool already produced a precise, model-facing message.
if (error instanceof ToolFailure) return error
const fallback = `Unable to search the web for ${input.query}`
if (!Schema.is(WebSearch.RequestError)(error)) return new ToolFailure({ message: fallback, error })
const status = HttpClientError.isHttpClientError(error.cause) ? error.cause.response?.status : undefined
Expand All @@ -197,8 +240,27 @@ export const Plugin = {
Effect.as(false),
Effect.catchTag("WebSearch.Disabled", () => Effect.succeed(true)),
)
if (disabled) return delete event.tools[name]
const providers = yield* websearch.providers()
// Policy can remove every provider, and the model shouldn't be offered a tool that can't search.
if (disabled || (yield* websearch.providers()).length === 0) delete event.tools[name]
if (providers.length === 0) return delete event.tools[name]
// The accepted ids are published here because a tool definition converts its schema once at registration.
// With `full_codemode` enabled this tool moves to the Code Mode catalog, which renders and caches its own
// schema from the registry, so the enum only reaches the model for a direct tool call; an unknown id still
// fails with the list of available ones below.
const tool = event.tools[name]
const properties = tool?.input.properties
if (!tool || !isRecord(properties)) return
tool.input = {
...tool.input,
properties: {
...properties,
providerID: {
type: "string",
enum: Array.from(new Set(providers.map((provider) => provider.id))).toSorted(),

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

When the user has saved a specific provider, the tool refuses every other id, but this enum still lists all providers. The model is invited to make calls that will always fail. Could the hook publish only the saved id in that case (or drop providerID from the schema), and keep the full list for random or no choice yet? It would only need the same websearch.selection() read the tool already does.

},
} satisfies JsonSchema.JsonSchema,
}
})
yield* ctx.session.hook("context", hook)
yield* ctx.session.hook("compaction", hook)
Expand Down
11 changes: 10 additions & 1 deletion packages/core/src/websearch.ts
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,8 @@ export type Error = ProviderRequiredError | ProviderNotFoundError | DisabledErro
export interface Interface extends State.Transformable<Editor> {
readonly providers: () => Effect.Effect<readonly Provider[]>
readonly default: () => Effect.Effect<Provider | undefined, DisabledError>
/** The saved choice: a provider id, `"random"`, `false` when disabled, or `undefined` before consent. */
readonly selection: () => Effect.Effect<Selection | undefined>
readonly select: (selection: Selection) => Effect.Effect<void>
readonly query: (
input: Input,
Expand Down Expand Up @@ -178,11 +180,18 @@ const layer = Layer.effect(
const provider = yield* defaultProvider(yield* selection())
return provider && { id: provider.id, name: provider.name }
}),
selection: Effect.fn("WebSearch.selectionValue")(function* () {
return yield* selection()
}),
select: Effect.fn("WebSearch.select")(function* (selection) {
yield* kv.set(ProviderKey, selection)
}),
query: Effect.fn("WebSearch.query")(function* (input, options) {
const choice = input.providerID ? undefined : yield* selection()
// The saved "disabled" choice outranks a per-call provider. An unset choice stays allowed, because
// asking for consent is the tool's job.
const saved = yield* selection()
if (saved === false) return yield* new DisabledError()
const choice = input.providerID ? undefined : saved
let provider = input.providerID
? yield* requireProvider(state.get().providers, input.providerID)
: yield* defaultProvider(choice)
Expand Down
1 change: 1 addition & 0 deletions packages/core/test/fixture/policy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -87,6 +87,7 @@ export const registerIntegrationPolicy = Effect.fn(function* (input: {
WebSearch.Service.of({
providers: () => Effect.die("unused WebSearch.providers"),
default: () => Effect.die("unused WebSearch.default"),
selection: () => Effect.die("unused WebSearch.selection"),
select: () => Effect.die("unused WebSearch.select"),
query: () => Effect.die("unused WebSearch.query"),
transform: () => Effect.succeed({ dispose: Effect.void }),
Expand Down
130 changes: 130 additions & 0 deletions packages/core/test/tool-websearch.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ const setup = Effect.gen(function* () {
fixture.events.push("permission")
fixture.assertions.push(input)
}),
assertNotDenied: () => Effect.void,
}),
),
WebSearch.node.replace(Layer.succeed(WebSearch.Service, websearch)),
Expand Down Expand Up @@ -192,6 +193,106 @@ describe("WebSearchTool registration", () => {
}),
)

it.effect("uses the provider the model picks when the saved choice is random", () =>
Effect.gen(function* () {
const fixture = yield* setup
yield* fixture.websearch.select("random")

expect(
yield* executeTool(fixture.registry, {
sessionID,
...toolIdentity,
call: {
type: "tool-call",
id: "call-provider",
name: "websearch",
input: { query: "effect", providerID: "parallel" },
},
}),
).toMatchObject({ status: "completed", metadata: { provider: "parallel" } })
expect(fixture.formRequests).toEqual([])
expect(fixture.websearch.queries).toEqual([{ query: "effect", providerID: WebSearch.ID.make("parallel") }])
expect(yield* fixture.kv.get(WebSearch.ProviderKey)).toBe("random")
}),
)

it.effect("keeps a provider the user pinned instead of the one the model asks for", () =>
Effect.gen(function* () {
const fixture = yield* setup
yield* fixture.websearch.select(WebSearch.ID.make("exa"))

expect(
yield* executeTool(fixture.registry, {
sessionID,
...toolIdentity,
call: {
type: "tool-call",
id: "call-pinned",
name: "websearch",
input: { query: "effect", providerID: "parallel" },
},
}),
).toEqual({
status: "error",
error: {
type: "tool.execution",
message: 'Web search is pinned to "exa" by the user. Omit providerID or pass "exa".',
},
})
expect(fixture.websearch.queries).toEqual([])
expect(yield* fixture.kv.get(WebSearch.ProviderKey)).toBe(WebSearch.ID.make("exa"))
}),
)

it.effect("rejects a provider that is not available before searching", () =>
Effect.gen(function* () {
const fixture = yield* setup

expect(
yield* executeTool(fixture.registry, {
sessionID,
...toolIdentity,
call: {
type: "tool-call",
id: "call-missing",
name: "websearch",
input: { query: "effect", providerID: "missing" },
},
}),
).toEqual({
status: "error",
error: {
type: "tool.execution",
message: 'Unknown web search provider "missing". Available: exa, parallel.',
},
})
expect(fixture.events).toEqual([])
expect(fixture.formRequests).toEqual([])
}),
)

it.effect("asks for consent before the first search with a provider the model picks", () =>
Effect.gen(function* () {
const fixture = yield* setup
fixture.formResponse = { status: "answered", answer: { choice: "allow" } }

expect(
yield* executeTool(fixture.registry, {
sessionID,
...toolIdentity,
call: {
type: "tool-call",
id: "call-provider-consent",
name: "websearch",
input: { query: "effect", providerID: "parallel" },
},
}),
).toMatchObject({ status: "completed", metadata: { provider: "parallel" } })
expect(fixture.formRequests).toHaveLength(1)
expect(fixture.websearch.queries).toEqual([{ query: "effect", providerID: WebSearch.ID.make("parallel") }])
}),
)

it.effect("uses the concise no-results fallback", () =>
Effect.gen(function* () {
const fixture = yield* setup
Expand Down Expand Up @@ -358,6 +459,35 @@ describe("WebSearchTool registration", () => {
}),
)

it.effect("lists the live provider ids in the schema the model sees", () =>
Effect.gen(function* () {
contextHooks.length = 0
const fixture = yield* setup
const definition = (yield* toolDefinitions(fixture.registry)).find((tool) => tool.name === "websearch")
const schema = () =>
Effect.gen(function* () {
const event = {
tools: {
[WebSearchTool.name]: {
description: definition?.description ?? "",
input: structuredClone(definition?.inputSchema ?? {}),
},
},
}
yield* Effect.forEach(contextHooks, (hook) => hook(event as unknown as SessionContext))
return event.tools[WebSearchTool.name]?.input as {
required?: ReadonlyArray<string>
properties: Record<string, { enum?: ReadonlyArray<string> }>
}
})

expect((yield* schema()).properties.providerID?.enum).toEqual(["exa", "parallel"])
expect((yield* schema()).required).toEqual(["query"])
// An unchanged provider set emits the same schema, so the prompt prefix stays stable.
expect(JSON.stringify(yield* schema())).toBe(JSON.stringify(yield* schema()))
}),
)

it.effect("offers the tool to the model only while a provider remains", () =>
Effect.gen(function* () {
contextHooks.length = 0
Expand Down
13 changes: 13 additions & 0 deletions packages/core/test/websearch.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -586,6 +586,19 @@ describe("WebSearch", () => {
)
})

it.effect("keeps an explicit provider disabled when web search is turned off", () =>
Effect.gen(function* () {
const exa = yield* register("exa")
const websearch = yield* WebSearch.Service
yield* websearch.select(false)

expect(yield* websearch.query({ query: "effect", providerID: exa.providerID }).pipe(Effect.flip)).toBeInstanceOf(
WebSearch.DisabledError,
)
expect(exa.calls).toEqual([])
}),
)

it.effect("fails when web search is explicitly disabled", () =>
Effect.gen(function* () {
yield* register("exa")
Expand Down
3 changes: 2 additions & 1 deletion services/site/src/docs/content/tools.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -148,7 +148,8 @@ URL as its resource.
### Websearch

`websearch` searches the selected integration for current information. Its
input is a search `query`.
input is a search `query` and an optional `providerID`; the accepted ids are
listed in that parameter's schema.

```text
Search the web for the latest Bun release notes.
Expand Down
9 changes: 9 additions & 0 deletions services/site/src/docs/content/websearch.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,15 @@ $ TAVILY_API_KEY=your-key opencode

Set a provider in `opencode.jsonc` to skip the selection prompt.

The model can also pick the provider for a single search by passing `providerID`;
the ids available in the current session are listed in that parameter's schema.
A pinned search uses only that provider, does not fall back to another one when
rate limited, and never changes your default.

If you saved a specific provider, that choice wins: `providerID` must match it,
and a different id is refused so a search never leaves the provider you chose.
With `"random"` (or before you have chosen) the model is free to pick.

```jsonc title="opencode.jsonc"
{
"$schema": "https://opencode.ai/config.json",
Expand Down
Loading