@effect-uai/core 0.9.0 → 0.11.0

package/dist/domain/AiError.d.mts

@@ -1,2 +1,2 @@
-import { a as Cancelled, c as GenerationFailed, d as RateLimited, f as Scope, h as Unsupported, i as AuthSubtype, l as IncompleteTurn, m as Unavailable, o as ContentFiltered, p as Timeout, r as AuthFailed, s as ContextLengthExceeded, t as AiError, u as InvalidRequest } from "../AiError-CrdR1EQi.mjs";
-export { AiError, AuthFailed, AuthSubtype, Cancelled, ContentFiltered, ContextLengthExceeded, GenerationFailed, IncompleteTurn, InvalidRequest, RateLimited, Scope, Timeout, Unavailable, Unsupported };
+import { a as Cancelled, c as GenerationFailed, d as RateLimited, f as Scope, g as describe, h as Unsupported, i as AuthSubtype, l as IncompleteTurn, m as Unavailable, o as ContentFiltered, p as Timeout, r as AuthFailed, s as ContextLengthExceeded, t as AiError, u as InvalidRequest } from "../AiError-Bf1pq4BB.mjs";
+export { AiError, AuthFailed, AuthSubtype, Cancelled, ContentFiltered, ContextLengthExceeded, GenerationFailed, IncompleteTurn, InvalidRequest, RateLimited, Scope, Timeout, Unavailable, Unsupported, describe };

package/dist/domain/AiError.mjs

@@ -1,5 +1,5 @@
 import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
