@effect-uai/core 0.7.0 → 0.9.0

package/src/tool/Toolkit.ts

@@ -1,35 +1,306 @@
-import { Array as Arr, Effect, Function, Ref, Schema, Stream } from "effect"
+import {
+  Array as Arr,
+  Cause,
+  Data,
+  Effect,
+  Fiber,
+  Function,
+  Match,
+  Option,
+  Queue,
+  Record,
+  Ref,
+  Schema,
+  Stream,
+} from "effect"
 import * as Loop from "../loop/Loop.js"
-import type { ToolCall, HistoryItem } from "../domain/Items.js"
+import type { HistoryItem, ToolCall } from "../domain/Items.js"
 import { appendToHistory, type Turn } from "../domain/Turn.js"
 import {
+  type AnyLocalTool,
   type AnyTool,
-  type AnyPlainTool,
-  type AnyStreamingTool,
-  isStreamingTool,
-  type StreamingTool,
+  type Emit,
+  type InteractionTool,
+  type ProviderTool,
+  type SignalTool,
   type Tool,
+  type ToolDescriptor,
+  type ToolR,
+  toDescriptors,
 } from "./Tool.js"
-import { ToolResult, executionError, failed, toToolCallOutput } from "./ToolResult.js"
+import {
+  ToolResult,
+  executionError,
+  failed,
+  nonLocalTool,
+  toToolCallOutput,
+  validationError,
+} from "./ToolResult.js"
 import { ToolEvent } from "./ToolEvent.js"
 import { isOutput } from "./ToolEvent.js"
 
+// ---------------------------------------------------------------------------
+// Toolkit: a name-indexed record of tools — "what the model sees". The record
+// gives O(1) dispatch and within-toolkit name-uniqueness for free; descriptors
+// are derived, not stored. Build a static one with `make` (compile-time
+// duplicate-name check), a dynamic one with `fromArray` (trusted single source,
+// last-wins), and combine independent ones with `compose` (the application
+// boundary where cross-source names can clash).
+// ---------------------------------------------------------------------------
+
+export type ToolMap = Record<string, AnyTool>
+
+export type Toolkit<Tools extends ToolMap = ToolMap> = Tools
+
+const indexByName = (tools: ReadonlyArray<AnyTool>): ToolMap =>
+  Object.fromEntries(tools.map((tool) => [tool.name, tool]))
+
 /**
- * Union of every tool's `R` requirements in a mixed plain + streaming array.
- * Used by `run` to surface the services tools need at the recipe level, so
- * the loop's stream type carries them through to `Effect.provide`.
+ * Index literal tools by their `name`. Duplicate names are a compile error
+ * (`UniqueTools`). Names are not otherwise checked: a malformed name is a
+ * developer typo in a literal that the provider rejects clearly on first use,
+ * and there is no single cross-provider name rule to enforce here anyway.
  */
-export type ToolKindR<Tools extends ReadonlyArray<AnyTool<any>>> =
-  Tools[number] extends StreamingTool<any, any, any, any, infer R>
-    ? R
-    : Tools[number] extends Tool<any, any, any, infer R>
-      ? R
-      : never
+const buildStatic = <Tools extends ReadonlyArray<AnyTool>>(
+  tools: Tools,
+): Toolkit<{ [T in Tools[number] as T["name"]]: T }> =>
+  indexByName(tools) as Toolkit<{ [T in Tools[number] as T["name"]]: T }>
+
+export const make = <const Tools extends ReadonlyArray<AnyTool>>(
+  ...tools: UniqueTools<Tools>
+): Toolkit<{ [T in Tools[number] as T["name"]]: T }> => buildStatic(tools as unknown as Tools)
+
+/**
+ * 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`.
+ */
+export const fromArray = (tools: ReadonlyArray<AnyTool>): Toolkit => indexByName(tools)
+
+/** Render the provider-facing descriptors for a toolkit on demand. */
+export const descriptors = (toolkit: Toolkit): ReadonlyArray<ToolDescriptor> =>
+  toDescriptors(Object.values(toolkit))
+
+/**
+ * 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.
+ */
+export type ToolkitR<T extends Toolkit> = ToolMap extends T ? never : ToolR<T[keyof T]>
 
 // ---------------------------------------------------------------------------
