@effect-uai/core 0.8.0 → 0.10.0

package/dist/Toolkit-Dr9l_hNy.d.mts

@@ -0,0 +1,196 @@
+import { o as HistoryItem, v as ToolCall } from "./Items-BnIduEV2.mjs";
+import { a as Emit, c as SignalTool, d as ToolE, h as ToolR, l as Tool, n as AnyTool, o as InteractionTool, p as ToolFailed, s as ProviderTool, u as ToolDescriptor } from "./Tool-2lC_XMth.mjs";
+import { Turn } from "./domain/Turn.mjs";
+import { r as Step } from "./Loop-D8nWpowc.mjs";
+import { t as ToolResult } from "./ToolResult-CL4hK_9z.mjs";
+import { t as ToolEvent } from "./ToolEvent-cWZ2BnbS.mjs";
+import { Cause, Effect, Stream } from "effect";
+import * as _$effect_Types0 from "effect/Types";
+
+//#region src/tool/Toolkit.d.ts
+declare namespace Toolkit_d_exports {
+  export { DuplicateToolName, ExecuteOptions, Middleware, NoDuplicateNames, ToolMap, Toolkit, ToolkitE, ToolkitR, UniqueTools, appendToolResults, collectResults, compose, continueWithResults, describeFailures, descriptors, fromArray, make, makeNamespaced, namespace, run, wrap };
+}
+type ToolMap = Record<string, AnyTool>;
+type Toolkit<Tools extends ToolMap = ToolMap> = Tools;
+declare const make: <const Tools extends ReadonlyArray<AnyTool>>(...tools: UniqueTools<Tools>) => Toolkit<{ [T in Tools[number] as T["name"]]: T }>;
+/**
+ * Build a toolkit from a dynamically-sourced array (MCP server, plugin). Names
+ * are not validated (MCP legitimately uses dots / >64 chars — sanitize at the
+ * provider adapter); same-named tools resolve last-wins. Cross-source clashes
+ * are caught by `compose`.
+ */
+declare const fromArray: (tools: ReadonlyArray<AnyTool>) => Toolkit;
+/** Render the provider-facing descriptors for a toolkit on demand. */
+declare const descriptors: (toolkit: Toolkit) => ReadonlyArray<ToolDescriptor>;
+/**
+ * Union of every tool's `R` requirements in a toolkit. Surfaced by `run` so the
+ * loop's stream type carries the services tools need through to `Effect.provide`.
+ *
+ * The `ToolMap extends T` guard yields `never` for the wide `Toolkit` type (a
+ * toolkit passed through an untyped boundary, where the requirements aren't
+ * statically known) instead of `any`, which would otherwise poison the
+ * resulting stream's `R`. Concrete toolkits from `make` keep their precise R.
+ */
+type ToolkitR<T extends Toolkit> = ToolMap extends T ? never : ToolR<T[keyof T]>;
+/**
+ * Union of every tool's `E` error type in a toolkit. `Toolkit.run` reports
+ * `Exclude<ToolkitE<T>, string | ToolFailed>` on its stream: the sentinel
+ * failures are absorbed into results, everything else propagates typed. The
+ * same `ToolMap extends T` guard as `ToolkitR` keeps a wide toolkit at
+ * `never` rather than `any`.
+ */
+type ToolkitE<T extends Toolkit> = ToolMap extends T ? never : ToolE<T[keyof T]>;
+type DuplicateName<Tools extends ReadonlyArray<AnyTool>, Seen extends string = never> = Tools extends readonly [infer Head extends AnyTool, ...infer Tail extends ReadonlyArray<AnyTool>] ? Head["name"] extends Seen ? Head["name"] : DuplicateName<Tail, Seen | Head["name"]> : never;
+type DuplicateNameError<Name extends string> = {
+  readonly __error: `Duplicate tool name: ${Name}`;
+};
+type NoDuplicateNames<Tools extends ReadonlyArray<AnyTool>> = [DuplicateName<Tools>] extends [never] ? unknown : DuplicateNameError<DuplicateName<Tools>>;
+/** `Tools` constrained so a repeated literal name is a compile error in `make`. */
+type UniqueTools<Tools extends ReadonlyArray<AnyTool>> = Tools & NoDuplicateNames<Tools>;
+type ComposeDuplicateKey<Kits extends ReadonlyArray<Toolkit>, Seen extends string = never> = Kits extends readonly [infer Head extends Toolkit, ...infer Tail extends ReadonlyArray<Toolkit>] ? string extends keyof Head ? ComposeDuplicateKey<Tail, Seen> : Extract<keyof Head & string, Seen> extends never ? ComposeDuplicateKey<Tail, Seen | (keyof Head & string)> : Extract<keyof Head & string, Seen> : never;
+type NoDuplicateComposedKeys<Kits extends ReadonlyArray<Toolkit>> = [ComposeDuplicateKey<Kits>] extends [never] ? unknown : DuplicateNameError<ComposeDuplicateKey<Kits>>;
+type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends ((x: infer I) => void) ? I : never;
+type Composed<Kits extends ReadonlyArray<Toolkit>> = UnionToIntersection<Kits[number]> extends infer M ? (M extends ToolMap ? M : ToolMap) : ToolMap;
+declare const DuplicateToolName_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => Cause.YieldableError & {
+  readonly _tag: "DuplicateToolName";
+} & Readonly<A>;
+/**
+ * Two composed toolkits resolved to the same final name. Carries the colliding
+ * `sources` (the positions of the clashing toolkits) so the error says *which*
+ * inputs collided. Raised at runtime by `compose` for dynamic sources; static
+ * collisions are caught earlier at compile time.
+ */
+declare class DuplicateToolName extends DuplicateToolName_base<{
+  readonly name: string;
+  readonly sources: ReadonlyArray<string>;
+}> {}
+type PrefixName<Prefix extends string, Name extends string> = `${Prefix}__${Name}`;
+type PrefixTool<Prefix extends string, T extends AnyTool> = T extends Tool<infer N, infer I, infer Ev, infer O, infer R> ? Tool<PrefixName<Prefix, N>, I, Ev, O, R> : T extends ProviderTool<infer N, infer I, infer P, infer C> ? ProviderTool<PrefixName<Prefix, N>, I, P, C> : T extends SignalTool<infer N, infer I> ? SignalTool<PrefixName<Prefix, N>, I> : T extends InteractionTool<infer N, infer I> ? InteractionTool<PrefixName<Prefix, N>, I> : T;
+type Namespaced<Prefix extends string, T extends ToolMap> = { readonly [K in keyof T & string as PrefixName<Prefix, K>]: T[K] extends AnyTool ? PrefixTool<Prefix, T[K]> : never };
+/**
+ * Prefix every tool name with `<namespace>__`, returning a new toolkit. Use it
+ * to keep generic names (`search`) from two sources distinct before `compose`.
+ * If two namespaces collide at the `__` separator, the duplicate final name
+ * surfaces from `compose` as a `DuplicateToolName`.
+ */
+declare const namespace: <const Prefix extends string, const T extends ToolMap>(prefix: Prefix, toolkit: Toolkit<T>) => Toolkit<Namespaced<Prefix, T>>;
+/** `namespace(prefix, make(...tools))` in one step, for static namespaced tools. */
+declare const makeNamespaced: <const Prefix extends string, const Tools extends ReadonlyArray<AnyTool>>(prefix: Prefix, ...tools: UniqueTools<Tools>) => Toolkit<Namespaced<Prefix, { [T in Tools[number] as T["name"]]: T }>>;
+/**
+ * Combine independently-built toolkits into one. This is where names from
+ * separate sources can collide, so it is the one effectful constructor: a
+ * duplicate final name fails with `DuplicateToolName` (naming the colliding
+ * input positions) instead of silently overwriting or 400-ing later at the
+ * provider. Statically-known collisions are additionally a compile error.
+ */
+declare const compose: <const Kits extends ReadonlyArray<Toolkit>>(...toolkits: Kits & NoDuplicateComposedKeys<Kits>) => Effect.Effect<Toolkit<Composed<Kits>>, DuplicateToolName>;
+type Handler<Input, Event, Output, E, R> = (input: Input, emit: Emit<Event>) => Effect.Effect<Output, E, R>;
+/**
+ * A `run` transform, tracking an added requirement `R2` and optional added
+ * error `E2`. The tool's own `E` is preserved; `describeFailures` is the
+ * combinator that *replaces* it (mapping every error to `string`).
+ */
+type Middleware<R2 = never, E2 = never> = <Input, Event, Output, E, R>(run: Handler<Input, Event, Output, E, R>, name: string) => Handler<Input, Event, Output, E | E2, R | R2>;
+type WrapTool<T extends AnyTool, R2, E2> = T extends Tool<infer N, infer I, infer Ev, infer O, infer E, infer R> ? Tool<N, I, Ev, O, E | E2, R | R2> : T;
+type WrapToolkit<T extends ToolMap, R2, E2> = { readonly [K in keyof T]: T[K] extends AnyTool ? WrapTool<T[K], R2, E2> : T[K] };
+/**
+ * Wrap every local tool's `run` with a middleware, preserving each tool's
+ * `Input`/`Output` and unioning the middleware's requirement `R2` into the
+ * toolkit's `ToolkitR`. Non-local kinds pass through unchanged. Stack with
+ * `pipe` - inner-first, so the last `wrap` applied is the outermost and runs
+ * first:
+ *
+ *   const observed = pipe(toolkit, Toolkit.wrap(logging), Toolkit.wrap(authz))
+ *   Toolkit.run(observed, calls) // authz runs, then logging, then the tool
+ *
+ * A middleware that fails with `string` / `ToolFailed` is absorbed by the
+ * executor into a `ToolResult.Failure`; any other error propagates typed. Use
+ * `describeFailures` for the total "everything to the model" case, or the
+ * `Approval` flow for a distinct "denied" verdict.
+ */
+declare const wrap: {
+  <R2, E2>(middleware: Middleware<R2, E2>): <T extends Toolkit>(toolkit: T) => WrapToolkit<T, R2, E2>;
+  <T extends Toolkit, R2, E2>(toolkit: T, middleware: Middleware<R2, E2>): WrapToolkit<T, R2, E2>;
+};
+type DescribeTool<T extends AnyTool> = T extends Tool<infer N, infer I, infer Ev, infer O, any, infer R> ? Tool<N, I, Ev, O, string, R> : T;
+type DescribeToolkit<T extends ToolMap> = { readonly [K in keyof T]: T[K] extends AnyTool ? DescribeTool<T[K]> : T[K] };
+/**
+ * Map every local tool's error to a `string`, so `Toolkit.run` absorbs those
+ * failures into `ToolResult.Failure` the model reads and adapts to. Pairs
+ * with the domain `describe` helpers (`AiError.describe`,
+ * `BrowserError.describe`). Non-local kinds pass through.
+ *
+ *   const kit = yield* Toolkit.compose(
+ *     Toolkit.describeFailures(searchKit, AiError.describe),
+ *     browserToolkit(session), // failures stay typed
+ *   )
+ */
+declare const describeFailures: {
+  <E>(describe: (e: E) => string): <T extends Toolkit>(toolkit: T) => DescribeToolkit<T>;
+  <T extends Toolkit>(toolkit: T, describe: (e: ToolkitE<T>) => string): DescribeToolkit<T>;
+};
+type ExecuteOptions = {
+  readonly concurrency?: number | "unbounded";
+};
+/**
+ * Execute every provided call. Approval/rejection policy belongs upstream.
+ *
+ * String and `ToolFailed` failures are absorbed into `ToolResult.Failure`
+ * (the model reads and adapts to them); every other tool error propagates
+ * typed on the stream, so `Exclude<ToolkitE<T>, string | ToolFailed>` is
+ * what a caller catches or lets end the run. If one call in a concurrent
+ * batch fails the stream, siblings may go unanswered: a loop that catches
+ * and continues must reconcile history first (`HistoryCheck.cancelAllPending`).
+ */
+declare const run: <T extends Toolkit>(toolkit: T, calls: ReadonlyArray<ToolCall>, options?: ExecuteOptions) => Stream.Stream<ToolEvent, Exclude<ToolkitE<T>, string | ToolFailed>, ToolkitR<T>>;
+/**
+ * Append a completed turn plus tool results to a state's history, converting
+ * the results to wire-format `ToolCallOutput`s. Curried so it slots directly
+ * into `continueWithResults`:
+ *
+ *   Toolkit.run(toolkit, calls).pipe(
+ *     Toolkit.continueWithResults(Toolkit.appendToolResults(state, turn)),
+ *   )
+ *
+ * Equivalent to `appendToHistory(state, turn, results.map(toToolCallOutput))`
+ * — the helper just hides the wire-conversion step.
+ */
+declare const appendToolResults: <S extends {
+  readonly history: ReadonlyArray<HistoryItem>;
+}>(state: S, turn: Turn) => (results: ReadonlyArray<ToolResult>) => S;
+/**
+ * Drain a `Stream<ToolEvent>` and return the accumulated `ToolResult`s
+ * from every `Output` event. One-shot — the type is `Effect<results>`,
+ * not a one-element stream — so it composes naturally with `Effect.map`
+ * to build state.
+ *
+ * Counterpart to `continueWithResults`: `continueWithResults` bundles
+ * drain + emit Next into one bridge; this one is the right arm of a
+ * broadcast/fork-and-merge for callers that want to vary the left arm
+ * (e.g., filter/tap ToolEvents before forwarding).
+ */
+declare const collectResults: <E, R>(stream: Stream.Stream<ToolEvent, E, R>) => Effect.Effect<ReadonlyArray<ToolResult>, E, R>;
+/**
+ * Bridge from a `Stream<ToolEvent>` to the loop's emit shape. Forwards
+ * every ToolEvent downstream as a `Loop.value` and at end-of-stream emits
+ * one `Loop.next(build(results))` carrying the accumulated `ToolResult`s
+ * from terminal `Output` events.
+ *
+ * Conceptually a broadcast fork (one arm passes events through, the other
+ * drains them into a state). Implemented as a single-pass Ref tap + concat
+ * for zero buffering — the broadcast version is observationally equivalent
+ * but holds events in a PubSub until both arms drain. The public primitives
+ * (`Loop.value`, `collectResults`, `Loop.next`) compose the same pattern
+ * when you need to vary an arm.
+ *
+ * Dual: data-first `continueWithResults(stream, build)` and data-last
+ * `stream.pipe(continueWithResults(build))` both work.
+ */
+declare const continueWithResults: {
+  <S>(build: (results: ReadonlyArray<ToolResult>) => S): <E, R>(stream: Stream.Stream<ToolEvent, E, R>) => Stream.Stream<Step<ToolEvent, S>, E, R>;
+  <S, E, R>(stream: Stream.Stream<ToolEvent, E, R>, build: (results: ReadonlyArray<ToolResult>) => S): Stream.Stream<Step<ToolEvent, S>, E, R>;
+};
+//#endregion
+export { wrap as S, fromArray as _, ToolMap as a, namespace as b, ToolkitR as c, appendToolResults as d, collectResults as f, descriptors as g, describeFailures as h, NoDuplicateNames as i, Toolkit_d_exports as l, continueWithResults as m, ExecuteOptions as n, Toolkit as o, compose as p, Middleware as r, ToolkitE as s, DuplicateToolName as t, UniqueTools as u, make as v, run as x, makeNamespaced as y };
+//# sourceMappingURL=Toolkit-Dr9l_hNy.d.mts.map

