@effect-uai/core 0.9.0 → 0.11.0

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),
+  }),
+)

package/src/browser/BrowserTool.ts

@@ -0,0 +1,161 @@
+import { Effect, Schema } from "effect"
+import * as Tool from "../tool/Tool.js"
+import * as Toolkit from "../tool/Toolkit.js"
+import type { BrowserSession } from "./Browser.js"
+
+// ---------------------------------------------------------------------------
+// Model-facing argument schemas. Annotated so the descriptions reach the
+// model through the rendered JSON Schema (JSDoc does not).
+// ---------------------------------------------------------------------------
+
+const GotoArgs = Schema.Struct({
+  url: Schema.String.annotate({ description: "Absolute URL to navigate to." }),
+})
+
+const ClickArgs = Schema.Struct({
+  ref: Schema.String.annotate({
+    description: "A CSS selector, or an element @ref if a page-reading tool provides one.",
+  }),
+})
+
+const FillArgs = Schema.Struct({
+  ref: Schema.String.annotate({
+    description: "A CSS selector (or element @ref) of the input to fill.",
+  }),
+  text: Schema.String.annotate({ description: "The text to put in the input." }),
+})
+
+const PressArgs = Schema.Struct({
+  key: Schema.String.annotate({
+    description: 'Key to press, e.g. "Enter" to submit the focused input, "Tab", "Escape".',
+  }),
+})
+
+const ScrollArgs = Schema.Struct({
+  direction: Schema.Literals(["up", "down"]).annotate({
+    description: "Scroll the viewport up or down.",
+  }),
+})
+
+// ---------------------------------------------------------------------------
+// Uniform action outcome: the model always learns where the action left it.
+// ---------------------------------------------------------------------------
+
+const currentUrl = (session: BrowserSession): Effect.Effect<string> =>
+  session.evaluate("location.href").pipe(
+    Effect.flatMap(Schema.decodeUnknownEffect(Schema.String)),
+    Effect.orElseSucceed(() => "(unknown)"),
+  )
+
+const okAt = (session: BrowserSession): Effect.Effect<string> =>
+  Effect.map(currentUrl(session), (url) => `ok (now at ${url})`)
+
+// ---------------------------------------------------------------------------
+// The canonical browser action tools, each closed over a live `BrowserSession`
+// and failing with the full `BrowserError`. `Output` is a compact outcome
+// (`ok (now at <url>)`), not a page dump - a page-reading tool is the recipe's
+// to define, so history does not accumulate a full page per action.
+//
+// A failed action (stale ref, dead control, timeout) fails typed on the error
+// channel. Whether the model gets to recover from it is the loop's decision:
+// wrap the toolkit in `Toolkit.describeFailures(BrowserError.describe)` to
+// surface failures to the model, or map selectively to keep session/infra
+// errors (e.g. `BrowserSessionExpired`) fatal.
+//
+// Browser actions are order-dependent (fill, then press Enter): run a turn's
+// calls with `{ concurrency: 1 }`.
+// ---------------------------------------------------------------------------
+
+export const gotoTool = (session: BrowserSession) =>
+  Tool.make({
+    name: "browser_goto",
+    description: "Navigate the browser to an absolute URL.",
+    inputSchema: Tool.fromEffectSchema(GotoArgs),
+    run: (args) =>
+      Effect.andThen(session.goto(args.url), okAt(session)).pipe(
+        Effect.withSpan("browser_goto", {
+          kind: "client",
+          attributes: { "browser.url": args.url },
+        }),
+      ),
+  })
+
+export const clickTool = (session: BrowserSession) =>
+  Tool.make({
+    name: "browser_click",
+    description: "Click the element named by ref. A click may navigate to a new page.",
+    inputSchema: Tool.fromEffectSchema(ClickArgs),
+    run: (args) =>
+      Effect.andThen(session.click(args.ref), okAt(session)).pipe(
+        Effect.withSpan("browser_click", {
+          kind: "client",
+          attributes: { "browser.ref": args.ref },
+        }),
+      ),
+  })
+
+export const fillTool = (session: BrowserSession) =>
+  Tool.make({
+    name: "browser_fill",
+    description:
+      "Put text into the input named by ref. Filling alone does not submit; press Enter to submit the input.",
+    inputSchema: Tool.fromEffectSchema(FillArgs),
+    run: (args) =>
+      Effect.andThen(session.fill(args.ref, args.text), okAt(session)).pipe(
+        Effect.withSpan("browser_fill", {
+          kind: "client",
+          attributes: { "browser.ref": args.ref },
+        }),
+      ),
+  })
+
+export const pressTool = (session: BrowserSession) =>
+  Tool.make({
+    name: "browser_press",
+    description: "Press a keyboard key against the focused element.",
+    inputSchema: Tool.fromEffectSchema(PressArgs),
+    run: (args) =>
+      Effect.andThen(session.press(args.key), okAt(session)).pipe(
+        Effect.withSpan("browser_press", {
+          kind: "client",
+          attributes: { "browser.key": args.key },
+        }),
+      ),
+  })
+
+export const scrollTool = (session: BrowserSession) =>
+  Tool.make({
+    name: "browser_scroll",
+    description:
+      "Scroll the viewport. Only useful to bring an element into view - a page-reading tool's text is already scroll-independent.",
+    inputSchema: Tool.fromEffectSchema(ScrollArgs),
+    run: (args) =>
+      Effect.andThen(session.scroll({ direction: args.direction }), okAt(session)).pipe(
+        Effect.withSpan("browser_scroll", {
+          kind: "client",
+          attributes: { "browser.direction": args.direction },
+        }),
+      ),
+  })
+
+/**
+ * The canonical browser action verbs bundled as a `Toolkit`, closed over a
+ * live `BrowserSession`. Compose it with a recipe-local page-reading tool and
+ * whatever finish/signal tools the agent needs:
+ *
+ *   const toolkit = yield* Toolkit.compose(
+ *     browserToolkit(session),
+ *     Toolkit.make(readPageTool(session), finishTool),
+ *   )
+ *
+ * For an à-la-carte subset, use the individual `gotoTool` / `clickTool` / …
+ * constructors directly. Run a turn's calls with `{ concurrency: 1 }`.
+ */
+export const browserToolkit = (session: BrowserSession) =>
+  Toolkit.make(
+    gotoTool(session),
+    clickTool(session),
+    fillTool(session),
+    pressTool(session),
+    scrollTool(session),
+  )