-import { Data } from "effect";
+import { Data, Match } from "effect";
 //#region src/domain/AiError.ts
 var AiError_exports = /* @__PURE__ */ __exportAll({
 	AuthFailed: () => AuthFailed,
@@ -12,7 +12,8 @@ var AiError_exports = /* @__PURE__ */ __exportAll({
 	RateLimited: () => RateLimited,
 	Timeout: () => Timeout,
 	Unavailable: () => Unavailable,
-	Unsupported: () => Unsupported
+	Unsupported: () => Unsupported,
+	describe: () => describe
 });
 var RateLimited = class extends Data.TaggedError("RateLimited") {};
 var Unavailable = class extends Data.TaggedError("Unavailable") {};
@@ -50,7 +51,25 @@ var IncompleteTurn = class extends Data.TaggedError("IncompleteTurn") {};
 * (`TtsIncrementalText`, `SttStreaming`) on the R channel instead.
 */
 var Unsupported = class extends Data.TaggedError("Unsupported") {};
+const withReason = (base, reason) => reason === void 0 ? base : `${base}: ${reason}`;
+/**
+* Short human-readable description of an error, for logs and model-facing
+* failure messages. Prose, not a contract; branch on `_tag` instead.
+*/
+const describe = Match.type().pipe(Match.discriminatorsExhaustive("_tag")({
+	RateLimited: (e) => `rate limited by ${e.provider}; try again later`,
+	Unavailable: (e) => `${e.provider} is temporarily unavailable`,
+	Timeout: (e) => `the ${e.provider} request timed out`,
+	ContentFiltered: (e) => withReason(`blocked by ${e.provider}'s content filter`, e.reason),
+	ContextLengthExceeded: (e) => `the request exceeded ${e.provider}'s context limit`,
+	InvalidRequest: (e) => e.param === void 0 ? `${e.provider} rejected the request` : `${e.provider} rejected the request (param: ${e.param})`,
+	AuthFailed: (e) => `authentication against ${e.provider} failed (${e.subtype})`,
+	Cancelled: (e) => `the ${e.provider} request was cancelled`,
+	IncompleteTurn: () => "the provider stream ended without completing",
+	GenerationFailed: (e) => e.message ?? `${e.provider} failed mid-generation`,
+	Unsupported: (e) => withReason(`${e.provider} does not support ${e.capability}`, e.reason)
+}));
 //#endregion
-export { AuthFailed, Cancelled, ContentFiltered, ContextLengthExceeded, GenerationFailed, IncompleteTurn, InvalidRequest, RateLimited, Timeout, Unavailable, Unsupported, AiError_exports as t };
+export { AuthFailed, Cancelled, ContentFiltered, ContextLengthExceeded, GenerationFailed, IncompleteTurn, InvalidRequest, RateLimited, Timeout, Unavailable, Unsupported, describe, AiError_exports as t };
 
 //# sourceMappingURL=AiError.mjs.map

package/dist/domain/AiError.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"AiError.mjs","names":[],"sources":["../../src/domain/AiError.ts"],"sourcesContent":["import { Data, Duration } from \"effect\"\n\nexport type Scope = \"rpm\" | \"tpm\" | \"rpd\" | \"tpd\"\n\nexport class RateLimited extends Data.TaggedError(\"RateLimited\")<{\n  provider: string\n  retryAfter?: Duration.Duration\n  scope?: Scope\n  requestId?: string\n  raw: unknown\n}> {}\n\nexport class Unavailable extends Data.TaggedError(\"Unavailable\")<{\n  provider: string\n  retryAfter?: Duration.Duration\n  status?: number\n  requestId?: string\n  raw: unknown\n}> {}\n\nexport class Timeout extends Data.TaggedError(\"Timeout\")<{\n  provider: string\n  requestId?: string\n  raw: unknown\n}> {}\n\nexport class ContentFiltered extends Data.TaggedError(\"ContentFiltered\")<{\n  provider: string\n  reason?: string\n  requestId?: string\n  raw: unknown\n}> {}\n\nexport class ContextLengthExceeded extends Data.TaggedError(\"ContextLengthExceeded\")<{\n  provider: string\n  modelLimit?: number\n  requested?: number\n  raw: unknown\n}> {}\n\nexport class InvalidRequest extends Data.TaggedError(\"InvalidRequest\")<{\n  provider: string\n  param?: string\n  requestId?: string\n  raw: unknown\n}> {}\n\nexport type AuthSubtype = \"auth\" | \"permission\" | \"billing\" | \"quota\"\n\nexport class AuthFailed extends Data.TaggedError(\"AuthFailed\")<{\n  provider: string\n  subtype: AuthSubtype\n  raw: unknown\n}> {}\n\nexport class Cancelled extends Data.TaggedError(\"Cancelled\")<{\n  provider: string\n}> {}\n\n/**\n * The model errored mid-generation. Distinct from `Unavailable` (transport\n * problem before generation started) and from `IncompleteTurn` (provider\n * stream ended without a terminal event). The provider's own error message,\n * if any, is on `message`.\n */\nexport class GenerationFailed extends Data.TaggedError(\"GenerationFailed\")<{\n  provider: string\n  code?: string\n  message?: string\n  requestId?: string\n  raw: unknown\n}> {}\n\n/**\n * The provider's delta stream ended without a terminal `TurnComplete`.\n * Indicates a misbehaving provider or a connection that dropped mid-flight.\n * Non-terminal deltas seen so far have already been emitted downstream.\n */\nexport class IncompleteTurn extends Data.TaggedError(\"IncompleteTurn\")<{\n  raw?: unknown\n}> {}\n\n/**\n * The provider does not implement the requested capability for this\n * specific request. Distinct from `InvalidRequest` (the request shape is\n * malformed) and `AuthFailed` (the request was rejected).\n *\n * Reserved for request-data-dependent gaps where the provider supports\n * the method in general but not for these inputs — e.g. Google's\n * `streamSynthesisFrom` works only for Chirp 3 HD voices; calling it\n * with a Neural2 voice ID fails `Unsupported`.\n *\n * Blanket provider-level gaps (e.g. OpenAI has no incremental-text-in\n * TTS at all) are gated at compile time via capability marker tags\n * (`TtsIncrementalText`, `SttStreaming`) on the R channel instead.\n */\nexport class Unsupported extends Data.TaggedError(\"Unsupported\")<{\n  provider: string\n  capability: string\n  reason?: string\n}> {}\n\nexport type AiError =\n  | RateLimited\n  | Unavailable\n  | Timeout\n  | ContentFiltered\n  | ContextLengthExceeded\n  | InvalidRequest\n  | AuthFailed\n  | Cancelled\n  | IncompleteTurn\n  | GenerationFailed\n  | Unsupported\n"],"mappings":";;;;;;;;;;;;;;;;AAIA,IAAa,cAAb,cAAiC,KAAK,YAAY,cAAc,CAM7D;AAEH,IAAa,cAAb,cAAiC,KAAK,YAAY,cAAc,CAM7D;AAEH,IAAa,UAAb,cAA6B,KAAK,YAAY,UAAU,CAIrD;AAEH,IAAa,kBAAb,cAAqC,KAAK,YAAY,kBAAkB,CAKrE;AAEH,IAAa,wBAAb,cAA2C,KAAK,YAAY,wBAAwB,CAKjF;AAEH,IAAa,iBAAb,cAAoC,KAAK,YAAY,iBAAiB,CAKnE;AAIH,IAAa,aAAb,cAAgC,KAAK,YAAY,aAAa,CAI3D;AAEH,IAAa,YAAb,cAA+B,KAAK,YAAY,YAAY,CAEzD;;;;;;;AAQH,IAAa,mBAAb,cAAsC,KAAK,YAAY,mBAAmB,CAMvE;;;;;;AAOH,IAAa,iBAAb,cAAoC,KAAK,YAAY,iBAAiB,CAEnE;;;;;;;;;;;;;;;AAgBH,IAAa,cAAb,cAAiC,KAAK,YAAY,cAAc,CAI7D"}
+{"version":3,"file":"AiError.mjs","names":[],"sources":["../../src/domain/AiError.ts"],"sourcesContent":["import { Data, Duration, Match } from \"effect\"\n\nexport type Scope = \"rpm\" | \"tpm\" | \"rpd\" | \"tpd\"\n\nexport class RateLimited extends Data.TaggedError(\"RateLimited\")<{\n  provider: string\n  retryAfter?: Duration.Duration\n  scope?: Scope\n  requestId?: string\n  raw: unknown\n}> {}\n\nexport class Unavailable extends Data.TaggedError(\"Unavailable\")<{\n  provider: string\n  retryAfter?: Duration.Duration\n  status?: number\n  requestId?: string\n  raw: unknown\n}> {}\n\nexport class Timeout extends Data.TaggedError(\"Timeout\")<{\n  provider: string\n  requestId?: string\n  raw: unknown\n}> {}\n\nexport class ContentFiltered extends Data.TaggedError(\"ContentFiltered\")<{\n  provider: string\n  reason?: string\n  requestId?: string\n  raw: unknown\n}> {}\n\nexport class ContextLengthExceeded extends Data.TaggedError(\"ContextLengthExceeded\")<{\n  provider: string\n  modelLimit?: number\n  requested?: number\n  raw: unknown\n}> {}\n\nexport class InvalidRequest extends Data.TaggedError(\"InvalidRequest\")<{\n  provider: string\n  param?: string\n  requestId?: string\n  raw: unknown\n}> {}\n\nexport type AuthSubtype = \"auth\" | \"permission\" | \"billing\" | \"quota\"\n\nexport class AuthFailed extends Data.TaggedError(\"AuthFailed\")<{\n  provider: string\n  subtype: AuthSubtype\n  raw: unknown\n}> {}\n\nexport class Cancelled extends Data.TaggedError(\"Cancelled\")<{\n  provider: string\n}> {}\n\n/**\n * The model errored mid-generation. Distinct from `Unavailable` (transport\n * problem before generation started) and from `IncompleteTurn` (provider\n * stream ended without a terminal event). The provider's own error message,\n * if any, is on `message`.\n */\nexport class GenerationFailed extends Data.TaggedError(\"GenerationFailed\")<{\n  provider: string\n  code?: string\n  message?: string\n  requestId?: string\n  raw: unknown\n}> {}\n\n/**\n * The provider's delta stream ended without a terminal `TurnComplete`.\n * Indicates a misbehaving provider or a connection that dropped mid-flight.\n * Non-terminal deltas seen so far have already been emitted downstream.\n */\nexport class IncompleteTurn extends Data.TaggedError(\"IncompleteTurn\")<{\n  raw?: unknown\n}> {}\n\n/**\n * The provider does not implement the requested capability for this\n * specific request. Distinct from `InvalidRequest` (the request shape is\n * malformed) and `AuthFailed` (the request was rejected).\n *\n * Reserved for request-data-dependent gaps where the provider supports\n * the method in general but not for these inputs — e.g. Google's\n * `streamSynthesisFrom` works only for Chirp 3 HD voices; calling it\n * with a Neural2 voice ID fails `Unsupported`.\n *\n * Blanket provider-level gaps (e.g. OpenAI has no incremental-text-in\n * TTS at all) are gated at compile time via capability marker tags\n * (`TtsIncrementalText`, `SttStreaming`) on the R channel instead.\n */\nexport class Unsupported extends Data.TaggedError(\"Unsupported\")<{\n  provider: string\n  capability: string\n  reason?: string\n}> {}\n\nexport type AiError =\n  | RateLimited\n  | Unavailable\n  | Timeout\n  | ContentFiltered\n  | ContextLengthExceeded\n  | InvalidRequest\n  | AuthFailed\n  | Cancelled\n  | IncompleteTurn\n  | GenerationFailed\n  | Unsupported\n\nconst withReason = (base: string, reason: string | undefined): string =>\n  reason === undefined ? base : `${base}: ${reason}`\n\n/**\n * Short human-readable description of an error, for logs and model-facing\n * failure messages. Prose, not a contract; branch on `_tag` instead.\n */\nexport const describe: (e: AiError) => string = Match.type<AiError>().pipe(\n  Match.discriminatorsExhaustive(\"_tag\")({\n    RateLimited: (e) => `rate limited by ${e.provider}; try again later`,\n    Unavailable: (e) => `${e.provider} is temporarily unavailable`,\n    Timeout: (e) => `the ${e.provider} request timed out`,\n    ContentFiltered: (e) => withReason(`blocked by ${e.provider}'s content filter`, e.reason),\n    ContextLengthExceeded: (e) => `the request exceeded ${e.provider}'s context limit`,\n    InvalidRequest: (e) =>\n      e.param === undefined\n        ? `${e.provider} rejected the request`\n        : `${e.provider} rejected the request (param: ${e.param})`,\n    AuthFailed: (e) => `authentication against ${e.provider} failed (${e.subtype})`,\n    Cancelled: (e) => `the ${e.provider} request was cancelled`,\n    IncompleteTurn: () => \"the provider stream ended without completing\",\n    GenerationFailed: (e) => e.message ?? `${e.provider} failed mid-generation`,\n    Unsupported: (e) => withReason(`${e.provider} does not support ${e.capability}`, e.reason),\n  }),\n)\n"],"mappings":";;;;;;;;;;;;;;;;;AAIA,IAAa,cAAb,cAAiC,KAAK,YAAY,cAAc,CAM7D;AAEH,IAAa,cAAb,cAAiC,KAAK,YAAY,cAAc,CAM7D;AAEH,IAAa,UAAb,cAA6B,KAAK,YAAY,UAAU,CAIrD;AAEH,IAAa,kBAAb,cAAqC,KAAK,YAAY,kBAAkB,CAKrE;AAEH,IAAa,wBAAb,cAA2C,KAAK,YAAY,wBAAwB,CAKjF;AAEH,IAAa,iBAAb,cAAoC,KAAK,YAAY,iBAAiB,CAKnE;AAIH,IAAa,aAAb,cAAgC,KAAK,YAAY,aAAa,CAI3D;AAEH,IAAa,YAAb,cAA+B,KAAK,YAAY,YAAY,CAEzD;;;;;;;AAQH,IAAa,mBAAb,cAAsC,KAAK,YAAY,mBAAmB,CAMvE;;;;;;AAOH,IAAa,iBAAb,cAAoC,KAAK,YAAY,iBAAiB,CAEnE;;;;;;;;;;;;;;;AAgBH,IAAa,cAAb,cAAiC,KAAK,YAAY,cAAc,CAI7D;AAeH,MAAM,cAAc,MAAc,WAChC,WAAW,KAAA,IAAY,OAAO,GAAG,KAAK,IAAI;;;;;AAM5C,MAAa,WAAmC,MAAM,MAAe,CAAC,KACpE,MAAM,yBAAyB,OAAO,CAAC;CACrC,cAAc,MAAM,mBAAmB,EAAE,SAAS;CAClD,cAAc,MAAM,GAAG,EAAE,SAAS;CAClC,UAAU,MAAM,OAAO,EAAE,SAAS;CAClC,kBAAkB,MAAM,WAAW,cAAc,EAAE,SAAS,oBAAoB,EAAE,OAAO;CACzF,wBAAwB,MAAM,wBAAwB,EAAE,SAAS;CACjE,iBAAiB,MACf,EAAE,UAAU,KAAA,IACR,GAAG,EAAE,SAAS,yBACd,GAAG,EAAE,SAAS,gCAAgC,EAAE,MAAM;CAC5D,aAAa,MAAM,0BAA0B,EAAE,SAAS,WAAW,EAAE,QAAQ;CAC7E,YAAY,MAAM,OAAO,EAAE,SAAS;CACpC,sBAAsB;CACtB,mBAAmB,MAAM,EAAE,WAAW,GAAG,EAAE,SAAS;CACpD,cAAc,MAAM,WAAW,GAAG,EAAE,SAAS,oBAAoB,EAAE,cAAc,EAAE,OAAO;CAC3F,CAAC,CACH"}

package/dist/domain/Audio.d.mts

@@ -1,2 +1,2 @@
-import { a as AudioSource, c as isAudioBytes, i as AudioMimeType, l as isAudioUrl, n as AudioChunk, r as AudioFormat, s as isAudioBase64, t as AudioBlob } from "../Audio-DDSKCkSe.mjs";
+import { a as AudioSource, c as isAudioBytes, i as AudioMimeType, l as isAudioUrl, n as AudioChunk, r as AudioFormat, s as isAudioBase64, t as AudioBlob } from "../Audio-CR7CSljJ.mjs";
 export { AudioBlob, AudioChunk, AudioFormat, AudioMimeType, AudioSource, isAudioBase64, isAudioBytes, isAudioUrl };

package/dist/domain/Citation.d.mts

@@ -0,0 +1,60 @@
+import { DateTime } from "effect";
+
+//#region src/domain/Citation.d.ts
+declare namespace Citation_d_exports {
+  export { CitationSpan, Citations, 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.
+ */
+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;
+};
+/**
+ * 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.
+ */
+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>;
+};
+/**
+ * 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.
+ */
+type Citations = {
+  readonly sources: ReadonlyArray<Source>;
+  readonly spans: ReadonlyArray<CitationSpan>;
+};
+//#endregion
+export { CitationSpan, Citations, Source, Citation_d_exports as t };
+//# sourceMappingURL=Citation.d.mts.map

package/dist/domain/Citation.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Citation.d.mts","names":[],"sources":["../../src/domain/Citation.ts"],"mappings":";;;;;;;;;;;;KAYY,MAAA;EAAA,SACD,GAAA;EAAA,SACA,KAAA;EAAA,SACA,OAAA;EAAA,SACA,aAAA,GAAgB,QAAA,CAAS,QAAA;EAAA,SACzB,UAAA;EAAA,SACA,GAAA;AAAA;;;;;;;;KAcC,YAAA;EAAA,SAEG,IAAA;EAAA,SACA,KAAA;EAAA,SACA,GAAA;EAAA,SACA,IAAA;EAAA,SACA,UAAA,EAAY,aAAA;EAAA,SACZ,UAAA;AAAA;EAAA,SAEA,IAAA;EAAA,SAAwB,IAAA;EAAA,SAAuB,UAAA,EAAY,aAAA;AAAA;EAAA,SAE3D,IAAA;EAAA,SACA,OAAA;EAAA,SACA,UAAA,EAAY,aAAA;AAAA;EAAA,SAEZ,IAAA;EAAA,SAAuB,UAAA,EAAY,aAAA;AAAA;;;;;;;;KAatC,SAAA;EAAA,SACD,OAAA,EAAS,aAAA,CAAc,MAAA;EAAA,SACvB,KAAA,EAAO,aAAA,CAAc,YAAA;AAAA"}

package/dist/domain/Citation.mjs

@@ -0,0 +1,7 @@
+import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
+//#region src/domain/Citation.ts
+var Citation_exports = /* @__PURE__ */ __exportAll({});
+//#endregion
+export { Citation_exports as t };
+
+//# sourceMappingURL=Citation.mjs.map

package/dist/domain/Citation.mjs.map

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

package/dist/domain/Image.d.mts

@@ -1,2 +1,2 @@
-import { a as ImageUrlSource, c as imageBytes, d as isImageBytes, f as isImageUrl, i as ImageSource, l as imageUrl, n as ImageBytesSource, r as ImageMimeType, s as imageBase64, t as ImageBase64Source, u as isImageBase64 } from "../Image-C_Zjpwhc.mjs";
+import { a as ImageUrlSource, c as imageBytes, d as isImageBytes, f as isImageUrl, i as ImageSource, l as imageUrl, n as ImageBytesSource, r as ImageMimeType, s as imageBase64, t as ImageBase64Source, u as isImageBase64 } from "../Image-C4vuBmu0.mjs";
 export { ImageBase64Source, ImageBytesSource, ImageMimeType, ImageSource, ImageUrlSource, imageBase64, imageBytes, imageUrl, isImageBase64, isImageBytes, isImageUrl };

package/dist/domain/Items.d.mts

@@ -1,2 +1,2 @@
-import { A as isReasoning, C as isContainerFileCitation, D as isInputText, E as isInputImage, F as systemText, I as toolCallOutput, L as userText, M as isToolCall, N as isToolCallOutput, O as isMessage, P as isUrlCitation, S as assistantText, T as isFilePath, _ as StopReason, a as FilePath, b as UrlCitation, c as InputText, d as Message, f as OutputText, g as Role, h as Refusal, i as FileCitation, j as isRefusal, k as isOutputText, l as InputTokensDetails, m as Reasoning, n as ContainerFileCitation, o as HistoryItem, p as OutputTokensDetails, r as ContentBlock, s as InputImage, t as Annotation, v as ToolCall, w as isFileCitation, x as Usage, y as ToolCallOutput } from "../Items-CgKD6Npw.mjs";
+import { A as isReasoning, C as isContainerFileCitation, D as isInputText, E as isInputImage, F as systemText, I as toolCallOutput, L as userText, M as isToolCall, N as isToolCallOutput, O as isMessage, P as isUrlCitation, S as assistantText, T as isFilePath, _ as StopReason, a as FilePath, b as UrlCitation, c as InputText, d as Message, f as OutputText, g as Role, h as Refusal, i as FileCitation, j as isRefusal, k as isOutputText, l as InputTokensDetails, m as Reasoning, n as ContainerFileCitation, o as HistoryItem, p as OutputTokensDetails, r as ContentBlock, s as InputImage, t as Annotation, v as ToolCall, w as isFileCitation, x as Usage, y as ToolCallOutput } from "../Items-BWNu6VGp.mjs";
 export { Annotation, ContainerFileCitation, ContentBlock, FileCitation, FilePath, HistoryItem, InputImage, InputText, InputTokensDetails, Message, OutputText, OutputTokensDetails, Reasoning, Refusal, Role, StopReason, ToolCall, ToolCallOutput, UrlCitation, Usage, assistantText, isContainerFileCitation, isFileCitation, isFilePath, isInputImage, isInputText, isMessage, isOutputText, isReasoning, isRefusal, isToolCall, isToolCallOutput, isUrlCitation, systemText, toolCallOutput, userText };

package/dist/domain/Items.mjs

@@ -56,12 +56,22 @@ const InputImage = Schema.Struct({
 	type: Schema.Literal("input_image"),
 	source: ImageSource
 });
+/**
+* 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.
+*/
 const UrlCitation = Schema.Struct({
 	type: Schema.Literal("url_citation"),
 	url: Schema.String,
-	start_index: Schema.Number,
-	end_index: Schema.Number,
-	title: Schema.String
+	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)
 });
 const FileCitation = Schema.Struct({
 	type: Schema.Literal("file_citation"),

package/dist/domain/Items.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Items.mjs","names":[],"sources":["../../src/domain/Items.ts"],"sourcesContent":["import { Schema } from \"effect\"\nimport { ImageSource } from \"./Image.js\"\n\n// ---------------------------------------------------------------------------\n// Content blocks (inside Message.content)\n// ---------------------------------------------------------------------------\n\nexport const InputText = Schema.Struct({\n  type: Schema.Literal(\"input_text\"),\n  text: Schema.String,\n})\nexport type InputText = typeof InputText.Type\n\n/**\n * User-provided image content block. Pair with `InputText` inside a\n * `Message.content` array to ask \"what's in this image?\" style questions.\n *\n * `source` is the cross-modality `ImageSource` from `domain/Image.ts` -\n * url, base64, or raw bytes. Provider codecs encode bytes to whatever\n * wire format the provider wants.\n */\nexport const InputImage = Schema.Struct({\n  type: Schema.Literal(\"input_image\"),\n  source: ImageSource,\n})\nexport type InputImage = typeof InputImage.Type\n\n// ---------------------------------------------------------------------------\n// Annotations - source / citation pointers attached to `output_text` blocks.\n// Mirrors OpenAI Responses API; other providers can omit or map onto these\n// shapes.\n// ---------------------------------------------------------------------------\n\nexport const UrlCitation = Schema.Struct({\n  type: Schema.Literal(\"url_citation\"),\n  url: Schema.String,\n  start_index: Schema.Number,\n  end_index: Schema.Number,\n  title: Schema.String,\n})\nexport type UrlCitation = typeof UrlCitation.Type\n\nexport const FileCitation = Schema.Struct({\n  type: Schema.Literal(\"file_citation\"),\n  file_id: Schema.String,\n  index: Schema.Number,\n})\nexport type FileCitation = typeof FileCitation.Type\n\nexport const ContainerFileCitation = Schema.Struct({\n  type: Schema.Literal(\"container_file_citation\"),\n  container_id: Schema.String,\n  file_id: Schema.String,\n  start_index: Schema.Number,\n  end_index: Schema.Number,\n})\nexport type ContainerFileCitation = typeof ContainerFileCitation.Type\n\nexport const FilePath = Schema.Struct({\n  type: Schema.Literal(\"file_path\"),\n  file_id: Schema.String,\n  index: Schema.Number,\n})\nexport type FilePath = typeof FilePath.Type\n\nexport const Annotation = Schema.Union([UrlCitation, FileCitation, ContainerFileCitation, FilePath])\nexport type Annotation = typeof Annotation.Type\n\nexport const isUrlCitation = Schema.is(UrlCitation)\nexport const isFileCitation = Schema.is(FileCitation)\nexport const isContainerFileCitation = Schema.is(ContainerFileCitation)\nexport const isFilePath = Schema.is(FilePath)\n\nexport const OutputText = Schema.Struct({\n  type: Schema.Literal(\"output_text\"),\n  text: Schema.String,\n  annotations: Schema.optional(Schema.Array(Annotation)),\n})\nexport type OutputText = typeof OutputText.Type\n\n/**\n * Model-emitted refusal. Distinct from `output_text`: the model declined\n * to answer rather than producing normal output. Pair with\n * `stop_reason: \"refusal\"` on the surrounding `Turn`. Streamed via the\n * `RefusalDelta` `TurnEvent`.\n */\nexport const Refusal = Schema.Struct({\n  type: Schema.Literal(\"refusal\"),\n  text: Schema.String,\n})\nexport type Refusal = typeof Refusal.Type\n\nexport const ContentBlock = Schema.Union([InputText, InputImage, OutputText, Refusal])\nexport type ContentBlock = typeof ContentBlock.Type\n\nexport const Role = Schema.Literals([\"user\", \"assistant\", \"system\"])\nexport type Role = typeof Role.Type\n\n// ---------------------------------------------------------------------------\n// Provider passthrough - every Item type carries this opaque slot.\n// The framework never reads or interprets it; provider modules decode\n// their own data via their own typed readers (see e.g.\n// the `@effect-uai/responses` package).\n// ---------------------------------------------------------------------------\n\nconst ProviderData = Schema.optional(Schema.Unknown)\n\n// ---------------------------------------------------------------------------\n// Items\n// ---------------------------------------------------------------------------\n\nexport const Message = Schema.Struct({\n  type: Schema.Literal(\"message\"),\n  role: Role,\n  content: Schema.Array(ContentBlock),\n  providerData: ProviderData,\n})\nexport type Message = typeof Message.Type\n\nexport const ToolCall = Schema.Struct({\n  type: Schema.Literal(\"function_call\"),\n  call_id: Schema.String,\n  name: Schema.String,\n  // JSON-encoded arguments string, mirroring OpenAI Responses API\n  arguments: Schema.String,\n  providerData: ProviderData,\n})\nexport type ToolCall = typeof ToolCall.Type\n\nexport const ToolCallOutput = Schema.Struct({\n  type: Schema.Literal(\"function_call_output\"),\n  call_id: Schema.String,\n  output: Schema.String,\n  providerData: ProviderData,\n})\nexport type ToolCallOutput = typeof ToolCallOutput.Type\n\n/**\n * Reasoning item - top-level, mirrors OpenAI Responses API. Common shape\n * across providers covers `summary` (human-readable text) and `signature`\n * (opaque round-trip blob - Anthropic's signed thinking, OpenAI's\n * encrypted_content, etc.). Provider-specific fields go in `providerData`.\n */\nexport const Reasoning = Schema.Struct({\n  type: Schema.Literal(\"reasoning\"),\n  id: Schema.optional(Schema.String),\n  summary: Schema.optional(Schema.String),\n  signature: Schema.optional(Schema.String),\n  providerData: ProviderData,\n})\nexport type Reasoning = typeof Reasoning.Type\n\nexport const HistoryItem = Schema.Union([Message, ToolCall, ToolCallOutput, Reasoning])\nexport type HistoryItem = typeof HistoryItem.Type\n\n// ---------------------------------------------------------------------------\n// Type guards\n// ---------------------------------------------------------------------------\n\nexport const isInputText = Schema.is(InputText)\nexport const isInputImage = Schema.is(InputImage)\nexport const isOutputText = Schema.is(OutputText)\nexport const isRefusal = Schema.is(Refusal)\n\nexport const isMessage = Schema.is(Message)\nexport const isToolCall = Schema.is(ToolCall)\nexport const isToolCallOutput = Schema.is(ToolCallOutput)\nexport const isReasoning = Schema.is(Reasoning)\n\n// ---------------------------------------------------------------------------\n// Usage and stop reason\n// ---------------------------------------------------------------------------\n\nexport const InputTokensDetails = Schema.Struct({\n  cached_tokens: Schema.optional(Schema.Number),\n})\nexport type InputTokensDetails = typeof InputTokensDetails.Type\n\nexport const OutputTokensDetails = Schema.Struct({\n  reasoning_tokens: Schema.optional(Schema.Number),\n})\nexport type OutputTokensDetails = typeof OutputTokensDetails.Type\n\nexport const Usage = Schema.Struct({\n  input_tokens: Schema.optional(Schema.Number),\n  output_tokens: Schema.optional(Schema.Number),\n  total_tokens: Schema.optional(Schema.Number),\n  input_tokens_details: Schema.optional(InputTokensDetails),\n  output_tokens_details: Schema.optional(OutputTokensDetails),\n})\nexport type Usage = typeof Usage.Type\n\nexport const StopReason = Schema.Literals([\n  \"stop\",\n  \"tool_calls\",\n  \"max_tokens\",\n  \"refusal\",\n  /** Provider-side safety classifier flagged the output. */\n  \"content_filter\",\n  /** Server-enforced cap on tool calls per turn was hit. */\n  \"max_tool_calls\",\n])\nexport type StopReason = typeof StopReason.Type\n\n// ---------------------------------------------------------------------------\n// Helper constructors\n// ---------------------------------------------------------------------------\n\nexport const userText = (text: string): Message => ({\n  type: \"message\",\n  role: \"user\",\n  content: [{ type: \"input_text\", text }],\n})\n\nexport const systemText = (text: string): Message => ({\n  type: \"message\",\n  role: \"system\",\n  content: [{ type: \"input_text\", text }],\n})\n\nexport const assistantText = (text: string): Message => ({\n  type: \"message\",\n  role: \"assistant\",\n  content: [{ type: \"output_text\", text }],\n})\n\nexport const toolCallOutput = (call_id: string, output: string): ToolCallOutput => ({\n  type: \"function_call_output\",\n  call_id,\n  output,\n})\n"],"mappings":"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"}
+{"version":3,"file":"Items.mjs","names":[],"sources":["../../src/domain/Items.ts"],"sourcesContent":["import { Schema } from \"effect\"\nimport { ImageSource } from \"./Image.js\"\n\n// ---------------------------------------------------------------------------\n// Content blocks (inside Message.content)\n// ---------------------------------------------------------------------------\n\nexport const InputText = Schema.Struct({\n  type: Schema.Literal(\"input_text\"),\n  text: Schema.String,\n})\nexport type InputText = typeof InputText.Type\n\n/**\n * User-provided image content block. Pair with `InputText` inside a\n * `Message.content` array to ask \"what's in this image?\" style questions.\n *\n * `source` is the cross-modality `ImageSource` from `domain/Image.ts` -\n * url, base64, or raw bytes. Provider codecs encode bytes to whatever\n * wire format the provider wants.\n */\nexport const InputImage = Schema.Struct({\n  type: Schema.Literal(\"input_image\"),\n  source: ImageSource,\n})\nexport type InputImage = typeof InputImage.Type\n\n// ---------------------------------------------------------------------------\n// Annotations - source / citation pointers attached to `output_text` blocks.\n// Provider-agnostic: each provider populates the fields it has (character\n// span, quote, or positional marker) and omits the rest.\n// ---------------------------------------------------------------------------\n\n/**\n * A cited source. `url` + `title` are the only near-universal fields; the\n * link from a source to the answer text varies by provider, so it is optional\n * and expressed three ways: `start_index`/`end_index` (a character span into\n * the answer), `cited_text` (an exact quote of the source, when no offsets are\n * given), or `marker` (a positional `[n]` reference into an ordered list). A\n * provider populates whichever it has; a bare source list sets none.\n */\nexport const UrlCitation = Schema.Struct({\n  type: Schema.Literal(\"url_citation\"),\n  url: Schema.String,\n  title: Schema.String,\n  start_index: Schema.optional(Schema.Number),\n  end_index: Schema.optional(Schema.Number),\n  cited_text: Schema.optional(Schema.String),\n  marker: Schema.optional(Schema.Number),\n})\nexport type UrlCitation = typeof UrlCitation.Type\n\nexport const FileCitation = Schema.Struct({\n  type: Schema.Literal(\"file_citation\"),\n  file_id: Schema.String,\n  index: Schema.Number,\n})\nexport type FileCitation = typeof FileCitation.Type\n\nexport const ContainerFileCitation = Schema.Struct({\n  type: Schema.Literal(\"container_file_citation\"),\n  container_id: Schema.String,\n  file_id: Schema.String,\n  start_index: Schema.Number,\n  end_index: Schema.Number,\n})\nexport type ContainerFileCitation = typeof ContainerFileCitation.Type\n\nexport const FilePath = Schema.Struct({\n  type: Schema.Literal(\"file_path\"),\n  file_id: Schema.String,\n  index: Schema.Number,\n})\nexport type FilePath = typeof FilePath.Type\n\nexport const Annotation = Schema.Union([UrlCitation, FileCitation, ContainerFileCitation, FilePath])\nexport type Annotation = typeof Annotation.Type\n\nexport const isUrlCitation = Schema.is(UrlCitation)\nexport const isFileCitation = Schema.is(FileCitation)\nexport const isContainerFileCitation = Schema.is(ContainerFileCitation)\nexport const isFilePath = Schema.is(FilePath)\n\nexport const OutputText = Schema.Struct({\n  type: Schema.Literal(\"output_text\"),\n  text: Schema.String,\n  annotations: Schema.optional(Schema.Array(Annotation)),\n})\nexport type OutputText = typeof OutputText.Type\n\n/**\n * Model-emitted refusal. Distinct from `output_text`: the model declined\n * to answer rather than producing normal output. Pair with\n * `stop_reason: \"refusal\"` on the surrounding `Turn`. Streamed via the\n * `RefusalDelta` `TurnEvent`.\n */\nexport const Refusal = Schema.Struct({\n  type: Schema.Literal(\"refusal\"),\n  text: Schema.String,\n})\nexport type Refusal = typeof Refusal.Type\n\nexport const ContentBlock = Schema.Union([InputText, InputImage, OutputText, Refusal])\nexport type ContentBlock = typeof ContentBlock.Type\n\nexport const Role = Schema.Literals([\"user\", \"assistant\", \"system\"])\nexport type Role = typeof Role.Type\n\n// ---------------------------------------------------------------------------\n// Provider passthrough - every Item type carries this opaque slot.\n// The framework never reads or interprets it; provider modules decode\n// their own data via their own typed readers (see e.g.\n// the `@effect-uai/responses` package).\n// ---------------------------------------------------------------------------\n\nconst ProviderData = Schema.optional(Schema.Unknown)\n\n// ---------------------------------------------------------------------------\n// Items\n// ---------------------------------------------------------------------------\n\nexport const Message = Schema.Struct({\n  type: Schema.Literal(\"message\"),\n  role: Role,\n  content: Schema.Array(ContentBlock),\n  providerData: ProviderData,\n})\nexport type Message = typeof Message.Type\n\nexport const ToolCall = Schema.Struct({\n  type: Schema.Literal(\"function_call\"),\n  call_id: Schema.String,\n  name: Schema.String,\n  // JSON-encoded arguments string, mirroring OpenAI Responses API\n  arguments: Schema.String,\n  providerData: ProviderData,\n})\nexport type ToolCall = typeof ToolCall.Type\n\nexport const ToolCallOutput = Schema.Struct({\n  type: Schema.Literal(\"function_call_output\"),\n  call_id: Schema.String,\n  output: Schema.String,\n  providerData: ProviderData,\n})\nexport type ToolCallOutput = typeof ToolCallOutput.Type\n\n/**\n * Reasoning item - top-level, mirrors OpenAI Responses API. Common shape\n * across providers covers `summary` (human-readable text) and `signature`\n * (opaque round-trip blob - Anthropic's signed thinking, OpenAI's\n * encrypted_content, etc.). Provider-specific fields go in `providerData`.\n */\nexport const Reasoning = Schema.Struct({\n  type: Schema.Literal(\"reasoning\"),\n  id: Schema.optional(Schema.String),\n  summary: Schema.optional(Schema.String),\n  signature: Schema.optional(Schema.String),\n  providerData: ProviderData,\n})\nexport type Reasoning = typeof Reasoning.Type\n\nexport const HistoryItem = Schema.Union([Message, ToolCall, ToolCallOutput, Reasoning])\nexport type HistoryItem = typeof HistoryItem.Type\n\n// ---------------------------------------------------------------------------\n// Type guards\n// ---------------------------------------------------------------------------\n\nexport const isInputText = Schema.is(InputText)\nexport const isInputImage = Schema.is(InputImage)\nexport const isOutputText = Schema.is(OutputText)\nexport const isRefusal = Schema.is(Refusal)\n\nexport const isMessage = Schema.is(Message)\nexport const isToolCall = Schema.is(ToolCall)\nexport const isToolCallOutput = Schema.is(ToolCallOutput)\nexport const isReasoning = Schema.is(Reasoning)\n\n// ---------------------------------------------------------------------------\n// Usage and stop reason\n// ---------------------------------------------------------------------------\n\nexport const InputTokensDetails = Schema.Struct({\n  cached_tokens: Schema.optional(Schema.Number),\n})\nexport type InputTokensDetails = typeof InputTokensDetails.Type\n\nexport const OutputTokensDetails = Schema.Struct({\n  reasoning_tokens: Schema.optional(Schema.Number),\n})\nexport type OutputTokensDetails = typeof OutputTokensDetails.Type\n\nexport const Usage = Schema.Struct({\n  input_tokens: Schema.optional(Schema.Number),\n  output_tokens: Schema.optional(Schema.Number),\n  total_tokens: Schema.optional(Schema.Number),\n  input_tokens_details: Schema.optional(InputTokensDetails),\n  output_tokens_details: Schema.optional(OutputTokensDetails),\n})\nexport type Usage = typeof Usage.Type\n\nexport const StopReason = Schema.Literals([\n  \"stop\",\n  \"tool_calls\",\n  \"max_tokens\",\n  \"refusal\",\n  /** Provider-side safety classifier flagged the output. */\n  \"content_filter\",\n  /** Server-enforced cap on tool calls per turn was hit. */\n  \"max_tool_calls\",\n])\nexport type StopReason = typeof StopReason.Type\n\n// ---------------------------------------------------------------------------\n// Helper constructors\n// ---------------------------------------------------------------------------\n\nexport const userText = (text: string): Message => ({\n  type: \"message\",\n  role: \"user\",\n  content: [{ type: \"input_text\", text }],\n})\n\nexport const systemText = (text: string): Message => ({\n  type: \"message\",\n  role: \"system\",\n  content: [{ type: \"input_text\", text }],\n})\n\nexport const assistantText = (text: string): Message => ({\n  type: \"message\",\n  role: \"assistant\",\n  content: [{ type: \"output_text\", text }],\n})\n\nexport const toolCallOutput = (call_id: string, output: string): ToolCallOutput => ({\n  type: \"function_call_output\",\n  call_id,\n  output,\n})\n"],"mappings":"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"}