package/dist/Toolkit-Dr9l_hNy.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Toolkit-Dr9l_hNy.d.mts","names":[],"sources":["../src/tool/Toolkit.ts"],"mappings":"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"}

package/dist/browser/Browser.d.mts

@@ -0,0 +1,190 @@
+import { BrowserError } from "./BrowserError.mjs";
+import { Brand, Context, Duration, Effect, Scope } from "effect";
+
+//#region src/browser/Browser.d.ts
+declare namespace Browser_d_exports {
+  export { AxNode, BoundingBox, Browser, BrowserService, BrowserSession, BrowserSessionId, BrowserSessionRef, CommonSessionRequest, Cookie, CookieApi, ElementInfo, PageFormat, ScreenshotOptions, ScrollDirection, ScrollOptions, attach, create, destroy, list };
+}
+/**
+ * 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(...)`.
+ */
+type BrowserSessionId = Brand.Branded<string, "BrowserSessionId">;
+declare const BrowserSessionId: Brand.Constructor<BrowserSessionId>;
+/** Reference returned by `list`; enough to `attach`. */
+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.
+ */
+type PageFormat = "markdown" | "html";
+/**
+ * Cross-provider session-create request. Provider-specific knobs (proxy,
+ * stealth, persistent profile, ...) live on each provider's narrowed
+ * request type which extends this.
+ */
+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;
+  };
+};
+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).
+ */
+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}. */
+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>;
+};
+type ScrollDirection = "up" | "down" | "left" | "right";
+type ScrollOptions = {
+  readonly direction: ScrollDirection; /** Distance in CSS pixels. Provider default applies when omitted. */
+  readonly pixels?: number;
+};
+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;
+};
+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. */
+type CookieApi = {
+  readonly get: Effect.Effect<ReadonlyArray<Cookie>, BrowserError>;
+  readonly set: (cookies: ReadonlyArray<Cookie>) => Effect.Effect<void, BrowserError>;
+};
+/**
+ * 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.
+ */
+type BrowserSession = {
+  readonly id: BrowserSessionId;
+  readonly goto: (url: string) => Effect.Effect<void, BrowserError>;
+  readonly waitFor: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly click: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly dblclick: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly fill: (selector: string, text: string) => Effect.Effect<void, BrowserError>;
+  readonly type: (selector: string, text: string) => Effect.Effect<void, BrowserError>;
+  readonly press: (key: string) => Effect.Effect<void, BrowserError>;
+  readonly hover: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly focus: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly select: (selector: string, value: string) => Effect.Effect<void, BrowserError>;
+  readonly check: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly uncheck: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly scroll: (options: ScrollOptions) => Effect.Effect<void, BrowserError>;
+  readonly scrollIntoView: (selector: string) => Effect.Effect<void, BrowserError>;
+  readonly content: (format?: PageFormat) => Effect.Effect<string, BrowserError>;
+  readonly screenshot: (options?: ScreenshotOptions) => Effect.Effect<Uint8Array, BrowserError>;
+  readonly snapshot: Effect.Effect<AxNode, BrowserError>;
+  readonly query: (selector: string) => Effect.Effect<ReadonlyArray<ElementInfo>, BrowserError>;
+  readonly cookies: CookieApi;
+  readonly evaluate: (script: string) => Effect.Effect<unknown, BrowserError>;
+};
+/**
+ * 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.
+ */
+type BrowserService = {
+  /**
+   * Provision a new session, bound to the caller's scope. Disposed on
+   * scope close.
+   */
+  readonly create: (request: CommonSessionRequest) => Effect.Effect<BrowserSession, 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, Scope.Scope>; /** Enumerate sessions visible to the configured account / project. */
+  readonly list: Effect.Effect<ReadonlyArray<BrowserSessionRef>, 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>;
+};
+declare const Browser_base: Context.ServiceClass<Browser, "@betalyra/effect-uai/Browser", BrowserService>;
+declare class Browser extends Browser_base {}
+/**
+ * Provision a session bound to the caller's scope. Drop the `Scope.Scope`
+ * requirement with `Effect.scoped`.
+ */
+declare const create: (request: CommonSessionRequest) => Effect.Effect<BrowserSession, BrowserError, Browser | Scope.Scope>;
+/**
+ * Re-acquire an existing session by id. Same scope semantics as `create`,
+ * but the finalizer detaches rather than destroying.
+ */
+declare const attach: (id: BrowserSessionId) => Effect.Effect<BrowserSession, BrowserError, Browser | Scope.Scope>;
+/** Enumerate sessions for the configured account / project. */
+declare const list: Effect.Effect<ReadonlyArray<BrowserSessionRef>, BrowserError, Browser>;
+/**
+ * Destroy a session from outside its owning scope. Most callers should let
+ * the scope finalizer handle this automatically.
+ */
+declare const destroy: (id: BrowserSessionId) => Effect.Effect<void, BrowserError, Browser>;
+//#endregion
+export { AxNode, BoundingBox, Browser, BrowserService, BrowserSession, BrowserSessionId, BrowserSessionRef, CommonSessionRequest, Cookie, CookieApi, ElementInfo, PageFormat, ScreenshotOptions, ScrollDirection, ScrollOptions, attach, create, destroy, list, Browser_d_exports as t };
+//# sourceMappingURL=Browser.d.mts.map

