@effect-uai/core 0.8.0 → 0.10.0

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

@@ -1,4 +1,5 @@
-import { a as Tool } from "../Tool-BKiieFXk.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, 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,UAA2B,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, 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,YAC4D;CAC5D,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.8.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))

package/src/browser/BrowserError.ts

@@ -0,0 +1,145 @@
+import { Data, Duration, Match } from "effect"
+
+/**
+ * Failed to provision a browser session: the transport could not connect,
+ * a launched engine did not come up, or the provider refused to mint a
+ * session. Provider's structured reason on `reason`; the raw transport /
+ * SDK error on `raw`.
+ */
+export class BrowserCreateFailed extends Data.TaggedError("BrowserCreateFailed")<{
+  provider: string
+  reason?: string
+  raw: unknown
+}> {}
+
+/**
+ * The requested session id does not exist. Raised by `attach` / `destroy`
+ * against a stale or never-known id. Distinct from
+ * {@link BrowserSessionExpired}, which is a session that existed and has
+ * since ended.
+ */
+export class BrowserSessionNotFound extends Data.TaggedError("BrowserSessionNotFound")<{
+  provider: string
+  id: string
+}> {}
+
+/**
+ * An operation was issued against a session that has ended: it reached its
+ * max lifetime (the create-time `timeout`), was destroyed, or the provider
+ * reaped it. The handle is dead; `create` or `attach` a live session.
+ * Distinct from {@link BrowserTimeout} (a single live operation was too
+ * slow).
+ */
+export class BrowserSessionExpired extends Data.TaggedError("BrowserSessionExpired")<{
+  provider: string
+  id: string
+}> {}
+
+/**
+ * A single operation exceeded its own time budget while the session was
+ * still alive (a navigation that never settled, a `waitFor` selector that
+ * never appeared). Carries the breached budget for observability.
+ */
+export class BrowserTimeout extends Data.TaggedError("BrowserTimeout")<{
+  provider: string
+  operation: "create" | "attach" | "navigate" | "action" | "query"
+  budget?: Duration.Duration
+  raw?: unknown
+}> {}
+
+/**
+ * An interaction or observation failed at the transport / protocol layer:
+ * a selector resolved to nothing, an element was not actionable, an
+ * `evaluate` script threw, a navigation errored. `selector` and `reason`
+ * carry what is known.
+ */
+export class BrowserActionFailed extends Data.TaggedError("BrowserActionFailed")<{
+  provider: string
+  operation: "navigate" | "interact" | "observe" | "evaluate" | "cookies"
+  selector?: string
+  reason?: string
+  raw: unknown
+}> {}
+
+/**
+ * Provider rejected the request because an account / project quota or
+ * concurrency limit was exceeded. Separate from {@link BrowserCreateFailed}
+ * so callers can back off and retry.
+ */
+export class BrowserQuotaExceeded extends Data.TaggedError("BrowserQuotaExceeded")<{
+  provider: string
+  reason?: string
+  raw: unknown
+}> {}
+
+/**
+ * Caller's request shape is malformed for the wired provider. Adapters
+ * should reject at the request-schema layer where possible; this is the
+ * runtime fallback.
+ */
+export class BrowserInvalidRequest extends Data.TaggedError("BrowserInvalidRequest")<{
+  provider: string
+  param?: string
+  reason?: string
+  raw?: unknown
+}> {}
+
+/**
+ * Transport could not authenticate against the provider. Subtype mirrors
+ * the model-side `AiError.AuthFailed` shape for consistency.
+ */
+export type BrowserAuthSubtype = "auth" | "permission" | "billing" | "quota"
+
+export class BrowserAuthFailed extends Data.TaggedError("BrowserAuthFailed")<{
+  provider: string
+  subtype: BrowserAuthSubtype
+  raw: unknown
+}> {}
+
+/**
+ * The wired provider does not implement the requested operation for these
+ * inputs. Distinct from {@link BrowserInvalidRequest} (malformed request)
+ * and from compile-time capability markers gating blanket provider gaps.
+ */
+export class BrowserUnsupported extends Data.TaggedError("BrowserUnsupported")<{
+  provider: string
+  capability: string
+  reason?: string
+}> {}
+
+export type BrowserError =
+  | BrowserCreateFailed
+  | BrowserSessionNotFound
+  | BrowserSessionExpired
+  | BrowserTimeout
+  | BrowserActionFailed
+  | BrowserQuotaExceeded
+  | BrowserInvalidRequest
+  | BrowserAuthFailed
+  | BrowserUnsupported
+
+const withReason = (base: string, reason: string | undefined): string =>
+  reason === undefined ? base : `${base}: ${reason}`
+
+/**
+ * Short human-readable description of an error, for logs and model-facing
+ * failure messages. Prose, not a contract; branch on `_tag` instead.
+ */
+export const describe: (e: BrowserError) => string = Match.type<BrowserError>().pipe(
+  Match.discriminatorsExhaustive("_tag")({
+    BrowserCreateFailed: (e) => withReason("the browser session could not be created", e.reason),
+    BrowserSessionNotFound: () => "the browser session does not exist",
+    BrowserSessionExpired: () => "the browser session has expired",
+    BrowserTimeout: (e) => `the ${e.operation} operation timed out`,
+    BrowserActionFailed: (e) =>
+      withReason(
+        `the ${e.operation} failed${e.selector === undefined ? "" : ` on ${e.selector}`}`,
+        e.reason,
+      ),
+    BrowserQuotaExceeded: (e) => withReason("the browser quota is exceeded", e.reason),
+    BrowserInvalidRequest: (e) => withReason("the request was invalid", e.reason),
+    BrowserAuthFailed: (e) => `browser authentication failed (${e.subtype})`,
+    BrowserUnsupported: (e) =>
+      withReason(`this browser does not support ${e.capability}`, e.reason),
+  }),
+)