@effect-uai/core 0.9.0 → 0.10.0

package/dist/web-read/WebRead.d.mts

@@ -0,0 +1,44 @@
+import { t as AiError } from "../AiError-Bf1pq4BB.mjs";
+import { Context, Duration, Effect } from "effect";
+
+//#region src/web-read/WebRead.d.ts
+declare namespace WebRead_d_exports {
+  export { CommonReadRequest, ReadFormat, ReadResponse, WebRead, WebReadService, read };
+}
+/** Representation to return for a page. `markdown` is the default. */
+type ReadFormat = "markdown" | "html";
+/**
+ * Cross-provider read request: one URL in, clean content out. Provider-specific
+ * knobs live on the provider-typed request.
+ */
+type CommonReadRequest = {
+  /** The page to read. */readonly url: string; /** Output representation. Defaults to `markdown`. See {@link ReadFormat}. */
+  readonly format?: ReadFormat; /** Upper bound on time spent fetching the page. */
+  readonly timeout?: Duration.Duration;
+};
+/** One normalized read result. */
+type ReadResponse = {
+  /** The URL that was read. */readonly url: string; /** Extracted content in the requested {@link ReadFormat}. */
+  readonly content: string; /** Page title, when reported. */
+  readonly title?: string; /** Links discovered on the page, when returned. */
+  readonly links?: ReadonlyArray<string>; /** The provider-native response. */
+  readonly raw: unknown;
+};
+/**
+ * The portable read surface: one operation, `read`. Every implementor can
+ * answer, so this capability needs no marker tags.
+ */
+type WebReadService = {
+  readonly read: (request: CommonReadRequest) => Effect.Effect<ReadResponse, AiError>;
+};
+declare const WebRead_base: Context.ServiceClass<WebRead, "@betalyra/effect-uai/WebRead", WebReadService>;
+/**
+ * Generic read service tag. Yield this for provider-portable code; yield a
+ * provider tag for provider-specific knobs. A provider `layer` registers both.
+ */
+declare class WebRead extends WebRead_base {}
+/** Read one URL against whichever provider Layer is in scope. */
+declare const read: (request: CommonReadRequest) => Effect.Effect<ReadResponse, AiError, WebRead>;
+//#endregion
+export { CommonReadRequest, ReadFormat, ReadResponse, WebRead, WebReadService, read, WebRead_d_exports as t };
+//# sourceMappingURL=WebRead.d.mts.map

package/dist/web-read/WebRead.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebRead.d.mts","names":[],"sources":["../../src/web-read/WebRead.ts"],"mappings":";;;;;;;;KAQY,UAAA;;;;;KAUA,iBAAA;mCAED,GAAA;WAEA,MAAA,GAAS,UAAA,EAdR;EAAA,SAgBD,OAAA,GAAU,QAAA,CAAS,QAAA;AAAA;;KAQlB,YAAA;EAdA,sCAgBD,GAAA;WAEA,OAAA,UAhBA;EAAA,SAkBA,KAAA,WAhBS;EAAA,SAkBT,KAAA,GAAQ,aAAA,UAhBE;EAAA,SAkBV,GAAA;AAAA;;AAVX;;;KAqBY,cAAA;EAAA,SACD,IAAA,GAAO,OAAA,EAAS,iBAAA,KAAsB,MAAA,CAAO,MAAA,CAAO,YAAA,EAAc,OAAA;AAAA;AAAA,cAC5E,YAAA;;;;;cAMY,OAAA,SAAgB,YAAA;;cAKhB,IAAA,GACX,OAAA,EAAS,iBAAA,KACR,MAAA,CAAO,MAAA,CAAO,YAAA,EAAc,OAAA,EAAiB,OAAA"}

package/dist/web-read/WebRead.mjs

@@ -0,0 +1,18 @@
+import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
+import { Context, Effect } from "effect";
+//#region src/web-read/WebRead.ts
+var WebRead_exports = /* @__PURE__ */ __exportAll({
+	WebRead: () => WebRead,
+	read: () => read
+});
+/**
+* Generic read service tag. Yield this for provider-portable code; yield a
+* provider tag for provider-specific knobs. A provider `layer` registers both.
+*/
+var WebRead = class extends Context.Service()("@betalyra/effect-uai/WebRead") {};
+/** Read one URL against whichever provider Layer is in scope. */
+const read = (request) => Effect.flatMap(WebRead.asEffect(), (s) => s.read(request));
+//#endregion
+export { WebRead, read, WebRead_exports as t };
+
+//# sourceMappingURL=WebRead.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WebRead.mjs","names":[],"sources":["../../src/web-read/WebRead.ts"],"sourcesContent":["import { Context, type Duration, Effect } from \"effect\"\nimport type * as AiError from \"../domain/AiError.js\"\n\n// ---------------------------------------------------------------------------\n// Format\n// ---------------------------------------------------------------------------\n\n/** Representation to return for a page. `markdown` is the default. */\nexport type ReadFormat = \"markdown\" | \"html\"\n\n// ---------------------------------------------------------------------------\n// Request\n// ---------------------------------------------------------------------------\n\n/**\n * Cross-provider read request: one URL in, clean content out. Provider-specific\n * knobs live on the provider-typed request.\n */\nexport type CommonReadRequest = {\n  /** The page to read. */\n  readonly url: string\n  /** Output representation. Defaults to `markdown`. See {@link ReadFormat}. */\n  readonly format?: ReadFormat\n  /** Upper bound on time spent fetching the page. */\n  readonly timeout?: Duration.Duration\n}\n\n// ---------------------------------------------------------------------------\n// Response\n// ---------------------------------------------------------------------------\n\n/** One normalized read result. */\nexport type ReadResponse = {\n  /** The URL that was read. */\n  readonly url: string\n  /** Extracted content in the requested {@link ReadFormat}. */\n  readonly content: string\n  /** Page title, when reported. */\n  readonly title?: string\n  /** Links discovered on the page, when returned. */\n  readonly links?: ReadonlyArray<string>\n  /** The provider-native response. */\n  readonly raw: unknown\n}\n\n// ---------------------------------------------------------------------------\n// Service + helper\n// ---------------------------------------------------------------------------\n\n/**\n * The portable read surface: one operation, `read`. Every implementor can\n * answer, so this capability needs no marker tags.\n */\nexport type WebReadService = {\n  readonly read: (request: CommonReadRequest) => Effect.Effect<ReadResponse, AiError.AiError>\n}\n\n/**\n * Generic read service tag. Yield this for provider-portable code; yield a\n * provider tag for provider-specific knobs. A provider `layer` registers both.\n */\nexport class WebRead extends Context.Service<WebRead, WebReadService>()(\n  \"@betalyra/effect-uai/WebRead\",\n) {}\n\n/** Read one URL against whichever provider Layer is in scope. */\nexport const read = (\n  request: CommonReadRequest,\n): Effect.Effect<ReadResponse, AiError.AiError, WebRead> =>\n  Effect.flatMap(WebRead.asEffect(), (s) => s.read(request))\n"],"mappings":";;;;;;;;;;;AA6DA,IAAa,UAAb,cAA6B,QAAQ,SAAkC,CACrE,+BACD,CAAC;;AAGF,MAAa,QACX,YAEA,OAAO,QAAQ,QAAQ,UAAU,GAAG,MAAM,EAAE,KAAK,QAAQ,CAAC"}