package/dist/browser/Browser.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Browser.d.mts","names":[],"sources":["../../src/browser/Browser.ts"],"mappings":"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"}

package/dist/browser/Browser.mjs

@@ -0,0 +1,34 @@
+import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
+import { Brand, Context, Effect } from "effect";
+//#region src/browser/Browser.ts
+var Browser_exports = /* @__PURE__ */ __exportAll({
+	Browser: () => Browser,
+	BrowserSessionId: () => BrowserSessionId,
+	attach: () => attach,
+	create: () => create,
+	destroy: () => destroy,
+	list: () => list
+});
+const BrowserSessionId = Brand.nominal();
+var Browser = class extends Context.Service()("@betalyra/effect-uai/Browser") {};
+/**
+* Provision a session bound to the caller's scope. Drop the `Scope.Scope`
+* requirement with `Effect.scoped`.
+*/
+const create = (request) => 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.
+*/
+const attach = (id) => Effect.flatMap(Browser.asEffect(), (s) => s.attach(id));
+/** Enumerate sessions for the configured account / project. */
+const list = 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.
+*/
+const destroy = (id) => Effect.flatMap(Browser.asEffect(), (s) => s.destroy(id));
+//#endregion
+export { Browser, BrowserSessionId, attach, create, destroy, list, Browser_exports as t };
+
+//# sourceMappingURL=Browser.mjs.map

