106 lines
4.8 KiB
Markdown
106 lines
4.8 KiB
Markdown
<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->
|
|
|
|
# ctx.web
|
|
|
|
`WebService` — provided by `@deepseek-ai/dsh-web`.
|
|
|
|
The web access service. Registered as `ctx.web` (one instance per context).
|
|
Selection semantics (resolved at execution time, never order-dependent):
|
|
- A configured id that is registered and `available()` → that provider.
|
|
- A configured id not registered → `WEB_PROVIDER_CONFIGURED_MISSING`.
|
|
- A configured id registered but unavailable → `WEB_PROVIDER_CONFIGURED_UNAVAILABLE`.
|
|
- No id configured, exactly one registered usable provider → that provider.
|
|
- No id configured, multiple usable providers → `WEB_PROVIDER_AMBIGUOUS`.
|
|
- No id configured, no usable provider → `WEB_PROVIDER_UNAVAILABLE`.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/web/web/src/index.ts#L74)
|
|
|
|
### ctx.web.registerSearchProvider(provider)
|
|
|
|
```ts website-api
|
|
/**
|
|
* Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
|
|
* if its id is already registered for search. Returns a disposer; disposed
|
|
* with the calling fiber.
|
|
* @param provider - the provider; its `id` is the registry key.
|
|
* @returns the disposer that unregisters the provider.
|
|
*/
|
|
registerSearchProvider(provider: WebSearchProvider): () => void
|
|
```
|
|
|
|
Register a search provider. Throws WebError `WEB_DUPLICATE_PROVIDER` if its id is already registered for search. Returns a disposer; disposed with the calling fiber.
|
|
|
|
- `provider` — the provider; its `id` is the registry key.
|
|
|
|
**Returns** the disposer that unregisters the provider.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/web/web/src/index.ts#L103)
|
|
|
|
### ctx.web.registerFetchProvider(provider)
|
|
|
|
```ts website-api
|
|
/**
|
|
* Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
|
|
* if its id is already registered for fetch. Returns a disposer; disposed
|
|
* with the calling fiber.
|
|
* @param provider - the provider; its `id` is the registry key.
|
|
* @returns the disposer that unregisters the provider.
|
|
*/
|
|
registerFetchProvider(provider: WebFetchProvider): () => void
|
|
```
|
|
|
|
Register a fetch provider. Throws WebError `WEB_DUPLICATE_PROVIDER` if its id is already registered for fetch. Returns a disposer; disposed with the calling fiber.
|
|
|
|
- `provider` — the provider; its `id` is the registry key.
|
|
|
|
**Returns** the disposer that unregisters the provider.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/web/web/src/index.ts#L114)
|
|
|
|
### ctx.web.search(request, signal?)
|
|
|
|
```ts website-api
|
|
/**
|
|
* Run one search through the selected provider. Resolves the provider at call
|
|
* time with the selection rules above; throws {@link WebError} when the
|
|
* capability cannot run. The seam enforces `request.maxResults` on the result:
|
|
* if the provider over-returns, `sources[]` is truncated and `truncated` set.
|
|
* @param request - the query plus result-shaping options.
|
|
* @param signal - optional cancellation signal forwarded to the provider.
|
|
* @returns the provider's results, capped to `request.maxResults`.
|
|
*/
|
|
async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
|
|
```
|
|
|
|
Run one search through the selected provider. Resolves the provider at call time with the selection rules above; throws WebError when the capability cannot run. The seam enforces `request.maxResults` on the result: if the provider over-returns, `sources[]` is truncated and `truncated` set.
|
|
|
|
- `request` — the query plus result-shaping options.
|
|
- `signal` — optional cancellation signal forwarded to the provider.
|
|
|
|
**Returns** the provider's results, capped to `request.maxResults`.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/web/web/src/index.ts#L140)
|
|
|
|
### ctx.web.fetch(request, signal?)
|
|
|
|
```ts website-api
|
|
/**
|
|
* Retrieve one URL through the selected provider. Resolves the provider at
|
|
* call time with the selection rules above; throws {@link WebError} when the
|
|
* capability cannot run. A non-2xx response is a result, not a throw.
|
|
* @param request - the URL plus retrieval options.
|
|
* @param signal - optional cancellation signal forwarded to the provider.
|
|
* @returns the retrieval outcome; non-2xx responses resolve descriptively.
|
|
*/
|
|
async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
|
|
```
|
|
|
|
Retrieve one URL through the selected provider. Resolves the provider at call time with the selection rules above; throws WebError when the capability cannot run. A non-2xx response is a result, not a throw.
|
|
|
|
- `request` — the URL plus retrieval options.
|
|
- `signal` — optional cancellation signal forwarded to the provider.
|
|
|
|
**Returns** the retrieval outcome; non-2xx responses resolve descriptively.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/web/web/src/index.ts#L157)
|