package/src/domain/AiError.ts

@@ -1,4 +1,4 @@
-import { Data, Duration } from "effect"
+import { Data, Duration, Match } from "effect"
 
 export type Scope = "rpm" | "tpm" | "rpd" | "tpd"
 
@@ -112,3 +112,29 @@ export type AiError =
   | IncompleteTurn
   | GenerationFailed
   | Unsupported
+
+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: AiError) => string = Match.type<AiError>().pipe(
+  Match.discriminatorsExhaustive("_tag")({
+    RateLimited: (e) => `rate limited by ${e.provider}; try again later`,
+    Unavailable: (e) => `${e.provider} is temporarily unavailable`,
+    Timeout: (e) => `the ${e.provider} request timed out`,
+    ContentFiltered: (e) => withReason(`blocked by ${e.provider}'s content filter`, e.reason),
+    ContextLengthExceeded: (e) => `the request exceeded ${e.provider}'s context limit`,
+    InvalidRequest: (e) =>
+      e.param === undefined
+        ? `${e.provider} rejected the request`
+        : `${e.provider} rejected the request (param: ${e.param})`,
+    AuthFailed: (e) => `authentication against ${e.provider} failed (${e.subtype})`,
+    Cancelled: (e) => `the ${e.provider} request was cancelled`,
+    IncompleteTurn: () => "the provider stream ended without completing",
+    GenerationFailed: (e) => e.message ?? `${e.provider} failed mid-generation`,
+    Unsupported: (e) => withReason(`${e.provider} does not support ${e.capability}`, e.reason),
+  }),
+)

package/src/domain/Citation.ts

@@ -0,0 +1,64 @@
+import type { DateTime } from "effect"
+
+// ---------------------------------------------------------------------------
+// Source
+// ---------------------------------------------------------------------------
+
+/**
+ * A document the model consulted. `url` and `title` are the only
+ * near-universal fields; the rest is best-effort. `raw` round-trips
+ * provider-opaque tokens (encrypted indices, chunk handles, document ids) so
+ * nothing is lost.
+ */
+export type Source = {
+  readonly url: string
+  readonly title?: string
+  readonly snippet?: string
+  readonly publishedDate?: DateTime.DateTime
+  readonly sourceType?: "web" | "x" | "news" | "file" | "document" | (string & {})
+  readonly raw?: unknown
+}
+
+// ---------------------------------------------------------------------------
+// Span
+// ---------------------------------------------------------------------------
+
+/**
+ * Where in the answer a claim is grounded, and which sources ground it.
+ * `sourceRefs` indexes into the sibling {@link Citations.sources} array
+ * (many-to-one). The four kinds normalize how providers link answer text to
+ * sources: a character / byte offset range, an exact source quote, a
+ * positional `[n]` marker, or `none` for a bare source with no anchor.
+ */
+export type CitationSpan =
+  | {
+      readonly kind: "char"
+      readonly start: number
+      readonly end: number
+      readonly unit: "char" | "byte"
+      readonly sourceRefs: ReadonlyArray<number>
+      readonly confidence?: number
+    }
+  | { readonly kind: "quote"; readonly text: string; readonly sourceRefs: ReadonlyArray<number> }
+  | {
+      readonly kind: "marker"
+      readonly ordinal: number
+      readonly sourceRefs: ReadonlyArray<number>
+    }
+  | { readonly kind: "none"; readonly sourceRefs: ReadonlyArray<number> }
+
+// ---------------------------------------------------------------------------
+// Citations
+// ---------------------------------------------------------------------------
+
+/**
+ * The grounding for a piece of generated text: the sources consulted, and the
+ * spans that reference them. This is the canonical, provider-agnostic form.
+ * The flat `Items.Annotation` array is its degenerate view (one `char` span
+ * with one inlined source), used where a wire-attached, per-`output_text`
+ * shape is enough.
+ */
+export type Citations = {
+  readonly sources: ReadonlyArray<Source>
+  readonly spans: ReadonlyArray<CitationSpan>
+}