package/dist/domain/Media.d.mts

@@ -1,2 +1,2 @@
-import { c as isMediaUrl, i as MediaUrl, n as MediaBytes, o as isMediaBase64, r as MediaSource, s as isMediaBytes, t as MediaBase64 } from "../Media-DOLyaygI.mjs";
+import { c as isMediaUrl, i as MediaUrl, n as MediaBytes, o as isMediaBase64, r as MediaSource, s as isMediaBytes, t as MediaBase64 } from "../Media-D_CpcM1Z.mjs";
 export { MediaBase64, MediaBytes, MediaSource, MediaUrl, isMediaBase64, isMediaBytes, isMediaUrl };

package/dist/domain/Music.d.mts

@@ -1,4 +1,4 @@
-import { n as AudioChunk, r as AudioFormat, t as AudioBlob } from "../Audio-DDSKCkSe.mjs";
+import { n as AudioChunk, r as AudioFormat, t as AudioBlob } from "../Audio-CR7CSljJ.mjs";
 import { Duration } from "effect";
 
 //#region src/domain/Music.d.ts

package/dist/domain/Research.d.mts

@@ -0,0 +1,37 @@
+import { o as HistoryItem } from "../Items-BWNu6VGp.mjs";
+import { JobRef, JobState } from "../job/Job.mjs";
+import { Turn } from "./Turn.mjs";
+
+//#region src/domain/Research.d.ts
+declare namespace Research_d_exports {
+  export { ResearchJobRef, ResearchRequest, ResearchState };
+}
+/**
+ * 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.
+ */
+type ResearchRequest = {
+  readonly history: ReadonlyArray<HistoryItem>; /** Model / agent id. Provider default if omitted; each provider narrows. */
+  readonly model?: string;
+};
+/**
+ * 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`. */
+type ResearchJobRef = JobRef<Turn>;
+/** Current state of a research job. See {@link Job.JobState}. */
+type ResearchState = JobState<Turn>;
+//#endregion
+export { ResearchJobRef, ResearchRequest, ResearchState, Research_d_exports as t };
+//# sourceMappingURL=Research.d.mts.map

