@effect-uai/core 0.10.0 → 0.12.0

package/dist/web-search/WebSearch.mjs.map

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

package/dist/web-search/WebSearchTool.d.mts

@@ -1,4 +1,4 @@
-import { l as Tool } from "../Tool-2lC_XMth.mjs";
+import { l as Tool } from "../Tool-u5bag8SO.mjs";
 import { t as AiError } from "../AiError-Bf1pq4BB.mjs";
 import { SearchResult, WebSearch } from "./WebSearch.mjs";
 import { Schema } from "effect";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-uai/core",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "description": "Low-level primitives (loop, conversation, items, tools, streaming codecs) for building AI agents with Effect.",
   "keywords": [
     "agents",
@@ -42,6 +42,22 @@
       "types": "./dist/domain/Audio.d.mts",
       "import": "./dist/domain/Audio.mjs"
     },
+    "./Citation": {
+      "types": "./dist/domain/Citation.d.mts",
+      "import": "./dist/domain/Citation.mjs"
+    },
+    "./Research": {
+      "types": "./dist/domain/Research.d.mts",
+      "import": "./dist/domain/Research.mjs"
+    },
+    "./Job": {
+      "types": "./dist/job/Job.d.mts",
+      "import": "./dist/job/Job.mjs"
+    },
+    "./DeepResearch": {
+      "types": "./dist/research/DeepResearch.d.mts",
+      "import": "./dist/research/DeepResearch.mjs"
+    },
     "./Browser": {
       "types": "./dist/browser/Browser.d.mts",
       "import": "./dist/browser/Browser.mjs"
@@ -226,11 +242,11 @@
     "@standard-schema/spec": "^1.1.0"
   },
   "devDependencies": {
-    "effect": "4.0.0-beta.57",
+    "effect": "4.0.0-beta.94",
     "typescript": "^6.0.3"
   },
   "peerDependencies": {
-    "effect": "4.0.0-beta.57"
+    "effect": ">=4.0.0-beta.94 <5.0.0"
   },
   "scripts": {
     "build": "tsdown",

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
 
@@ -101,6 +111,12 @@ export type Role = typeof Role.Type
 // The framework never reads or interprets it; provider modules decode
 // their own data via their own typed readers (see e.g.
 // the `@effect-uai/responses` package).
+//
+// The slot is shared, so a provider keys its data under its own name
+// (`{ responses: ... }`, `{ gemini: ... }`) and reads only that key. One item
+// can pass through several providers - falling back from one to another
+// leaves both keys on it - and a provider that finds no key of its own must
+// encode the item normally rather than assume the slot is its own.
 // ---------------------------------------------------------------------------
 
 const ProviderData = Schema.optional(Schema.Unknown)
@@ -171,8 +187,20 @@ export const isReasoning = Schema.is(Reasoning)
 // Usage and stop reason
 // ---------------------------------------------------------------------------
 
+/**
+ * Prompt-cache token breakdown. `cached_tokens` is cache reads;
+ * `cache_write_tokens` is tokens written to the cache this turn (billed at a
+ * premium). Field names mirror the OpenAI Responses usage shape.
+ *
+ * Whether these are a subset of `input_tokens` or a separate bucket is
+ * provider-specific: OpenAI counts cache reads inside `input_tokens`, while
+ * Anthropic reports `input_tokens` as post-breakpoint tokens only, with reads
+ * and writes as separate additive buckets. Read a provider's usage in its own
+ * terms; do not assume one relationship holds everywhere.
+ */
 export const InputTokensDetails = Schema.Struct({
   cached_tokens: Schema.optional(Schema.Number),
+  cache_write_tokens: Schema.optional(Schema.Number),
 })
 export type InputTokensDetails = typeof InputTokensDetails.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/observability/Metrics.test.ts

@@ -25,6 +25,9 @@ const turnComplete = (usage: Usage): TurnEvent =>
 
 const text = (s: string): TurnEvent => TurnEvent.TextDelta({ text: s })
 
+const toolArgs = (s: string): TurnEvent =>
+  TurnEvent.ToolCallArgsDelta({ call_id: "call_1", delta: s })
+
 const samples = (events: ReadonlyArray<unknown>): ReadonlyArray<MetricEvent> =>
   events.filter(isMetricEvent)
 
@@ -94,6 +97,30 @@ describe("tokenTotals", () => {
       expect(m).toEqual({ name: "effect_uai_output_tokens", kind: "counter", value: 7 })
     }),
   )
