@effect-uai/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Betalyra Sociedade Unipessoal Lda.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,43 @@
+# @effect-uai/core
+
+Low-level primitives for building AI agents with [Effect](https://effect.website).
+
+The core thesis: **the user owns the loop**. State is a plain record;
+`Loop` events control iteration; the body is a `Stream`. There is no
+agent runtime, no orchestrator, no provider lock-in.
+
+This package exposes:
+
+- **Domain types** - `Items`, `Turn`, `AiError`
+- **Provider contract** - `LanguageModel`
+- **Loop primitive** - `Loop` (`loop`, `value`, `next`, `stop`, `nextAfter`, `nextAfterFold`, `streamUntilComplete`)
+- **Tools** - `Tool`, `Toolkit`, `Outcome`, `ToolEvent`, `Resolvers`, `HistoryCheck`
+- **Streaming codecs** - `SSE`, `JSONL`, `Lines`
+- **Structured output** - `StructuredFormat`
+- **Observability** - `Metrics`
+- **Testing** - `testing/MockProvider`
+
+No provider deps. Pair with one of:
+
+- [`@effect-uai/responses`](https://www.npmjs.com/package/@effect-uai/responses) - OpenAI Responses API
+- [`@effect-uai/anthropic`](https://www.npmjs.com/package/@effect-uai/anthropic) - Anthropic Messages
+- [`@effect-uai/google`](https://www.npmjs.com/package/@effect-uai/google) - Google Gemini
+
+## Install
+
+```sh
+pnpm add @effect-uai/core effect
+```
+
+ESM-only. Requires `effect@4.x` as a peer.
+
+## Docs
+
+Full docs: <https://effect-uai.betalyra.com>
+
+Start with the [Quickstart](https://effect-uai.betalyra.com/start/getting-started/)
+and then [Basic usage](https://effect-uai.betalyra.com/recipes/basic-usage/).
+
+## License
+
+MIT

package/dist/AiError-CqmYjXyx.d.mts

@@ -0,0 +1,110 @@
+import { Duration } from "effect";
+import * as _$effect_Types0 from "effect/Types";
+import * as _$effect_Cause0 from "effect/Cause";
+
+//#region src/domain/AiError.d.ts
+declare namespace AiError_d_exports {
+  export { AiError, AuthFailed, AuthSubtype, Cancelled, ContentFiltered, ContextLengthExceeded, GenerationFailed, IncompleteTurn, InvalidRequest, RateLimited, Scope$1 as Scope, Timeout, Unavailable };
+}
+type Scope$1 = "rpm" | "tpm" | "rpd" | "tpd";
+declare const RateLimited_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "RateLimited";
+} & Readonly<A>;
+declare class RateLimited extends RateLimited_base<{
+  provider: string;
+  retryAfter?: Duration.Duration;
+  scope?: Scope$1;
+  requestId?: string;
+  raw: unknown;
+}> {}
+declare const Unavailable_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "Unavailable";
+} & Readonly<A>;
+declare class Unavailable extends Unavailable_base<{
+  provider: string;
+  retryAfter?: Duration.Duration;
+  status?: number;
+  requestId?: string;
+  raw: unknown;
+}> {}
+declare const Timeout_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "Timeout";
+} & Readonly<A>;
+declare class Timeout extends Timeout_base<{
+  provider: string;
+  requestId?: string;
+  raw: unknown;
+}> {}
+declare const ContentFiltered_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "ContentFiltered";
+} & Readonly<A>;
+declare class ContentFiltered extends ContentFiltered_base<{
+  provider: string;
+  reason?: string;
+  requestId?: string;
+  raw: unknown;
+}> {}
+declare const ContextLengthExceeded_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "ContextLengthExceeded";
+} & Readonly<A>;
+declare class ContextLengthExceeded extends ContextLengthExceeded_base<{
+  provider: string;
+  modelLimit?: number;
+  requested?: number;
+  raw: unknown;
+}> {}
+declare const InvalidRequest_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "InvalidRequest";
+} & Readonly<A>;
+declare class InvalidRequest extends InvalidRequest_base<{
+  provider: string;
+  param?: string;
+  requestId?: string;
+  raw: unknown;
+}> {}
+type AuthSubtype = "auth" | "permission" | "billing" | "quota";
+declare const AuthFailed_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "AuthFailed";
+} & Readonly<A>;
+declare class AuthFailed extends AuthFailed_base<{
+  provider: string;
+  subtype: AuthSubtype;
+  raw: unknown;
+}> {}
+declare const Cancelled_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "Cancelled";
+} & Readonly<A>;
+declare class Cancelled extends Cancelled_base<{
+  provider: string;
+}> {}
+declare const GenerationFailed_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "GenerationFailed";
+} & Readonly<A>;
+/**
+ * The model errored mid-generation. Distinct from `Unavailable` (transport
+ * problem before generation started) and from `IncompleteTurn` (provider
+ * stream ended without a terminal event). The provider's own error message,
+ * if any, is on `message`.
+ */
+declare class GenerationFailed extends GenerationFailed_base<{
+  provider: string;
+  code?: string;
+  message?: string;
+  requestId?: string;
+  raw: unknown;
+}> {}
+declare const IncompleteTurn_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "IncompleteTurn";
+} & Readonly<A>;
+/**
+ * The provider's delta stream ended without a terminal `turn_complete`.
+ * Indicates a misbehaving provider or a connection that dropped mid-flight.
+ * Non-terminal deltas seen so far have already been emitted downstream.
+ */
+declare class IncompleteTurn extends IncompleteTurn_base<{
+  raw?: unknown;
+}> {}
+type AiError = RateLimited | Unavailable | Timeout | ContentFiltered | ContextLengthExceeded | InvalidRequest | AuthFailed | Cancelled | IncompleteTurn | GenerationFailed;
+//#endregion
+export { Cancelled as a, GenerationFailed as c, RateLimited as d, Scope$1 as f, AuthSubtype as i, IncompleteTurn as l, Unavailable as m, AiError_d_exports as n, ContentFiltered as o, Timeout as p, AuthFailed as r, ContextLengthExceeded as s, AiError as t, InvalidRequest as u };
+//# sourceMappingURL=AiError-CqmYjXyx.d.mts.map

