@effect-uai/core 0.10.0 → 0.11.0

package/src/browser/Browser.ts

@@ -240,7 +240,7 @@ export class Browser extends Context.Service<Browser, BrowserService>()(
 export const create = (
   request: CommonSessionRequest,
 ): Effect.Effect<BrowserSession, BrowserError.BrowserError, Browser | Scope.Scope> =>
-  Effect.flatMap(Browser.asEffect(), (s) => s.create(request))
+  Effect.flatMap(Browser, (s) => s.create(request))
 
 /**
  * Re-acquire an existing session by id. Same scope semantics as `create`,
@@ -249,14 +249,14 @@ export const create = (
 export const attach = (
   id: BrowserSessionId,
 ): Effect.Effect<BrowserSession, BrowserError.BrowserError, Browser | Scope.Scope> =>
-  Effect.flatMap(Browser.asEffect(), (s) => s.attach(id))
+  Effect.flatMap(Browser, (s) => s.attach(id))
 
 /** Enumerate sessions for the configured account / project. */
 export const list: Effect.Effect<
   ReadonlyArray<BrowserSessionRef>,
   BrowserError.BrowserError,
   Browser
-> = Effect.flatMap(Browser.asEffect(), (s) => s.list)
+> = Effect.flatMap(Browser, (s) => s.list)
 
 /**
  * Destroy a session from outside its owning scope. Most callers should let
@@ -265,4 +265,4 @@ export const list: Effect.Effect<
 export const destroy = (
   id: BrowserSessionId,
 ): Effect.Effect<void, BrowserError.BrowserError, Browser> =>
-  Effect.flatMap(Browser.asEffect(), (s) => s.destroy(id))
+  Effect.flatMap(Browser, (s) => s.destroy(id))

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

@@ -4,10 +4,14 @@ 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"

package/src/job/Job.ts

@@ -0,0 +1,125 @@
+import { Duration, Effect, Schedule } from "effect"
+import * as AiError from "../domain/AiError.js"
+
+// ---------------------------------------------------------------------------
+// Status + handle
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalized state of a provider-hosted background job. Implementors map their
+ * provider's status vocabulary onto these four states. The terminal states
+ * carry their payload: `Succeeded` the collected result, `Failed` an optional
+ * reason and the raw provider error. This mirrors the wire, where a single
+ * poll response returns both status and (when done) the result.
+ */
+export type JobState<A> =
+  | { readonly _tag: "Pending" }
+  | { readonly _tag: "Running" }
+  | { readonly _tag: "Succeeded"; readonly result: A }
+  | { readonly _tag: "Failed"; readonly reason?: string; readonly raw?: unknown }
+
+/** The two states that end a poll loop. */
+export const isSettled = <A>(
+  state: JobState<A>,
+): state is Extract<JobState<A>, { _tag: "Succeeded" | "Failed" }> =>
+  state._tag === "Succeeded" || state._tag === "Failed"
+
+declare const ResultType: unique symbol
+
+/**
+ * Opaque, provider-tagged handle to a running background job. Jobs can run for
+ * minutes and outlive a single process, so the handle is detachable: submit
+ * now, collect later. `provider` tags who owns `id`.
+ *
+ * Parameterized by the result type `A` it collects to, so a ref cannot be
+ * crossed between capabilities (a `JobRef<Turn>` is not a `JobRef<VideoResult>`).
+ * The brand is phantom: the runtime value is just `{ _tag, provider, id }`, so
+ * a ref stays plain serializable data for persistence across restarts.
+ */
+export type JobRef<A = unknown> = {
+  readonly _tag: "JobRef"
+  readonly provider: string
+  readonly id: string
+  readonly [ResultType]?: A
+}
+
+export const jobRef = <A = unknown>(provider: string, id: string): JobRef<A> => ({
+  _tag: "JobRef",
+  provider,
+  id,
+})
+
+// ---------------------------------------------------------------------------
+// Poll driver
+// ---------------------------------------------------------------------------
+
+/**
+ * The three wire operations a poll-based async job supplies. `run` / `collect`
+ * drive the submit -> poll -> settle cadence around them, so an implementor
+ * states only its provider calls, not the loop. `poll` returns the current
+ * `JobState`, carrying the result in `Succeeded`. Generic over the collected
+ * `Result`.
+ */
+export type JobOps<Result> = {
+  readonly submit: Effect.Effect<JobRef<Result>, AiError.AiError>
+  readonly poll: (ref: JobRef<Result>) => Effect.Effect<JobState<Result>, AiError.AiError>
+  readonly cancel: (ref: JobRef<Result>) => Effect.Effect<void, AiError.AiError>
+}
+
+export type JobConfig = {
+  /** Cadence between status fetches. Default 10 seconds, jittered. */
+  readonly pollInterval?: Duration.Input
+  /** Overall wait cap; exceeding it fails `Timeout`. Default 45 minutes. */
+  readonly timeout?: Duration.Input
+}
+
+const DEFAULT_POLL_INTERVAL: Duration.Input = "10 seconds"
+const DEFAULT_TIMEOUT: Duration.Input = "45 minutes"
+
+/**
+ * Poll `poll(ref)` on a jittered fixed cadence until the job settles, then
+ * return the result or fail `GenerationFailed`. Bounded by `timeout`, which
+ * fails `Timeout` if the job never settles. Takes the poll op alone (not the
+ * full `JobOps`) so a detached `collect(ref)` needs no submit-bound request.
+ */
+export const collect = <Result>(
+  poll: (ref: JobRef<Result>) => Effect.Effect<JobState<Result>, AiError.AiError>,
+  ref: JobRef<Result>,
+  config?: JobConfig,
+): Effect.Effect<Result, AiError.AiError> =>
+  poll(ref).pipe(
+    Effect.repeat({
+      schedule: Schedule.jittered(Schedule.spaced(config?.pollInterval ?? DEFAULT_POLL_INTERVAL)),
+      until: isSettled,
+    }),
+    Effect.flatMap((state) =>
+      state._tag === "Succeeded"
+        ? Effect.succeed(state.result)
+        : Effect.fail(
+            new AiError.GenerationFailed({
+              provider: ref.provider,
+              message: state._tag === "Failed" ? (state.reason ?? "job failed") : "job failed",
+              raw: state._tag === "Failed" ? (state.raw ?? ref) : ref,
+            }),
+          ),
+    ),
+    Effect.timeoutOrElse({
+      duration: config?.timeout ?? DEFAULT_TIMEOUT,
+      orElse: () => Effect.fail(new AiError.Timeout({ provider: ref.provider, raw: ref })),
+    }),
+  )
+
+/**
+ * Submit, then poll to completion. Best-effort cancels the server job if the
+ * caller interrupts (where the provider supports it). The one-call path; use
+ * `ops.submit` + `collect` directly for the detached case.
+ */
+export const run = <Result>(
+  ops: JobOps<Result>,
+  config?: JobConfig,
+): Effect.Effect<Result, AiError.AiError> =>
+  ops.submit.pipe(
+    Effect.flatMap((ref) =>
+      collect(ops.poll, ref, config).pipe(Effect.onInterrupt(() => Effect.ignore(ops.cancel(ref)))),
+    ),
+  )

package/src/language-model/LanguageModel.ts

@@ -65,7 +65,7 @@ export class LanguageModel extends Context.Service<LanguageModel, LanguageModelS
 export const streamTurn = (
   request: CommonRequest,
 ): Stream.Stream<TurnEvent, AiError.AiError, LanguageModel> =>
-  Stream.unwrap(Effect.map(LanguageModel.asEffect(), (m) => m.streamTurn(request)))
+  Stream.unwrap(Effect.map(LanguageModel, (m) => m.streamTurn(request)))
 
 /**
  * Drain a single turn and return the assembled `Turn`. Delegates to the
@@ -74,7 +74,7 @@ export const streamTurn = (
  * {@link turnFromStream}.
  */
 export const turn = (request: CommonRequest): Effect.Effect<Turn, AiError.AiError, LanguageModel> =>
-  Effect.flatMap(LanguageModel.asEffect(), (m) => m.turn(request))
+  Effect.flatMap(LanguageModel, (m) => m.turn(request))
 
 /**
  * Build a `turn` implementation from a `streamTurn` implementation.

package/src/music-generator/MusicGenerator.ts

@@ -94,13 +94,13 @@ export class MusicInteractiveSession extends Context.Service<MusicInteractiveSes
 export const generate = (
   request: CommonGenerateMusicRequest,
 ): Effect.Effect<GenerateResult, AiError.AiError, MusicGenerator> =>
-  Effect.flatMap(MusicGenerator.asEffect(), (s) => s.generate(request))
+  Effect.flatMap(MusicGenerator, (s) => s.generate(request))
 
 /** Prompt in, audio chunks out. */
 export const streamGeneration = (
   request: CommonStreamGenerateMusicRequest,
 ): Stream.Stream<AudioChunk, AiError.AiError, MusicGenerator> =>
-  Stream.unwrap(Effect.map(MusicGenerator.asEffect(), (s) => s.streamGeneration(request)))
+  Stream.unwrap(Effect.map(MusicGenerator, (s) => s.streamGeneration(request)))
 
 /**
  * Bidirectional generation. Dual-arity: pipeable (data-last) and
@@ -156,8 +156,8 @@ export const streamGenerationFrom: {
   > =>
     Stream.unwrap(
       Effect.gen(function* () {
-        const s = yield* MusicGenerator.asEffect()
-        yield* MusicInteractiveSession.asEffect()
+        const s = yield* MusicGenerator
+        yield* MusicInteractiveSession
         return s.streamGenerationFrom(input, request)
       }),
     ),

package/src/research/DeepResearch.ts

@@ -0,0 +1,137 @@
+import { Context, Effect, Stream } from "effect"
+import * as AiError from "../domain/AiError.js"
+import * as Job from "../job/Job.js"
+import type { ResearchJobRef, ResearchRequest, ResearchState } from "../domain/Research.js"
+import type { Turn } from "../domain/Turn.js"
+import { TurnEvent } from "../domain/Turn.js"
+
+export type { ResearchJobRef, ResearchRequest, ResearchState } from "../domain/Research.js"
+
+/**
+ * Deep research: submit a question, watch a long-running background job, collect
+ * one cited report. Every provider is modeled as a job (`submit` / `poll` /
+ * `cancel`), so the surface is uniform. The convenience derivations
+ * (`research` / `researchStream` / `collect` / `status`) are the same for every
+ * provider and are built once by {@link fromJob}, so an implementor states only
+ * its wire calls, never the poll loop.
+ *
+ * `research` is the blocking one-liner (submit then poll to the terminal `Turn`);
+ * `researchStream` forwards live progress as `TurnEvent`s, terminating in
+ * `TurnComplete` whose `turn` is the value `research` / `collect` return. The job
+ * ref is plain serializable data, so it can be persisted and collected from a
+ * later process where the provider's job is server-backed.
+ */
+export type DeepResearchServiceShape<Req> = {
+  readonly submit: (request: Req) => Effect.Effect<ResearchJobRef, AiError.AiError>
+  readonly status: (ref: ResearchJobRef) => Effect.Effect<ResearchState, AiError.AiError>
+  readonly collect: (ref: ResearchJobRef) => Effect.Effect<Turn, AiError.AiError>
+  readonly streamFrom: (ref: ResearchJobRef) => Stream.Stream<TurnEvent, AiError.AiError>
+  readonly cancel: (ref: ResearchJobRef) => Effect.Effect<void, AiError.AiError>
+  readonly research: (request: Req) => Effect.Effect<Turn, AiError.AiError>
+  readonly researchStream: (request: Req) => Stream.Stream<TurnEvent, AiError.AiError>
+}
+
+export type DeepResearchService = DeepResearchServiceShape<ResearchRequest>
+
+export class DeepResearch extends Context.Service<DeepResearch, DeepResearchService>()(
+  "@betalyra/effect-uai/DeepResearch",
+) {}
+
+// ---------------------------------------------------------------------------
+// fromJob: build the whole service from the three job ops (+ an optional real
+// live stream). The derivations are identical for every provider.
+// ---------------------------------------------------------------------------
+
+/** The wire ops a provider supplies. `streamFrom` is optional: poll-only jobs
+ *  get a synthesized stream ({@link synthesizedStream}) in its place. */
+export type ResearchJobOps<Req> = {
+  readonly submit: (request: Req) => Effect.Effect<ResearchJobRef, AiError.AiError>
+  readonly poll: (ref: ResearchJobRef) => Effect.Effect<ResearchState, AiError.AiError>
+  readonly cancel: (ref: ResearchJobRef) => Effect.Effect<void, AiError.AiError>
+  readonly streamFrom?: (ref: ResearchJobRef) => Stream.Stream<TurnEvent, AiError.AiError>
+}
+
+// A poll-only job has no event stream, so synthesize one: a leading "searching"
+// progress event, then the terminal `TurnComplete` off the poll loop. Honest
+// low-fidelity progress, not a fabricated per-search feed.
+const synthesizedStream = <Req>(
+  ops: ResearchJobOps<Req>,
+  ref: ResearchJobRef,
+  config?: Job.JobConfig,
+): Stream.Stream<TurnEvent, AiError.AiError> =>
+  Stream.concat(
+    Stream.make(TurnEvent.WebSearchCall({ status: "searching" })),
+    Stream.map(Stream.fromEffect(Job.collect(ops.poll, ref, config)), (turn) =>
+      TurnEvent.TurnComplete({ turn }),
+    ),
+  )
+
+/**
+ * Assemble a {@link DeepResearchServiceShape} from the job ops. `research` is
+ * `submit` then poll-to-settle (best-effort cancel on interrupt, via
+ * {@link Job.run}); `collect` / `status` are the detached equivalents;
+ * `researchStream` submits then attaches. Generic over the request type so a
+ * provider-typed tag keeps its narrowed `submit`. `config` tunes the poll
+ * cadence and overall timeout of every derived poll loop (see
+ * {@link Job.JobConfig} for the defaults).
+ */
+export const fromJob = <Req extends ResearchRequest>(
+  ops: ResearchJobOps<Req>,
+  config?: Job.JobConfig,
+): DeepResearchServiceShape<Req> => {
+  const streamFrom =
+    ops.streamFrom ?? ((ref: ResearchJobRef) => synthesizedStream(ops, ref, config))
+  return {
+    submit: ops.submit,
+    status: ops.poll,
+    collect: (ref) => Job.collect(ops.poll, ref, config),
+    cancel: ops.cancel,
+    streamFrom,
+    research: (request) =>
+      Job.run({ submit: ops.submit(request), poll: ops.poll, cancel: ops.cancel }, config),
+    researchStream: (request) => Stream.unwrap(Effect.map(ops.submit(request), streamFrom)),
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Top-level accessors over the generic tag. Portable code uses these; they
+// require only `DeepResearch` in `R`.
+// ---------------------------------------------------------------------------
+
+/** Submit and poll to the terminal `Turn`. Cancels the job on interrupt. */
+export const research = (
+  request: ResearchRequest,
+): Effect.Effect<Turn, AiError.AiError, DeepResearch> =>
+  Effect.flatMap(DeepResearch, (s) => s.research(request))
+
+/** Submit and forward live progress, terminating in `TurnComplete`. */
+export const researchStream = (
+  request: ResearchRequest,
+): Stream.Stream<TurnEvent, AiError.AiError, DeepResearch> =>
+  Stream.unwrap(Effect.map(DeepResearch, (s) => s.researchStream(request)))
+
+/** Submit a detached job and return its ref. */
+export const submit = (
+  request: ResearchRequest,
+): Effect.Effect<ResearchJobRef, AiError.AiError, DeepResearch> =>
+  Effect.flatMap(DeepResearch, (s) => s.submit(request))
+
+/** Current state of a job. */
+export const status = (
+  ref: ResearchJobRef,
+): Effect.Effect<ResearchState, AiError.AiError, DeepResearch> =>
+  Effect.flatMap(DeepResearch, (s) => s.status(ref))
+
+/** Poll a detached job to completion. */
+export const collect = (ref: ResearchJobRef): Effect.Effect<Turn, AiError.AiError, DeepResearch> =>
+  Effect.flatMap(DeepResearch, (s) => s.collect(ref))
+
+/** Attach a live progress stream to a job (call again to re-attach). */
+export const streamFrom = (
+  ref: ResearchJobRef,
+): Stream.Stream<TurnEvent, AiError.AiError, DeepResearch> =>
+  Stream.unwrap(Effect.map(DeepResearch, (s) => s.streamFrom(ref)))
+
+/** Cancel a running job. */
+export const cancel = (ref: ResearchJobRef): Effect.Effect<void, AiError.AiError, DeepResearch> =>
+  Effect.flatMap(DeepResearch, (s) => s.cancel(ref))