@effect-uai/core 0.9.0 → 0.10.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/index.ts

@@ -1,5 +1,8 @@
 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 Image from "./domain/Image.js"
 export * as Items from "./domain/Items.js"
@@ -18,6 +21,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"

package/src/tool/Approval.test.ts

@@ -15,7 +15,13 @@ import { describe, expect, it } from "vitest"
 import * as Items from "../domain/Items.js"
 import { findUnansweredCalls, cancelAllPending, isReconciled } from "./HistoryCheck.js"
 import { type ToolResult, isFailure, isOk, toToolCallOutput } from "./ToolResult.js"
-import { type ApprovalMapEntry, type ApprovalDecision, fromMap, fromQueue } from "./Approval.js"
+import {
+  type ApprovalMapEntry,
+  type ApprovalDecision,
+  type Verdict,
+  fromMap,
+  fromQueue,
+} from "./Approval.js"
 import { fromEffectSchema, make as makeTool } from "./Tool.js"
 import { make as makeToolkit, run } from "./Toolkit.js"
 import { ToolEvent, isApprovalRequested, isProgress, isOutput } from "./ToolEvent.js"
@@ -249,6 +255,50 @@ describe("fromQueue + run", () => {
       reason: "too risky",
     })
   })
+
+  it("router retires per round, so sequential rounds over one queue both resolve", async () => {
+    // A verdict-per-round over one shared queue and scope. The old
+    // never-terminating router would still be alive for round 1 and steal
+    // round 2's verdict (not in its map), hanging round 2.
+    const decisions = await Effect.runPromise(
+      Effect.scoped(
+        Effect.gen(function* () {
+          const verdicts = yield* Queue.unbounded<Verdict>()
+          const round = (id: string) => [fc(id, "delete_database", { name: "prod" })]
+
+          const r1 = yield* fromQueue(isSensitive, verdicts)(round("c1"))
+          yield* Queue.offer(verdicts, { call_id: "c1", decision: "approve" })
+          const d1 = Array.from(yield* Stream.runCollect(r1.decisions))
+
+          const r2 = yield* fromQueue(isSensitive, verdicts)(round("c2"))
+          yield* Queue.offer(verdicts, { call_id: "c2", decision: "deny", reason: "no" })
+          const d2 = Array.from(yield* Stream.runCollect(r2.decisions))
+
+          return { d1, d2 }
+        }),
+      ),
+    )
+    expect(decisions.d1[0]).toMatchObject({ _tag: "Approved" })
+    expect(decisions.d2[0]).toMatchObject({ _tag: "Rejected", result: { kind: "denied" } })
+  })
+
+  it("timeout resolves an unanswered gated call as cancelled", async () => {
+    const decisions = await Effect.runPromise(
+      Effect.scoped(
+        Effect.gen(function* () {
+          const verdicts = yield* Queue.unbounded<Verdict>()
+          const { decisions } = yield* fromQueue(isSensitive, verdicts, { timeout: "10 millis" })([
+            fc("c1", "delete_database", { name: "prod" }),
+          ])
+          return Array.from(yield* Stream.runCollect(decisions))
+        }),
+      ),
+    )
+    expect(decisions[0]).toMatchObject({
+      _tag: "Rejected",
+      result: { _tag: "Failure", kind: "cancelled" },
+    })
+  })
 })
 
 // ---------------------------------------------------------------------------
@@ -313,7 +363,7 @@ describe("toToolCallOutput", () => {
     expect(JSON.parse(out.output)).toEqual({ count: 3 })
   })
 