package/src/domain/Items.ts

@@ -27,16 +27,26 @@ export type InputImage = typeof InputImage.Type
 
 // ---------------------------------------------------------------------------
 // Annotations - source / citation pointers attached to `output_text` blocks.
-// Mirrors OpenAI Responses API; other providers can omit or map onto these
-// shapes.
+// Provider-agnostic: each provider populates the fields it has (character
+// span, quote, or positional marker) and omits the rest.
 // ---------------------------------------------------------------------------
 
+/**
+ * A cited source. `url` + `title` are the only near-universal fields; the
+ * link from a source to the answer text varies by provider, so it is optional
+ * and expressed three ways: `start_index`/`end_index` (a character span into
+ * the answer), `cited_text` (an exact quote of the source, when no offsets are
+ * given), or `marker` (a positional `[n]` reference into an ordered list). A
+ * provider populates whichever it has; a bare source list sets none.
+ */
 export const UrlCitation = Schema.Struct({
   type: Schema.Literal("url_citation"),
   url: Schema.String,
-  start_index: Schema.Number,
-  end_index: Schema.Number,
   title: Schema.String,
+  start_index: Schema.optional(Schema.Number),
+  end_index: Schema.optional(Schema.Number),
+  cited_text: Schema.optional(Schema.String),
+  marker: Schema.optional(Schema.Number),
 })
 export type UrlCitation = typeof UrlCitation.Type
 

package/src/domain/Research.ts

@@ -0,0 +1,42 @@
+import type * as Job from "../job/Job.js"
+import type * as Items from "./Items.js"
+import type { Turn } from "./Turn.js"
+
+// ---------------------------------------------------------------------------
+// Request
+// ---------------------------------------------------------------------------
+
+/**
+ * Cross-provider deep-research request: a question in, a cited report out.
+ * Deliberately minimal, only the input every provider shares. Depth, search
+ * caps, and structured-output knobs vary too much to unify, so they live on
+ * each provider's typed request, which extends this and narrows `model`.
+ *
+ * `history` reuses the `LanguageModel` input primitive: the common case is a
+ * single user message with the question. There is no history threading. A
+ * research call is one background job, not a conversation, but the input
+ * encoding is shared.
+ */
+export type ResearchRequest = {
+  readonly history: ReadonlyArray<Items.HistoryItem>
+  /** Model / agent id. Provider default if omitted; each provider narrows. */
+  readonly model?: string
+}
+
+// ---------------------------------------------------------------------------
+// Result + job handle
+// ---------------------------------------------------------------------------
+
+/**
+ * A completed research result is a `Turn`: one assistant message with the
+ * report text and its citations on `OutputText.annotations`, plus usage.
+ * Project it with `Turn.assistantText` / `Turn.citations` /
+ * `Turn.decodeStructured`. There is no bespoke report type; the streaming
+ * terminal (`TurnComplete.turn`) and the collected result are the same shape.
+ */
+
+/** Provider-tagged handle to a running research job, branded to `Turn`. */
+export type ResearchJobRef = Job.JobRef<Turn>
+
+/** Current state of a research job. See {@link Job.JobState}. */
+export type ResearchState = Job.JobState<Turn>

package/src/domain/Turn.ts

