@effect-uai/core 0.9.0 → 0.11.0

package/dist/web-read/WebReadTool.mjs

@@ -0,0 +1,59 @@
+import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
+import { fromEffectSchema, make } from "../tool/Tool.mjs";
+import { read } from "./WebRead.mjs";
+import { Effect, Schema } from "effect";
+//#region src/web-read/WebReadTool.ts
+var WebReadTool_exports = /* @__PURE__ */ __exportAll({ webReadTool: () => webReadTool });
+/**
+* Model-facing argument schema. Deliberately narrow: the URL is the only
+* thing that is genuinely the model's call. Output format and the content
+* cost ceiling are app policy, pinned on the constructor instead, so they
+* are guaranteed rather than left to the model to remember each call.
+*/
+const WebReadToolArgs = Schema.Struct({ url: Schema.String.annotate({ description: "Absolute URL of the page to read." }) });
+/** `title / url` header plus the extracted content - what a model reads best. */
+const defaultRender = (response, maxChars) => {
+	return `${response.title === void 0 ? response.url : `${response.title}\n${response.url}`}\n\n${response.content.length > maxChars ? `${response.content.slice(0, maxChars)}\n[content truncated at ${maxChars} characters]` : response.content}`;
+};
+/**
+* The canonical web-read tool. Its `R` is just `WebRead`, so providing any
+* read-provider Layer satisfies it and the model-facing contract (name,
+* description, schema) is identical no matter which backend answers - swap
+* `FirecrawlRead.layer` for `JinaRead.layer` and the tool the model sees
+* does not change. Drops straight into a `Toolkit` next to `webSearchTool`
+* (search finds the URLs, read fetches the ones worth reading in full).
+*
+* `Output` is the rendered page; failures stay typed on the `AiError`
+* channel. To let the model recover from a failed read, wrap the toolkit in
+* `Toolkit.describeFailures(AiError.describe)`.
+*
+* This is a simple default implementation for quick use. For more elaborate
+* cases (a different output contract, more model-facing knobs), build your
+* own tool with `Tool.make` over the same `read` helper.
+*/
+const webReadTool = (options) => {
+	const name = options?.name ?? "web_read";
+	const format = options?.format ?? "markdown";
+	const maxChars = options?.maxChars ?? 2e4;
+	const render = options?.render ?? ((response) => defaultRender(response, maxChars));
+	return make({
+		name,
+		description: "Read a web page and return its content as clean text. Use it to read a promising URL in full (e.g. one found via search).",
+		inputSchema: fromEffectSchema(WebReadToolArgs),
+		run: (args) => read({
+			url: args.url,
+			format
+		}).pipe(Effect.tap((r) => Effect.annotateCurrentSpan("web_read.content_chars", r.content.length)), Effect.map(render), Effect.withSpan(name, {
+			kind: "client",
+			attributes: {
+				"web_read.url": args.url,
+				"web_read.format": format,
+				"web_read.max_chars": maxChars
+			}
+		}))
+	});
+};
+//#endregion
+export { WebReadTool_exports as t, webReadTool };
+
+//# sourceMappingURL=WebReadTool.mjs.map

package/dist/web-read/WebReadTool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebReadTool.mjs","names":["Tool.make","Tool.fromEffectSchema"],"sources":["../../src/web-read/WebReadTool.ts"],"sourcesContent":["import { Effect, Schema } from \"effect\"\nimport type * as AiError from \"../domain/AiError.js\"\nimport * as Tool from \"../tool/Tool.js\"\nimport { read, type ReadFormat, type ReadResponse, WebRead } from \"./WebRead.js\"\n\n/**\n * Model-facing argument schema. Deliberately narrow: the URL is the only\n * thing that is genuinely the model's call. Output format and the content\n * cost ceiling are app policy, pinned on the constructor instead, so they\n * are guaranteed rather than left to the model to remember each call.\n */\nconst WebReadToolArgs = Schema.Struct({\n  url: Schema.String.annotate({\n    description: \"Absolute URL of the page to read.\",\n  }),\n})\n\nexport type WebReadToolArgs = typeof WebReadToolArgs.Type\n\n/** `title / url` header plus the extracted content - what a model reads best. */\nconst defaultRender = (response: ReadResponse, maxChars: number): string => {\n  const header = response.title === undefined ? response.url : `${response.title}\\n${response.url}`\n  const body =\n    response.content.length > maxChars\n      ? `${response.content.slice(0, maxChars)}\\n[content truncated at ${maxChars} characters]`\n      : response.content\n  return `${header}\\n\\n${body}`\n}\n\nexport type WebReadToolOptions = {\n  /** Tool name the model sees. Default `\"web_read\"`. */\n  readonly name?: string\n  /**\n   * App-fixed representation for every read - a policy choice, not a model\n   * knob. Default `\"markdown\"` (what models read best).\n   */\n  readonly format?: ReadFormat\n  /**\n   * App-fixed ceiling on rendered content characters per call - a context\n   * cost guard, not exposed to the model. Default `20000`.\n   */\n  readonly maxChars?: number\n  /**\n   * Override how a read response is rendered into the model-facing string.\n   * Default: `title / url` header plus the content, truncated at `maxChars`.\n   */\n  readonly render?: (response: ReadResponse) => string\n}\n\n/**\n * The canonical web-read tool. Its `R` is just `WebRead`, so providing any\n * read-provider Layer satisfies it and the model-facing contract (name,\n * description, schema) is identical no matter which backend answers - swap\n * `FirecrawlRead.layer` for `JinaRead.layer` and the tool the model sees\n * does not change. Drops straight into a `Toolkit` next to `webSearchTool`\n * (search finds the URLs, read fetches the ones worth reading in full).\n *\n * `Output` is the rendered page; failures stay typed on the `AiError`\n * channel. To let the model recover from a failed read, wrap the toolkit in\n * `Toolkit.describeFailures(AiError.describe)`.\n *\n * This is a simple default implementation for quick use. For more elaborate\n * cases (a different output contract, more model-facing knobs), build your\n * own tool with `Tool.make` over the same `read` helper.\n */\nexport const webReadTool = (\n  options?: WebReadToolOptions,\n): Tool.Tool<string, WebReadToolArgs, never, string, AiError.AiError, WebRead> => {\n  const name = options?.name ?? \"web_read\"\n  const format = options?.format ?? \"markdown\"\n  const maxChars = options?.maxChars ?? 20_000\n  const render = options?.render ?? ((response: ReadResponse) => defaultRender(response, maxChars))\n  return Tool.make({\n    name,\n    description:\n      \"Read a web page and return its content as clean text. Use it to read a promising URL in full (e.g. one found via search).\",\n    inputSchema: Tool.fromEffectSchema(WebReadToolArgs),\n    // The call is wrapped in a tracing span so agent traces show the tool\n    // invocation (url, format, content length) nested under the model turn.\n    // `withSpan` is a no-op until a Tracer is installed, so this is free by\n    // default and adds nothing to the requirements.\n    run: (args) =>\n      read({ url: args.url, format }).pipe(\n        Effect.tap((r) => Effect.annotateCurrentSpan(\"web_read.content_chars\", r.content.length)),\n        Effect.map(render),\n        Effect.withSpan(name, {\n          kind: \"client\",\n          attributes: {\n            \"web_read.url\": args.url,\n            \"web_read.format\": format,\n            \"web_read.max_chars\": maxChars,\n          },\n        }),\n      ),\n  })\n}\n"],"mappings":";;;;;;;;;;;;AAWA,MAAM,kBAAkB,OAAO,OAAO,EACpC,KAAK,OAAO,OAAO,SAAS,EAC1B,aAAa,qCACd,CAAC,EACH,CAAC;;AAKF,MAAM,iBAAiB,UAAwB,aAA6B;AAM1E,QAAO,GALQ,SAAS,UAAU,KAAA,IAAY,SAAS,MAAM,GAAG,SAAS,MAAM,IAAI,SAAS,MAK3E,MAHf,SAAS,QAAQ,SAAS,WACtB,GAAG,SAAS,QAAQ,MAAM,GAAG,SAAS,CAAC,0BAA0B,SAAS,gBAC1E,SAAS;;;;;;;;;;;;;;;;;;AAwCjB,MAAa,eACX,YACgF;CAChF,MAAM,OAAO,SAAS,QAAQ;CAC9B,MAAM,SAAS,SAAS,UAAU;CAClC,MAAM,WAAW,SAAS,YAAY;CACtC,MAAM,SAAS,SAAS,YAAY,aAA2B,cAAc,UAAU,SAAS;AAChG,QAAOA,KAAU;EACf;EACA,aACE;EACF,aAAaC,iBAAsB,gBAAgB;EAKnD,MAAM,SACJ,KAAK;GAAE,KAAK,KAAK;GAAK;GAAQ,CAAC,CAAC,KAC9B,OAAO,KAAK,MAAM,OAAO,oBAAoB,0BAA0B,EAAE,QAAQ,OAAO,CAAC,EACzF,OAAO,IAAI,OAAO,EAClB,OAAO,SAAS,MAAM;GACpB,MAAM;GACN,YAAY;IACV,gBAAgB,KAAK;IACrB,mBAAmB;IACnB,sBAAsB;IACvB;GACF,CAAC,CACH;EACJ,CAAC"}