package/dist/AiError-CqmYjXyx.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AiError-CqmYjXyx.d.mts","names":[],"sources":["../src/domain/AiError.ts"],"mappings":";;;;;;;;KAEY,OAAA;AAAA,cAAqC,gBAAA;;;cAEpC,WAAA,SAAoB,gBAAA;EAC/B,QAAA;EACA,UAAA,GAAa,QAAA,CAAS,QAAA;EACtB,KAAA,GAAQ,OAAA;EACR,SAAA;EACA,GAAA;AAAA;AAAA,cACG,gBAAA;;;cAEQ,WAAA,SAAoB,gBAAA;EAC/B,QAAA;EACA,UAAA,GAAa,QAAA,CAAS,QAAA;EACtB,MAAA;EACA,SAAA;EACA,GAAA;AAAA;AAAA,cACG,YAAA;;;cAEQ,OAAA,SAAgB,YAAA;EAC3B,QAAA;EACA,SAAA;EACA,GAAA;AAAA;AAAA,cACG,oBAAA;;;cAEQ,eAAA,SAAwB,oBAAA;EACnC,QAAA;EACA,MAAA;EACA,SAAA;EACA,GAAA;AAAA;AAAA,cACG,0BAAA;;;cAEQ,qBAAA,SAA8B,0BAAA;EACzC,QAAA;EACA,UAAA;EACA,SAAA;EACA,GAAA;AAAA;AAAA,cACG,mBAAA;;;cAEQ,cAAA,SAAuB,mBAAA;EAClC,QAAA;EACA,KAAA;EACA,SAAA;EACA,GAAA;AAAA;AAAA,KAGU,WAAA;AAAA,cAAyD,eAAA;;;cAExD,UAAA,SAAmB,eAAA;EAC9B,QAAA;EACA,OAAA,EAAS,WAAA;EACT,GAAA;AAAA;AAAA,cACG,cAAA;;;cAEQ,SAAA,SAAkB,cAAA;EAC7B,QAAA;AAAA;AAAA,cACG,qBAAA;;;;;;;;;cAQQ,gBAAA,SAAyB,qBAAA;EACpC,QAAA;EACA,IAAA;EACA,OAAA;EACA,SAAA;EACA,GAAA;AAAA;AAAA,cACG,mBAAA;;;;;;;;cAOQ,cAAA,SAAuB,mBAAA;EAClC,GAAA;AAAA;AAAA,KAGU,OAAA,GACR,WAAA,GACA,WAAA,GACA,OAAA,GACA,eAAA,GACA,qBAAA,GACA,cAAA,GACA,UAAA,GACA,SAAA,GACA,cAAA,GACA,gBAAA"}