+
+  it.effect("carries cache read and write tokens through usage and measurements", () =>
+    Effect.gen(function* () {
+      const stream = Stream.make(
+        turnComplete({
+          input_tokens: 94,
+          input_tokens_details: { cached_tokens: 31851, cache_write_tokens: 604 },
+        }),
+        turnComplete({ input_tokens: 6, input_tokens_details: { cached_tokens: 32000 } }),
+      )
+      const out = yield* Stream.runCollect(stream.pipe(tokenTotals))
+      const totals = tagged(out, "TokenTotals") as ReadonlyArray<TokenTotals>
+      expect(totals.map((t) => t.cumulative.input_tokens_details?.cache_write_tokens)).toEqual([
+        604, 604,
+      ])
+      expect(totals.map((t) => t.cumulative.input_tokens_details?.cached_tokens)).toEqual([
+        31851, 63851,
+      ])
+      const write = head(totals).measurements.find(
+        (m) => m.name === "effect_uai_cache_write_tokens",
+      )
+      expect(write).toEqual({ name: "effect_uai_cache_write_tokens", kind: "counter", value: 604 })
+    }),
+  )
 })
 
 describe("timeToFirstToken", () => {
@@ -238,6 +265,44 @@ describe("throughput (metronome)", () => {
       expect(head(rates).ratePerSecond).toBeGreaterThan(0)
     }),
   )
+
+  it.effect("counts tool-call arguments: a turn with no prose still reports a rate", () =>
+    Effect.gen(function* () {
+      // The shape of an agent turn that only calls tools. Before output deltas
+      // were counted beyond TextDelta this measured 0 for the whole run.
+      const source = Stream.make(toolArgs('{"city":'), toolArgs('"Lisbon"}')).pipe(
+        Stream.concat(timed<TurnEvent>([["10 seconds", turnComplete({})]])),
+      )
+      const stream = source.pipe(
+        throughput({ every: "1 second", unit: "char" }),
+        metricEvents,
+        Stream.take(1),
+      )
+      const out = yield* runTimed(stream, ["1 second"])
+      const rates = out.filter((e): e is Throughput => e._tag === "Throughput")
+      expect(rates).toHaveLength(1)
+      expect(head(rates).ratePerSecond).toBeGreaterThan(0)
+    }),
+  )
+
+  // Runs on the real clock: this asserts an absence, so there is no sample to
+  // wait for and the stream has to end by the source closing. Under TestClock
+  // that path does not settle, because the metronome re-arms a sleep that no
+  // remaining `adjust` resolves.
+  it.live("ignores events that carry no generated output", () =>
+    Effect.gen(function* () {
+      // ToolCallStart and UsageUpdate are turn bookkeeping, not output.
+      const source = Stream.make(
+        TurnEvent.ToolCallStart({ call_id: "call_1", name: "get_weather" }),
+        TurnEvent.UsageUpdate({ usage: { output_tokens: 5 } }),
+      ).pipe(Stream.concat(timed<TurnEvent>([["30 millis", turnComplete({})]])))
+      const stream = source.pipe(throughput({ every: "10 millis", unit: "char" }), metricEvents)
+      const out = yield* Stream.runCollect(stream)
+      // No output delta ever landed, so the accumulator never started and the
+      // metronome ticks produce nothing.
+      expect(out.filter((e): e is Throughput => e._tag === "Throughput")).toHaveLength(0)
+    }),
+  )
 })
 
 describe("custom events and helpers", () => {