-  it("round-trips a Failure result with reason", () => {
+  it("renders a Failure with reason as a nested error object", () => {
     const r: ToolResult = {
       _tag: "Failure",
       call_id: "c2",
@@ -322,10 +372,10 @@ describe("toToolCallOutput", () => {
       reason: "spam concern",
     }
     const out = toToolCallOutput(r)
-    expect(JSON.parse(out.output)).toEqual({ kind: "denied", reason: "spam concern" })
+    expect(JSON.parse(out.output)).toEqual({ error: { kind: "denied", message: "spam concern" } })
   })
 
-  it("round-trips a Failure result without reason (omits the field)", () => {
+  it("renders a Failure without reason (omits message)", () => {
     const r: ToolResult = {
       _tag: "Failure",
       call_id: "c3",
@@ -333,7 +383,7 @@ describe("toToolCallOutput", () => {
       kind: "cancelled",
     }
     const out = toToolCallOutput(r)
-    expect(JSON.parse(out.output)).toEqual({ kind: "cancelled" })
+    expect(JSON.parse(out.output)).toEqual({ error: { kind: "cancelled" } })
   })
 })
 

package/src/tool/Approval.ts

@@ -5,7 +5,7 @@
  * results must be returned to the model. Tool execution stays explicit at
  * the recipe boundary via `Toolkit.run`.
  */
-import { Data, Deferred, Effect, Queue, Scope, Stream } from "effect"
+import { Data, Deferred, type Duration, Effect, Queue, Ref, Scope, Stream } from "effect"
 import type { ToolCall } from "../domain/Items.js"
 import { type ToolResult, cancelled, denied } from "./ToolResult.js"
 import { ToolEvent } from "./ToolEvent.js"
@@ -53,13 +53,30 @@ export type Verdict = {
   readonly reason?: string
 }
 
+export type FromQueueOptions = {
+  /**
+   * Resolve any still-pending gated call as `cancelled` once this elapses,
+   * so a lost or never-sent verdict cannot hang the decisions stream
+   * forever. Omit to wait indefinitely.
+   */
+  readonly timeout?: Duration.Input
+}
+
 /**
  * Queue-backed approval planner. Safe calls are returned immediately in
  * `approved`; gated calls emit `ApprovalRequested` events and later produce
  * one `ApprovalDecision` when their matching verdict arrives.
+ *
+ * The verdict queue is a single-consumer transport: run one approval round
+ * at a time (the router retires once every gated call of the round is
+ * resolved). For overlapping rounds, use one queue per round.
  */
 export const fromQueue =
-  (predicate: (call: ToolCall) => boolean, verdicts: Queue.Dequeue<Verdict>) =>
+  (
+    predicate: (call: ToolCall) => boolean,
+    verdicts: Queue.Dequeue<Verdict>,
+    options?: FromQueueOptions,
+  ) =>
   (
     calls: ReadonlyArray<ToolCall>,
   ): Effect.Effect<
@@ -76,37 +93,65 @@ export const fromQueue =
       const approved = calls.filter((call) => !predicate(call))
 
       const entries = yield* Effect.forEach(gated, (call) =>
-        Deferred.make<Verdict>().pipe(Effect.map((d) => [call.call_id, d] as const)),
+        Deferred.make<ApprovalDecision>().pipe(Effect.map((d) => [call.call_id, d] as const)),
       )
-      const deferreds: ReadonlyMap<string, Deferred.Deferred<Verdict>> = new Map(entries)
-
-      // Router is forked into the surrounding Scope so it lives as long
-      // as the consumer is pulling events. Recipes typically supply the
-      // scope by wrapping the events construction in `Stream.unwrap`.
-      yield* Effect.forkScoped(
-        Effect.forever(
-          Effect.gen(function* () {
-            const v = yield* Queue.take(verdicts)
-            const d = deferreds.get(v.call_id)
-            if (d !== undefined) yield* Deferred.succeed(d, v)
-          }),
+      const deferreds: ReadonlyMap<string, Deferred.Deferred<ApprovalDecision>> = new Map(entries)
+      const callById: ReadonlyMap<string, ToolCall> = new Map(gated.map((c) => [c.call_id, c]))
+      const outstanding = yield* Ref.make(gated.length)
+
+      // Complete a deferred once; decrement only on the winning transition so
+      // a late verdict for an already-resolved call is a no-op.
+      const resolve = (call: ToolCall, decision: ApprovalDecision) =>
+        Deferred.succeed(deferreds.get(call.call_id)!, decision).pipe(
+          Effect.flatMap((won) => (won ? Ref.update(outstanding, (n) => n - 1) : Effect.void)),
+        )
+
+      // Router retires once every gated call is resolved (by verdict or
+      // timeout), so sequential rounds over one queue do not accumulate
+      // racing routers. Recursive + suspended: stack-safe, no imperative loop.
+      const route: Effect.Effect<void> = Effect.suspend(() =>
+        Ref.get(outstanding).pipe(
+          Effect.flatMap((n) =>
+            n <= 0
+              ? Effect.void
+              : Queue.take(verdicts).pipe(
+                  Effect.flatMap((v) => {
+                    const call = callById.get(v.call_id)
+                    return (
+                      call === undefined
+                        ? Effect.void
+                        : resolve(
+                            call,
+                            v.decision === "approve"
+                              ? approve(call)
+                              : reject(denied(call, v.reason)),
+                          )
+                    ).pipe(Effect.andThen(route))
+                  }),
+                ),
+          ),
         ),
       )
 
-      const decisions = Stream.fromIterable(gated).pipe(
-        Stream.flatMap(
-          (call) => {
-            const d = deferreds.get(call.call_id)!
-            return Stream.fromEffect(
-              Deferred.await(d).pipe(
-                Effect.map((v) =>
-                  v.decision === "approve" ? approve(call) : reject(denied(call, v.reason)),
+      if (gated.length > 0) {
+        yield* Effect.forkScoped(route)
+        if (options?.timeout !== undefined) {
+          yield* Effect.forkScoped(
+            Effect.sleep(options.timeout).pipe(
+              Effect.andThen(
+                Effect.forEach(gated, (call) =>
+                  resolve(call, reject(cancelled(call, "approval timed out"))),
                 ),
               ),
-            )
-          },
-          { concurrency: "unbounded" },
-        ),
+            ),
+          )
+        }
+      }
+
+      const decisions = Stream.fromIterable(gated).pipe(
+        Stream.flatMap((call) => Stream.fromEffect(Deferred.await(deferreds.get(call.call_id)!)), {
+          concurrency: "unbounded",
+        }),
       )
 
       const approvalRequests = Stream.fromIterable<ToolEvent>(gated.map(approvalRequested))