package/dist/Items-D1C2686t.d.mts

@@ -0,0 +1,372 @@
+import { Schema } from "effect";
+
+//#region src/domain/Items.d.ts
+declare namespace Items_d_exports {
+  export { Annotation, ContainerFileCitation, ContentBlock, FileCitation, FilePath, FunctionCall, FunctionCallOutput, ImageBase64Source, ImageSource, ImageUrlSource, InputImage, InputText, InputTokensDetails, Item, Message, OutputText, OutputTokensDetails, Reasoning, Refusal, Role, StopReason, UrlCitation, Usage, assistantText, functionCallOutput, isContainerFileCitation, isFileCitation, isFilePath, isFunctionCall, isFunctionCallOutput, isImageBase64Source, isImageUrlSource, isInputImage, isInputText, isMessage, isOutputText, isReasoning, isRefusal, isUrlCitation, systemText, userText };
+}
+declare const InputText: Schema.Struct<{
+  readonly type: Schema.Literal<"input_text">;
+  readonly text: Schema.String;
+}>;
+type InputText = typeof InputText.Type;
+/**
+ * Where an image lives. `url` covers HTTP(S) URLs (the model fetches
+ * them); `base64` covers inline bytes embedded in the request. Provider
+ * encoders dispatch on `_tag`. File-id / uploaded-asset references are
+ * provider-specific and stay out of this union for now.
+ */
+declare const ImageUrlSource: Schema.Struct<{
+  readonly _tag: Schema.Literal<"url">;
+  readonly url: Schema.String;
+}>;
+type ImageUrlSource = typeof ImageUrlSource.Type;
+/**
+ * Inline image bytes. `data` is **already base64-encoded** (matches what
+ * the wire formats expect; no double-encoding needed downstream).
+ * `media_type` is the MIME type, e.g. `"image/png"`.
+ */
+declare const ImageBase64Source: Schema.Struct<{
+  readonly _tag: Schema.Literal<"base64">;
+  readonly media_type: Schema.String;
+  readonly data: Schema.String;
+}>;
+type ImageBase64Source = typeof ImageBase64Source.Type;
+declare const ImageSource: Schema.Union<readonly [Schema.Struct<{
+  readonly _tag: Schema.Literal<"url">;
+  readonly url: Schema.String;
+}>, Schema.Struct<{
+  readonly _tag: Schema.Literal<"base64">;
+  readonly media_type: Schema.String;
+  readonly data: Schema.String;
+}>]>;
+type ImageSource = typeof ImageSource.Type;
+declare const isImageUrlSource: (s: ImageSource) => s is ImageUrlSource;
+declare const isImageBase64Source: (s: ImageSource) => s is ImageBase64Source;
+/**
+ * User-provided image content block. Pair with `InputText` inside a
+ * `Message.content` array to ask "what's in this image?" style questions.
+ */
+declare const InputImage: Schema.Struct<{
+  readonly type: Schema.Literal<"input_image">;
+  readonly source: Schema.Union<readonly [Schema.Struct<{
+    readonly _tag: Schema.Literal<"url">;
+    readonly url: Schema.String;
+  }>, Schema.Struct<{
+    readonly _tag: Schema.Literal<"base64">;
+    readonly media_type: Schema.String;
+    readonly data: Schema.String;
+  }>]>;
+}>;
+type InputImage = typeof InputImage.Type;
+declare const UrlCitation: 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;
+}>;
+type UrlCitation = typeof UrlCitation.Type;
+declare const FileCitation: Schema.Struct<{
+  readonly type: Schema.Literal<"file_citation">;
+  readonly file_id: Schema.String;
+  readonly index: Schema.Number;
+}>;
+type FileCitation = typeof FileCitation.Type;
+declare const ContainerFileCitation: Schema.Struct<{
+  readonly type: Schema.Literal<"container_file_citation">;
+  readonly container_id: Schema.String;
+  readonly file_id: Schema.String;
+  readonly start_index: Schema.Number;
+  readonly end_index: Schema.Number;
+}>;
+type ContainerFileCitation = typeof ContainerFileCitation.Type;
+declare const FilePath: Schema.Struct<{
+  readonly type: Schema.Literal<"file_path">;
+  readonly file_id: Schema.String;
+  readonly index: Schema.Number;
+}>;
+type FilePath = typeof FilePath.Type;
+declare const Annotation: 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;
+}>, Schema.Struct<{
+  readonly type: Schema.Literal<"file_citation">;
+  readonly file_id: Schema.String;
+  readonly index: Schema.Number;
+}>, Schema.Struct<{
+  readonly type: Schema.Literal<"container_file_citation">;
+  readonly container_id: Schema.String;
+  readonly file_id: Schema.String;
+  readonly start_index: Schema.Number;
+  readonly end_index: Schema.Number;
+}>, Schema.Struct<{
+  readonly type: Schema.Literal<"file_path">;
+  readonly file_id: Schema.String;
+  readonly index: Schema.Number;
+}>]>;
+type Annotation = typeof Annotation.Type;
+declare const isUrlCitation: (a: Annotation) => a is UrlCitation;
+declare const isFileCitation: (a: Annotation) => a is FileCitation;
+declare const isContainerFileCitation: (a: Annotation) => a is ContainerFileCitation;
+declare const isFilePath: (a: Annotation) => a is FilePath;
+declare const OutputText: Schema.Struct<{
+  readonly type: Schema.Literal<"output_text">;
+  readonly text: Schema.String;
+  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;
+  }>, Schema.Struct<{
+    readonly type: Schema.Literal<"file_citation">;
+    readonly file_id: Schema.String;
+    readonly index: Schema.Number;
+  }>, Schema.Struct<{
+    readonly type: Schema.Literal<"container_file_citation">;
+    readonly container_id: Schema.String;
+    readonly file_id: Schema.String;
+    readonly start_index: Schema.Number;
+    readonly end_index: Schema.Number;
+  }>, Schema.Struct<{
+    readonly type: Schema.Literal<"file_path">;
+    readonly file_id: Schema.String;
+    readonly index: Schema.Number;
+  }>]>>>;
+}>;
+type OutputText = typeof OutputText.Type;
+/**
+ * Model-emitted refusal. Distinct from `output_text`: the model declined
+ * to answer rather than producing normal output. Pair with
+ * `stop_reason: "refusal"` on the surrounding `Turn`. Streamed via the
+ * `refusal_delta` `TurnEvent`.
+ */
+declare const Refusal: Schema.Struct<{
+  readonly type: Schema.Literal<"refusal">;
+  readonly text: Schema.String;
+}>;
+type Refusal = typeof Refusal.Type;
+declare const ContentBlock: Schema.Union<readonly [Schema.Struct<{
+  readonly type: Schema.Literal<"input_text">;
+  readonly text: Schema.String;
+}>, Schema.Struct<{
+  readonly type: Schema.Literal<"input_image">;
+  readonly source: Schema.Union<readonly [Schema.Struct<{
+    readonly _tag: Schema.Literal<"url">;
+    readonly url: Schema.String;
+  }>, Schema.Struct<{
+    readonly _tag: Schema.Literal<"base64">;
+    readonly media_type: Schema.String;
+    readonly data: Schema.String;
+  }>]>;
+}>, Schema.Struct<{
+  readonly type: Schema.Literal<"output_text">;
+  readonly text: Schema.String;
+  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;
+  }>, Schema.Struct<{
+    readonly type: Schema.Literal<"file_citation">;
+    readonly file_id: Schema.String;
+    readonly index: Schema.Number;
+  }>, Schema.Struct<{
+    readonly type: Schema.Literal<"container_file_citation">;
+    readonly container_id: Schema.String;
+    readonly file_id: Schema.String;
+    readonly start_index: Schema.Number;
+    readonly end_index: Schema.Number;
+  }>, Schema.Struct<{
+    readonly type: Schema.Literal<"file_path">;
+    readonly file_id: Schema.String;
+    readonly index: Schema.Number;
+  }>]>>>;
+}>, Schema.Struct<{
+  readonly type: Schema.Literal<"refusal">;
+  readonly text: Schema.String;
+}>]>;
+type ContentBlock = typeof ContentBlock.Type;
+declare const Role: Schema.Literals<readonly ["user", "assistant", "system"]>;
+type Role = typeof Role.Type;
+declare const Message: Schema.Struct<{
+  readonly type: Schema.Literal<"message">;
+  readonly role: Schema.Literals<readonly ["user", "assistant", "system"]>;
+  readonly content: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"input_text">;
+    readonly text: Schema.String;
+  }>, Schema.Struct<{
+    readonly type: Schema.Literal<"input_image">;
+    readonly source: Schema.Union<readonly [Schema.Struct<{
+      readonly _tag: Schema.Literal<"url">;
+      readonly url: Schema.String;
+    }>, Schema.Struct<{
+      readonly _tag: Schema.Literal<"base64">;
+      readonly media_type: Schema.String;
+      readonly data: Schema.String;
+    }>]>;
+  }>, Schema.Struct<{
+    readonly type: Schema.Literal<"output_text">;
+    readonly text: Schema.String;
+    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;
+    }>, Schema.Struct<{
+      readonly type: Schema.Literal<"file_citation">;
+      readonly file_id: Schema.String;
+      readonly index: Schema.Number;
+    }>, Schema.Struct<{
+      readonly type: Schema.Literal<"container_file_citation">;
+      readonly container_id: Schema.String;
+      readonly file_id: Schema.String;
+      readonly start_index: Schema.Number;
+      readonly end_index: Schema.Number;
+    }>, Schema.Struct<{
+      readonly type: Schema.Literal<"file_path">;
+      readonly file_id: Schema.String;
+      readonly index: Schema.Number;
+    }>]>>>;
+  }>, Schema.Struct<{
+    readonly type: Schema.Literal<"refusal">;
+    readonly text: Schema.String;
+  }>]>>;
+  readonly providerData: Schema.optional<Schema.Unknown>;
+}>;
+type Message = typeof Message.Type;
+declare const FunctionCall: Schema.Struct<{
+  readonly type: Schema.Literal<"function_call">;
+  readonly call_id: Schema.String;
+  readonly name: Schema.String;
+  readonly arguments: Schema.String;
+  readonly providerData: Schema.optional<Schema.Unknown>;
+}>;
+type FunctionCall = typeof FunctionCall.Type;
+declare const FunctionCallOutput: Schema.Struct<{
+  readonly type: Schema.Literal<"function_call_output">;
+  readonly call_id: Schema.String;
+  readonly output: Schema.String;
+  readonly providerData: Schema.optional<Schema.Unknown>;
+}>;
+type FunctionCallOutput = typeof FunctionCallOutput.Type;
+/**
+ * Reasoning item - top-level, mirrors OpenAI Responses API. Common shape
+ * across providers covers `summary` (human-readable text) and `signature`
+ * (opaque round-trip blob - Anthropic's signed thinking, OpenAI's
+ * encrypted_content, etc.). Provider-specific fields go in `providerData`.
+ */
+declare const Reasoning: Schema.Struct<{
+  readonly type: Schema.Literal<"reasoning">;
+  readonly id: Schema.optional<Schema.String>;
+  readonly summary: Schema.optional<Schema.String>;
+  readonly signature: Schema.optional<Schema.String>;
+  readonly providerData: Schema.optional<Schema.Unknown>;
+}>;
+type Reasoning = typeof Reasoning.Type;
+declare const Item: Schema.Union<readonly [Schema.Struct<{
+  readonly type: Schema.Literal<"message">;
+  readonly role: Schema.Literals<readonly ["user", "assistant", "system"]>;
+  readonly content: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+    readonly type: Schema.Literal<"input_text">;
+    readonly text: Schema.String;
+  }>, Schema.Struct<{
+    readonly type: Schema.Literal<"input_image">;
+    readonly source: Schema.Union<readonly [Schema.Struct<{
+      readonly _tag: Schema.Literal<"url">;
+      readonly url: Schema.String;
+    }>, Schema.Struct<{
+      readonly _tag: Schema.Literal<"base64">;
+      readonly media_type: Schema.String;
+      readonly data: Schema.String;
+    }>]>;
+  }>, Schema.Struct<{
+    readonly type: Schema.Literal<"output_text">;
+    readonly text: Schema.String;
+    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;
+    }>, Schema.Struct<{
+      readonly type: Schema.Literal<"file_citation">;
+      readonly file_id: Schema.String;
+      readonly index: Schema.Number;
+    }>, Schema.Struct<{
+      readonly type: Schema.Literal<"container_file_citation">;
+      readonly container_id: Schema.String;
+      readonly file_id: Schema.String;
+      readonly start_index: Schema.Number;
+      readonly end_index: Schema.Number;
+    }>, Schema.Struct<{
+      readonly type: Schema.Literal<"file_path">;
+      readonly file_id: Schema.String;
+      readonly index: Schema.Number;
+    }>]>>>;
+  }>, Schema.Struct<{
+    readonly type: Schema.Literal<"refusal">;
+    readonly text: Schema.String;
+  }>]>>;
+  readonly providerData: Schema.optional<Schema.Unknown>;
+}>, Schema.Struct<{
+  readonly type: Schema.Literal<"function_call">;
+  readonly call_id: Schema.String;
+  readonly name: Schema.String;
+  readonly arguments: Schema.String;
+  readonly providerData: Schema.optional<Schema.Unknown>;
+}>, Schema.Struct<{
+  readonly type: Schema.Literal<"function_call_output">;
+  readonly call_id: Schema.String;
+  readonly output: Schema.String;
+  readonly providerData: Schema.optional<Schema.Unknown>;
+}>, Schema.Struct<{
+  readonly type: Schema.Literal<"reasoning">;
+  readonly id: Schema.optional<Schema.String>;
+  readonly summary: Schema.optional<Schema.String>;
+  readonly signature: Schema.optional<Schema.String>;
+  readonly providerData: Schema.optional<Schema.Unknown>;
+}>]>;
+type Item = typeof Item.Type;
+declare const isInputText: (block: ContentBlock) => block is InputText;
+declare const isInputImage: (block: ContentBlock) => block is InputImage;
+declare const isOutputText: (block: ContentBlock) => block is OutputText;
+declare const isRefusal: (block: ContentBlock) => block is Refusal;
+declare const isMessage: (item: Item) => item is Message;
+declare const isFunctionCall: (item: Item) => item is FunctionCall;
+declare const isFunctionCallOutput: (item: Item) => item is FunctionCallOutput;
+declare const isReasoning: (item: Item) => item is Reasoning;
+declare const InputTokensDetails: Schema.Struct<{
+  readonly cached_tokens: Schema.optional<Schema.Number>;
+}>;
+type InputTokensDetails = typeof InputTokensDetails.Type;
+declare const OutputTokensDetails: Schema.Struct<{
+  readonly reasoning_tokens: Schema.optional<Schema.Number>;
+}>;
+type OutputTokensDetails = typeof OutputTokensDetails.Type;
+declare const Usage: Schema.Struct<{
+  readonly input_tokens: Schema.optional<Schema.Number>;
+  readonly output_tokens: Schema.optional<Schema.Number>;
+  readonly total_tokens: Schema.optional<Schema.Number>;
+  readonly input_tokens_details: Schema.optional<Schema.Struct<{
+    readonly cached_tokens: Schema.optional<Schema.Number>;
+  }>>;
+  readonly output_tokens_details: Schema.optional<Schema.Struct<{
+    readonly reasoning_tokens: Schema.optional<Schema.Number>;
+  }>>;
+}>;
+type Usage = typeof Usage.Type;
+declare const StopReason: Schema.Literals<readonly ["stop", "tool_calls", "max_tokens", "refusal", "content_filter", "max_tool_calls"]>;
+type StopReason = typeof StopReason.Type;
+declare const userText: (text: string) => Message;
+declare const systemText: (text: string) => Message;
+declare const assistantText: (text: string) => Message;
+declare const functionCallOutput: (call_id: string, output: string) => FunctionCallOutput;
+//#endregion
+export { isFunctionCall as A, isUrlCitation as B, UrlCitation as C, isContainerFileCitation as D, functionCallOutput as E, isInputText as F, userText as H, isMessage as I, isOutputText as L, isImageBase64Source as M, isImageUrlSource as N, isFileCitation as O, isInputImage as P, isReasoning as R, StopReason as S, assistantText as T, systemText as V, OutputText as _, FilePath as a, Refusal as b, ImageBase64Source as c, InputImage as d, InputText as f, Message as g, Items_d_exports as h, FileCitation as i, isFunctionCallOutput as j, isFilePath as k, ImageSource as l, Item as m, ContainerFileCitation as n, FunctionCall as o, InputTokensDetails as p, ContentBlock as r, FunctionCallOutput as s, Annotation as t, ImageUrlSource as u, OutputTokensDetails as v, Usage as w, Role as x, Reasoning as y, isRefusal as z };
+//# sourceMappingURL=Items-D1C2686t.d.mts.map