package/dist/domain/Research.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Research.d.mts","names":[],"sources":["../../src/domain/Research.ts"],"mappings":";;;;;;;;;;;;;;;;AAmBA;;;KAAY,eAAA;EAAA,SACD,OAAA,EAAS,aAAA,CAAc,WAAA,GAAd;EAAA,SAET,KAAA;AAAA;;;;AAgBX;;;;;KAAY,cAAA,GAAiB,MAAA,CAAW,IAAA;;KAG5B,aAAA,GAAgB,QAAA,CAAa,IAAA"}

package/dist/domain/Research.mjs

@@ -0,0 +1,7 @@
+import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
+//#region src/domain/Research.ts
+var Research_exports = /* @__PURE__ */ __exportAll({});
+//#endregion
+export { Research_exports as t };
+
+//# sourceMappingURL=Research.mjs.map

package/dist/domain/Research.mjs.map

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

package/dist/domain/Turn.d.mts

@@ -1,6 +1,6 @@
-import { i as ImageSource } from "../Image-C_Zjpwhc.mjs";
-import { d as Message, m as Reasoning, o as HistoryItem, v as ToolCall, x as Usage, y as ToolCallOutput } from "../Items-CgKD6Npw.mjs";
-import { i as StructuredFormat, n as JsonParseError, r as StructuredDecodeError } from "../StructuredFormat-CMJFD3sn.mjs";
+import { i as ImageSource } from "../Image-C4vuBmu0.mjs";
+import { d as Message, m as Reasoning, o as HistoryItem, t as Annotation, v as ToolCall, x as Usage, y as ToolCallOutput } from "../Items-BWNu6VGp.mjs";
+import { i as StructuredFormat, n as JsonParseError, r as StructuredDecodeError } from "../StructuredFormat-DHaUJBdd.mjs";
 import { Data, Effect, Schema, Stream } from "effect";
 import * as _$effect_Cause0 from "effect/Cause";
 import * as _$effect_Types0 from "effect/Types";