package/dist/browser/Browser.mjs.map

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

package/dist/browser/BrowserError.d.mts

@@ -0,0 +1,141 @@
+import { Duration } from "effect";
+import * as _$effect_Cause0 from "effect/Cause";
+import * as _$effect_Types0 from "effect/Types";
+
+//#region src/browser/BrowserError.d.ts
+declare namespace BrowserError_d_exports {
+  export { BrowserActionFailed, BrowserAuthFailed, BrowserAuthSubtype, BrowserCreateFailed, BrowserError, BrowserInvalidRequest, BrowserQuotaExceeded, BrowserSessionExpired, BrowserSessionNotFound, BrowserTimeout, BrowserUnsupported, describe };
+}
+declare const BrowserCreateFailed_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserCreateFailed";
+} & Readonly<A>;
+/**
+ * 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`.
+ */
+declare class BrowserCreateFailed extends BrowserCreateFailed_base<{
+  provider: string;
+  reason?: string;
+  raw: unknown;
+}> {}
+declare const BrowserSessionNotFound_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserSessionNotFound";
+} & Readonly<A>;
+/**
+ * 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.
+ */
+declare class BrowserSessionNotFound extends BrowserSessionNotFound_base<{
+  provider: string;
+  id: string;
+}> {}
+declare const BrowserSessionExpired_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserSessionExpired";
+} & Readonly<A>;
+/**
+ * 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).
+ */
+declare class BrowserSessionExpired extends BrowserSessionExpired_base<{
+  provider: string;
+  id: string;
+}> {}
+declare const BrowserTimeout_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserTimeout";
+} & Readonly<A>;
+/**
+ * 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.
+ */
+declare class BrowserTimeout extends BrowserTimeout_base<{
+  provider: string;
+  operation: "create" | "attach" | "navigate" | "action" | "query";
+  budget?: Duration.Duration;
+  raw?: unknown;
+}> {}
+declare const BrowserActionFailed_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserActionFailed";
+} & Readonly<A>;
+/**
+ * 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.
+ */
+declare class BrowserActionFailed extends BrowserActionFailed_base<{
+  provider: string;
+  operation: "navigate" | "interact" | "observe" | "evaluate" | "cookies";
+  selector?: string;
+  reason?: string;
+  raw: unknown;
+}> {}
+declare const BrowserQuotaExceeded_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserQuotaExceeded";
+} & Readonly<A>;
+/**
+ * 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.
+ */
+declare class BrowserQuotaExceeded extends BrowserQuotaExceeded_base<{
+  provider: string;
+  reason?: string;
+  raw: unknown;
+}> {}
+declare const BrowserInvalidRequest_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserInvalidRequest";
+} & Readonly<A>;
+/**
+ * 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.
+ */
+declare class BrowserInvalidRequest extends BrowserInvalidRequest_base<{
+  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.
+ */
+type BrowserAuthSubtype = "auth" | "permission" | "billing" | "quota";
+declare const BrowserAuthFailed_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserAuthFailed";
+} & Readonly<A>;
+declare class BrowserAuthFailed extends BrowserAuthFailed_base<{
+  provider: string;
+  subtype: BrowserAuthSubtype;
+  raw: unknown;
+}> {}
+declare const BrowserUnsupported_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "BrowserUnsupported";
+} & Readonly<A>;
+/**
+ * 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.
+ */
+declare class BrowserUnsupported extends BrowserUnsupported_base<{
+  provider: string;
+  capability: string;
+  reason?: string;
+}> {}
+type BrowserError = BrowserCreateFailed | BrowserSessionNotFound | BrowserSessionExpired | BrowserTimeout | BrowserActionFailed | BrowserQuotaExceeded | BrowserInvalidRequest | BrowserAuthFailed | BrowserUnsupported;
+/**
+ * Short human-readable description of an error, for logs and model-facing
+ * failure messages. Prose, not a contract; branch on `_tag` instead.
+ */
+declare const describe: (e: BrowserError) => string;
+//#endregion
+export { BrowserActionFailed, BrowserAuthFailed, BrowserAuthSubtype, BrowserCreateFailed, BrowserError, BrowserInvalidRequest, BrowserQuotaExceeded, BrowserSessionExpired, BrowserSessionNotFound, BrowserTimeout, BrowserUnsupported, describe, BrowserError_d_exports as t };
+//# sourceMappingURL=BrowserError.d.mts.map