@@ -1,6 +1,7 @@
 import { Data, Effect, Result, Schema, Stream, pipe } from "effect"
 import * as StructuredFormat from "../structured-format/StructuredFormat.js"
 import {
+  type Annotation,
   HistoryItem,
   Message,
   Reasoning,
@@ -44,6 +45,14 @@ export type Turn = typeof Turn.Type
  * `UsageUpdate`: mid-stream cumulative usage. Anthropic emits this on
  * `message_start` and `message_delta`; other providers may only deliver
  * usage via `TurnComplete.turn.usage`.
+ *
+ * `WebSearchCall`: lifecycle of a provider-executed web search within the
+ * turn. Fires only when the turn grounds against search; absent otherwise.
+ *
+ * `CitationAdded`: a citation attached to the answer, emitted incrementally
+ * where the provider streams citations. Providers that bundle citations emit
+ * none of these; their citations still arrive on `TurnComplete.turn`
+ * (`OutputText.annotations`). Either way the final set is on the assembled turn.
  */
 export type TurnEvent = Data.TaggedEnum<{
   TextDelta: { readonly text: string }
@@ -52,6 +61,12 @@ export type TurnEvent = Data.TaggedEnum<{
   ToolCallStart: { readonly call_id: string; readonly name: string }
   ToolCallArgsDelta: { readonly call_id: string; readonly delta: string }
   UsageUpdate: { readonly usage: Usage }
+  WebSearchCall: {
+    readonly status: "started" | "searching" | "completed"
+    readonly query?: string
+    readonly action?: "search" | "open_page" | "find_in_page"
+  }
+  CitationAdded: { readonly annotation: Annotation }
   TurnComplete: { readonly turn: Turn }
 }>
 
@@ -94,6 +109,17 @@ export const assistantTexts = (turn: Turn): ReadonlyArray<string> =>
  */
 export const assistantText = (turn: Turn): string => assistantTexts(turn).join("")
 
+/**
+ * Every citation annotation attached to the turn's assistant `output_text`
+ * blocks, in order. The flat view of a grounded turn's sources, whether the
+ * turn came from a normal generation with native search or a deep-research job.
+ */
+export const citations = (turn: Turn): ReadonlyArray<Annotation> =>
+  assistantMessages(turn)
+    .flatMap((m) => m.content)
+    .filter(isOutputText)
+    .flatMap((b) => b.annotations ?? [])
+
 /**
  * Append a completed turn and optional follow-up items to a state record's
  * history. Recipes use this at the point where structured tool results are

package/src/embedding-model/EmbeddingModel.ts

@@ -108,13 +108,13 @@ export class EmbeddingModel extends Context.Service<EmbeddingModel, EmbeddingMod
 export const embed = <E extends EmbedEncoding | undefined = undefined>(
   request: Omit<CommonEmbedRequest, "encoding"> & { readonly encoding?: E },
 ): Effect.Effect<EmbedResponse<E>, AiError.AiError, EmbeddingModel> =>
-  Effect.flatMap(EmbeddingModel.asEffect(), (m) => m.embed(request))
+  Effect.flatMap(EmbeddingModel, (m) => m.embed(request))
 
 /** Embed a batch in one provider call. Same `task` for every input. */
 export const embedMany = <E extends EmbedEncoding | undefined = undefined>(
   request: Omit<CommonEmbedManyRequest, "encoding"> & { readonly encoding?: E },
 ): Effect.Effect<EmbedManyResponse<E>, AiError.AiError, EmbeddingModel> =>
-  Effect.flatMap(EmbeddingModel.asEffect(), (m) => m.embedMany(request))
+  Effect.flatMap(EmbeddingModel, (m) => m.embedMany(request))
 
 /**
  * Guard a requested `encoding` against a provider's supported set. Returns

package/src/index.ts

@@ -1,10 +1,17 @@
 export * as AiError from "./domain/AiError.js"
 export * as Audio from "./domain/Audio.js"
+export * as Browser from "./browser/Browser.js"
+export * as BrowserError from "./browser/BrowserError.js"
+export * as BrowserTool from "./browser/BrowserTool.js"
 export * as Capabilities from "./capabilities/Capabilities.js"
+export * as Citation from "./domain/Citation.js"
+export * as DeepResearch from "./research/DeepResearch.js"
 export * as Image from "./domain/Image.js"
 export * as Items from "./domain/Items.js"
+export * as Job from "./job/Job.js"
 export * as Media from "./domain/Media.js"
 export * as Music from "./domain/Music.js"
+export * as Research from "./domain/Research.js"
 export * as Transcript from "./domain/Transcript.js"
 export * as Turn from "./domain/Turn.js"
 export * as Embedding from "./embedding-model/Embedding.js"
@@ -18,6 +25,8 @@ export * as SandboxImage from "./sandbox/SandboxImage.js"
 export * as SandboxNetwork from "./sandbox/SandboxNetwork.js"
 export * as SpeechSynthesizer from "./speech-synthesizer/SpeechSynthesizer.js"
 export * as Transcriber from "./transcriber/Transcriber.js"
+export * as WebRead from "./web-read/WebRead.js"
+export * as WebReadTool from "./web-read/WebReadTool.js"
 export * as WebSearch from "./web-search/WebSearch.js"
 export * as WebSearchTool from "./web-search/WebSearchTool.js"
 export * as Vector from "./math/Vector.js"