package/dist/Items-D1C2686t.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Items-D1C2686t.d.mts","names":[],"sources":["../src/domain/Items.ts"],"mappings":"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"}

package/dist/Loop-CzSJo1h8.d.mts

@@ -0,0 +1,87 @@
+import { l as IncompleteTurn } from "./AiError-CqmYjXyx.mjs";
+import { a as TurnEvent, i as Turn } from "./Turn-rlTfuHaQ.mjs";
+import { Data, Effect, Stream } from "effect";
+
+//#region src/loop/Loop.d.ts
+declare namespace Loop_d_exports {
+  export { Event, loop, next, nextAfter, nextAfterFold, stop, stopAfter, stopEvent, streamUntilComplete, value };
+}
+/**
+ * The tagged union a body emits per pull. `Value` carries a payload that
+ * flows downstream. `Next` ends the current iteration and continues with a
+ * new state. `Stop` ends the loop entirely.
+ */
+type Event<A, S> = Data.TaggedEnum<{
+  Value: {
+    readonly value: A;
+  };
+  Next: {
+    readonly state: S;
+  };
+  Stop: {};
+}>;
+/** Wrap a value so it flows through the loop to downstream consumers. */
+declare const value: <A>(a: A) => Event<A, never>;
+/** End the current iteration and continue with a new state. */
+declare const next: <S>(state: S) => Event<never, S>;
+/** The terminal `Stop` event. Use `stop` (the Stream) to end a loop body. */
+declare const stopEvent: Event<never, never>;
+/**
+ * A single-element stream that ends the loop. Return this from a body when
+ * there's nothing else to emit; equivalent to `stopAfter(Stream.empty)` but
+ * named for the common case.
+ */
+declare const stop: Stream.Stream<Event<never, never>>;
+/**
+ * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the
+ * iteration with `next(state)`. Common shape for "stream this turn's
+ * deltas, then continue with updated history."
+ */
+declare const nextAfter: <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S) => Stream.Stream<Event<A, S>, E, R>;
+/**
+ * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the
+ * loop. Common shape for "stream this turn's deltas, then we're done."
+ */
+declare const stopAfter: <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, never>, E, R>;
+/**
+ * General `nextAfter` variant: drain `stream` to the consumer, fold elements
+ * into an accumulator, and at end-of-stream emit one `next(build(finalAcc))`.
+ *
+ * Subsumes `nextAfter` when state is constant (`reduce: (s, _) => s`,
+ * `build: (s) => s`). Used by `Toolkit.nextStateFrom` to collect tool
+ * results and build next state without exposing a Ref to recipes.
+ */
+declare const nextAfterFold: <A, B, S, E, R>(stream: Stream.Stream<A, E, R>, initial: B, reduce: (acc: B, a: A) => B, build: (b: B) => S) => Stream.Stream<Event<A, S>, E, R>;
+/**
+ * Lift a provider's `Stream<TurnEvent>` into a loop body's `Stream<Event<TurnEvent | A, S>>`.
+ * Each delta passes through as `value(delta)` (including the terminal
+ * `turn_complete`, so the consumer sees turn boundaries naturally). Once
+ * the terminal arrives, `then(turn)` runs and its returned stream of loop
+ * events (typically tool outputs followed by `next(state)` or `stop`) is
+ * concatenated.
+ *
+ * Pre-pipe transforms (`Stream.tap` / `Stream.map` / `Stream.filter`) on
+ * the raw delta stream cover anything an `emit`-style callback would do.
+ *
+ * If the upstream ends without a `turn_complete`, the resulting stream
+ * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if
+ * you want to recover.
+ */
+declare const streamUntilComplete: <S, A, E2 = never, R2 = never>(then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>) => <E, R>(deltas: Stream.Stream<TurnEvent, E, R>) => Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>;
+type LoopBody<S, A, E, R> = (state: S) => Stream.Stream<Event<A, S>, E, R> | Effect.Effect<Stream.Stream<Event<A, S>, E, R>, E, R>;
+/**
+ * Drive a state-threaded loop body. Each iteration runs `body(state)` to get
+ * a `Stream<Event<A, S>>`; values flow downstream, `next(s)` continues with
+ * a new state, `stop` ends the loop. See the file header for the full
+ * pull-based execution model.
+ *
+ * Dual: data-first `loop(initial, body)` and data-last `loop(body)(initial)`
+ * (or `pipe(initial, loop(body))`) both work.
+ */
+declare const loop: {
+  <S, A, E, R>(body: LoopBody<S, A, E, R>): (initial: S) => Stream.Stream<A, E, R>;
+  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R>;
+};
+//#endregion
+export { nextAfter as a, stopAfter as c, value as d, next as i, stopEvent as l, Loop_d_exports as n, nextAfterFold as o, loop as r, stop as s, Event as t, streamUntilComplete as u };
+//# sourceMappingURL=Loop-CzSJo1h8.d.mts.map