-// Tool executor. Streams `ToolEvent`s in real time and dispatches streaming
-// and plain tools uniformly. Policy stays outside this module: callers pass
-// only the calls they have already decided should run.
+// Uniqueness & composition. `make` rejects duplicate literal names at compile
+// time; `compose` rejects cross-source collisions — at compile time when the
+// names are statically known, and at runtime (`DuplicateToolName`) for dynamic
+// sources whose keys are only `string`. No silent last-wins overwrite, no late
+// provider 400.
+// ---------------------------------------------------------------------------
+
+// --- compile-time duplicate detection --------------------------------------
+
+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}`
+}
+
+export 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`. */
+export type UniqueTools<Tools extends ReadonlyArray<AnyTool>> = Tools & NoDuplicateNames<Tools>
+
+// Cross-toolkit literal-key collision, skipping wide (`string`-keyed, dynamic)
+// toolkits so the compile-time check never false-positives on `fromArray`.
+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
+
+// --- uniqueness error ------------------------------------------------------
+
+/**
+ * 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.
+ */
+export class DuplicateToolName extends Data.TaggedError("DuplicateToolName")<{
+  readonly name: string
+  readonly sources: ReadonlyArray<string>
+}> {}
+
+// --- namespacing -----------------------------------------------------------
+
+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`.
+ */
+export const namespace = <const Prefix extends string, const T extends ToolMap>(
+  prefix: Prefix,
+  toolkit: Toolkit<T>,
+): Toolkit<Namespaced<Prefix, T>> => {
+  const renamed = Arr.map(Record.values(toolkit), (tool) => ({
+    ...tool,
+    name: `${prefix}__${tool.name}`,
+  }))
+  return indexByName(renamed) as Toolkit<Namespaced<Prefix, T>>
+}
+
+/** `namespace(prefix, make(...tools))` in one step, for static namespaced tools. */
+export 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 }>> =>
+  namespace(prefix, buildStatic(tools as unknown as Tools))
+
+// --- composition (the application boundary) --------------------------------
+
+/**
+ * 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.
+ */
+export const compose = <const Kits extends ReadonlyArray<Toolkit>>(
+  ...toolkits: Kits & NoDuplicateComposedKeys<Kits>
+): Effect.Effect<Toolkit<Composed<Kits>>, DuplicateToolName> =>
+  Effect.gen(function* () {
+    const kits = toolkits as unknown as ReadonlyArray<Toolkit>
+    const labelled = Arr.flatMap(kits, (kit, i) =>
+      Arr.map(Record.keys(kit), (name) => ({ name, source: `toolkit-${i}` })),
+    )
+    const collision = Arr.findFirst(
+      Record.toEntries(Arr.groupBy(labelled, (entry) => entry.name)),
+      ([, group]) => group.length > 1,
+    )
+    if (Option.isSome(collision)) {
+      const [name, group] = collision.value
+      return yield* new DuplicateToolName({ name, sources: Arr.map(group, (e) => e.source) })
+    }
+    return Arr.reduce(kits, {} as ToolMap, (acc, kit) => ({ ...acc, ...kit })) as Toolkit<
+      Composed<Kits>
+    >
+  })
+
+// ---------------------------------------------------------------------------
+// Middleware: a `Toolkit -> Toolkit` transform applied up front, then the
+// wrapped toolkit is run. A middleware transforms one local tool's `run` given
+// its name (logging, retry, auth, metrics); `wrap` lifts it over the whole
+// toolkit, leaving provider/signal/interaction kinds untouched. The one reason
+// this is a combinator rather than native `Record.map`: it tracks the
+// middleware's added requirement `R2`, unioning it into `ToolkitR` instead of
+// widening every tool's type.
+// ---------------------------------------------------------------------------
+
+type Handler<Input, Event, Output, R> = (
+  input: Input,
+  emit: Emit<Event>,
+) => Effect.Effect<Output, unknown, R>
+
+export type Middleware<R2 = never> = <Input, Event, Output, R>(
+  run: Handler<Input, Event, Output, R>,
+  name: string,
+) => Handler<Input, Event, Output, R | R2>
+
+type WrapTool<T extends AnyTool, R2> =
+  T extends Tool<infer N, infer I, infer Ev, infer O, infer R> ? Tool<N, I, Ev, O, R | R2> : T
+
+type WrapToolkit<T extends ToolMap, R2> = {
+  readonly [K in keyof T]: T[K] extends AnyTool ? WrapTool<T[K], R2> : 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`:
+ *
+ *   const observed = pipe(toolkit, Toolkit.wrap(logging), Toolkit.wrap(authz))
+ *   Toolkit.run(observed, calls) // R = ToolkitR<typeof toolkit> | <authz R>
+ *
+ * A middleware that `Effect.fail`s surfaces as a `ToolResult.Failure` from the
+ * executor like any run failure; use the `Approval` flow for a distinct
+ * "denied" verdict.
+ */
+export const wrap: {
+  <R2>(middleware: Middleware<R2>): <T extends Toolkit>(toolkit: T) => WrapToolkit<T, R2>
+  <T extends Toolkit, R2>(toolkit: T, middleware: Middleware<R2>): WrapToolkit<T, R2>
+} = Function.dual(
+  2,
+  <T extends Toolkit, R2>(toolkit: T, middleware: Middleware<R2>): WrapToolkit<T, R2> =>
+    Record.map(toolkit, (tool) =>
+      tool._tag === "LocalTool" ? { ...tool, run: middleware(tool.run, tool.name) } : tool,
+    ) as WrapToolkit<T, R2>,
+)
+
+// ---------------------------------------------------------------------------
+// Tool executor. Streams `ToolEvent`s in real time. Policy stays outside this
+// module: callers pass only the calls they have already decided should run.
 // ---------------------------------------------------------------------------
 
 export type ExecuteOptions = {
@@ -37,69 +308,40 @@ export type ExecuteOptions = {
 }
 
 /** Execute every provided call. Approval/rejection policy belongs upstream. */
-export const run = <Tools extends ReadonlyArray<AnyTool<any>>>(
-  tools: Tools,
+export const run = <T extends Toolkit>(
+  toolkit: T,
   calls: ReadonlyArray<ToolCall>,
   options?: ExecuteOptions,
-): Stream.Stream<ToolEvent, never, ToolKindR<Tools>> =>
+): Stream.Stream<ToolEvent, never, ToolkitR<T>> =>
   Stream.fromIterable(calls).pipe(
-    Stream.flatMap((call) => runOne(tools, call), {
+    Stream.flatMap((call) => runOne(toolkit, call), {
       concurrency: options?.concurrency ?? "unbounded",
     }),
-  )
+  ) as Stream.Stream<ToolEvent, never, ToolkitR<T>>
 
 const okResult = (call: ToolCall, tool: string, value: unknown): ToolResult =>
-  ToolResult.Ok({
-    call_id: call.call_id,
-    tool,
-    value,
-  })
+  ToolResult.Ok({ call_id: call.call_id, tool, value })
 
-const runOne = <R>(
-  tools: ReadonlyArray<AnyTool<R>>,
-  call: ToolCall,
-): Stream.Stream<ToolEvent, never, R> => {
-  const tool = tools.find((t) => t.name === call.name)
-  if (tool === undefined) {
-    // Graceful: emit a synthetic Failure so OTHER calls in this turn
-    // still execute. LLMs hallucinate tool names; MCP tools come and go.
-    return Stream.succeed(
-      ToolEvent.Output({
-        result: failed(call, "unknown_tool", `No tool registered with name "${call.name}"`),
-      }),
-    )
-  }
-  if (isStreamingTool(tool)) return runStreaming(tool, call)
-  return runPlain(tool, call)
-}
+const outputEvent = (result: ToolResult): Stream.Stream<ToolEvent, never, any> =>
+  Stream.succeed(ToolEvent.Output({ result }))
 
-const parseJsonUnknown = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown))
-
-const runPlain = <R>(tool: AnyPlainTool<R>, call: ToolCall): Stream.Stream<ToolEvent, never, R> =>
-  Stream.fromEffect(
-    Effect.gen(function* () {
-      const parsed = yield* parseJsonUnknown(call.arguments).pipe(
-        Effect.mapError(() => "json_parse_error" as const),
-      )
-      const validated = yield* Effect.tryPromise({
-        try: () => Promise.resolve(tool.inputSchema["~standard"].validate(parsed)),
-        catch: () => "validation_threw" as const,
-      })
-      if (validated.issues !== undefined) {
-        return executionError(call, "Tool input failed schema validation")
-      }
-      const output = yield* tool.run(validated.value)
-      return okResult(call, tool.name, output)
-    }).pipe(
-      Effect.catchCause(() => Effect.succeed(executionError(call, "Tool execution failed"))),
-      Effect.map((result) => ToolEvent.Output({ result })),
+const runOne = (toolkit: ToolMap, call: ToolCall): Stream.Stream<ToolEvent, never, any> =>
+  Match.value(toolkit[call.name]).pipe(
+    // No such tool. Graceful: emit a synthetic Failure so OTHER calls in this
+    // turn still execute. LLMs hallucinate tool names; MCP tools come and go.
+    Match.when(Match.undefined, () =>
+      outputEvent(failed(call, "unknown_tool", `No tool registered with name "${call.name}"`)),
     ),
+    Match.tag("LocalTool", (local) => runTool(local, call)),
+    // Provider/signal/interaction tools are model-visible but not locally
+    // executable. The loop is expected to intercept these (decode + act) before
+    // execution; reaching here means it didn't, so report it rather than crash.
+    Match.orElse(() => outputEvent(nonLocalTool(call))),
   )
 
-const runStreaming = <R>(
-  tool: AnyStreamingTool<R>,
-  call: ToolCall,
-): Stream.Stream<ToolEvent, never, R> =>
+const parseJsonUnknown = Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.Unknown))
+
+const runTool = (tool: AnyLocalTool, call: ToolCall): Stream.Stream<ToolEvent, never, any> =>
   Stream.unwrap(
     Effect.gen(function* () {
       const parsed = yield* parseJsonUnknown(call.arguments).pipe(
@@ -110,45 +352,40 @@ const runStreaming = <R>(
         catch: () => "validation_threw" as const,
       })
       if (validated.issues !== undefined) {
-        return Stream.succeed<ToolEvent>(
-          ToolEvent.Output({
-            result: executionError(call, "Tool input failed schema validation"),
-          }),
-        )
+        return Stream.succeed<ToolEvent>(ToolEvent.Output({ result: validationError(call) }))
       }
 
-      // Real-time: tap each event into a Ref as it flows; emit one
-      // Progress per event; then concat one synthetic Output element
-      // built from the accumulated Ref via `finalize`.
-      const ref = yield* Ref.make<Array<unknown>>([])
-      const progress = tool.run(validated.value).pipe(
-        Stream.tap((event) => Ref.update(ref, Arr.append(event))),
-        Stream.map((data) =>
-          ToolEvent.Progress({
-            call_id: call.call_id,
-            tool: tool.name,
-            data,
-          }),
-        ),
+      // Per-call queue: `emit` offers events as `run` produces them; the
+      // progress stream drains them in real time; `Queue.end` (in the
+      // `ensuring`) flushes pending events then signals a clean end, which
+      // `Stream.fromQueue` treats as completion. `Queue.shutdown` would clear
+      // queued items and interrupt pending takes — wrong for graceful teardown.
+      const queue = yield* Queue.make<unknown, Cause.Done>({ capacity: tool.emitBufferSize })
+      const emit = (event: unknown) => Effect.asVoid(Queue.offer(queue, event))
+      const fiber = yield* tool
+        .run(validated.value, emit)
+        .pipe(Effect.ensuring(Queue.end(queue)), Effect.forkScoped)
+
+      const progress = Stream.fromQueue(queue).pipe(
+        Stream.map((data) => ToolEvent.Progress({ call_id: call.call_id, tool: tool.name, data })),
       )
       const output = Stream.fromEffect(
-        Ref.get(ref).pipe(
-          Effect.map((events) =>
-            ToolEvent.Output({
-              result: okResult(call, tool.name, tool.finalize(events)),
-            }),
+        Fiber.join(fiber).pipe(
+          Effect.map((value) => ToolEvent.Output({ result: okResult(call, tool.name, value) })),
+          Effect.catchCause(() =>
+            Effect.succeed(
+              ToolEvent.Output({ result: executionError(call, "Tool execution failed") }),
+            ),
           ),
         ),
       )
       return progress.pipe(Stream.concat(output))
     }),
   ).pipe(
+    // Backstop for the input-parsing failures (`json_parse_error`,
+    // `validation_threw`) and any defect before the run fiber is forked.
     Stream.catchCause(() =>
-      Stream.succeed(
-        ToolEvent.Output({
-          result: executionError(call, "Tool execution failed"),
-        }),
-      ),
+      Stream.succeed(ToolEvent.Output({ result: executionError(call, "Tool execution failed") })),
     ),
   )
 
@@ -167,7 +404,7 @@ const runStreaming = <R>(
  * the results to wire-format `ToolCallOutput`s. Curried so it slots directly
  * into `continueWithResults`:
  *
- *   Toolkit.run(tools, calls).pipe(
+ *   Toolkit.run(toolkit, calls).pipe(
  *     Toolkit.continueWithResults(Toolkit.appendToolResults(state, turn)),
  *   )
  *

package/src/web-search/WebSearch.ts

@@ -0,0 +1,150 @@
+import { Context, type DateTime, Effect, Schema } from "effect"
+import type * as AiError from "../domain/AiError.js"
+
+// ---------------------------------------------------------------------------
+// Recency
+// ---------------------------------------------------------------------------
+
+/**
+ * Convenience freshness enum shared by every provider. A coarse "published
+ * within the last …" filter that maps onto each provider's native recency
+ * knob (Perplexity `search_recency_filter`, Brave `freshness`, Tavily
+ * `time_range`, You.com `freshness`), or onto a computed published-date
+ * range where a provider has no enum (Exa).
+ *
+ * For a precise window use {@link CommonSearchRequest.startDate} /
+ * {@link CommonSearchRequest.endDate} instead; `recency` is the sugar for
+ * the common "past week / past month" case.
+ *
+ * Exposed as a `Schema` so {@link "../web-search/WebSearchTool".webSearchTool}
+ * can hand it straight to a model as a tool parameter; the
+ * {@link SearchRecency} type is derived from it.
+ */
+export const SearchRecency = Schema.Literals(["hour", "day", "week", "month", "year"])
+
+export type SearchRecency = typeof SearchRecency.Type
+
+// ---------------------------------------------------------------------------
+// Request
+// ---------------------------------------------------------------------------
+
+/**
+ * Cross-provider web-search request. A field earns a place here only if
+ * most of the supported providers honor it and a developer would expect it
+ * from a generic search interface; everything provider-specific (Exa
+ * `type`, Tavily `searchDepth`, Brave `goggles`, pagination `offset`,
+ * `safeSearch`, `topic`, …) lives on that provider's typed request.
+ *
+ * Note the one structural difference from `EmbeddingModel` /
+ * `Transcriber`: there is no `model`. None of the pure-`/search` endpoints
+ * take one - what looks model-shaped on a provider (Exa `type`, Tavily
+ * `searchDepth`) is a mode knob, so it stays on the provider-typed request.
+ */
+export type CommonSearchRequest = {
+  /** The search query. The one field every provider requires. */
+  readonly query: string
+  /**
+   * Upper bound on the number of results to return in this one call.
+   * Providers cap differently (Perplexity / Tavily / Brave at ~20, Exa /
+   * You.com at ~100); a value above a provider's cap is clamped by that
+   * provider. There is no common pagination - only two providers paginate
+   * and only shallowly, so `offset` is provider-typed.
+   */
+  readonly maxResults?: number
+  /** Restrict results to these domains (e.g. `["docs.foo.com"]`). */
+  readonly includeDomains?: ReadonlyArray<string>
+  /** Drop results from these domains. */
+  readonly excludeDomains?: ReadonlyArray<string>
+  /**
+   * Coarse freshness filter - see {@link SearchRecency}. Sugar over an
+   * explicit `startDate`; ignored where {@link startDate} is also set and
+   * the provider takes only one.
+   */
+  readonly recency?: SearchRecency
+  /** Published-after bound. The precise alternative to {@link recency}. */
+  readonly startDate?: DateTime.DateTime
+  /** Published-before bound. */
+  readonly endDate?: DateTime.DateTime
+  /** ISO 3166-1 alpha-2 country code to localize results (e.g. `"us"`). */
+  readonly country?: string
+  /** ISO 639-1 language code to bias results toward (e.g. `"en"`). */
+  readonly language?: string
+}
+
+// ---------------------------------------------------------------------------
+// Response
+// ---------------------------------------------------------------------------
+
+/**
+ * One normalized web-search hit. A flat record with optionals rather than a
+ * tagged union: the providers differ by *which fields are present*, not by
+ * *kind*. The provider's untouched result object is always on `raw`, so a
+ * caller holding a typed provider tag can recover anything not promoted
+ * here (`author`, `favicon`, multi-chunk `snippets[]`, …).
+ */
+export type SearchResult = {
+  /** Canonical result URL. Always present. */
+  readonly url: string
+  /** Result title / headline, when the provider returns one. */
+  readonly title?: string
+  /**
+   * Primary short excerpt - the one text field all providers return (under
+   * various wire names: `snippet`, `content`, `description`). The richer
+   * extract fields (`text`, `highlights`, `summary`) belong to the
+   * out-of-scope extract feature and stay on the provider-typed result.
+   */
+  readonly snippet?: string
+  /** Publication date, when the provider reports one. */
+  readonly publishedDate?: DateTime.DateTime
+  /**
+   * Relevance score, only from providers that rank (Exa, Tavily);
+   * `undefined` for providers that return an unscored list. Kept despite
+   * being non-universal because ranking is core to what a "search result"
+   * means - and `undefined` cleanly says "this backend doesn't score."
+   */
+  readonly score?: number
+  /** The provider-native result object, never lossy. */
+  readonly raw: unknown
+}
+
+export type SearchResponse = {
+  readonly results: ReadonlyArray<SearchResult>
+  /**
+   * The provider-native top-level response object. Cost / usage reporting
+   * is deliberately not modeled on this surface yet: providers disagree on
+   * both what (Exa returns USD, Tavily credits, Brave nothing in-body) and
+   * where (Brave reports cost in response headers), so it is deferred to the
+   * unified usage design (see plans/usage-tracking.md). Anything a provider
+   * reports survives here on `raw`.
+   */
+  readonly raw: unknown
+}
+
+// ---------------------------------------------------------------------------
+// Service + helper
+// ---------------------------------------------------------------------------
+
+/**
+ * The portable web-search surface: one operation, `search`. Pure search is
+ * the one thing every provider does, so - unlike `SpeechSynthesizer` /
+ * `Transcriber` - this capability needs no marker tags; every provider
+ * Layer can answer.
+ */
+export type WebSearchService = {
+  readonly search: (request: CommonSearchRequest) => Effect.Effect<SearchResponse, AiError.AiError>
+}
+
+/**
+ * Generic web-search service tag. Yield this for provider-portable code;
+ * yield a provider tag (`PerplexitySearch`, `ExaSearch`, …) when you need
+ * that provider's own knobs. A provider's `layer` registers both.
+ */
+export class WebSearch extends Context.Service<WebSearch, WebSearchService>()(
+  "@betalyra/effect-uai/WebSearch",
+) {}
+
+/** Run one web search against whichever provider Layer is in scope. */
+export const search = (
+  request: CommonSearchRequest,
+): Effect.Effect<SearchResponse, AiError.AiError, WebSearch> =>
+  Effect.flatMap(WebSearch.asEffect(), (s) => s.search(request))