package/dist/web-search/WebSearch.d.mts

@@ -1,4 +1,4 @@
-import { t as AiError } from "../AiError-CrdR1EQi.mjs";
+import { t as AiError } from "../AiError-Bf1pq4BB.mjs";
 import { Context, DateTime, Effect, Schema } from "effect";
 
 //#region src/web-search/WebSearch.d.ts

package/dist/web-search/WebSearch.mjs

@@ -35,7 +35,7 @@ const SearchRecency = Schema.Literals([
 */
 var WebSearch = class extends Context.Service()("@betalyra/effect-uai/WebSearch") {};
 /** Run one web search against whichever provider Layer is in scope. */
-const search = (request) => Effect.flatMap(WebSearch.asEffect(), (s) => s.search(request));
+const search = (request) => Effect.flatMap(WebSearch, (s) => s.search(request));
 //#endregion
 export { SearchRecency, WebSearch, search, WebSearch_exports as t };
 

package/dist/web-search/WebSearch.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"WebSearch.mjs","names":[],"sources":["../../src/web-search/WebSearch.ts"],"sourcesContent":["import { Context, type DateTime, Effect, Schema } from \"effect\"\nimport type * as AiError from \"../domain/AiError.js\"\n\n// ---------------------------------------------------------------------------\n// Recency\n// ---------------------------------------------------------------------------\n\n/**\n * Convenience freshness enum shared by every provider. A coarse \"published\n * within the last …\" filter that maps onto each provider's native recency\n * knob (Perplexity `search_recency_filter`, Brave `freshness`, Tavily\n * `time_range`, You.com `freshness`), or onto a computed published-date\n * range where a provider has no enum (Exa).\n *\n * For a precise window use {@link CommonSearchRequest.startDate} /\n * {@link CommonSearchRequest.endDate} instead; `recency` is the sugar for\n * the common \"past week / past month\" case.\n *\n * Exposed as a `Schema` so {@link \"../web-search/WebSearchTool\".webSearchTool}\n * can hand it straight to a model as a tool parameter; the\n * {@link SearchRecency} type is derived from it.\n */\nexport const SearchRecency = Schema.Literals([\"hour\", \"day\", \"week\", \"month\", \"year\"])\n\nexport type SearchRecency = typeof SearchRecency.Type\n\n// ---------------------------------------------------------------------------\n// Request\n// ---------------------------------------------------------------------------\n\n/**\n * Cross-provider web-search request. A field earns a place here only if\n * most of the supported providers honor it and a developer would expect it\n * from a generic search interface; everything provider-specific (Exa\n * `type`, Tavily `searchDepth`, Brave `goggles`, pagination `offset`,\n * `safeSearch`, `topic`, …) lives on that provider's typed request.\n *\n * Note the one structural difference from `EmbeddingModel` /\n * `Transcriber`: there is no `model`. None of the pure-`/search` endpoints\n * take one - what looks model-shaped on a provider (Exa `type`, Tavily\n * `searchDepth`) is a mode knob, so it stays on the provider-typed request.\n */\nexport type CommonSearchRequest = {\n  /** The search query. The one field every provider requires. */\n  readonly query: string\n  /**\n   * Upper bound on the number of results to return in this one call.\n   * Providers cap differently (Perplexity / Tavily / Brave at ~20, Exa /\n   * You.com at ~100); a value above a provider's cap is clamped by that\n   * provider. There is no common pagination - only two providers paginate\n   * and only shallowly, so `offset` is provider-typed.\n   */\n  readonly maxResults?: number\n  /** Restrict results to these domains (e.g. `[\"docs.foo.com\"]`). */\n  readonly includeDomains?: ReadonlyArray<string>\n  /** Drop results from these domains. */\n  readonly excludeDomains?: ReadonlyArray<string>\n  /**\n   * Coarse freshness filter - see {@link SearchRecency}. Sugar over an\n   * explicit `startDate`; ignored where {@link startDate} is also set and\n   * the provider takes only one.\n   */\n  readonly recency?: SearchRecency\n  /** Published-after bound. The precise alternative to {@link recency}. */\n  readonly startDate?: DateTime.DateTime\n  /** Published-before bound. */\n  readonly endDate?: DateTime.DateTime\n  /** ISO 3166-1 alpha-2 country code to localize results (e.g. `\"us\"`). */\n  readonly country?: string\n  /** ISO 639-1 language code to bias results toward (e.g. `\"en\"`). */\n  readonly language?: string\n}\n\n// ---------------------------------------------------------------------------\n// Response\n// ---------------------------------------------------------------------------\n\n/**\n * One normalized web-search hit. A flat record with optionals rather than a\n * tagged union: the providers differ by *which fields are present*, not by\n * *kind*. The provider's untouched result object is always on `raw`, so a\n * caller holding a typed provider tag can recover anything not promoted\n * here (`author`, `favicon`, multi-chunk `snippets[]`, …).\n */\nexport type SearchResult = {\n  /** Canonical result URL. Always present. */\n  readonly url: string\n  /** Result title / headline, when the provider returns one. */\n  readonly title?: string\n  /**\n   * Primary short excerpt - the one text field all providers return (under\n   * various wire names: `snippet`, `content`, `description`). The richer\n   * extract fields (`text`, `highlights`, `summary`) belong to the\n   * out-of-scope extract feature and stay on the provider-typed result.\n   */\n  readonly snippet?: string\n  /** Publication date, when the provider reports one. */\n  readonly publishedDate?: DateTime.DateTime\n  /**\n   * Relevance score, only from providers that rank (Exa, Tavily);\n   * `undefined` for providers that return an unscored list. Kept despite\n   * being non-universal because ranking is core to what a \"search result\"\n   * means - and `undefined` cleanly says \"this backend doesn't score.\"\n   */\n  readonly score?: number\n  /** The provider-native result object, never lossy. */\n  readonly raw: unknown\n}\n\nexport type SearchResponse = {\n  readonly results: ReadonlyArray<SearchResult>\n  /**\n   * The provider-native top-level response object. Cost / usage reporting\n   * is deliberately not modeled on this surface yet: providers disagree on\n   * both what (Exa returns USD, Tavily credits, Brave nothing in-body) and\n   * where (Brave reports cost in response headers), so it is deferred to the\n   * unified usage design (see plans/usage-tracking.md). Anything a provider\n   * reports survives here on `raw`.\n   */\n  readonly raw: unknown\n}\n\n// ---------------------------------------------------------------------------\n// Service + helper\n// ---------------------------------------------------------------------------\n\n/**\n * The portable web-search surface: one operation, `search`. Pure search is\n * the one thing every provider does, so - unlike `SpeechSynthesizer` /\n * `Transcriber` - this capability needs no marker tags; every provider\n * Layer can answer.\n */\nexport type WebSearchService = {\n  readonly search: (request: CommonSearchRequest) => Effect.Effect<SearchResponse, AiError.AiError>\n}\n\n/**\n * Generic web-search service tag. Yield this for provider-portable code;\n * yield a provider tag (`PerplexitySearch`, `ExaSearch`, …) when you need\n * that provider's own knobs. A provider's `layer` registers both.\n */\nexport class WebSearch extends Context.Service<WebSearch, WebSearchService>()(\n  \"@betalyra/effect-uai/WebSearch\",\n) {}\n\n/** Run one web search against whichever provider Layer is in scope. */\nexport const search = (\n  request: CommonSearchRequest,\n): Effect.Effect<SearchResponse, AiError.AiError, WebSearch> =>\n  Effect.flatMap(WebSearch.asEffect(), (s) => s.search(request))\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAsBA,MAAa,gBAAgB,OAAO,SAAS;CAAC;CAAQ;CAAO;CAAQ;CAAS;CAAO,CAAC;;;;;;AAuHtF,IAAa,YAAb,cAA+B,QAAQ,SAAsC,CAC3E,iCACD,CAAC;;AAGF,MAAa,UACX,YAEA,OAAO,QAAQ,UAAU,UAAU,GAAG,MAAM,EAAE,OAAO,QAAQ,CAAC"}
+{"version":3,"file":"WebSearch.mjs","names":[],"sources":["../../src/web-search/WebSearch.ts"],"sourcesContent":["import { Context, type DateTime, Effect, Schema } from \"effect\"\nimport type * as AiError from \"../domain/AiError.js\"\n\n// ---------------------------------------------------------------------------\n// Recency\n// ---------------------------------------------------------------------------\n\n/**\n * Convenience freshness enum shared by every provider. A coarse \"published\n * within the last …\" filter that maps onto each provider's native recency\n * knob (Perplexity `search_recency_filter`, Brave `freshness`, Tavily\n * `time_range`, You.com `freshness`), or onto a computed published-date\n * range where a provider has no enum (Exa).\n *\n * For a precise window use {@link CommonSearchRequest.startDate} /\n * {@link CommonSearchRequest.endDate} instead; `recency` is the sugar for\n * the common \"past week / past month\" case.\n *\n * Exposed as a `Schema` so {@link \"../web-search/WebSearchTool\".webSearchTool}\n * can hand it straight to a model as a tool parameter; the\n * {@link SearchRecency} type is derived from it.\n */\nexport const SearchRecency = Schema.Literals([\"hour\", \"day\", \"week\", \"month\", \"year\"])\n\nexport type SearchRecency = typeof SearchRecency.Type\n\n// ---------------------------------------------------------------------------\n// Request\n// ---------------------------------------------------------------------------\n\n/**\n * Cross-provider web-search request. A field earns a place here only if\n * most of the supported providers honor it and a developer would expect it\n * from a generic search interface; everything provider-specific (Exa\n * `type`, Tavily `searchDepth`, Brave `goggles`, pagination `offset`,\n * `safeSearch`, `topic`, …) lives on that provider's typed request.\n *\n * Note the one structural difference from `EmbeddingModel` /\n * `Transcriber`: there is no `model`. None of the pure-`/search` endpoints\n * take one - what looks model-shaped on a provider (Exa `type`, Tavily\n * `searchDepth`) is a mode knob, so it stays on the provider-typed request.\n */\nexport type CommonSearchRequest = {\n  /** The search query. The one field every provider requires. */\n  readonly query: string\n  /**\n   * Upper bound on the number of results to return in this one call.\n   * Providers cap differently (Perplexity / Tavily / Brave at ~20, Exa /\n   * You.com at ~100); a value above a provider's cap is clamped by that\n   * provider. There is no common pagination - only two providers paginate\n   * and only shallowly, so `offset` is provider-typed.\n   */\n  readonly maxResults?: number\n  /** Restrict results to these domains (e.g. `[\"docs.foo.com\"]`). */\n  readonly includeDomains?: ReadonlyArray<string>\n  /** Drop results from these domains. */\n  readonly excludeDomains?: ReadonlyArray<string>\n  /**\n   * Coarse freshness filter - see {@link SearchRecency}. Sugar over an\n   * explicit `startDate`; ignored where {@link startDate} is also set and\n   * the provider takes only one.\n   */\n  readonly recency?: SearchRecency\n  /** Published-after bound. The precise alternative to {@link recency}. */\n  readonly startDate?: DateTime.DateTime\n  /** Published-before bound. */\n  readonly endDate?: DateTime.DateTime\n  /** ISO 3166-1 alpha-2 country code to localize results (e.g. `\"us\"`). */\n  readonly country?: string\n  /** ISO 639-1 language code to bias results toward (e.g. `\"en\"`). */\n  readonly language?: string\n}\n\n// ---------------------------------------------------------------------------\n// Response\n// ---------------------------------------------------------------------------\n\n/**\n * One normalized web-search hit. A flat record with optionals rather than a\n * tagged union: the providers differ by *which fields are present*, not by\n * *kind*. The provider's untouched result object is always on `raw`, so a\n * caller holding a typed provider tag can recover anything not promoted\n * here (`author`, `favicon`, multi-chunk `snippets[]`, …).\n */\nexport type SearchResult = {\n  /** Canonical result URL. Always present. */\n  readonly url: string\n  /** Result title / headline, when the provider returns one. */\n  readonly title?: string\n  /**\n   * Primary short excerpt - the one text field all providers return (under\n   * various wire names: `snippet`, `content`, `description`). The richer\n   * extract fields (`text`, `highlights`, `summary`) belong to the\n   * out-of-scope extract feature and stay on the provider-typed result.\n   */\n  readonly snippet?: string\n  /** Publication date, when the provider reports one. */\n  readonly publishedDate?: DateTime.DateTime\n  /**\n   * Relevance score, only from providers that rank (Exa, Tavily);\n   * `undefined` for providers that return an unscored list. Kept despite\n   * being non-universal because ranking is core to what a \"search result\"\n   * means - and `undefined` cleanly says \"this backend doesn't score.\"\n   */\n  readonly score?: number\n  /** The provider-native result object, never lossy. */\n  readonly raw: unknown\n}\n\nexport type SearchResponse = {\n  readonly results: ReadonlyArray<SearchResult>\n  /**\n   * The provider-native top-level response object. Cost / usage reporting\n   * is deliberately not modeled on this surface yet: providers disagree on\n   * both what (Exa returns USD, Tavily credits, Brave nothing in-body) and\n   * where (Brave reports cost in response headers), so it is deferred to the\n   * unified usage design (see plans/usage-tracking.md). Anything a provider\n   * reports survives here on `raw`.\n   */\n  readonly raw: unknown\n}\n\n// ---------------------------------------------------------------------------\n// Service + helper\n// ---------------------------------------------------------------------------\n\n/**\n * The portable web-search surface: one operation, `search`. Pure search is\n * the one thing every provider does, so - unlike `SpeechSynthesizer` /\n * `Transcriber` - this capability needs no marker tags; every provider\n * Layer can answer.\n */\nexport type WebSearchService = {\n  readonly search: (request: CommonSearchRequest) => Effect.Effect<SearchResponse, AiError.AiError>\n}\n\n/**\n * Generic web-search service tag. Yield this for provider-portable code;\n * yield a provider tag (`PerplexitySearch`, `ExaSearch`, …) when you need\n * that provider's own knobs. A provider's `layer` registers both.\n */\nexport class WebSearch extends Context.Service<WebSearch, WebSearchService>()(\n  \"@betalyra/effect-uai/WebSearch\",\n) {}\n\n/** Run one web search against whichever provider Layer is in scope. */\nexport const search = (\n  request: CommonSearchRequest,\n): Effect.Effect<SearchResponse, AiError.AiError, WebSearch> =>\n  Effect.flatMap(WebSearch, (s) => s.search(request))\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAsBA,MAAa,gBAAgB,OAAO,SAAS;CAAC;CAAQ;CAAO;CAAQ;CAAS;CAAO,CAAC;;;;;;AAuHtF,IAAa,YAAb,cAA+B,QAAQ,SAAsC,CAC3E,iCACD,CAAC;;AAGF,MAAa,UACX,YAEA,OAAO,QAAQ,YAAY,MAAM,EAAE,OAAO,QAAQ,CAAC"}

package/dist/web-search/WebSearchTool.d.mts

@@ -1,4 +1,5 @@
-import { c as Tool } from "../Tool-0XUIT2A2.mjs";
+import { l as Tool } from "../Tool-CXFHCQrT.mjs";
+import { t as AiError } from "../AiError-Bf1pq4BB.mjs";
 import { SearchResult, WebSearch } from "./WebSearch.mjs";
 import { Schema } from "effect";
 
@@ -47,12 +48,17 @@ type WebSearchToolOptions = {
  * `LanguageModel` tool-calling loop.
  *
  * The model controls only `query` and `recency`; domain scoping and the
- * result cap are app policy, fixed here on the constructor. `Output` is
- * rendered text, not raw `SearchResult[]`: the model reads the list, while
- * the app still gets the structured results through the normal tool-result
- * channel. Pass `render` to change the format.
+ * result cap are app policy, fixed here on the constructor. `Output` is the
+ * rendered text (the model reads a numbered list better than raw
+ * `SearchResult[]`; pass `render` to change the format); failures stay typed
+ * on the `AiError` channel. To let the model recover from a failed search,
+ * wrap the toolkit in `Toolkit.describeFailures(AiError.describe)`.
+ *
+ * This is a simple default implementation for quick use. For more elaborate
+ * cases (a different output contract, more model-facing knobs), build your
+ * own tool with `Tool.make` over the same `search` helper.
  */
-declare const webSearchTool: (options?: WebSearchToolOptions) => Tool<string, WebSearchToolArgs, never, string, WebSearch>;
+declare const webSearchTool: (options?: WebSearchToolOptions) => Tool<string, WebSearchToolArgs, never, string, AiError, WebSearch>;
 //#endregion
 export { WebSearchToolArgs, WebSearchToolOptions, WebSearchTool_d_exports as t, webSearchTool };
 //# sourceMappingURL=WebSearchTool.d.mts.map

package/dist/web-search/WebSearchTool.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"WebSearchTool.d.mts","names":[],"sources":["../../src/web-search/WebSearchTool.ts"],"mappings":";;;;;;;;;;;;;;;;cAYM,iBAAA,EAAiB,MAAA,CAAA,MAAA;EAAA;;;KAKX,iBAAA,UAA2B,iBAAA,CAAkB,IAAA;AAAA,KAa7C,oBAAA;EAlBW,iEAoBZ,IAAA;EApBY;;;;EAAA,SAyBZ,UAAA;;;;;WAKA,cAAA,GAAiB,aAAA;WAEjB,cAAA,GAAiB,aAAA;;AA3B5B;;;WAgCW,MAAA,IAAU,OAAA,EAAS,aAAA,CAAc,YAAA;AAAA;AAnB5C;;;;;;;;;;;;;;AAAA,cAoCa,aAAA,GACX,OAAA,GAAU,oBAAA,KACT,IAAA,SAAkB,iBAAA,iBAAkC,SAAA"}
+{"version":3,"file":"WebSearchTool.d.mts","names":[],"sources":["../../src/web-search/WebSearchTool.ts"],"mappings":";;;;;;;;;;;;;;;;;cAaM,iBAAA,EAAiB,MAAA,CAAA,MAAA;EAAA;;;KAKX,iBAAA,UAA2B,iBAAA,CAAkB,IAAA;AAAA,KAa7C,oBAAA;EAlBW,iEAoBZ,IAAA;EApBY;;;;EAAA,SAyBZ,UAAA;;;;;WAKA,cAAA,GAAiB,aAAA;WAEjB,cAAA,GAAiB,aAAA;;AA3B5B;;;WAgCW,MAAA,IAAU,OAAA,EAAS,aAAA,CAAc,YAAA;AAAA;AAnB5C;;;;;;;;;;;;;;;;;;;AAAA,cAyCa,aAAA,GACX,OAAA,GAAU,oBAAA,KACT,IAAA,SAAkB,iBAAA,iBAAkC,OAAA,EAAiB,SAAA"}

package/dist/web-search/WebSearchTool.mjs

@@ -1,6 +1,6 @@
 import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
-import { SearchRecency, search } from "./WebSearch.mjs";
 import { fromEffectSchema, make } from "../tool/Tool.mjs";
+import { SearchRecency, search } from "./WebSearch.mjs";
 import { Effect, Schema } from "effect";
 //#region src/web-search/WebSearchTool.ts
 var WebSearchTool_exports = /* @__PURE__ */ __exportAll({ webSearchTool: () => webSearchTool });
@@ -30,10 +30,15 @@ const defaultRender = (results) => results.length === 0 ? "No results found." :
 * `LanguageModel` tool-calling loop.
 *
 * The model controls only `query` and `recency`; domain scoping and the
-* result cap are app policy, fixed here on the constructor. `Output` is
-* rendered text, not raw `SearchResult[]`: the model reads the list, while
-* the app still gets the structured results through the normal tool-result
-* channel. Pass `render` to change the format.
+* result cap are app policy, fixed here on the constructor. `Output` is the
+* rendered text (the model reads a numbered list better than raw
+* `SearchResult[]`; pass `render` to change the format); failures stay typed
+* on the `AiError` channel. To let the model recover from a failed search,
+* wrap the toolkit in `Toolkit.describeFailures(AiError.describe)`.
+*
+* This is a simple default implementation for quick use. For more elaborate
+* cases (a different output contract, more model-facing knobs), build your
+* own tool with `Tool.make` over the same `search` helper.
 */
 const webSearchTool = (options) => {
 	const name = options?.name ?? "web_search";

package/dist/web-search/WebSearchTool.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"WebSearchTool.mjs","names":["Tool.make","Tool.fromEffectSchema"],"sources":["../../src/web-search/WebSearchTool.ts"],"sourcesContent":["import { Effect, Schema } from \"effect\"\nimport * as Tool from \"../tool/Tool.js\"\nimport { search, SearchRecency, type SearchResult, WebSearch } from \"./WebSearch.js\"\n\n/**\n * Model-facing argument schema. Deliberately narrow: `query` plus the one\n * filter that is genuinely the model's call - `recency` (it knows whether a\n * question is about current events or evergreen). App-policy scoping\n * (`includeDomains` / `excludeDomains`) and the `maxResults` cost ceiling\n * are pinned on the constructor instead, so they are guaranteed rather than\n * left to the model to remember each call.\n */\nconst WebSearchToolArgs = Schema.Struct({\n  query: Schema.String,\n  recency: Schema.optional(SearchRecency),\n})\n\nexport type WebSearchToolArgs = typeof WebSearchToolArgs.Type\n\n/** Numbered `title / url / snippet` list - what a model reads best. */\nconst defaultRender = (results: ReadonlyArray<SearchResult>): string =>\n  results.length === 0\n    ? \"No results found.\"\n    : results\n        .map((r, i) => {\n          const head = `${i + 1}. ${r.title ?? r.url}\\n   ${r.url}`\n          return r.snippet === undefined ? head : `${head}\\n   ${r.snippet}`\n        })\n        .join(\"\\n\\n\")\n\nexport type WebSearchToolOptions = {\n  /** Tool name the model sees. Default `\"web_search\"`. */\n  readonly name?: string\n  /**\n   * App-fixed ceiling on results per call - a cost guard, not exposed to\n   * the model. Default `5`.\n   */\n  readonly maxResults?: number\n  /**\n   * App-fixed allowlist applied to every search. A policy scope (\"only\n   * search our docs\"), not a model knob - so it is enforced, not requested.\n   */\n  readonly includeDomains?: ReadonlyArray<string>\n  /** App-fixed denylist applied to every search (\"never return X\"). */\n  readonly excludeDomains?: ReadonlyArray<string>\n  /**\n   * Override how results are rendered into the model-facing string.\n   * Default: a numbered `title / url / snippet` list.\n   */\n  readonly render?: (results: ReadonlyArray<SearchResult>) => string\n}\n\n/**\n * The canonical web-search tool. Its `R` is just `WebSearch`, so providing\n * any search-provider Layer satisfies it and the model-facing contract\n * (name, description, schema) is identical no matter which backend answers\n * - swap `PerplexitySearch.layer` for `ExaSearch.layer` and the tool the\n * model sees does not change. Drops straight into a `Toolkit` and the\n * `LanguageModel` tool-calling loop.\n *\n * The model controls only `query` and `recency`; domain scoping and the\n * result cap are app policy, fixed here on the constructor. `Output` is\n * rendered text, not raw `SearchResult[]`: the model reads the list, while\n * the app still gets the structured results through the normal tool-result\n * channel. Pass `render` to change the format.\n */\nexport const webSearchTool = (\n  options?: WebSearchToolOptions,\n): Tool.Tool<string, WebSearchToolArgs, never, string, WebSearch> => {\n  const name = options?.name ?? \"web_search\"\n  const render = options?.render ?? defaultRender\n  const maxResults = options?.maxResults ?? 5\n  const includeDomains = options?.includeDomains\n  const excludeDomains = options?.excludeDomains\n  return Tool.make({\n    name,\n    description:\n      \"Search the web for current information. Returns ranked results with titles, URLs, and snippets.\",\n    inputSchema: Tool.fromEffectSchema(WebSearchToolArgs),\n    // The call is wrapped in a tracing span so agent traces show the tool\n    // invocation (query, filters, result count) nested under the model turn.\n    // `withSpan` is a no-op until a Tracer is installed, so this is free by\n    // default and adds nothing to the requirements.\n    run: (args) =>\n      search({\n        query: args.query,\n        maxResults,\n        ...(args.recency !== undefined && { recency: args.recency }),\n        ...(includeDomains !== undefined && { includeDomains }),\n        ...(excludeDomains !== undefined && { excludeDomains }),\n      }).pipe(\n        Effect.tap((r) => Effect.annotateCurrentSpan(\"web_search.result_count\", r.results.length)),\n        Effect.map((r) => render(r.results)),\n        Effect.withSpan(name, {\n          kind: \"client\",\n          attributes: {\n            \"web_search.query\": args.query,\n            \"web_search.max_results\": maxResults,\n            ...(args.recency !== undefined && { \"web_search.recency\": args.recency }),\n            ...(includeDomains !== undefined && { \"web_search.include_domains\": includeDomains }),\n            ...(excludeDomains !== undefined && { \"web_search.exclude_domains\": excludeDomains }),\n          },\n        }),\n      ),\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;AAYA,MAAM,oBAAoB,OAAO,OAAO;CACtC,OAAO,OAAO;CACd,SAAS,OAAO,SAAS,cAAc;CACxC,CAAC;;AAKF,MAAM,iBAAiB,YACrB,QAAQ,WAAW,IACf,sBACA,QACG,KAAK,GAAG,MAAM;CACb,MAAM,OAAO,GAAG,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,OAAO,EAAE;AACpD,QAAO,EAAE,YAAY,KAAA,IAAY,OAAO,GAAG,KAAK,OAAO,EAAE;EACzD,CACD,KAAK,OAAO;;;;;;;;;;;;;;;AAsCrB,MAAa,iBACX,YACmE;CACnE,MAAM,OAAO,SAAS,QAAQ;CAC9B,MAAM,SAAS,SAAS,UAAU;CAClC,MAAM,aAAa,SAAS,cAAc;CAC1C,MAAM,iBAAiB,SAAS;CAChC,MAAM,iBAAiB,SAAS;AAChC,QAAOA,KAAU;EACf;EACA,aACE;EACF,aAAaC,iBAAsB,kBAAkB;EAKrD,MAAM,SACJ,OAAO;GACL,OAAO,KAAK;GACZ;GACA,GAAI,KAAK,YAAY,KAAA,KAAa,EAAE,SAAS,KAAK,SAAS;GAC3D,GAAI,mBAAmB,KAAA,KAAa,EAAE,gBAAgB;GACtD,GAAI,mBAAmB,KAAA,KAAa,EAAE,gBAAgB;GACvD,CAAC,CAAC,KACD,OAAO,KAAK,MAAM,OAAO,oBAAoB,2BAA2B,EAAE,QAAQ,OAAO,CAAC,EAC1F,OAAO,KAAK,MAAM,OAAO,EAAE,QAAQ,CAAC,EACpC,OAAO,SAAS,MAAM;GACpB,MAAM;GACN,YAAY;IACV,oBAAoB,KAAK;IACzB,0BAA0B;IAC1B,GAAI,KAAK,YAAY,KAAA,KAAa,EAAE,sBAAsB,KAAK,SAAS;IACxE,GAAI,mBAAmB,KAAA,KAAa,EAAE,8BAA8B,gBAAgB;IACpF,GAAI,mBAAmB,KAAA,KAAa,EAAE,8BAA8B,gBAAgB;IACrF;GACF,CAAC,CACH;EACJ,CAAC"}
+{"version":3,"file":"WebSearchTool.mjs","names":["Tool.make","Tool.fromEffectSchema"],"sources":["../../src/web-search/WebSearchTool.ts"],"sourcesContent":["import { Effect, Schema } from \"effect\"\nimport type * as AiError from \"../domain/AiError.js\"\nimport * as Tool from \"../tool/Tool.js\"\nimport { search, SearchRecency, type SearchResult, WebSearch } from \"./WebSearch.js\"\n\n/**\n * Model-facing argument schema. Deliberately narrow: `query` plus the one\n * filter that is genuinely the model's call - `recency` (it knows whether a\n * question is about current events or evergreen). App-policy scoping\n * (`includeDomains` / `excludeDomains`) and the `maxResults` cost ceiling\n * are pinned on the constructor instead, so they are guaranteed rather than\n * left to the model to remember each call.\n */\nconst WebSearchToolArgs = Schema.Struct({\n  query: Schema.String,\n  recency: Schema.optional(SearchRecency),\n})\n\nexport type WebSearchToolArgs = typeof WebSearchToolArgs.Type\n\n/** Numbered `title / url / snippet` list - what a model reads best. */\nconst defaultRender = (results: ReadonlyArray<SearchResult>): string =>\n  results.length === 0\n    ? \"No results found.\"\n    : results\n        .map((r, i) => {\n          const head = `${i + 1}. ${r.title ?? r.url}\\n   ${r.url}`\n          return r.snippet === undefined ? head : `${head}\\n   ${r.snippet}`\n        })\n        .join(\"\\n\\n\")\n\nexport type WebSearchToolOptions = {\n  /** Tool name the model sees. Default `\"web_search\"`. */\n  readonly name?: string\n  /**\n   * App-fixed ceiling on results per call - a cost guard, not exposed to\n   * the model. Default `5`.\n   */\n  readonly maxResults?: number\n  /**\n   * App-fixed allowlist applied to every search. A policy scope (\"only\n   * search our docs\"), not a model knob - so it is enforced, not requested.\n   */\n  readonly includeDomains?: ReadonlyArray<string>\n  /** App-fixed denylist applied to every search (\"never return X\"). */\n  readonly excludeDomains?: ReadonlyArray<string>\n  /**\n   * Override how results are rendered into the model-facing string.\n   * Default: a numbered `title / url / snippet` list.\n   */\n  readonly render?: (results: ReadonlyArray<SearchResult>) => string\n}\n\n/**\n * The canonical web-search tool. Its `R` is just `WebSearch`, so providing\n * any search-provider Layer satisfies it and the model-facing contract\n * (name, description, schema) is identical no matter which backend answers\n * - swap `PerplexitySearch.layer` for `ExaSearch.layer` and the tool the\n * model sees does not change. Drops straight into a `Toolkit` and the\n * `LanguageModel` tool-calling loop.\n *\n * The model controls only `query` and `recency`; domain scoping and the\n * result cap are app policy, fixed here on the constructor. `Output` is the\n * rendered text (the model reads a numbered list better than raw\n * `SearchResult[]`; pass `render` to change the format); failures stay typed\n * on the `AiError` channel. To let the model recover from a failed search,\n * wrap the toolkit in `Toolkit.describeFailures(AiError.describe)`.\n *\n * This is a simple default implementation for quick use. For more elaborate\n * cases (a different output contract, more model-facing knobs), build your\n * own tool with `Tool.make` over the same `search` helper.\n */\nexport const webSearchTool = (\n  options?: WebSearchToolOptions,\n): Tool.Tool<string, WebSearchToolArgs, never, string, AiError.AiError, WebSearch> => {\n  const name = options?.name ?? \"web_search\"\n  const render = options?.render ?? defaultRender\n  const maxResults = options?.maxResults ?? 5\n  const includeDomains = options?.includeDomains\n  const excludeDomains = options?.excludeDomains\n  return Tool.make({\n    name,\n    description:\n      \"Search the web for current information. Returns ranked results with titles, URLs, and snippets.\",\n    inputSchema: Tool.fromEffectSchema(WebSearchToolArgs),\n    // The call is wrapped in a tracing span so agent traces show the tool\n    // invocation (query, filters, result count) nested under the model turn.\n    // `withSpan` is a no-op until a Tracer is installed, so this is free by\n    // default and adds nothing to the requirements.\n    run: (args) =>\n      search({\n        query: args.query,\n        maxResults,\n        ...(args.recency !== undefined && { recency: args.recency }),\n        ...(includeDomains !== undefined && { includeDomains }),\n        ...(excludeDomains !== undefined && { excludeDomains }),\n      }).pipe(\n        Effect.tap((r) => Effect.annotateCurrentSpan(\"web_search.result_count\", r.results.length)),\n        Effect.map((r) => render(r.results)),\n        Effect.withSpan(name, {\n          kind: \"client\",\n          attributes: {\n            \"web_search.query\": args.query,\n            \"web_search.max_results\": maxResults,\n            ...(args.recency !== undefined && { \"web_search.recency\": args.recency }),\n            ...(includeDomains !== undefined && { \"web_search.include_domains\": includeDomains }),\n            ...(excludeDomains !== undefined && { \"web_search.exclude_domains\": excludeDomains }),\n          },\n        }),\n      ),\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;AAaA,MAAM,oBAAoB,OAAO,OAAO;CACtC,OAAO,OAAO;CACd,SAAS,OAAO,SAAS,cAAc;CACxC,CAAC;;AAKF,MAAM,iBAAiB,YACrB,QAAQ,WAAW,IACf,sBACA,QACG,KAAK,GAAG,MAAM;CACb,MAAM,OAAO,GAAG,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,OAAO,EAAE;AACpD,QAAO,EAAE,YAAY,KAAA,IAAY,OAAO,GAAG,KAAK,OAAO,EAAE;EACzD,CACD,KAAK,OAAO;;;;;;;;;;;;;;;;;;;;AA2CrB,MAAa,iBACX,YACoF;CACpF,MAAM,OAAO,SAAS,QAAQ;CAC9B,MAAM,SAAS,SAAS,UAAU;CAClC,MAAM,aAAa,SAAS,cAAc;CAC1C,MAAM,iBAAiB,SAAS;CAChC,MAAM,iBAAiB,SAAS;AAChC,QAAOA,KAAU;EACf;EACA,aACE;EACF,aAAaC,iBAAsB,kBAAkB;EAKrD,MAAM,SACJ,OAAO;GACL,OAAO,KAAK;GACZ;GACA,GAAI,KAAK,YAAY,KAAA,KAAa,EAAE,SAAS,KAAK,SAAS;GAC3D,GAAI,mBAAmB,KAAA,KAAa,EAAE,gBAAgB;GACtD,GAAI,mBAAmB,KAAA,KAAa,EAAE,gBAAgB;GACvD,CAAC,CAAC,KACD,OAAO,KAAK,MAAM,OAAO,oBAAoB,2BAA2B,EAAE,QAAQ,OAAO,CAAC,EAC1F,OAAO,KAAK,MAAM,OAAO,EAAE,QAAQ,CAAC,EACpC,OAAO,SAAS,MAAM;GACpB,MAAM;GACN,YAAY;IACV,oBAAoB,KAAK;IACzB,0BAA0B;IAC1B,GAAI,KAAK,YAAY,KAAA,KAAa,EAAE,sBAAsB,KAAK,SAAS;IACxE,GAAI,mBAAmB,KAAA,KAAa,EAAE,8BAA8B,gBAAgB;IACpF,GAAI,mBAAmB,KAAA,KAAa,EAAE,8BAA8B,gBAAgB;IACrF;GACF,CAAC,CACH;EACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-uai/core",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Low-level primitives (loop, conversation, items, tools, streaming codecs) for building AI agents with Effect.",
   "keywords": [
     "agents",
@@ -42,6 +42,34 @@
       "types": "./dist/domain/Audio.d.mts",
       "import": "./dist/domain/Audio.mjs"
     },
+    "./Citation": {
+      "types": "./dist/domain/Citation.d.mts",
+      "import": "./dist/domain/Citation.mjs"
+    },
+    "./Research": {
+      "types": "./dist/domain/Research.d.mts",
+      "import": "./dist/domain/Research.mjs"
+    },
+    "./Job": {
+      "types": "./dist/job/Job.d.mts",
+      "import": "./dist/job/Job.mjs"
+    },
+    "./DeepResearch": {
+      "types": "./dist/research/DeepResearch.d.mts",
+      "import": "./dist/research/DeepResearch.mjs"
+    },
+    "./Browser": {
+      "types": "./dist/browser/Browser.d.mts",
+      "import": "./dist/browser/Browser.mjs"
+    },
+    "./BrowserError": {
+      "types": "./dist/browser/BrowserError.d.mts",
+      "import": "./dist/browser/BrowserError.mjs"
+    },
+    "./BrowserTool": {
+      "types": "./dist/browser/BrowserTool.d.mts",
+      "import": "./dist/browser/BrowserTool.mjs"
+    },
     "./Image": {
       "types": "./dist/domain/Image.d.mts",
       "import": "./dist/domain/Image.mjs"
@@ -110,6 +138,14 @@
       "types": "./dist/transcriber/Transcriber.d.mts",
       "import": "./dist/transcriber/Transcriber.mjs"
     },
+    "./WebRead": {
+      "types": "./dist/web-read/WebRead.d.mts",
+      "import": "./dist/web-read/WebRead.mjs"
+    },
+    "./WebReadTool": {
+      "types": "./dist/web-read/WebReadTool.d.mts",
+      "import": "./dist/web-read/WebReadTool.mjs"
+    },
     "./WebSearch": {
       "types": "./dist/web-search/WebSearch.d.mts",
       "import": "./dist/web-search/WebSearch.mjs"
@@ -206,11 +242,11 @@
     "@standard-schema/spec": "^1.1.0"
   },
   "devDependencies": {
-    "effect": "4.0.0-beta.57",
+    "effect": "4.0.0-beta.94",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "effect": "4.0.0-beta.57"
+    "effect": ">=4.0.0-beta.94 <5.0.0"
   },
   "scripts": {
     "build": "tsdown",

package/src/browser/Browser.ts

@@ -0,0 +1,268 @@
+import { Brand, Context, type Duration, Effect, Scope } from "effect"
+import type * as BrowserError from "./BrowserError.js"
+
+// ---------------------------------------------------------------------------
+// Identity
+// ---------------------------------------------------------------------------
+
+/**
+ * Session identifier. Branded `string` so providers don't accidentally
+ * accept a raw user-supplied id, and so a session id can't be passed where
+ * another service's id is expected. Each provider mints these per its own
+ * scheme; core code treats them opaquely. Mint via `BrowserSessionId(...)`.
+ */
+export type BrowserSessionId = Brand.Branded<string, "BrowserSessionId">
+export const BrowserSessionId = Brand.nominal<BrowserSessionId>()
+
+/** Reference returned by `list`; enough to `attach`. */
+export type BrowserSessionRef = {
+  readonly id: BrowserSessionId
+  /** Current top-level URL, when the provider reports it. */
+  readonly url?: string
+}
+
+/**
+ * Output representation for {@link BrowserSession.content}. `markdown` is
+ * the default.
+ */
+export type PageFormat = "markdown" | "html"
+
+// ---------------------------------------------------------------------------
+// Create request
+// ---------------------------------------------------------------------------
+
+/**
+ * Cross-provider session-create request. Provider-specific knobs (proxy,
+ * stealth, persistent profile, ...) live on each provider's narrowed
+ * request type which extends this.
+ */
+export type CommonSessionRequest = {
+  /**
+   * Hard max lifetime of the session. Enforced locally (the handle is
+   * disposed and further calls fail with `BrowserSessionExpired`) and,
+   * where the provider supports it, passed through as a server-side cap so
+   * a crashed client still gets the session reclaimed. The provider cap
+   * must be >= the local reaper. Accepts millis, a string like
+   * `"5 minutes"`, or a `Duration`.
+   */
+  readonly timeout?: Duration.Input
+  /**
+   * Idle teardown: dispose the session after this much inactivity, the
+   * timer resetting on each operation. Opt-in; omit for no idle limit.
+   */
+  readonly idleTimeout?: Duration.Input
+  /** Initial viewport size. Providers default differently. */
+  readonly viewport?: { readonly width: number; readonly height: number }
+}
+
+// ---------------------------------------------------------------------------
+// Observation shapes
+// ---------------------------------------------------------------------------
+
+export type BoundingBox = {
+  readonly x: number
+  readonly y: number
+  readonly width: number
+  readonly height: number
+}
+
+/**
+ * One element returned by {@link BrowserSession.query}. Serializable data,
+ * not a live handle (handles go stale across navigation and do not cross a
+ * provider boundary cleanly).
+ */
+export type ElementInfo = {
+  /**
+   * Reference usable as a selector for a follow-up action. Valid until the
+   * next navigation; do not cache across `goto` or a page-changing click.
+   */
+  readonly ref: string
+  readonly tag: string
+  readonly text?: string
+  readonly attributes: Readonly<Record<string, string>>
+  readonly box?: BoundingBox
+}
+
+/** Accessibility-tree node returned by {@link BrowserSession.snapshot}. */
+export type AxNode = {
+  readonly role: string
+  readonly name?: string
+  readonly value?: string
+  /**
+   * Reference usable as a selector for a follow-up action. Valid until the
+   * next navigation; do not cache across `goto` or a page-changing click.
+   */
+  readonly ref?: string
+  readonly children: ReadonlyArray<AxNode>
+}
+
+// ---------------------------------------------------------------------------
+// Interaction shapes
+// ---------------------------------------------------------------------------
+
+export type ScrollDirection = "up" | "down" | "left" | "right"
+
+export type ScrollOptions = {
+  readonly direction: ScrollDirection
+  /** Distance in CSS pixels. Provider default applies when omitted. */
+  readonly pixels?: number
+}
+
+export type ScreenshotOptions = {
+  /** Clip to the first element matching this selector. */
+  readonly selector?: string
+  /** Capture the full scrollable page rather than the viewport. */
+  readonly fullPage?: boolean
+}
+
+export type Cookie = {
+  readonly name: string
+  readonly value: string
+  readonly domain?: string
+  readonly path?: string
+  readonly expires?: number
+  readonly httpOnly?: boolean
+  readonly secure?: boolean
+  readonly sameSite?: "Strict" | "Lax" | "None"
+}
+
+/** Read / write the session's cookie jar. Needed for authenticated flows. */
+export type CookieApi = {
+  readonly get: Effect.Effect<ReadonlyArray<Cookie>, BrowserError.BrowserError>
+  readonly set: (cookies: ReadonlyArray<Cookie>) => Effect.Effect<void, BrowserError.BrowserError>
+}
+
+// ---------------------------------------------------------------------------
+// Live session handle
+// ---------------------------------------------------------------------------
+
+/**
+ * Live session handle. Actions take a CSS selector string (so `#id` is
+ * just `#id`). Methods are plain `Effect` values; disposal is the scope
+ * finalizer, not a method here (see {@link BrowserService}). Anything not
+ * covered by a verb is reachable via `evaluate`. Per-operation time budgets
+ * are the provider's default; wrap any call in `Effect.timeout` for a
+ * tighter bound.
+ */
+export type BrowserSession = {
+  readonly id: BrowserSessionId
+
+  // Navigation and waiting
+  readonly goto: (url: string) => Effect.Effect<void, BrowserError.BrowserError>
+  readonly waitFor: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>
+
+  // Interaction
+  readonly click: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>
+  readonly dblclick: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>
+  readonly fill: (selector: string, text: string) => Effect.Effect<void, BrowserError.BrowserError>
+  readonly type: (selector: string, text: string) => Effect.Effect<void, BrowserError.BrowserError>
+  readonly press: (key: string) => Effect.Effect<void, BrowserError.BrowserError>
+  readonly hover: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>
+  readonly focus: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>
+  readonly select: (
+    selector: string,
+    value: string,
+  ) => Effect.Effect<void, BrowserError.BrowserError>
+  readonly check: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>
+  readonly uncheck: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>
+  readonly scroll: (options: ScrollOptions) => Effect.Effect<void, BrowserError.BrowserError>
+  readonly scrollIntoView: (selector: string) => Effect.Effect<void, BrowserError.BrowserError>
+
+  // Observation
+  readonly content: (format?: PageFormat) => Effect.Effect<string, BrowserError.BrowserError>
+  readonly screenshot: (
+    options?: ScreenshotOptions,
+  ) => Effect.Effect<Uint8Array, BrowserError.BrowserError>
+  readonly snapshot: Effect.Effect<AxNode, BrowserError.BrowserError>
+  readonly query: (
+    selector: string,
+  ) => Effect.Effect<ReadonlyArray<ElementInfo>, BrowserError.BrowserError>
+
+  // State and escape hatch
+  readonly cookies: CookieApi
+  readonly evaluate: (script: string) => Effect.Effect<unknown, BrowserError.BrowserError>
+}
+
+// ---------------------------------------------------------------------------
+// Service definition
+// ---------------------------------------------------------------------------
+
+/**
+ * Cross-provider browser service.
+ *
+ * Lifetime: `create` and `attach` return a handle in `Scope.Scope`. The
+ * scope finalizer disposes the session (close the transport, destroy or
+ * detach the remote session, kill the local engine). Bind with
+ * `Effect.scoped` for a single call, or hold a wider scope to keep a
+ * session warm across many calls. This is why there is no `dispose()` on
+ * {@link BrowserSession}; the scope is the lifecycle handle.
+ */
+export type BrowserService = {
+  /**
+   * Provision a new session, bound to the caller's scope. Disposed on
+   * scope close.
+   */
+  readonly create: (
+    request: CommonSessionRequest,
+  ) => Effect.Effect<BrowserSession, BrowserError.BrowserError, Scope.Scope>
+
+  /**
+   * Re-acquire an existing session by id. Scope-bound, but the finalizer
+   * detaches rather than destroying, for sessions kept warm beyond a
+   * single run.
+   */
+  readonly attach: (
+    id: BrowserSessionId,
+  ) => Effect.Effect<BrowserSession, BrowserError.BrowserError, Scope.Scope>
+
+  /** Enumerate sessions visible to the configured account / project. */
+  readonly list: Effect.Effect<ReadonlyArray<BrowserSessionRef>, BrowserError.BrowserError>
+
+  /**
+   * Destroy a session from outside its owning scope. Most callers should
+   * let the scope finalizer handle this.
+   */
+  readonly destroy: (id: BrowserSessionId) => Effect.Effect<void, BrowserError.BrowserError>
+}
+
+export class Browser extends Context.Service<Browser, BrowserService>()(
+  "@betalyra/effect-uai/Browser",
+) {}
+
+// ---------------------------------------------------------------------------
+// Free helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Provision a session bound to the caller's scope. Drop the `Scope.Scope`
+ * requirement with `Effect.scoped`.
+ */
+export const create = (
+  request: CommonSessionRequest,
+): Effect.Effect<BrowserSession, BrowserError.BrowserError, Browser | Scope.Scope> =>
+  Effect.flatMap(Browser, (s) => s.create(request))
+
+/**
+ * Re-acquire an existing session by id. Same scope semantics as `create`,
+ * but the finalizer detaches rather than destroying.
+ */
+export const attach = (
+  id: BrowserSessionId,
+): Effect.Effect<BrowserSession, BrowserError.BrowserError, Browser | Scope.Scope> =>
+  Effect.flatMap(Browser, (s) => s.attach(id))
+
+/** Enumerate sessions for the configured account / project. */
+export const list: Effect.Effect<
+  ReadonlyArray<BrowserSessionRef>,
+  BrowserError.BrowserError,
+  Browser
+> = Effect.flatMap(Browser, (s) => s.list)
+
+/**
+ * Destroy a session from outside its owning scope. Most callers should let
+ * the scope finalizer handle this automatically.
+ */
+export const destroy = (
+  id: BrowserSessionId,
+): Effect.Effect<void, BrowserError.BrowserError, Browser> =>
+  Effect.flatMap(Browser, (s) => s.destroy(id))