package/dist/Loop-CzSJo1h8.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Loop-CzSJo1h8.d.mts","names":[],"sources":["../src/loop/Loop.ts"],"mappings":";;;;;;;;;;;;;KAgCY,KAAA,SAAc,IAAA,CAAK,UAAA;EAC7B,KAAA;IAAA,SAAkB,KAAA,EAAO,CAAA;EAAA;EACzB,IAAA;IAAA,SAAiB,KAAA,EAAO,CAAA;EAAA;EACxB,IAAA;AAAA;;cAUW,KAAA,MAAY,CAAA,EAAG,CAAA,KAAI,KAAA,CAAM,CAAA;;cAGzB,IAAA,MAAW,KAAA,EAAO,CAAA,KAAI,KAAA,QAAa,CAAA;;cAGnC,SAAA,EAAW,KAAA;;;;;;cAOX,IAAA,EAAM,MAAA,CAAO,MAAA,CAAO,KAAA;;;;;;cAOpB,SAAA,eACX,MAAA,EAAQ,MAAA,CAAO,MAAA,CAAO,CAAA,EAAG,CAAA,EAAG,CAAA,GAC5B,KAAA,EAAO,CAAA,KACN,MAAA,CAAO,MAAA,CAAO,KAAA,CAAM,CAAA,EAAG,CAAA,GAAI,CAAA,EAAG,CAAA;AApBjC;;;;AAAA,cA2Ba,SAAA,YACX,MAAA,EAAQ,MAAA,CAAO,MAAA,CAAO,CAAA,EAAG,CAAA,EAAG,CAAA,MAC3B,MAAA,CAAO,MAAA,CAAO,KAAA,CAAM,CAAA,UAAW,CAAA,EAAG,CAAA;;;;;;;;;cAWxB,aAAA,kBACX,MAAA,EAAQ,MAAA,CAAO,MAAA,CAAO,CAAA,EAAG,CAAA,EAAG,CAAA,GAC5B,OAAA,EAAS,CAAA,EACT,MAAA,GAAS,GAAA,EAAK,CAAA,EAAG,CAAA,EAAG,CAAA,KAAM,CAAA,EAC1B,KAAA,GAAQ,CAAA,EAAG,CAAA,KAAM,CAAA,KAChB,MAAA,CAAO,MAAA,CAAO,KAAA,CAAM,CAAA,EAAG,CAAA,GAAI,CAAA,EAAG,CAAA;;AA1CjC;;;;;AAOA;;;;;;;;;cAqEa,mBAAA,iCAET,IAAA,GAAO,IAAA,EAAM,IAAA,KAAS,MAAA,CAAO,MAAA,CAAO,MAAA,CAAO,MAAA,CAAO,KAAA,CAAM,CAAA,EAAG,CAAA,GAAI,EAAA,EAAI,EAAA,GAAK,EAAA,EAAI,EAAA,aAG5E,MAAA,EAAQ,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,CAAA,EAAG,CAAA,MACnC,MAAA,CAAO,MAAA,CAAO,KAAA,CAAM,SAAA,GAAY,CAAA,EAAG,CAAA,GAAI,CAAA,GAAI,EAAA,GAAK,cAAA,EAAgB,CAAA,GAAI,EAAA;AAAA,KAkEpE,QAAA,gBACH,KAAA,EAAO,CAAA,KACJ,MAAA,CAAO,MAAA,CAAO,KAAA,CAAM,CAAA,EAAG,CAAA,GAAI,CAAA,EAAG,CAAA,IAAK,MAAA,CAAO,MAAA,CAAO,MAAA,CAAO,MAAA,CAAO,KAAA,CAAM,CAAA,EAAG,CAAA,GAAI,CAAA,EAAG,CAAA,GAAI,CAAA,EAAG,CAAA;;;;;;;;;;cAW9E,IAAA;EAAA,aACE,IAAA,EAAM,QAAA,CAAS,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAA,KAAM,OAAA,EAAS,CAAA,KAAM,MAAA,CAAO,MAAA,CAAO,CAAA,EAAG,CAAA,EAAG,CAAA;EAAA,aACjE,OAAA,EAAS,CAAA,EAAG,IAAA,EAAM,QAAA,CAAS,CAAA,EAAG,CAAA,EAAG,CAAA,EAAG,CAAA,IAAK,MAAA,CAAO,MAAA,CAAO,CAAA,EAAG,CAAA,EAAG,CAAA;AAAA"}