package/dist/browser/BrowserError.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrowserError.d.mts","names":[],"sources":["../../src/browser/BrowserError.ts"],"mappings":";;;;;;;;cAA8C,wBAAA;;;;;;;;;cAQjC,mBAAA,SAA4B,wBAAA;EACvC,QAAA;EACA,MAAA;EACA,GAAA;AAAA;AAAA,cACG,2BAAA;;;;AAZyC;;;;;cAoBjC,sBAAA,SAA+B,2BAAA;EAC1C,QAAA;EACA,EAAA;AAAA;AAAA,cACG,0BAAA;;;;;;;;;;cASQ,qBAAA,SAA8B,0BAAA;EACzC,QAAA;EACA,EAAA;AAAA;AAAA,cACG,mBAAA;;;;;;AA3BL;;cAkCa,cAAA,SAAuB,mBAAA;EAClC,QAAA;EACA,SAAA;EACA,MAAA,GAAS,QAAA,CAAS,QAAA;EAClB,GAAA;AAAA;AAAA,cACG,wBAAA;;;;;;;;;cAQQ,mBAAA,SAA4B,wBAAA;EACvC,QAAA;EACA,SAAA;EACA,QAAA;EACA,MAAA;EACA,GAAA;AAAA;AAAA,cACG,yBAAA;;;;;;;;cAOQ,oBAAA,SAA6B,yBAAA;EACxC,QAAA;EACA,MAAA;EACA,GAAA;AAAA;AAAA,cACG,0BAAA;;;;;;;;cAOQ,qBAAA,SAA8B,0BAAA;EACzC,QAAA;EACA,KAAA;EACA,MAAA;EACA,GAAA;AAAA;;;;;KAOU,kBAAA;AAAA,cAAgE,sBAAA;;;cAE/D,iBAAA,SAA0B,sBAAA;EACrC,QAAA;EACA,OAAA,EAAS,kBAAA;EACT,GAAA;AAAA;AAAA,cACG,uBAAA;;;;;;;;cAOQ,kBAAA,SAA2B,uBAAA;EACtC,QAAA;EACA,UAAA;EACA,MAAA;AAAA;AAAA,KAGU,YAAA,GACR,mBAAA,GACA,sBAAA,GACA,qBAAA,GACA,cAAA,GACA,mBAAA,GACA,oBAAA,GACA,qBAAA,GACA,iBAAA,GACA,kBAAA;;;;;cASS,QAAA,GAAW,CAAA,EAAG,YAAA"}