package/dist/web-read/WebReadTool.d.mts

@@ -0,0 +1,57 @@
+import { l as Tool } from "../Tool-2lC_XMth.mjs";
+import { t as AiError } from "../AiError-Bf1pq4BB.mjs";
+import { ReadFormat, ReadResponse, WebRead } from "./WebRead.mjs";
+import { Schema } from "effect";
+
+//#region src/web-read/WebReadTool.d.ts
+declare namespace WebReadTool_d_exports {
+  export { WebReadToolArgs, WebReadToolOptions, 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.
+ */
+declare const WebReadToolArgs: Schema.Struct<{
+  readonly url: Schema.String;
+}>;
+type WebReadToolArgs = typeof WebReadToolArgs.Type;
+type WebReadToolOptions = {
+  /** Tool name the model sees. Default `"web_read"`. */readonly name?: string;
+  /**
+   * App-fixed representation for every read - a policy choice, not a model
+   * knob. Default `"markdown"` (what models read best).
+   */
+  readonly format?: ReadFormat;
+  /**
+   * App-fixed ceiling on rendered content characters per call - a context
+   * cost guard, not exposed to the model. Default `20000`.
+   */
+  readonly maxChars?: number;
+  /**
+   * Override how a read response is rendered into the model-facing string.
+   * Default: `title / url` header plus the content, truncated at `maxChars`.
+   */
+  readonly render?: (response: ReadResponse) => string;
+};
+/**
+ * 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.
+ */
+declare const webReadTool: (options?: WebReadToolOptions) => Tool<string, WebReadToolArgs, never, string, AiError, WebRead>;
+//#endregion
+export { WebReadToolArgs, WebReadToolOptions, WebReadTool_d_exports as t, webReadTool };
+//# sourceMappingURL=WebReadTool.d.mts.map

package/dist/web-read/WebReadTool.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WebReadTool.d.mts","names":[],"sources":["../../src/web-read/WebReadTool.ts"],"mappings":";;;;;;;;;;;;;;;cAWM,eAAA,EAAe,MAAA,CAAA,MAAA;EAAA,cAInB,MAAA,CAAA,MAAA;AAAA;AAAA,KAEU,eAAA,UAAyB,eAAA,CAAgB,IAAA;AAAA,KAYzC,kBAAA;EAlBS,+DAoBV,IAAA;EApBU;;;;EAAA,SAyBV,MAAA,GAAS,UAAA;;AAnBpB;;;WAwBW,QAAA;EAxB8C;AAYzD;;;EAZyD,SA6B9C,MAAA,IAAU,QAAA,EAAU,YAAA;AAAA;;;;;;;;;AAmB/B;;;;;;;;cAAa,WAAA,GACX,OAAA,GAAU,kBAAA,KACT,IAAA,SAAkB,eAAA,iBAAgC,OAAA,EAAiB,OAAA"}

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/WebSearchTool.d.mts

@@ -1,4 +1,5 @@
-import { c as Tool } from "../Tool-0XUIT2A2.mjs";
+import { l as Tool } from "../Tool-2lC_XMth.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.10.0",
   "description": "Low-level primitives (loop, conversation, items, tools, streaming codecs) for building AI agents with Effect.",
   "keywords": [
     "agents",
@@ -42,6 +42,18 @@
       "types": "./dist/domain/Audio.d.mts",
       "import": "./dist/domain/Audio.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 +122,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"

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.asEffect(), (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.asEffect(), (s) => s.attach(id))
+
+/** Enumerate sessions for the configured account / project. */
+export const list: Effect.Effect<
+  ReadonlyArray<BrowserSessionRef>,
+  BrowserError.BrowserError,
+  Browser
+> = Effect.flatMap(Browser.asEffect(), (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.asEffect(), (s) => s.destroy(id))