@@ -8,7 +8,7 @@ import * as _$effect_Unify0 from "effect/Unify";
 
 //#region src/domain/Turn.d.ts
 declare namespace Turn_d_exports {
-  export { InteractionEvent, RefusalRejected, Turn, TurnEvent, appendToHistory, assistantMessages, assistantText, assistantTexts, decodeStructured, getToolCalls, isTurnComplete, reasonings, textDeltas };
+  export { InteractionEvent, RefusalRejected, Turn, TurnEvent, appendToHistory, assistantMessages, assistantText, assistantTexts, citations, decodeStructured, getToolCalls, isTurnComplete, reasonings, textDeltas };
 }
 /**
  * The result of a single LLM generation. A turn produces zero or more items
@@ -31,9 +31,11 @@ declare const Turn: Schema.Struct<{
       readonly annotations: Schema.optional<Schema.$Array<Schema.Union<readonly [Schema.Struct<{
         readonly type: Schema.Literal<"url_citation">;
         readonly url: Schema.String;
-        readonly start_index: Schema.Number;
-        readonly end_index: Schema.Number;
         readonly title: Schema.String;
+        readonly start_index: Schema.optional<Schema.Number>;
+        readonly end_index: Schema.optional<Schema.Number>;
+        readonly cited_text: Schema.optional<Schema.String>;
+        readonly marker: Schema.optional<Schema.Number>;
       }>, Schema.Struct<{
         readonly type: Schema.Literal<"file_citation">;
         readonly file_id: Schema.String;
@@ -104,6 +106,14 @@ 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.
  */
 type TurnEvent = Data.TaggedEnum<{
   TextDelta: {
@@ -127,6 +137,14 @@ type TurnEvent = Data.TaggedEnum<{
   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;
   };
@@ -159,11 +177,21 @@ declare const TurnEvent: {
     readonly _tag: "UsageUpdate";
     readonly usage: Usage;
   }, "_tag">;
+  readonly WebSearchCall: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "WebSearchCall";
+    readonly status: "started" | "searching" | "completed";
+    readonly query?: string;
+    readonly action?: "search" | "open_page" | "find_in_page";
+  }, "_tag">;
+  readonly CitationAdded: Data.TaggedEnum.ConstructorFrom<{
+    readonly _tag: "CitationAdded";
+    readonly annotation: Annotation;
+  }, "_tag">;
   readonly TurnComplete: Data.TaggedEnum.ConstructorFrom<{
     readonly _tag: "TurnComplete";
     readonly turn: Turn;
   }, "_tag">;
-  readonly $is: <Tag extends "TextDelta" | "ReasoningDelta" | "RefusalDelta" | "ToolCallStart" | "ToolCallArgsDelta" | "UsageUpdate" | "TurnComplete">(tag: Tag) => (u: unknown) => u is Extract<{
+  readonly $is: <Tag extends "TextDelta" | "ReasoningDelta" | "RefusalDelta" | "ToolCallStart" | "ToolCallArgsDelta" | "UsageUpdate" | "WebSearchCall" | "CitationAdded" | "TurnComplete">(tag: Tag) => (u: unknown) => u is Extract<{
     readonly _tag: "TextDelta";
     readonly text: string;
   }, {
@@ -196,6 +224,18 @@ declare const TurnEvent: {
     readonly usage: Usage;
   }, {
     readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "WebSearchCall";
+    readonly status: "started" | "searching" | "completed";
+    readonly query?: string;
+    readonly action?: "search" | "open_page" | "find_in_page";
+  }, {
+    readonly _tag: Tag;
+  }> | Extract<{
+    readonly _tag: "CitationAdded";
+    readonly annotation: Annotation;
+  }, {
+    readonly _tag: Tag;
   }> | Extract<{
     readonly _tag: "TurnComplete";
     readonly turn: Turn;
@@ -231,6 +271,16 @@ declare const TurnEvent: {
         readonly _tag: "UsageUpdate";
         readonly usage: Usage;
       }) => any;
+      readonly WebSearchCall: (args: {
+        readonly _tag: "WebSearchCall";
+        readonly status: "started" | "searching" | "completed";
+        readonly query?: string;
+        readonly action?: "search" | "open_page" | "find_in_page";
+      }) => any;
+      readonly CitationAdded: (args: {
+        readonly _tag: "CitationAdded";
+        readonly annotation: Annotation;
+      }) => any;
       readonly TurnComplete: (args: {
         readonly _tag: "TurnComplete";
         readonly turn: Turn;
@@ -256,10 +306,18 @@ declare const TurnEvent: {
     } | {
       readonly _tag: "UsageUpdate";
       readonly usage: Usage;
+    } | {
+      readonly _tag: "WebSearchCall";
+      readonly status: "started" | "searching" | "completed";
+      readonly query?: string;
+      readonly action?: "search" | "open_page" | "find_in_page";
+    } | {
+      readonly _tag: "CitationAdded";
+      readonly annotation: Annotation;
     } | {
       readonly _tag: "TurnComplete";
       readonly turn: Turn;
-    }) => _$effect_Unify0.Unify<ReturnType<Cases["TextDelta" | "ReasoningDelta" | "RefusalDelta" | "ToolCallStart" | "ToolCallArgsDelta" | "UsageUpdate" | "TurnComplete"]>>;
+    }) => _$effect_Unify0.Unify<ReturnType<Cases["TextDelta" | "ReasoningDelta" | "RefusalDelta" | "ToolCallStart" | "ToolCallArgsDelta" | "UsageUpdate" | "WebSearchCall" | "CitationAdded" | "TurnComplete"]>>;
     <Cases extends {
       readonly TextDelta: (args: {
         readonly _tag: "TextDelta";
@@ -288,6 +346,16 @@ declare const TurnEvent: {
         readonly _tag: "UsageUpdate";
         readonly usage: Usage;
       }) => any;
+      readonly WebSearchCall: (args: {
+        readonly _tag: "WebSearchCall";
+        readonly status: "started" | "searching" | "completed";
+        readonly query?: string;
+        readonly action?: "search" | "open_page" | "find_in_page";
+      }) => any;
+      readonly CitationAdded: (args: {
+        readonly _tag: "CitationAdded";
+        readonly annotation: Annotation;
+      }) => any;
       readonly TurnComplete: (args: {
         readonly _tag: "TurnComplete";
         readonly turn: Turn;
@@ -313,10 +381,18 @@ declare const TurnEvent: {
     } | {
       readonly _tag: "UsageUpdate";
       readonly usage: Usage;
+    } | {
+      readonly _tag: "WebSearchCall";
+      readonly status: "started" | "searching" | "completed";
+      readonly query?: string;
+      readonly action?: "search" | "open_page" | "find_in_page";
+    } | {
+      readonly _tag: "CitationAdded";
+      readonly annotation: Annotation;
     } | {
       readonly _tag: "TurnComplete";
       readonly turn: Turn;
-    }, cases: Cases): _$effect_Unify0.Unify<ReturnType<Cases["TextDelta" | "ReasoningDelta" | "RefusalDelta" | "ToolCallStart" | "ToolCallArgsDelta" | "UsageUpdate" | "TurnComplete"]>>;
+    }, cases: Cases): _$effect_Unify0.Unify<ReturnType<Cases["TextDelta" | "ReasoningDelta" | "RefusalDelta" | "ToolCallStart" | "ToolCallArgsDelta" | "UsageUpdate" | "WebSearchCall" | "CitationAdded" | "TurnComplete"]>>;
   };
 };
 /**
@@ -347,6 +423,12 @@ declare const assistantTexts: (turn: Turn) => ReadonlyArray<string>;
  * that want one concatenated string.
  */
 declare const assistantText: (turn: Turn) => string;
+/**
+ * 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.
+ */
+declare const citations: (turn: Turn) => ReadonlyArray<Annotation>;
 /**
  * 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
@@ -384,5 +466,5 @@ declare class RefusalRejected extends RefusalRejected_base<{
  */
 declare const decodeStructured: <A>(turn: Turn, format: StructuredFormat<A>) => Effect.Effect<A, RefusalRejected | JsonParseError | StructuredDecodeError>;
 //#endregion
-export { InteractionEvent, RefusalRejected, Turn, TurnEvent, appendToHistory, assistantMessages, assistantText, assistantTexts, decodeStructured, getToolCalls, isTurnComplete, reasonings, Turn_d_exports as t, textDeltas };
+export { InteractionEvent, RefusalRejected, Turn, TurnEvent, appendToHistory, assistantMessages, assistantText, assistantTexts, citations, decodeStructured, getToolCalls, isTurnComplete, reasonings, Turn_d_exports as t, textDeltas };
 //# sourceMappingURL=Turn.d.mts.map

package/dist/domain/Turn.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"Turn.d.mts","names":[],"sources":["../../src/domain/Turn.ts"],"mappings":";;;;;;;;;;;;;;;;;cAqBa,IAAA,EAAI,MAAA,CAAA,MAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAKL,IAAA,UAAc,IAAA,CAAK,IAAA;;;;;;;;;;;;;;;;;;;;KAqBnB,SAAA,GAAY,IAAA,CAAK,UAAA;EAC3B,SAAA;IAAA,SAAsB,IAAA;EAAA;EACtB,cAAA;IAAA,SAA2B,IAAA;IAAA,SAAuB,IAAA;EAAA;EAClD,YAAA;IAAA,SAAyB,IAAA;EAAA;EACzB,aAAA;IAAA,SAA0B,OAAA;IAAA,SAA0B,IAAA;EAAA;EACpD,iBAAA;IAAA,SAA8B,OAAA;IAAA,SAA0B,KAAA;EAAA;EACxD,WAAA;IAAA,SAAwB,KAAA,EAAO,KAAA;EAAA;EAC/B,YAAA;IAAA,SAAyB,IAAA,EAAM,IAAA;EAAA;AAAA;AAAA,cAGpB,SAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;oBAJoB,KAAA;EAAA;EAAA;;mBACA,IAAA;EAAA;EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;oBADA,KAAA;EAAA;IAAA;;;mBACA,IAAA;EAAA;IAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBADA,KAAA;MAAA;MAAA;;uBACA,IAAA;MAAA;IAAA;;;;;;;;;;;;;;;;;;;;sBADA,KAAA;IAAA;MAAA;qBACA,IAAA;IAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;wBADA,KAAA;MAAA;MAAA;;uBACA,IAAA;MAAA;IAAA;;;;;;;;;;;;;;;;;;;;sBADA,KAAA;IAAA;MAAA;qBACA,IAAA;IAAA;;;;;;;;;KAWrB,gBAAA,GAAmB,SAAA,GAAY,cAAA;AAAA,cAE9B,cAAA,GAAc,CAAA,cAAA,CAAA;EAAA;iBAbM,IAAA;AAAA;AAAA,cAepB,YAAA,GAAgB,IAAA,EAAM,IAAA,KAAO,aAAA,CAAc,QAAA;AAAA,cAE3C,UAAA,GAAc,IAAA,EAAM,IAAA,KAAO,aAAA,CAAc,SAAA;AAAA,cAEzC,iBAAA,GAAqB,IAAA,EAAM,IAAA,KAAO,aAAA,CAAc,OAAA;;;;;;;;cAUhD,cAAA,GAAkB,IAAA,EAAM,IAAA,KAAO,aAAA;;;;;;cAW/B,aAAA,GAAiB,IAAA,EAAM,IAAA;;;;;AA/CpC;cAsDa,eAAA;EAAA,SAAwC,OAAA,EAAS,aAAA,CAAc,WAAA;AAAA,GAC1E,KAAA,EAAO,CAAA,EACP,IAAA,EAAM,IAAA,EACN,KAAA,GAAO,aAAA,CAAc,WAAA,MACpB,CAAA;;;;;;cAcU,UAAA,SACX,IAAA,EAAM,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,CAAA,EAAG,CAAA,MACjC,MAAA,CAAO,MAAA,SAAe,CAAA,EAAG,CAAA;AAAA,cAGzB,oBAAA;;;;;;;;cAWU,eAAA,SAAwB,oBAAA;EAAA,SAC1B,IAAA,EAAM,IAAA;AAAA;;;;;;;;;;AA/EjB;cAwGa,gBAAA,MACX,IAAA,EAAM,IAAA,EACN,MAAA,EAAQ,gBAAA,CAAkC,CAAA,MACzC,MAAA,CAAO,MAAA,CACR,CAAA,EACA,eAAA,GAAkB,cAAA,GAAkC,qBAAA"}
+{"version":3,"file":"Turn.d.mts","names":[],"sources":["../../src/domain/Turn.ts"],"mappings":"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"}

package/dist/domain/Turn.mjs

@@ -11,6 +11,7 @@ var Turn_exports = /* @__PURE__ */ __exportAll({
 	assistantMessages: () => assistantMessages,
 	assistantText: () => assistantText,
 	assistantTexts: () => assistantTexts,
+	citations: () => citations,
 	decodeStructured: () => decodeStructured,
 	getToolCalls: () => getToolCalls,
 	isTurnComplete: () => isTurnComplete,
@@ -47,6 +48,12 @@ const assistantTexts = (turn) => assistantMessages(turn).flatMap((m) => m.conten
 */
 const assistantText = (turn) => 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.
+*/
+const citations = (turn) => 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
 * converted to model-facing `ToolCallOutput`s.
@@ -99,6 +106,6 @@ const lastAssistantContent = (turn) => {
 */
 const decodeStructured = (turn, format) => pipe(lastAssistantContent(turn), ({ text, refused }) => refused ? Effect.fail(new RefusalRejected({ turn })) : parseJson(format)(text));
 //#endregion
-export { RefusalRejected, Turn, TurnEvent, appendToHistory, assistantMessages, assistantText, assistantTexts, decodeStructured, getToolCalls, isTurnComplete, reasonings, Turn_exports as t, textDeltas };
+export { RefusalRejected, Turn, TurnEvent, appendToHistory, assistantMessages, assistantText, assistantTexts, citations, decodeStructured, getToolCalls, isTurnComplete, reasonings, Turn_exports as t, textDeltas };
 
 //# sourceMappingURL=Turn.mjs.map

package/dist/domain/Turn.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Turn.mjs","names":["StructuredFormat.parseJson"],"sources":["../../src/domain/Turn.ts"],"sourcesContent":["import { Data, Effect, Result, Schema, Stream, pipe } from \"effect\"\nimport * as StructuredFormat from \"../structured-format/StructuredFormat.js\"\nimport {\n  HistoryItem,\n  Message,\n  Reasoning,\n  StopReason,\n  ToolCall,\n  ToolCallOutput,\n  Usage,\n  isOutputText,\n  isReasoning,\n  isRefusal,\n  isToolCall,\n} from \"./Items.js\"\n\n/**\n * The result of a single LLM generation. A turn produces zero or more items\n * (typically one assistant message and zero or more function_call items)\n * and reports usage + a stop reason.\n */\nexport const Turn = Schema.Struct({\n  items: Schema.Array(HistoryItem),\n  usage: Usage,\n  stop_reason: StopReason,\n})\nexport type Turn = typeof Turn.Type\n\n/**\n * Canonical events emitted while a single turn is being generated. Most\n * variants are streaming deltas (text, reasoning, tool-call args); the\n * terminal `TurnComplete` carries the assembled `Turn`. Lifecycle members\n * aren't deltas, hence the union name.\n *\n * `ReasoningDelta.kind`: `trace` is the model's raw chain-of-thought;\n * `summary` is a model-written summary intended for display. OpenAI\n * Responses emits both; Anthropic and Gemini only emit `trace`.\n *\n * `RefusalDelta`: the model declined to answer. OpenAI Responses emits\n * this as its own event; Anthropic surfaces refusals via `stop_reason`\n * and Gemini collapses them into `finishReason: SAFETY` — both go\n * without a `RefusalDelta`.\n *\n * `UsageUpdate`: mid-stream cumulative usage. Anthropic emits this on\n * `message_start` and `message_delta`; other providers may only deliver\n * usage via `TurnComplete.turn.usage`.\n */\nexport type TurnEvent = Data.TaggedEnum<{\n  TextDelta: { readonly text: string }\n  ReasoningDelta: { readonly text: string; readonly kind: \"trace\" | \"summary\" }\n  RefusalDelta: { readonly text: string }\n  ToolCallStart: { readonly call_id: string; readonly name: string }\n  ToolCallArgsDelta: { readonly call_id: string; readonly delta: string }\n  UsageUpdate: { readonly usage: Usage }\n  TurnComplete: { readonly turn: Turn }\n}>\n\nexport const TurnEvent = Data.taggedEnum<TurnEvent>()\n\n/**\n * What flows out of an agent loop body to its consumer per turn: every\n * `TurnEvent` the provider emits (including the terminal `TurnComplete`\n * carrying the assembled `Turn`), plus the output of any tool the loop ran.\n * Both variants carry a `_tag` discriminator.\n */\nexport type InteractionEvent = TurnEvent | ToolCallOutput\n\nexport const isTurnComplete = TurnEvent.$is(\"TurnComplete\")\n\nexport const getToolCalls = (turn: Turn): ReadonlyArray<ToolCall> => turn.items.filter(isToolCall)\n\nexport const reasonings = (turn: Turn): ReadonlyArray<Reasoning> => turn.items.filter(isReasoning)\n\nexport const assistantMessages = (turn: Turn): ReadonlyArray<Message> =>\n  turn.items.filter((i): i is Message => i.type === \"message\" && i.role === \"assistant\")\n\n/**\n * Every `output_text` payload across every assistant message in the turn,\n * preserving order. Refusals and other content blocks are dropped — use\n * `assistantMessages` if you need to inspect them. The primitive for\n * \"give me the assistant's text\"; callers decide how to combine\n * (typically `.join(\"\")` for prose or `.join(\" \")` for log strings).\n */\nexport const assistantTexts = (turn: Turn): ReadonlyArray<string> =>\n  assistantMessages(turn)\n    .flatMap((m) => m.content)\n    .filter(isOutputText)\n    .map((b) => b.text)\n\n/**\n * Sugar over `assistantTexts(turn).join(\"\")` — the common case for\n * summarizers, classifiers, judge calls, and structured-output backstops\n * that want one concatenated string.\n */\nexport const assistantText = (turn: Turn): string => assistantTexts(turn).join(\"\")\n\n/**\n * Append a completed turn and optional follow-up items to a state record's\n * history. Recipes use this at the point where structured tool results are\n * converted to model-facing `ToolCallOutput`s.\n */\nexport const appendToHistory = <S extends { readonly history: ReadonlyArray<HistoryItem> }>(\n  state: S,\n  turn: Turn,\n  items: ReadonlyArray<HistoryItem> = [],\n): S => ({\n  ...state,\n  history: [...state.history, ...turn.items, ...items],\n})\n\n// ---------------------------------------------------------------------------\n// Stream operators\n// ---------------------------------------------------------------------------\n\n/**\n * Project a `TurnEvent` stream onto its `TextDelta` payloads. Other\n * variants are dropped. Composes with `Lines.lines` +\n * `decodeJsonLines` for prompted-JSONL streaming.\n */\nexport const textDeltas = <E, R>(\n  self: Stream.Stream<TurnEvent, E, R>,\n): Stream.Stream<string, E, R> =>\n  self.pipe(\n    Stream.filterMap((ev) => (ev._tag === \"TextDelta\" ? Result.succeed(ev.text) : Result.failVoid)),\n  )\n\n// ---------------------------------------------------------------------------\n// Structured-output integration\n// ---------------------------------------------------------------------------\n\n/**\n * The assistant message on the just-completed turn was a refusal block,\n * not an `output_text` payload. Returned by `decodeStructured` to short-circuit\n * decoding before `JSON.parse` / schema validation runs.\n */\nexport class RefusalRejected extends Data.TaggedError(\"RefusalRejected\")<{\n  readonly turn: Turn\n}> {}\n\nconst lastAssistantContent = (turn: Turn): { readonly text: string; readonly refused: boolean } => {\n  const assistants = assistantMessages(turn)\n  const last = assistants[assistants.length - 1]\n  if (last === undefined) return { text: \"\", refused: false }\n  if (last.content.some(isRefusal)) return { text: \"\", refused: true }\n  const text = last.content\n    .filter(isOutputText)\n    .map((b) => b.text)\n    .join(\"\")\n  return { text, refused: false }\n}\n\n/**\n * Validate a completed `Turn` against a `StructuredFormat`. Concatenates\n * `output_text` blocks on the last assistant message, then runs\n * `JSON.parse` + the format's schema validation.\n *\n * Three failure modes:\n * - `RefusalRejected` — the assistant emitted a refusal block.\n * - `JsonParseError` — the assembled text wasn't valid JSON.\n * - `StructuredDecodeError` — the JSON didn't match the schema.\n */\nexport const decodeStructured = <A>(\n  turn: Turn,\n  format: StructuredFormat.StructuredFormat<A>,\n): Effect.Effect<\n  A,\n  RefusalRejected | StructuredFormat.JsonParseError | StructuredFormat.StructuredDecodeError\n> =>\n  pipe(lastAssistantContent(turn), ({ text, refused }) =>\n    refused ? Effect.fail(new RefusalRejected({ turn })) : StructuredFormat.parseJson(format)(text),\n  )\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAqBA,MAAa,OAAO,OAAO,OAAO;CAChC,OAAO,OAAO,MAAM,YAAY;CAChC,OAAO;CACP,aAAa;CACd,CAAC;AAgCF,MAAa,YAAY,KAAK,YAAuB;AAUrD,MAAa,iBAAiB,UAAU,IAAI,eAAe;AAE3D,MAAa,gBAAgB,SAAwC,KAAK,MAAM,OAAO,WAAW;AAElG,MAAa,cAAc,SAAyC,KAAK,MAAM,OAAO,YAAY;AAElG,MAAa,qBAAqB,SAChC,KAAK,MAAM,QAAQ,MAAoB,EAAE,SAAS,aAAa,EAAE,SAAS,YAAY;;;;;;;;AASxF,MAAa,kBAAkB,SAC7B,kBAAkB,KAAK,CACpB,SAAS,MAAM,EAAE,QAAQ,CACzB,OAAO,aAAa,CACpB,KAAK,MAAM,EAAE,KAAK;;;;;;AAOvB,MAAa,iBAAiB,SAAuB,eAAe,KAAK,CAAC,KAAK,GAAG;;;;;;AAOlF,MAAa,mBACX,OACA,MACA,QAAoC,EAAE,MAC/B;CACP,GAAG;CACH,SAAS;EAAC,GAAG,MAAM;EAAS,GAAG,KAAK;EAAO,GAAG;EAAM;CACrD;;;;;;AAWD,MAAa,cACX,SAEA,KAAK,KACH,OAAO,WAAW,OAAQ,GAAG,SAAS,cAAc,OAAO,QAAQ,GAAG,KAAK,GAAG,OAAO,SAAU,CAChG;;;;;;AAWH,IAAa,kBAAb,cAAqC,KAAK,YAAY,kBAAkB,CAErE;AAEH,MAAM,wBAAwB,SAAqE;CACjG,MAAM,aAAa,kBAAkB,KAAK;CAC1C,MAAM,OAAO,WAAW,WAAW,SAAS;AAC5C,KAAI,SAAS,KAAA,EAAW,QAAO;EAAE,MAAM;EAAI,SAAS;EAAO;AAC3D,KAAI,KAAK,QAAQ,KAAK,UAAU,CAAE,QAAO;EAAE,MAAM;EAAI,SAAS;EAAM;AAKpE,QAAO;EAAE,MAJI,KAAK,QACf,OAAO,aAAa,CACpB,KAAK,MAAM,EAAE,KAAK,CAClB,KAAK,GACK;EAAE,SAAS;EAAO;;;;;;;;;;;;AAajC,MAAa,oBACX,MACA,WAKA,KAAK,qBAAqB,KAAK,GAAG,EAAE,MAAM,cACxC,UAAU,OAAO,KAAK,IAAI,gBAAgB,EAAE,MAAM,CAAC,CAAC,GAAGA,UAA2B,OAAO,CAAC,KAAK,CAChG"}
+{"version":3,"file":"Turn.mjs","names":["StructuredFormat.parseJson"],"sources":["../../src/domain/Turn.ts"],"sourcesContent":["import { Data, Effect, Result, Schema, Stream, pipe } from \"effect\"\nimport * as StructuredFormat from \"../structured-format/StructuredFormat.js\"\nimport {\n  type Annotation,\n  HistoryItem,\n  Message,\n  Reasoning,\n  StopReason,\n  ToolCall,\n  ToolCallOutput,\n  Usage,\n  isOutputText,\n  isReasoning,\n  isRefusal,\n  isToolCall,\n} from \"./Items.js\"\n\n/**\n * The result of a single LLM generation. A turn produces zero or more items\n * (typically one assistant message and zero or more function_call items)\n * and reports usage + a stop reason.\n */\nexport const Turn = Schema.Struct({\n  items: Schema.Array(HistoryItem),\n  usage: Usage,\n  stop_reason: StopReason,\n})\nexport type Turn = typeof Turn.Type\n\n/**\n * Canonical events emitted while a single turn is being generated. Most\n * variants are streaming deltas (text, reasoning, tool-call args); the\n * terminal `TurnComplete` carries the assembled `Turn`. Lifecycle members\n * aren't deltas, hence the union name.\n *\n * `ReasoningDelta.kind`: `trace` is the model's raw chain-of-thought;\n * `summary` is a model-written summary intended for display. OpenAI\n * Responses emits both; Anthropic and Gemini only emit `trace`.\n *\n * `RefusalDelta`: the model declined to answer. OpenAI Responses emits\n * this as its own event; Anthropic surfaces refusals via `stop_reason`\n * and Gemini collapses them into `finishReason: SAFETY` — both go\n * without a `RefusalDelta`.\n *\n * `UsageUpdate`: mid-stream cumulative usage. Anthropic emits this on\n * `message_start` and `message_delta`; other providers may only deliver\n * usage via `TurnComplete.turn.usage`.\n *\n * `WebSearchCall`: lifecycle of a provider-executed web search within the\n * turn. Fires only when the turn grounds against search; absent otherwise.\n *\n * `CitationAdded`: a citation attached to the answer, emitted incrementally\n * where the provider streams citations. Providers that bundle citations emit\n * none of these; their citations still arrive on `TurnComplete.turn`\n * (`OutputText.annotations`). Either way the final set is on the assembled turn.\n */\nexport type TurnEvent = Data.TaggedEnum<{\n  TextDelta: { readonly text: string }\n  ReasoningDelta: { readonly text: string; readonly kind: \"trace\" | \"summary\" }\n  RefusalDelta: { readonly text: string }\n  ToolCallStart: { readonly call_id: string; readonly name: string }\n  ToolCallArgsDelta: { readonly call_id: string; readonly delta: string }\n  UsageUpdate: { readonly usage: Usage }\n  WebSearchCall: {\n    readonly status: \"started\" | \"searching\" | \"completed\"\n    readonly query?: string\n    readonly action?: \"search\" | \"open_page\" | \"find_in_page\"\n  }\n  CitationAdded: { readonly annotation: Annotation }\n  TurnComplete: { readonly turn: Turn }\n}>\n\nexport const TurnEvent = Data.taggedEnum<TurnEvent>()\n\n/**\n * What flows out of an agent loop body to its consumer per turn: every\n * `TurnEvent` the provider emits (including the terminal `TurnComplete`\n * carrying the assembled `Turn`), plus the output of any tool the loop ran.\n * Both variants carry a `_tag` discriminator.\n */\nexport type InteractionEvent = TurnEvent | ToolCallOutput\n\nexport const isTurnComplete = TurnEvent.$is(\"TurnComplete\")\n\nexport const getToolCalls = (turn: Turn): ReadonlyArray<ToolCall> => turn.items.filter(isToolCall)\n\nexport const reasonings = (turn: Turn): ReadonlyArray<Reasoning> => turn.items.filter(isReasoning)\n\nexport const assistantMessages = (turn: Turn): ReadonlyArray<Message> =>\n  turn.items.filter((i): i is Message => i.type === \"message\" && i.role === \"assistant\")\n\n/**\n * Every `output_text` payload across every assistant message in the turn,\n * preserving order. Refusals and other content blocks are dropped — use\n * `assistantMessages` if you need to inspect them. The primitive for\n * \"give me the assistant's text\"; callers decide how to combine\n * (typically `.join(\"\")` for prose or `.join(\" \")` for log strings).\n */\nexport const assistantTexts = (turn: Turn): ReadonlyArray<string> =>\n  assistantMessages(turn)\n    .flatMap((m) => m.content)\n    .filter(isOutputText)\n    .map((b) => b.text)\n\n/**\n * Sugar over `assistantTexts(turn).join(\"\")` — the common case for\n * summarizers, classifiers, judge calls, and structured-output backstops\n * that want one concatenated string.\n */\nexport const assistantText = (turn: Turn): string => assistantTexts(turn).join(\"\")\n\n/**\n * Every citation annotation attached to the turn's assistant `output_text`\n * blocks, in order. The flat view of a grounded turn's sources, whether the\n * turn came from a normal generation with native search or a deep-research job.\n */\nexport const citations = (turn: Turn): ReadonlyArray<Annotation> =>\n  assistantMessages(turn)\n    .flatMap((m) => m.content)\n    .filter(isOutputText)\n    .flatMap((b) => b.annotations ?? [])\n\n/**\n * Append a completed turn and optional follow-up items to a state record's\n * history. Recipes use this at the point where structured tool results are\n * converted to model-facing `ToolCallOutput`s.\n */\nexport const appendToHistory = <S extends { readonly history: ReadonlyArray<HistoryItem> }>(\n  state: S,\n  turn: Turn,\n  items: ReadonlyArray<HistoryItem> = [],\n): S => ({\n  ...state,\n  history: [...state.history, ...turn.items, ...items],\n})\n\n// ---------------------------------------------------------------------------\n// Stream operators\n// ---------------------------------------------------------------------------\n\n/**\n * Project a `TurnEvent` stream onto its `TextDelta` payloads. Other\n * variants are dropped. Composes with `Lines.lines` +\n * `decodeJsonLines` for prompted-JSONL streaming.\n */\nexport const textDeltas = <E, R>(\n  self: Stream.Stream<TurnEvent, E, R>,\n): Stream.Stream<string, E, R> =>\n  self.pipe(\n    Stream.filterMap((ev) => (ev._tag === \"TextDelta\" ? Result.succeed(ev.text) : Result.failVoid)),\n  )\n\n// ---------------------------------------------------------------------------\n// Structured-output integration\n// ---------------------------------------------------------------------------\n\n/**\n * The assistant message on the just-completed turn was a refusal block,\n * not an `output_text` payload. Returned by `decodeStructured` to short-circuit\n * decoding before `JSON.parse` / schema validation runs.\n */\nexport class RefusalRejected extends Data.TaggedError(\"RefusalRejected\")<{\n  readonly turn: Turn\n}> {}\n\nconst lastAssistantContent = (turn: Turn): { readonly text: string; readonly refused: boolean } => {\n  const assistants = assistantMessages(turn)\n  const last = assistants[assistants.length - 1]\n  if (last === undefined) return { text: \"\", refused: false }\n  if (last.content.some(isRefusal)) return { text: \"\", refused: true }\n  const text = last.content\n    .filter(isOutputText)\n    .map((b) => b.text)\n    .join(\"\")\n  return { text, refused: false }\n}\n\n/**\n * Validate a completed `Turn` against a `StructuredFormat`. Concatenates\n * `output_text` blocks on the last assistant message, then runs\n * `JSON.parse` + the format's schema validation.\n *\n * Three failure modes:\n * - `RefusalRejected` — the assistant emitted a refusal block.\n * - `JsonParseError` — the assembled text wasn't valid JSON.\n * - `StructuredDecodeError` — the JSON didn't match the schema.\n */\nexport const decodeStructured = <A>(\n  turn: Turn,\n  format: StructuredFormat.StructuredFormat<A>,\n): Effect.Effect<\n  A,\n  RefusalRejected | StructuredFormat.JsonParseError | StructuredFormat.StructuredDecodeError\n> =>\n  pipe(lastAssistantContent(turn), ({ text, refused }) =>\n    refused ? Effect.fail(new RefusalRejected({ turn })) : StructuredFormat.parseJson(format)(text),\n  )\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAsBA,MAAa,OAAO,OAAO,OAAO;CAChC,OAAO,OAAO,MAAM,YAAY;CAChC,OAAO;CACP,aAAa;CACd,CAAC;AA8CF,MAAa,YAAY,KAAK,YAAuB;AAUrD,MAAa,iBAAiB,UAAU,IAAI,eAAe;AAE3D,MAAa,gBAAgB,SAAwC,KAAK,MAAM,OAAO,WAAW;AAElG,MAAa,cAAc,SAAyC,KAAK,MAAM,OAAO,YAAY;AAElG,MAAa,qBAAqB,SAChC,KAAK,MAAM,QAAQ,MAAoB,EAAE,SAAS,aAAa,EAAE,SAAS,YAAY;;;;;;;;AASxF,MAAa,kBAAkB,SAC7B,kBAAkB,KAAK,CACpB,SAAS,MAAM,EAAE,QAAQ,CACzB,OAAO,aAAa,CACpB,KAAK,MAAM,EAAE,KAAK;;;;;;AAOvB,MAAa,iBAAiB,SAAuB,eAAe,KAAK,CAAC,KAAK,GAAG;;;;;;AAOlF,MAAa,aAAa,SACxB,kBAAkB,KAAK,CACpB,SAAS,MAAM,EAAE,QAAQ,CACzB,OAAO,aAAa,CACpB,SAAS,MAAM,EAAE,eAAe,EAAE,CAAC;;;;;;AAOxC,MAAa,mBACX,OACA,MACA,QAAoC,EAAE,MAC/B;CACP,GAAG;CACH,SAAS;EAAC,GAAG,MAAM;EAAS,GAAG,KAAK;EAAO,GAAG;EAAM;CACrD;;;;;;AAWD,MAAa,cACX,SAEA,KAAK,KACH,OAAO,WAAW,OAAQ,GAAG,SAAS,cAAc,OAAO,QAAQ,GAAG,KAAK,GAAG,OAAO,SAAU,CAChG;;;;;;AAWH,IAAa,kBAAb,cAAqC,KAAK,YAAY,kBAAkB,CAErE;AAEH,MAAM,wBAAwB,SAAqE;CACjG,MAAM,aAAa,kBAAkB,KAAK;CAC1C,MAAM,OAAO,WAAW,WAAW,SAAS;AAC5C,KAAI,SAAS,KAAA,EAAW,QAAO;EAAE,MAAM;EAAI,SAAS;EAAO;AAC3D,KAAI,KAAK,QAAQ,KAAK,UAAU,CAAE,QAAO;EAAE,MAAM;EAAI,SAAS;EAAM;AAKpE,QAAO;EAAE,MAJI,KAAK,QACf,OAAO,aAAa,CACpB,KAAK,MAAM,EAAE,KAAK,CAClB,KAAK,GACK;EAAE,SAAS;EAAO;;;;;;;;;;;;AAajC,MAAa,oBACX,MACA,WAKA,KAAK,qBAAqB,KAAK,GAAG,EAAE,MAAM,cACxC,UAAU,OAAO,KAAK,IAAI,gBAAgB,EAAE,MAAM,CAAC,CAAC,GAAGA,UAA2B,OAAO,CAAC,KAAK,CAChG"}