@effect-uai/core 0.1.0 → 0.3.0

package/dist/embedding-model/EmbeddingModel.d.mts

@@ -0,0 +1,97 @@
+import { t as AiError } from "../AiError-CBuPHVKA.mjs";
+import { EmbedInput, Embedding, Usage } from "./Embedding.mjs";
+import { Context, Effect } from "effect";
+
+//#region src/embedding-model/EmbeddingModel.d.ts
+declare namespace EmbeddingModel_d_exports {
+  export { CommonEmbedManyRequest, CommonEmbedRequest, EmbedManyResponse, EmbedResponse, EmbeddingModel, EmbeddingModelService, Encoding, embed, embedMany };
+}
+/**
+ * Output representation requested from the provider.
+ *
+ * Dense quantizations - same vector at different storage cost:
+ * - `float32` — universal default.
+ * - `int8` — ~4x smaller; minimal recall loss on most benchmarks.
+ * - `binary` — ~32x smaller; meaningful recall loss but pairs well with
+ *   a float32 reranker pass over a small candidate set.
+ *
+ * Non-dense representations:
+ * - `sparse` — learned sparse vector for hybrid (dense + lexical) search.
+ *   Currently Jina ELSER only on hosted APIs.
+ * - `multivector` — one vector per token for late-interaction (ColBERT-
+ *   style) scoring via `Vector.maxSim`. Currently Jina v4 only.
+ *
+ * Each provider's typed request narrows this to its supported set at
+ * compile time (e.g. `JinaEncoding = "float32" | "binary" | "sparse" |
+ * "multivector"`). On the generic `EmbeddingModel` path, callers can
+ * pass any `Encoding` and the provider's API will reject mismatches at
+ * runtime.
+ */
+type Encoding = "float32" | "int8" | "binary" | "sparse" | "multivector";
+/**
+ * Cross-provider single-embed request. Mirrors the shape of
+ * `LanguageModel.CommonRequest`: cross-cutting fields here, vendor
+ * specifics in the provider's typed request.
+ *
+ * Provider-specific extensions (Cohere widened `task` enum, Jina LoRA
+ * tasks, Mixedbread free-form `prompt`, etc.) live in that provider's own
+ * request interface, which extends this and narrows `model` / widens
+ * `task`.
+ */
+type CommonEmbedRequest = {
+  readonly input: EmbedInput;
+  /**
+   * Model identifier. Each provider narrows this to its typed literal
+   * union, so code that yields a typed provider tag gets autocompletion.
+   */
+  readonly model: string;
+  /**
+   * Retrieval-task hint. Applies to the input. OpenAI ignores this;
+   * Mixedbread doesn't have it; Cohere v3+ requires it on the wire (typed
+   * as required in `CohereEmbedRequest`). Provider-specific task enums
+   * (classification, clustering, code retrieval, …) live on the
+   * provider's own request type.
+   */
+  readonly task?: "query" | "document";
+  /**
+   * Matryoshka truncation. Default: provider's native dimension.
+   * Discrete-value providers (Cohere, Vertex `multimodalembedding@001`)
+   * narrow this to a literal union in their typed request.
+   */
+  readonly dimensions?: number;
+  /**
+   * Output representation - see {@link Encoding}. Dense float32 is the
+   * default; provider layers reject unsupported values up front with
+   * `InvalidRequest`.
+   */
+  readonly encoding?: Encoding;
+};
+/**
+ * Cross-provider batch-embed request. One `task` for the whole batch -
+ * mixed-task batches aren't a real provider feature (rerankers exist for
+ * that).
+ */
+type CommonEmbedManyRequest = Omit<CommonEmbedRequest, "input"> & {
+  readonly inputs: ReadonlyArray<EmbedInput>;
+};
+type EmbedResponse = {
+  readonly embedding: Embedding;
+  readonly usage: Usage;
+};
+type EmbedManyResponse = {
+  readonly embeddings: ReadonlyArray<Embedding>;
+  readonly usage: Usage;
+};
+type EmbeddingModelService = {
+  readonly embed: (request: CommonEmbedRequest) => Effect.Effect<EmbedResponse, AiError>;
+  readonly embedMany: (request: CommonEmbedManyRequest) => Effect.Effect<EmbedManyResponse, AiError>;
+};
+declare const EmbeddingModel_base: Context.ServiceClass<EmbeddingModel, "@betalyra/effect-uai/EmbeddingModel", EmbeddingModelService>;
+declare class EmbeddingModel extends EmbeddingModel_base {}
+/** Embed a single input. */
+declare const embed: (request: CommonEmbedRequest) => Effect.Effect<EmbedResponse, AiError, EmbeddingModel>;
+/** Embed a batch in one provider call. Same `task` for every input. */
+declare const embedMany: (request: CommonEmbedManyRequest) => Effect.Effect<EmbedManyResponse, AiError, EmbeddingModel>;
+//#endregion
+export { CommonEmbedManyRequest, CommonEmbedRequest, EmbedManyResponse, EmbedResponse, EmbeddingModel, EmbeddingModelService, Encoding, embed, embedMany, EmbeddingModel_d_exports as t };
+//# sourceMappingURL=EmbeddingModel.d.mts.map

package/dist/embedding-model/EmbeddingModel.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmbeddingModel.d.mts","names":[],"sources":["../../src/embedding-model/EmbeddingModel.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAyBA;;;;;AAYA;;KAZY,QAAA;;;;;;;;;;;KAYA,kBAAA;EAAA,SACD,KAAA,EAAO,UAAA;;;;;WAKP,KAAA;EA6BqB;;;;;;;EAAA,SArBrB,IAAA;EAqBgC;AAG3C;;;;EAH2C,SAfhC,UAAA;EAmBW;;;;;EAAA,SAbX,QAAA,GAAW,QAAA;AAAA;;;;;;KAQV,sBAAA,GAAyB,IAAA,CAAK,kBAAA;EAAA,SAC/B,MAAA,EAAQ,aAAA,CAAc,UAAA;AAAA;AAAA,KAGrB,aAAA;EAAA,SACD,SAAA,EAAW,SAAA;EAAA,SACX,KAAA,EAAO,KAAA;AAAA;AAAA,KAGN,iBAAA;EAAA,SACD,UAAA,EAAY,aAAA,CAAc,SAAA;EAAA,SAC1B,KAAA,EAAO,KAAA;AAAA;AAAA,KAGN,qBAAA;EAAA,SACD,KAAA,GAAQ,OAAA,EAAS,kBAAA,KAAuB,MAAA,CAAO,MAAA,CAAO,aAAA,EAAe,OAAA;EAAA,SACrE,SAAA,GACP,OAAA,EAAS,sBAAA,KACN,MAAA,CAAO,MAAA,CAAO,iBAAA,EAAmB,OAAA;AAAA;AAAA,cACvC,mBAAA;cAEY,cAAA,SAAuB,mBAAA;;cAKvB,KAAA,GACX,OAAA,EAAS,kBAAA,KACR,MAAA,CAAO,MAAA,CAAO,aAAA,EAAe,OAAA,EAAiB,cAAA;;cAIpC,SAAA,GACX,OAAA,EAAS,sBAAA,KACR,MAAA,CAAO,MAAA,CAAO,iBAAA,EAAmB,OAAA,EAAiB,cAAA"}

package/dist/embedding-model/EmbeddingModel.mjs

@@ -0,0 +1,17 @@
+import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
+import { Context, Effect } from "effect";
+//#region src/embedding-model/EmbeddingModel.ts
+var EmbeddingModel_exports = /* @__PURE__ */ __exportAll({
+	EmbeddingModel: () => EmbeddingModel,
+	embed: () => embed,
+	embedMany: () => embedMany
+});
+var EmbeddingModel = class extends Context.Service()("@betalyra/effect-uai/EmbeddingModel") {};
+/** Embed a single input. */
+const embed = (request) => Effect.flatMap(EmbeddingModel.asEffect(), (m) => m.embed(request));
+/** Embed a batch in one provider call. Same `task` for every input. */
+const embedMany = (request) => Effect.flatMap(EmbeddingModel.asEffect(), (m) => m.embedMany(request));
+//#endregion
+export { EmbeddingModel, embed, embedMany, EmbeddingModel_exports as t };
+
+//# sourceMappingURL=EmbeddingModel.mjs.map

package/dist/embedding-model/EmbeddingModel.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"EmbeddingModel.mjs","names":[],"sources":["../../src/embedding-model/EmbeddingModel.ts"],"sourcesContent":["import { Context, Effect } from \"effect\"\nimport * as AiError from \"../domain/AiError.js\"\nimport type { Embedding, EmbedInput, Usage } from \"./Embedding.js\"\n\n/**\n * Output representation requested from the provider.\n *\n * Dense quantizations - same vector at different storage cost:\n * - `float32` — universal default.\n * - `int8` — ~4x smaller; minimal recall loss on most benchmarks.\n * - `binary` — ~32x smaller; meaningful recall loss but pairs well with\n *   a float32 reranker pass over a small candidate set.\n *\n * Non-dense representations:\n * - `sparse` — learned sparse vector for hybrid (dense + lexical) search.\n *   Currently Jina ELSER only on hosted APIs.\n * - `multivector` — one vector per token for late-interaction (ColBERT-\n *   style) scoring via `Vector.maxSim`. Currently Jina v4 only.\n *\n * Each provider's typed request narrows this to its supported set at\n * compile time (e.g. `JinaEncoding = \"float32\" | \"binary\" | \"sparse\" |\n * \"multivector\"`). On the generic `EmbeddingModel` path, callers can\n * pass any `Encoding` and the provider's API will reject mismatches at\n * runtime.\n */\nexport type Encoding = \"float32\" | \"int8\" | \"binary\" | \"sparse\" | \"multivector\"\n\n/**\n * Cross-provider single-embed request. Mirrors the shape of\n * `LanguageModel.CommonRequest`: cross-cutting fields here, vendor\n * specifics in the provider's typed request.\n *\n * Provider-specific extensions (Cohere widened `task` enum, Jina LoRA\n * tasks, Mixedbread free-form `prompt`, etc.) live in that provider's own\n * request interface, which extends this and narrows `model` / widens\n * `task`.\n */\nexport type CommonEmbedRequest = {\n  readonly input: EmbedInput\n  /**\n   * Model identifier. Each provider narrows this to its typed literal\n   * union, so code that yields a typed provider tag gets autocompletion.\n   */\n  readonly model: string\n  /**\n   * Retrieval-task hint. Applies to the input. OpenAI ignores this;\n   * Mixedbread doesn't have it; Cohere v3+ requires it on the wire (typed\n   * as required in `CohereEmbedRequest`). Provider-specific task enums\n   * (classification, clustering, code retrieval, …) live on the\n   * provider's own request type.\n   */\n  readonly task?: \"query\" | \"document\"\n  /**\n   * Matryoshka truncation. Default: provider's native dimension.\n   * Discrete-value providers (Cohere, Vertex `multimodalembedding@001`)\n   * narrow this to a literal union in their typed request.\n   */\n  readonly dimensions?: number\n  /**\n   * Output representation - see {@link Encoding}. Dense float32 is the\n   * default; provider layers reject unsupported values up front with\n   * `InvalidRequest`.\n   */\n  readonly encoding?: Encoding\n}\n\n/**\n * Cross-provider batch-embed request. One `task` for the whole batch -\n * mixed-task batches aren't a real provider feature (rerankers exist for\n * that).\n */\nexport type CommonEmbedManyRequest = Omit<CommonEmbedRequest, \"input\"> & {\n  readonly inputs: ReadonlyArray<EmbedInput>\n}\n\nexport type EmbedResponse = {\n  readonly embedding: Embedding\n  readonly usage: Usage\n}\n\nexport type EmbedManyResponse = {\n  readonly embeddings: ReadonlyArray<Embedding>\n  readonly usage: Usage\n}\n\nexport type EmbeddingModelService = {\n  readonly embed: (request: CommonEmbedRequest) => Effect.Effect<EmbedResponse, AiError.AiError>\n  readonly embedMany: (\n    request: CommonEmbedManyRequest,\n  ) => Effect.Effect<EmbedManyResponse, AiError.AiError>\n}\n\nexport class EmbeddingModel extends Context.Service<EmbeddingModel, EmbeddingModelService>()(\n  \"@betalyra/effect-uai/EmbeddingModel\",\n) {}\n\n/** Embed a single input. */\nexport const embed = (\n  request: CommonEmbedRequest,\n): Effect.Effect<EmbedResponse, AiError.AiError, EmbeddingModel> =>\n  Effect.flatMap(EmbeddingModel.asEffect(), (m) => m.embed(request))\n\n/** Embed a batch in one provider call. Same `task` for every input. */\nexport const embedMany = (\n  request: CommonEmbedManyRequest,\n): Effect.Effect<EmbedManyResponse, AiError.AiError, EmbeddingModel> =>\n  Effect.flatMap(EmbeddingModel.asEffect(), (m) => m.embedMany(request))\n"],"mappings":";;;;;;;;AA4FA,IAAa,iBAAb,cAAoC,QAAQ,SAAgD,CAC1F,sCACD,CAAC;;AAGF,MAAa,SACX,YAEA,OAAO,QAAQ,eAAe,UAAU,GAAG,MAAM,EAAE,MAAM,QAAQ,CAAC;;AAGpE,MAAa,aACX,YAEA,OAAO,QAAQ,eAAe,UAAU,GAAG,MAAM,EAAE,UAAU,QAAQ,CAAC"}

package/dist/index.d.mts

@@ -1,14 +1,22 @@
-import { n as AiError_d_exports } from "./AiError-CqmYjXyx.mjs";
-import { h as Items_d_exports } from "./Items-D1C2686t.mjs";
-import { a as StructuredFormat_d_exports } from "./StructuredFormat-B5ueioNr.mjs";
-import { o as Turn_d_exports } from "./Turn-rlTfuHaQ.mjs";
-import { l as Tool_d_exports } from "./Tool-5wxOCuOh.mjs";
+import { n as AiError_d_exports } from "./AiError-CBuPHVKA.mjs";
+import { a as Media_d_exports } from "./Media-D_CpcM1Z.mjs";
+import { o as Image_d_exports } from "./Image-BZmKfIdq.mjs";
+import { f as Items_d_exports } from "./Items-CB8Bo3FI.mjs";
+import { a as StructuredFormat_d_exports } from "./StructuredFormat-BWq5Hd1O.mjs";
+import { a as Turn_d_exports } from "./Turn-OPaILVIB.mjs";
+import { t as Embedding_d_exports } from "./embedding-model/Embedding.mjs";
+import { t as EmbeddingModel_d_exports } from "./embedding-model/EmbeddingModel.mjs";
+import { l as Tool_d_exports } from "./Tool-DjVufH7i.mjs";
 import { t as LanguageModel_d_exports } from "./language-model/LanguageModel.mjs";
-import { n as Loop_d_exports } from "./Loop-CzSJo1h8.mjs";
-import { t as Match_d_exports } from "./match/Match.mjs";
+import { t as Vector_d_exports } from "./math/Vector.mjs";
+import { t as Loop_d_exports } from "./loop/Loop.mjs";
+import { t as Outcome_d_exports } from "./tool/Outcome.mjs";
+import { t as ToolEvent_d_exports } from "./tool/ToolEvent.mjs";
 import { t as Toolkit_d_exports } from "./tool/Toolkit.mjs";
+import { t as Resolvers_d_exports } from "./tool/Resolvers.mjs";
+import { t as HistoryCheck_d_exports } from "./tool/HistoryCheck.mjs";
 import { t as JSONL_d_exports } from "./streaming/JSONL.mjs";
 import { t as Lines_d_exports } from "./streaming/Lines.mjs";
 import { t as SSE_d_exports } from "./streaming/SSE.mjs";
 import { t as Metrics_d_exports } from "./observability/Metrics.mjs";
-export { AiError_d_exports as AiError, Items_d_exports as Items, JSONL_d_exports as JSONL, LanguageModel_d_exports as LanguageModel, Lines_d_exports as Lines, Loop_d_exports as Loop, Match_d_exports as Match, Metrics_d_exports as Metrics, SSE_d_exports as SSE, StructuredFormat_d_exports as StructuredFormat, Tool_d_exports as Tool, Toolkit_d_exports as Toolkit, Turn_d_exports as Turn };
+export { AiError_d_exports as AiError, Embedding_d_exports as Embedding, EmbeddingModel_d_exports as EmbeddingModel, HistoryCheck_d_exports as HistoryCheck, Image_d_exports as Image, Items_d_exports as Items, JSONL_d_exports as JSONL, LanguageModel_d_exports as LanguageModel, Lines_d_exports as Lines, Loop_d_exports as Loop, Media_d_exports as Media, Metrics_d_exports as Metrics, Outcome_d_exports as Outcome, Resolvers_d_exports as Resolvers, SSE_d_exports as SSE, StructuredFormat_d_exports as StructuredFormat, Tool_d_exports as Tool, ToolEvent_d_exports as ToolEvent, Toolkit_d_exports as Toolkit, Turn_d_exports as Turn, Vector_d_exports as Vector };

package/dist/index.mjs

@@ -1,14 +1,22 @@
 import { t as AiError_exports } from "./domain/AiError.mjs";
+import { t as Image_exports } from "./domain/Image.mjs";
 import { t as Items_exports } from "./domain/Items.mjs";
+import { t as Media_exports } from "./domain/Media.mjs";
 import { t as StructuredFormat_exports } from "./structured-format/StructuredFormat.mjs";
 import { t as Turn_exports } from "./domain/Turn.mjs";
+import { t as Embedding_exports } from "./embedding-model/Embedding.mjs";
+import { t as EmbeddingModel_exports } from "./embedding-model/EmbeddingModel.mjs";
 import { t as LanguageModel_exports } from "./language-model/LanguageModel.mjs";
+import { t as Vector_exports } from "./math/Vector.mjs";
 import { t as Loop_exports } from "./loop/Loop.mjs";
-import { t as Match_exports } from "./match/Match.mjs";
 import { t as Tool_exports } from "./tool/Tool.mjs";
+import { t as Outcome_exports } from "./tool/Outcome.mjs";
+import { t as ToolEvent_exports } from "./tool/ToolEvent.mjs";
 import { t as Toolkit_exports } from "./tool/Toolkit.mjs";
+import { t as Resolvers_exports } from "./tool/Resolvers.mjs";
+import { t as HistoryCheck_exports } from "./tool/HistoryCheck.mjs";
 import { t as JSONL_exports } from "./streaming/JSONL.mjs";
 import { t as Lines_exports } from "./streaming/Lines.mjs";
 import { t as SSE_exports } from "./streaming/SSE.mjs";
 import { t as Metrics_exports } from "./observability/Metrics.mjs";
-export { AiError_exports as AiError, Items_exports as Items, JSONL_exports as JSONL, LanguageModel_exports as LanguageModel, Lines_exports as Lines, Loop_exports as Loop, Match_exports as Match, Metrics_exports as Metrics, SSE_exports as SSE, StructuredFormat_exports as StructuredFormat, Tool_exports as Tool, Toolkit_exports as Toolkit, Turn_exports as Turn };
+export { AiError_exports as AiError, Embedding_exports as Embedding, EmbeddingModel_exports as EmbeddingModel, HistoryCheck_exports as HistoryCheck, Image_exports as Image, Items_exports as Items, JSONL_exports as JSONL, LanguageModel_exports as LanguageModel, Lines_exports as Lines, Loop_exports as Loop, Media_exports as Media, Metrics_exports as Metrics, Outcome_exports as Outcome, Resolvers_exports as Resolvers, SSE_exports as SSE, StructuredFormat_exports as StructuredFormat, Tool_exports as Tool, ToolEvent_exports as ToolEvent, Toolkit_exports as Toolkit, Turn_exports as Turn, Vector_exports as Vector };

package/dist/language-model/LanguageModel.d.mts

@@ -1,13 +1,13 @@
-import { t as AiError } from "../AiError-CqmYjXyx.mjs";
-import { m as Item } from "../Items-D1C2686t.mjs";
-import { i as StructuredFormat } from "../StructuredFormat-B5ueioNr.mjs";
-import { a as TurnEvent, i as Turn } from "../Turn-rlTfuHaQ.mjs";
-import { o as ToolDescriptor } from "../Tool-5wxOCuOh.mjs";
-import { Context, Effect, Stream } from "effect";
+import { t as AiError } from "../AiError-CBuPHVKA.mjs";
+import { d as Item } from "../Items-CB8Bo3FI.mjs";
+import { i as StructuredFormat } from "../StructuredFormat-BWq5Hd1O.mjs";
+import { i as TurnEvent } from "../Turn-OPaILVIB.mjs";
+import { o as ToolDescriptor } from "../Tool-DjVufH7i.mjs";
+import { Context, Stream } from "effect";
 
 //#region src/language-model/LanguageModel.d.ts
 declare namespace LanguageModel_d_exports {
-  export { CommonRequest, LanguageModel, LanguageModelService, streamTurn, turn };
+  export { CommonRequest, LanguageModel, LanguageModelService, streamTurn };
 }
 /**
  * Cross-provider request shape. Every call carries its own `history` and
@@ -15,7 +15,7 @@ declare namespace LanguageModel_d_exports {
  * to a single provider (reasoning effort, prompt caching, store flags,
  * ...) lives in that provider's own request interface, which extends this.
  */
-interface CommonRequest {
+type CommonRequest = {
   readonly history: ReadonlyArray<Item>;
   /**
    * Model identifier. Each provider narrows this to its typed literal union,
@@ -37,24 +37,16 @@ interface CommonRequest {
    * `output_config`, Gemini `responseJsonSchema`).
    */
   readonly structured?: StructuredFormat<unknown>;
-}
-interface LanguageModelService {
+};
+type LanguageModelService = {
   readonly streamTurn: (request: CommonRequest) => Stream.Stream<TurnEvent, AiError>;
-}
+};
 declare const LanguageModel_base: Context.ServiceClass<LanguageModel, "@betalyra/effect-uai/LanguageModel", LanguageModelService>;
 declare class LanguageModel extends LanguageModel_base {}
 /**
  * Stream the deltas of a single turn.
  */
 declare const streamTurn: (request: CommonRequest) => Stream.Stream<TurnEvent, AiError, LanguageModel>;
-/**
- * Run a single turn to completion and return the assembled `Turn`.
- *
- * Implementation: drain the delta stream and pluck the terminal
- * `turn_complete` event. The provider is contractually required to emit
- * exactly one such event as the last delta.
- */
-declare const turn: (request: CommonRequest) => Effect.Effect<Turn, AiError, LanguageModel>;
 //#endregion
-export { CommonRequest, LanguageModel, LanguageModelService, streamTurn, LanguageModel_d_exports as t, turn };
+export { CommonRequest, LanguageModel, LanguageModelService, streamTurn, LanguageModel_d_exports as t };
 //# sourceMappingURL=LanguageModel.d.mts.map

package/dist/language-model/LanguageModel.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"LanguageModel.d.mts","names":[],"sources":["../../src/language-model/LanguageModel.ts"],"mappings":";;;;;;;;;;;;;;;;;UAaiB,aAAA;EAAA,SACN,OAAA,EAAS,aAAA,CAAc,IAAA;;;AADlC;;WAMW,KAAA;EAAA,SACA,KAAA,GAAQ,aAAA,CAAc,cAAA;EAAA,SACtB,UAAA;IAAA,SAIM,IAAA;IAAA,SAA2B,IAAA;EAAA;EAAA,SACjC,WAAA;EAAA,SACA,IAAA;EAAA,SACA,eAAA;EAdS;;;;;;EAAA,SAqBT,UAAA,GAAa,gBAAA;AAAA;AAAA,UAGP,oBAAA;EAAA,SACN,UAAA,GAAa,OAAA,EAAS,aAAA,KAAkB,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,OAAA;AAAA;AAAA,cAC3E,kBAAA;cAEY,aAAA,SAAsB,kBAAA;;;;cAOtB,UAAA,GACX,OAAA,EAAS,aAAA,KACR,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,OAAA,EAAiB,aAAA;;;;;;;;cAUhC,IAAA,GAAQ,OAAA,EAAS,aAAA,KAAgB,MAAA,CAAO,MAAA,CAAO,IAAA,EAAM,OAAA,EAAiB,aAAA"}
+{"version":3,"file":"LanguageModel.d.mts","names":[],"sources":["../../src/language-model/LanguageModel.ts"],"mappings":";;;;;;;;;;;;;;;;;KAaY,aAAA;EAAA,SACD,OAAA,EAAS,aAAA,CAAc,IAAA;;AADlC;;;WAMW,KAAA;EAAA,SACA,KAAA,GAAQ,aAAA,CAAc,cAAA;EAAA,SACtB,UAAA;IAAA,SAIM,IAAA;IAAA,SAA2B,IAAA;EAAA;EAAA,SACjC,WAAA;EAAA,SACA,IAAA;EAAA,SACA,eAAA;EAduB;;;;;;EAAA,SAqBvB,UAAA,GAAa,gBAAA;AAAA;AAAA,KAGZ,oBAAA;EAAA,SACD,UAAA,GAAa,OAAA,EAAS,aAAA,KAAkB,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,OAAA;AAAA;AAAA,cAC3E,kBAAA;cAEY,aAAA,SAAsB,kBAAA;;;AAJnC;cAWa,UAAA,GACX,OAAA,EAAS,aAAA,KACR,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,OAAA,EAAiB,aAAA"}

package/dist/language-model/LanguageModel.mjs

@@ -1,33 +1,16 @@
-import { t as __exportAll } from "../chunk-CfYAbeIz.mjs";
-import { Unavailable } from "../domain/AiError.mjs";
-import { isTurnComplete } from "../domain/Turn.mjs";
+import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
 import { Context, Effect, Stream } from "effect";
 //#region src/language-model/LanguageModel.ts
 var LanguageModel_exports = /* @__PURE__ */ __exportAll({
 	LanguageModel: () => LanguageModel,
-	streamTurn: () => streamTurn,
-	turn: () => turn
+	streamTurn: () => streamTurn
 });
 var LanguageModel = class extends Context.Service()("@betalyra/effect-uai/LanguageModel") {};
 /**
 * Stream the deltas of a single turn.
 */
 const streamTurn = (request) => Stream.unwrap(Effect.map(LanguageModel.asEffect(), (m) => m.streamTurn(request)));
-/**
-* Run a single turn to completion and return the assembled `Turn`.
-*
-* Implementation: drain the delta stream and pluck the terminal
-* `turn_complete` event. The provider is contractually required to emit
-* exactly one such event as the last delta.
-*/
-const turn = (request) => Effect.flatMap(Stream.runCollect(streamTurn(request)), (deltas) => {
-	const last = deltas[deltas.length - 1];
-	return last !== void 0 && isTurnComplete(last) ? Effect.succeed(last.turn) : Effect.fail(new Unavailable({
-		provider: "unknown",
-		raw: "Provider stream ended without a turn_complete event"
-	}));
-});
 //#endregion
-export { LanguageModel, streamTurn, LanguageModel_exports as t, turn };
+export { LanguageModel, streamTurn, LanguageModel_exports as t };
 
 //# sourceMappingURL=LanguageModel.mjs.map

package/dist/language-model/LanguageModel.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"LanguageModel.mjs","names":["AiError.Unavailable"],"sources":["../../src/language-model/LanguageModel.ts"],"sourcesContent":["import { Context, Effect, Stream } from \"effect\"\nimport * as AiError from \"../domain/AiError.js\"\nimport type { Item } from \"../domain/Items.js\"\nimport type * as StructuredFormat from \"../structured-format/StructuredFormat.js\"\nimport type { ToolDescriptor } from \"../tool/Tool.js\"\nimport { isTurnComplete, type Turn, type TurnEvent } from \"../domain/Turn.js\"\n\n/**\n * Cross-provider request shape. Every call carries its own `history` and\n * `model` - models are not bound at layer construction. Anything specific\n * to a single provider (reasoning effort, prompt caching, store flags,\n * ...) lives in that provider's own request interface, which extends this.\n */\nexport interface CommonRequest {\n  readonly history: ReadonlyArray<Item>\n  /**\n   * Model identifier. Each provider narrows this to its typed literal union,\n   * so code that yields a typed provider tag gets autocompletion.\n   */\n  readonly model: string\n  readonly tools?: ReadonlyArray<ToolDescriptor>\n  readonly toolChoice?:\n    | \"auto\"\n    | \"required\"\n    | \"none\"\n    | { readonly type: \"function\"; readonly name: string }\n  readonly temperature?: number\n  readonly topP?: number\n  readonly maxOutputTokens?: number\n  /**\n   * Schema-bound JSON output. The provider constrains the wire to match the\n   * schema; pair with `Turn.toStructured` for runtime validation. Supported\n   * across all current providers (OpenAI Responses json_schema, Anthropic\n   * `output_config`, Gemini `responseJsonSchema`).\n   */\n  readonly structured?: StructuredFormat.StructuredFormat<unknown>\n}\n\nexport interface LanguageModelService {\n  readonly streamTurn: (request: CommonRequest) => Stream.Stream<TurnEvent, AiError.AiError>\n}\n\nexport class LanguageModel extends Context.Service<LanguageModel, LanguageModelService>()(\n  \"@betalyra/effect-uai/LanguageModel\",\n) {}\n\n/**\n * Stream the deltas of a single turn.\n */\nexport const streamTurn = (\n  request: CommonRequest,\n): Stream.Stream<TurnEvent, AiError.AiError, LanguageModel> =>\n  Stream.unwrap(Effect.map(LanguageModel.asEffect(), (m) => m.streamTurn(request)))\n\n/**\n * Run a single turn to completion and return the assembled `Turn`.\n *\n * Implementation: drain the delta stream and pluck the terminal\n * `turn_complete` event. The provider is contractually required to emit\n * exactly one such event as the last delta.\n */\nexport const turn = (request: CommonRequest): Effect.Effect<Turn, AiError.AiError, LanguageModel> =>\n  Effect.flatMap(Stream.runCollect(streamTurn(request)), (deltas) => {\n    const last = deltas[deltas.length - 1]\n    return last !== undefined && isTurnComplete(last)\n      ? Effect.succeed(last.turn)\n      : Effect.fail(\n          new AiError.Unavailable({\n            provider: \"unknown\",\n            raw: \"Provider stream ended without a turn_complete event\",\n          }),\n        )\n  })\n"],"mappings":";;;;;;;;;;AA0CA,IAAa,gBAAb,cAAmC,QAAQ,SAA8C,CACvF,qCACD,CAAC;;;;AAKF,MAAa,cACX,YAEA,OAAO,OAAO,OAAO,IAAI,cAAc,UAAU,GAAG,MAAM,EAAE,WAAW,QAAQ,CAAC,CAAC;;;;;;;;AASnF,MAAa,QAAQ,YACnB,OAAO,QAAQ,OAAO,WAAW,WAAW,QAAQ,CAAC,GAAG,WAAW;CACjE,MAAM,OAAO,OAAO,OAAO,SAAS;AACpC,QAAO,SAAS,KAAA,KAAa,eAAe,KAAK,GAC7C,OAAO,QAAQ,KAAK,KAAK,GACzB,OAAO,KACL,IAAIA,YAAoB;EACtB,UAAU;EACV,KAAK;EACN,CAAC,CACH;EACL"}
+{"version":3,"file":"LanguageModel.mjs","names":[],"sources":["../../src/language-model/LanguageModel.ts"],"sourcesContent":["import { Context, Effect, Stream } from \"effect\"\nimport * as AiError from \"../domain/AiError.js\"\nimport type { Item } from \"../domain/Items.js\"\nimport type * as StructuredFormat from \"../structured-format/StructuredFormat.js\"\nimport type { ToolDescriptor } from \"../tool/Tool.js\"\nimport { isTurnComplete, type Turn, type TurnEvent } from \"../domain/Turn.js\"\n\n/**\n * Cross-provider request shape. Every call carries its own `history` and\n * `model` - models are not bound at layer construction. Anything specific\n * to a single provider (reasoning effort, prompt caching, store flags,\n * ...) lives in that provider's own request interface, which extends this.\n */\nexport type CommonRequest = {\n  readonly history: ReadonlyArray<Item>\n  /**\n   * Model identifier. Each provider narrows this to its typed literal union,\n   * so code that yields a typed provider tag gets autocompletion.\n   */\n  readonly model: string\n  readonly tools?: ReadonlyArray<ToolDescriptor>\n  readonly toolChoice?:\n    | \"auto\"\n    | \"required\"\n    | \"none\"\n    | { readonly type: \"function\"; readonly name: string }\n  readonly temperature?: number\n  readonly topP?: number\n  readonly maxOutputTokens?: number\n  /**\n   * Schema-bound JSON output. The provider constrains the wire to match the\n   * schema; pair with `Turn.toStructured` for runtime validation. Supported\n   * across all current providers (OpenAI Responses json_schema, Anthropic\n   * `output_config`, Gemini `responseJsonSchema`).\n   */\n  readonly structured?: StructuredFormat.StructuredFormat<unknown>\n}\n\nexport type LanguageModelService = {\n  readonly streamTurn: (request: CommonRequest) => Stream.Stream<TurnEvent, AiError.AiError>\n}\n\nexport class LanguageModel extends Context.Service<LanguageModel, LanguageModelService>()(\n  \"@betalyra/effect-uai/LanguageModel\",\n) {}\n\n/**\n * Stream the deltas of a single turn.\n */\nexport const streamTurn = (\n  request: CommonRequest,\n): Stream.Stream<TurnEvent, AiError.AiError, LanguageModel> =>\n  Stream.unwrap(Effect.map(LanguageModel.asEffect(), (m) => m.streamTurn(request)))\n"],"mappings":";;;;;;;AA0CA,IAAa,gBAAb,cAAmC,QAAQ,SAA8C,CACvF,qCACD,CAAC;;;;AAKF,MAAa,cACX,YAEA,OAAO,OAAO,OAAO,IAAI,cAAc,UAAU,GAAG,MAAM,EAAE,WAAW,QAAQ,CAAC,CAAC"}

package/dist/loop/Loop.d.mts

@@ -1,2 +1,111 @@
-import { a as nextAfter, c as stopAfter, d as value, i as next, l as stopEvent, o as nextAfterFold, r as loop, s as stop, t as Event, u as streamUntilComplete } from "../Loop-CzSJo1h8.mjs";
-export { Event, loop, next, nextAfter, nextAfterFold, stop, stopAfter, stopEvent, streamUntilComplete, value };
+import { l as IncompleteTurn } from "../AiError-CBuPHVKA.mjs";
+import { i as TurnEvent, r as Turn } from "../Turn-OPaILVIB.mjs";
+import { Data, Effect, Stream, SubscriptionRef } from "effect";
+
+//#region src/loop/Loop.d.ts
+declare namespace Loop_d_exports {
+  export { Event, loop, loopWithState, next, nextAfter, nextAfterFold, onTurnComplete, stop, stopAfter, stopEvent, 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.continueWith` 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 onTurnComplete: <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>;
+};
+/**
+ * Like `loop`, but exposes the current loop state as a `SubscriptionRef`
+ * alongside the value stream.
+ *
+ * Allocates one `SubscriptionRef<S>` seeded with `initial`, then runs the
+ * loop with a wrapped body that taps every `Next(s)` event into the ref
+ * before forwarding it. The caller decides how to consume both channels:
+ *
+ *   - **Final state**: drain the stream, then `SubscriptionRef.get(state)`
+ *     - the ref holds the state from the last `Next` (or `initial` if the
+ *     loop ended without advancing).
+ *   - **Live transitions**: `SubscriptionRef.changes(state)` is a
+ *     `Stream<S>` of every state observed; subscribe alongside the value
+ *     stream.
+ *   - **Mid-iteration peek**: `SubscriptionRef.get(state)` at any time.
+ *
+ * The returned stream and ref are independent of each other - the ref
+ * lives outside the stream's scope, so reading it after the stream
+ * completes is safe.
+ */
+declare const loopWithState: <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>) => Effect.Effect<{
+  readonly stream: Stream.Stream<A, E, R>;
+  readonly state: SubscriptionRef.SubscriptionRef<S>;
+}>;
+//#endregion
+export { Event, loop, loopWithState, next, nextAfter, nextAfterFold, onTurnComplete, stop, stopAfter, stopEvent, Loop_d_exports as t, value };
+//# sourceMappingURL=Loop.d.mts.map

package/dist/loop/Loop.d.mts.map

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

package/dist/loop/Loop.mjs

@@ -1,7 +1,7 @@
-import { t as __exportAll } from "../chunk-CfYAbeIz.mjs";
+import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
 import { IncompleteTurn } from "../domain/AiError.mjs";
 import { isTurnComplete } from "../domain/Turn.mjs";
-import { Cause, Channel, Data, Effect, Exit, Function, Option, Ref, Scope, Stream } from "effect";
+import { Cause, Channel, Data, Effect, Exit, Function, Option, Ref, Scope, Stream, SubscriptionRef } from "effect";
 //#region src/loop/Loop.ts
 /**
 * Pull-based `loop` for state-threaded sub-streams.
@@ -24,13 +24,14 @@ import { Cause, Channel, Data, Effect, Exit, Function, Option, Ref, Scope, Strea
 */
 var Loop_exports = /* @__PURE__ */ __exportAll({
 	loop: () => loop,
+	loopWithState: () => loopWithState,
 	next: () => next,
 	nextAfter: () => nextAfter,
 	nextAfterFold: () => nextAfterFold,
+	onTurnComplete: () => onTurnComplete,
 	stop: () => stop,
 	stopAfter: () => stopAfter,
 	stopEvent: () => stopEvent,
-	streamUntilComplete: () => streamUntilComplete,
 	value: () => value
 });
 const Event = Data.taggedEnum();
@@ -62,7 +63,7 @@ const stopAfter = (stream) => Stream.concat(Stream.map(stream, value), Stream.fr
 * 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
+* `build: (s) => s`). Used by `Toolkit.continueWith` to collect tool
 * results and build next state without exposing a Ref to recipes.
 */
 const nextAfterFold = (stream, initial, reduce, build) => Stream.unwrap(Effect.gen(function* () {
@@ -86,7 +87,7 @@ const nextAfterFold = (stream, initial, reduce, build) => Stream.unwrap(Effect.g
 * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if
 * you want to recover.
 */
-const streamUntilComplete = (then) => (deltas) => Stream.unwrap(Effect.gen(function* () {
+const onTurnComplete = (then) => (deltas) => Stream.unwrap(Effect.gen(function* () {
 	const turnRef = yield* Ref.make(Option.none());
 	const events = deltas.pipe(Stream.tap((delta) => isTurnComplete(delta) ? Ref.set(turnRef, Option.some(delta.turn)) : Effect.void), Stream.map(value));
 	const continuation = Stream.unwrap(Effect.gen(function* () {
@@ -166,7 +167,39 @@ const loop = Function.dual(2, (initial, body) => Stream.scoped(Stream.fromPull(E
 		}
 	});
 }))));
+/**
+* Like `loop`, but exposes the current loop state as a `SubscriptionRef`
+* alongside the value stream.
+*
+* Allocates one `SubscriptionRef<S>` seeded with `initial`, then runs the
+* loop with a wrapped body that taps every `Next(s)` event into the ref
+* before forwarding it. The caller decides how to consume both channels:
+*
+*   - **Final state**: drain the stream, then `SubscriptionRef.get(state)`
+*     - the ref holds the state from the last `Next` (or `initial` if the
+*     loop ended without advancing).
+*   - **Live transitions**: `SubscriptionRef.changes(state)` is a
+*     `Stream<S>` of every state observed; subscribe alongside the value
+*     stream.
+*   - **Mid-iteration peek**: `SubscriptionRef.get(state)` at any time.
+*
+* The returned stream and ref are independent of each other - the ref
+* lives outside the stream's scope, so reading it after the stream
+* completes is safe.
+*/
+const loopWithState = (initial, body) => Effect.gen(function* () {
+	const stateRef = yield* SubscriptionRef.make(initial);
+	const tap = (stream) => stream.pipe(Stream.tap((event) => event._tag === "Next" ? SubscriptionRef.set(stateRef, event.state) : Effect.void));
+	const wrappedBody = (s) => {
+		const result = body(s);
+		return Effect.isEffect(result) ? Effect.map(result, tap) : tap(result);
+	};
+	return {
+		stream: loop(initial, wrappedBody),
+		state: stateRef
+	};
+});
 //#endregion
-export { loop, next, nextAfter, nextAfterFold, stop, stopAfter, stopEvent, streamUntilComplete, Loop_exports as t, value };
+export { loop, loopWithState, next, nextAfter, nextAfterFold, onTurnComplete, stop, stopAfter, stopEvent, Loop_exports as t, value };
 
 //# sourceMappingURL=Loop.mjs.map

package/dist/loop/Loop.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Loop.mjs","names":[],"sources":["../../src/loop/Loop.ts"],"sourcesContent":["/**\n * Pull-based `loop` for state-threaded sub-streams.\n *\n * Each iteration runs a body that returns a `Stream<Event<A, S>>`. The body\n * emits values via `Loop.value(a)` and signals iteration control via\n * `Loop.next(state)` (continue with new state) or `Loop.stop` (terminate).\n * The loop unwraps `Value` events back to `A` for downstream consumers, so\n * the resulting stream is a plain `Stream<A>`.\n *\n * The next body stream is only pulled when downstream pulls the outer\n * stream - no producer fiber, no queue buffering. Cancellation, failures,\n * scoped resources, and backpressure stay aligned with normal Stream\n * semantics.\n *\n * Convention: a `Next` or `Stop` event is the terminal element of a body's\n * iteration. Values emitted in the same chunk after one are discarded\n * (their producing side effects may already have run). Prefer the\n * `Loop.nextAfter` / `Loop.stopAfter` helpers to terminate cleanly.\n */\nimport { Cause, Channel, Data, Effect, Exit, Function, Option, Ref, Scope, Stream } from \"effect\"\nimport { IncompleteTurn } from \"../domain/AiError.js\"\nimport { isTurnComplete, type Turn, type TurnEvent } from \"../domain/Turn.js\"\n\n// ---------------------------------------------------------------------------\n// Event type - the body's emit shape\n// ---------------------------------------------------------------------------\n\n/**\n * The tagged union a body emits per pull. `Value` carries a payload that\n * flows downstream. `Next` ends the current iteration and continues with a\n * new state. `Stop` ends the loop entirely.\n */\nexport type Event<A, S> = Data.TaggedEnum<{\n  Value: { readonly value: A }\n  Next: { readonly state: S }\n  Stop: {}\n}>\n\ninterface EventDef extends Data.TaggedEnum.WithGenerics<2> {\n  readonly taggedEnum: Event<this[\"A\"], this[\"B\"]>\n}\n\nconst Event = Data.taggedEnum<EventDef>()\n\n/** Wrap a value so it flows through the loop to downstream consumers. */\nexport const value = <A>(a: A): Event<A, never> => Event.Value({ value: a })\n\n/** End the current iteration and continue with a new state. */\nexport const next = <S>(state: S): Event<never, S> => Event.Next({ state })\n\n/** The terminal `Stop` event. Use `stop` (the Stream) to end a loop body. */\nexport const stopEvent: Event<never, never> = Event.Stop()\n\n/**\n * A single-element stream that ends the loop. Return this from a body when\n * there's nothing else to emit; equivalent to `stopAfter(Stream.empty)` but\n * named for the common case.\n */\nexport const stop: Stream.Stream<Event<never, never>> = Stream.succeed(stopEvent)\n\n/**\n * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the\n * iteration with `next(state)`. Common shape for \"stream this turn's\n * deltas, then continue with updated history.\"\n */\nexport const nextAfter = <S, A, E, R>(\n  stream: Stream.Stream<A, E, R>,\n  state: S,\n): Stream.Stream<Event<A, S>, E, R> =>\n  Stream.concat(Stream.map(stream, value), Stream.fromIterable([next(state)]))\n\n/**\n * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the\n * loop. Common shape for \"stream this turn's deltas, then we're done.\"\n */\nexport const stopAfter = <A, E, R>(\n  stream: Stream.Stream<A, E, R>,\n): Stream.Stream<Event<A, never>, E, R> =>\n  Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopEvent]))\n\n/**\n * General `nextAfter` variant: drain `stream` to the consumer, fold elements\n * into an accumulator, and at end-of-stream emit one `next(build(finalAcc))`.\n *\n * Subsumes `nextAfter` when state is constant (`reduce: (s, _) => s`,\n * `build: (s) => s`). Used by `Toolkit.nextStateFrom` to collect tool\n * results and build next state without exposing a Ref to recipes.\n */\nexport const nextAfterFold = <A, B, S, E, R>(\n  stream: Stream.Stream<A, E, R>,\n  initial: B,\n  reduce: (acc: B, a: A) => B,\n  build: (b: B) => S,\n): Stream.Stream<Event<A, S>, E, R> =>\n  Stream.unwrap(\n    Effect.gen(function* () {\n      const ref = yield* Ref.make(initial)\n      const tapped = stream.pipe(\n        Stream.tap((a) => Ref.update(ref, (acc) => reduce(acc, a))),\n        Stream.map(value),\n      )\n      const continuation = Stream.fromEffect(\n        Ref.get(ref).pipe(Effect.map((acc) => next(build(acc)))),\n      )\n      return tapped.pipe(Stream.concat(continuation))\n    }),\n  )\n\n// ---------------------------------------------------------------------------\n// streamUntilComplete - turn-aware stream operator for loop bodies\n// ---------------------------------------------------------------------------\n\n/**\n * Lift a provider's `Stream<TurnEvent>` into a loop body's `Stream<Event<TurnEvent | A, S>>`.\n * Each delta passes through as `value(delta)` (including the terminal\n * `turn_complete`, so the consumer sees turn boundaries naturally). Once\n * the terminal arrives, `then(turn)` runs and its returned stream of loop\n * events (typically tool outputs followed by `next(state)` or `stop`) is\n * concatenated.\n *\n * Pre-pipe transforms (`Stream.tap` / `Stream.map` / `Stream.filter`) on\n * the raw delta stream cover anything an `emit`-style callback would do.\n *\n * If the upstream ends without a `turn_complete`, the resulting stream\n * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if\n * you want to recover.\n */\nexport const streamUntilComplete =\n  <S, A, E2 = never, R2 = never>(\n    then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,\n  ) =>\n  <E, R>(\n    deltas: Stream.Stream<TurnEvent, E, R>,\n  ): Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2> =>\n    Stream.unwrap(\n      Effect.gen(function* () {\n        const turnRef = yield* Ref.make<Option.Option<Turn>>(Option.none())\n\n        const events: Stream.Stream<Event<TurnEvent, S>, E, R> = deltas.pipe(\n          Stream.tap((delta) =>\n            isTurnComplete(delta) ? Ref.set(turnRef, Option.some(delta.turn)) : Effect.void,\n          ),\n          Stream.map(value),\n        )\n\n        const continuation = Stream.unwrap(\n          Effect.gen(function* () {\n            const opt = yield* Ref.get(turnRef)\n            if (Option.isNone(opt)) return yield* Effect.fail(new IncompleteTurn({}))\n            return yield* then(opt.value)\n          }),\n        )\n\n        return Stream.concat(events, continuation)\n      }),\n    )\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nconst isNonEmpty = <A>(array: ReadonlyArray<A>): array is readonly [A, ...Array<A>] =>\n  array.length > 0\n\ninterface CurrentBody<S, A, E, R> {\n  readonly scope: Scope.Closeable\n  readonly pull: Effect.Effect<ReadonlyArray<Event<A, S>>, E | Cause.Done<void>, R>\n}\n\nconst closeBody = <S, A, E, R>(\n  current: CurrentBody<S, A, E, R>,\n  exit: Exit.Exit<unknown, unknown>,\n) => Scope.close(current.scope, exit)\n\n/**\n * Walk a chunk of `Event<A, S>` until a terminal `Next` or `Stop` is found.\n * Returns the unwrapped values seen so far and (optionally) the terminal\n * event. Anything in the chunk after the terminal is discarded - its\n * producing side effects may have run, but downstream never sees it.\n */\nconst partitionChunk = <A, S>(\n  chunk: ReadonlyArray<Event<A, S>>,\n): { readonly values: Array<A>; readonly decision: Event<A, S> | undefined } => {\n  const values: Array<A> = []\n  for (let i = 0; i < chunk.length; i++) {\n    const event = chunk[i]!\n    if (event._tag === \"Value\") {\n      values.push(event.value)\n    } else {\n      return { values, decision: event }\n    }\n  }\n  return { values, decision: undefined }\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\ntype LoopBody<S, A, E, R> = (\n  state: S,\n) => Stream.Stream<Event<A, S>, E, R> | Effect.Effect<Stream.Stream<Event<A, S>, E, R>, E, R>\n\n/**\n * Drive a state-threaded loop body. Each iteration runs `body(state)` to get\n * a `Stream<Event<A, S>>`; values flow downstream, `next(s)` continues with\n * a new state, `stop` ends the loop. See the file header for the full\n * pull-based execution model.\n *\n * Dual: data-first `loop(initial, body)` and data-last `loop(body)(initial)`\n * (or `pipe(initial, loop(body))`) both work.\n */\nexport const loop: {\n  <S, A, E, R>(body: LoopBody<S, A, E, R>): (initial: S) => Stream.Stream<A, E, R>\n  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R>\n} = Function.dual(\n  2,\n  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R> =>\n    Stream.scoped(\n      Stream.fromPull(\n        Effect.gen(function* () {\n          const outerScope = yield* Effect.scope\n          let state = initial\n          let current: CurrentBody<S, A, E, R> | undefined\n          let done = false\n\n          const closeActive = (\n            active: CurrentBody<S, A, E, R>,\n            exit: Exit.Exit<unknown, unknown>,\n          ) => {\n            const isActive = current === active\n            if (isActive) current = undefined\n            // Scope.close is idempotent. Multiple paths can race to close the\n            // active body during cancellation/failure, so closing twice is safe.\n            return closeBody(active, exit)\n          }\n\n          yield* Scope.addFinalizerExit(outerScope, (exit) =>\n            current === undefined ? Effect.void : closeActive(current, exit),\n          )\n\n          const pull = Effect.gen(function* () {\n            while (true) {\n              if (done) return yield* Cause.done()\n\n              if (current === undefined) {\n                const result = body(state)\n                const stream = Effect.isEffect(result) ? Stream.unwrap(result) : result\n                const bodyScope = yield* Scope.fork(outerScope)\n                const bodyPull = yield* Channel.toPullScoped(\n                  Stream.toChannel(stream),\n                  bodyScope,\n                ).pipe(Effect.onError((cause) => Scope.close(bodyScope, Exit.failCause(cause))))\n                current = { scope: bodyScope, pull: bodyPull }\n              }\n\n              const active = current\n              const chunk = yield* active.pull.pipe(\n                Effect.catchIf(Cause.isDone, () =>\n                  closeActive(active, Exit.void).pipe(\n                    Effect.as(undefined as ReadonlyArray<Event<A, S>> | undefined),\n                  ),\n                ),\n                Effect.onError((cause) => closeActive(active, Exit.failCause(cause))),\n              )\n\n              if (chunk === undefined) {\n                done = true\n                return yield* Cause.done()\n              }\n\n              const { values, decision } = partitionChunk(chunk)\n\n              if (decision !== undefined) {\n                yield* closeActive(active, Exit.void)\n                if (decision._tag === \"Stop\") {\n                  done = true\n                } else if (decision._tag === \"Next\") {\n                  state = decision.state\n                }\n              }\n\n              // Emit the values seen so far if any. Chunks from a Stream pull\n              // are non-empty, so when `decision === undefined` every event was\n              // a `Value` and `values` is non-empty here. With a decision and\n              // no preceding values, fall through to the next iteration.\n              if (isNonEmpty(values)) return values\n            }\n          })\n\n          return pull\n        }),\n      ),\n    ),\n)\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,MAAM,QAAQ,KAAK,YAAsB;;AAGzC,MAAa,SAAY,MAA0B,MAAM,MAAM,EAAE,OAAO,GAAG,CAAC;;AAG5E,MAAa,QAAW,UAA8B,MAAM,KAAK,EAAE,OAAO,CAAC;;AAG3E,MAAa,YAAiC,MAAM,MAAM;;;;;;AAO1D,MAAa,OAA2C,OAAO,QAAQ,UAAU;;;;;;AAOjF,MAAa,aACX,QACA,UAEA,OAAO,OAAO,OAAO,IAAI,QAAQ,MAAM,EAAE,OAAO,aAAa,CAAC,KAAK,MAAM,CAAC,CAAC,CAAC;;;;;AAM9E,MAAa,aACX,WAEA,OAAO,OAAO,OAAO,IAAI,QAAQ,MAAM,EAAE,OAAO,aAAa,CAAC,UAAU,CAAC,CAAC;;;;;;;;;AAU5E,MAAa,iBACX,QACA,SACA,QACA,UAEA,OAAO,OACL,OAAO,IAAI,aAAa;CACtB,MAAM,MAAM,OAAO,IAAI,KAAK,QAAQ;CACpC,MAAM,SAAS,OAAO,KACpB,OAAO,KAAK,MAAM,IAAI,OAAO,MAAM,QAAQ,OAAO,KAAK,EAAE,CAAC,CAAC,EAC3D,OAAO,IAAI,MAAM,CAClB;CACD,MAAM,eAAe,OAAO,WAC1B,IAAI,IAAI,IAAI,CAAC,KAAK,OAAO,KAAK,QAAQ,KAAK,MAAM,IAAI,CAAC,CAAC,CAAC,CACzD;AACD,QAAO,OAAO,KAAK,OAAO,OAAO,aAAa,CAAC;EAC/C,CACH;;;;;;;;;;;;;;;;AAqBH,MAAa,uBAET,UAGA,WAEA,OAAO,OACL,OAAO,IAAI,aAAa;CACtB,MAAM,UAAU,OAAO,IAAI,KAA0B,OAAO,MAAM,CAAC;CAEnE,MAAM,SAAmD,OAAO,KAC9D,OAAO,KAAK,UACV,eAAe,MAAM,GAAG,IAAI,IAAI,SAAS,OAAO,KAAK,MAAM,KAAK,CAAC,GAAG,OAAO,KAC5E,EACD,OAAO,IAAI,MAAM,CAClB;CAED,MAAM,eAAe,OAAO,OAC1B,OAAO,IAAI,aAAa;EACtB,MAAM,MAAM,OAAO,IAAI,IAAI,QAAQ;AACnC,MAAI,OAAO,OAAO,IAAI,CAAE,QAAO,OAAO,OAAO,KAAK,IAAI,eAAe,EAAE,CAAC,CAAC;AACzE,SAAO,OAAO,KAAK,IAAI,MAAM;GAC7B,CACH;AAED,QAAO,OAAO,OAAO,QAAQ,aAAa;EAC1C,CACH;AAML,MAAM,cAAiB,UACrB,MAAM,SAAS;AAOjB,MAAM,aACJ,SACA,SACG,MAAM,MAAM,QAAQ,OAAO,KAAK;;;;;;;AAQrC,MAAM,kBACJ,UAC8E;CAC9E,MAAM,SAAmB,EAAE;AAC3B,MAAK,IAAI,IAAI,GAAG,IAAI,MAAM,QAAQ,KAAK;EACrC,MAAM,QAAQ,MAAM;AACpB,MAAI,MAAM,SAAS,QACjB,QAAO,KAAK,MAAM,MAAM;MAExB,QAAO;GAAE;GAAQ,UAAU;GAAO;;AAGtC,QAAO;EAAE;EAAQ,UAAU,KAAA;EAAW;;;;;;;;;;;AAoBxC,MAAa,OAGT,SAAS,KACX,IACa,SAAY,SACvB,OAAO,OACL,OAAO,SACL,OAAO,IAAI,aAAa;CACtB,MAAM,aAAa,OAAO,OAAO;CACjC,IAAI,QAAQ;CACZ,IAAI;CACJ,IAAI,OAAO;CAEX,MAAM,eACJ,QACA,SACG;AAEH,MADiB,YAAY,OACf,WAAU,KAAA;AAGxB,SAAO,UAAU,QAAQ,KAAK;;AAGhC,QAAO,MAAM,iBAAiB,aAAa,SACzC,YAAY,KAAA,IAAY,OAAO,OAAO,YAAY,SAAS,KAAK,CACjE;AAmDD,QAjDa,OAAO,IAAI,aAAa;AACnC,SAAO,MAAM;AACX,OAAI,KAAM,QAAO,OAAO,MAAM,MAAM;AAEpC,OAAI,YAAY,KAAA,GAAW;IACzB,MAAM,SAAS,KAAK,MAAM;IAC1B,MAAM,SAAS,OAAO,SAAS,OAAO,GAAG,OAAO,OAAO,OAAO,GAAG;IACjE,MAAM,YAAY,OAAO,MAAM,KAAK,WAAW;AAK/C,cAAU;KAAE,OAAO;KAAW,MAAM,OAJZ,QAAQ,aAC9B,OAAO,UAAU,OAAO,EACxB,UACD,CAAC,KAAK,OAAO,SAAS,UAAU,MAAM,MAAM,WAAW,KAAK,UAAU,MAAM,CAAC,CAAC,CAAC;KAClC;;GAGhD,MAAM,SAAS;GACf,MAAM,QAAQ,OAAO,OAAO,KAAK,KAC/B,OAAO,QAAQ,MAAM,cACnB,YAAY,QAAQ,KAAK,KAAK,CAAC,KAC7B,OAAO,GAAG,KAAA,EAAoD,CAC/D,CACF,EACD,OAAO,SAAS,UAAU,YAAY,QAAQ,KAAK,UAAU,MAAM,CAAC,CAAC,CACtE;AAED,OAAI,UAAU,KAAA,GAAW;AACvB,WAAO;AACP,WAAO,OAAO,MAAM,MAAM;;GAG5B,MAAM,EAAE,QAAQ,aAAa,eAAe,MAAM;AAElD,OAAI,aAAa,KAAA,GAAW;AAC1B,WAAO,YAAY,QAAQ,KAAK,KAAK;AACrC,QAAI,SAAS,SAAS,OACpB,QAAO;aACE,SAAS,SAAS,OAC3B,SAAQ,SAAS;;AAQrB,OAAI,WAAW,OAAO,CAAE,QAAO;;GAIxB;EACX,CACH,CACF,CACJ"}
+{"version":3,"file":"Loop.mjs","names":[],"sources":["../../src/loop/Loop.ts"],"sourcesContent":["/**\n * Pull-based `loop` for state-threaded sub-streams.\n *\n * Each iteration runs a body that returns a `Stream<Event<A, S>>`. The body\n * emits values via `Loop.value(a)` and signals iteration control via\n * `Loop.next(state)` (continue with new state) or `Loop.stop` (terminate).\n * The loop unwraps `Value` events back to `A` for downstream consumers, so\n * the resulting stream is a plain `Stream<A>`.\n *\n * The next body stream is only pulled when downstream pulls the outer\n * stream - no producer fiber, no queue buffering. Cancellation, failures,\n * scoped resources, and backpressure stay aligned with normal Stream\n * semantics.\n *\n * Convention: a `Next` or `Stop` event is the terminal element of a body's\n * iteration. Values emitted in the same chunk after one are discarded\n * (their producing side effects may already have run). Prefer the\n * `Loop.nextAfter` / `Loop.stopAfter` helpers to terminate cleanly.\n */\nimport {\n  Cause,\n  Channel,\n  Data,\n  Effect,\n  Exit,\n  Function,\n  Option,\n  Ref,\n  Scope,\n  Stream,\n  SubscriptionRef,\n} from \"effect\"\nimport { IncompleteTurn } from \"../domain/AiError.js\"\nimport { isTurnComplete, type Turn, type TurnEvent } from \"../domain/Turn.js\"\n\n// ---------------------------------------------------------------------------\n// Event type - the body's emit shape\n// ---------------------------------------------------------------------------\n\n/**\n * The tagged union a body emits per pull. `Value` carries a payload that\n * flows downstream. `Next` ends the current iteration and continues with a\n * new state. `Stop` ends the loop entirely.\n */\nexport type Event<A, S> = Data.TaggedEnum<{\n  Value: { readonly value: A }\n  Next: { readonly state: S }\n  Stop: {}\n}>\n\ninterface EventDef extends Data.TaggedEnum.WithGenerics<2> {\n  readonly taggedEnum: Event<this[\"A\"], this[\"B\"]>\n}\n\nconst Event = Data.taggedEnum<EventDef>()\n\n/** Wrap a value so it flows through the loop to downstream consumers. */\nexport const value = <A>(a: A): Event<A, never> => Event.Value({ value: a })\n\n/** End the current iteration and continue with a new state. */\nexport const next = <S>(state: S): Event<never, S> => Event.Next({ state })\n\n/** The terminal `Stop` event. Use `stop` (the Stream) to end a loop body. */\nexport const stopEvent: Event<never, never> = Event.Stop()\n\n/**\n * A single-element stream that ends the loop. Return this from a body when\n * there's nothing else to emit; equivalent to `stopAfter(Stream.empty)` but\n * named for the common case.\n */\nexport const stop: Stream.Stream<Event<never, never>> = Stream.succeed(stopEvent)\n\n/**\n * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the\n * iteration with `next(state)`. Common shape for \"stream this turn's\n * deltas, then continue with updated history.\"\n */\nexport const nextAfter = <S, A, E, R>(\n  stream: Stream.Stream<A, E, R>,\n  state: S,\n): Stream.Stream<Event<A, S>, E, R> =>\n  Stream.concat(Stream.map(stream, value), Stream.fromIterable([next(state)]))\n\n/**\n * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the\n * loop. Common shape for \"stream this turn's deltas, then we're done.\"\n */\nexport const stopAfter = <A, E, R>(\n  stream: Stream.Stream<A, E, R>,\n): Stream.Stream<Event<A, never>, E, R> =>\n  Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopEvent]))\n\n/**\n * General `nextAfter` variant: drain `stream` to the consumer, fold elements\n * into an accumulator, and at end-of-stream emit one `next(build(finalAcc))`.\n *\n * Subsumes `nextAfter` when state is constant (`reduce: (s, _) => s`,\n * `build: (s) => s`). Used by `Toolkit.continueWith` to collect tool\n * results and build next state without exposing a Ref to recipes.\n */\nexport const nextAfterFold = <A, B, S, E, R>(\n  stream: Stream.Stream<A, E, R>,\n  initial: B,\n  reduce: (acc: B, a: A) => B,\n  build: (b: B) => S,\n): Stream.Stream<Event<A, S>, E, R> =>\n  Stream.unwrap(\n    Effect.gen(function* () {\n      const ref = yield* Ref.make(initial)\n      const tapped = stream.pipe(\n        Stream.tap((a) => Ref.update(ref, (acc) => reduce(acc, a))),\n        Stream.map(value),\n      )\n      const continuation = Stream.fromEffect(\n        Ref.get(ref).pipe(Effect.map((acc) => next(build(acc)))),\n      )\n      return tapped.pipe(Stream.concat(continuation))\n    }),\n  )\n\n// ---------------------------------------------------------------------------\n// onTurnComplete - turn-aware stream operator for loop bodies\n// ---------------------------------------------------------------------------\n\n/**\n * Lift a provider's `Stream<TurnEvent>` into a loop body's `Stream<Event<TurnEvent | A, S>>`.\n * Each delta passes through as `value(delta)` (including the terminal\n * `turn_complete`, so the consumer sees turn boundaries naturally). Once\n * the terminal arrives, `then(turn)` runs and its returned stream of loop\n * events (typically tool outputs followed by `next(state)` or `stop`) is\n * concatenated.\n *\n * Pre-pipe transforms (`Stream.tap` / `Stream.map` / `Stream.filter`) on\n * the raw delta stream cover anything an `emit`-style callback would do.\n *\n * If the upstream ends without a `turn_complete`, the resulting stream\n * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if\n * you want to recover.\n */\nexport const onTurnComplete =\n  <S, A, E2 = never, R2 = never>(\n    then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,\n  ) =>\n  <E, R>(\n    deltas: Stream.Stream<TurnEvent, E, R>,\n  ): Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2> =>\n    Stream.unwrap(\n      Effect.gen(function* () {\n        const turnRef = yield* Ref.make<Option.Option<Turn>>(Option.none())\n\n        const events: Stream.Stream<Event<TurnEvent, S>, E, R> = deltas.pipe(\n          Stream.tap((delta) =>\n            isTurnComplete(delta) ? Ref.set(turnRef, Option.some(delta.turn)) : Effect.void,\n          ),\n          Stream.map(value),\n        )\n\n        const continuation = Stream.unwrap(\n          Effect.gen(function* () {\n            const opt = yield* Ref.get(turnRef)\n            if (Option.isNone(opt)) return yield* Effect.fail(new IncompleteTurn({}))\n            return yield* then(opt.value)\n          }),\n        )\n\n        return Stream.concat(events, continuation)\n      }),\n    )\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nconst isNonEmpty = <A>(array: ReadonlyArray<A>): array is readonly [A, ...Array<A>] =>\n  array.length > 0\n\ntype CurrentBody<S, A, E, R> = {\n  readonly scope: Scope.Closeable\n  readonly pull: Effect.Effect<ReadonlyArray<Event<A, S>>, E | Cause.Done<void>, R>\n}\n\nconst closeBody = <S, A, E, R>(\n  current: CurrentBody<S, A, E, R>,\n  exit: Exit.Exit<unknown, unknown>,\n) => Scope.close(current.scope, exit)\n\n/**\n * Walk a chunk of `Event<A, S>` until a terminal `Next` or `Stop` is found.\n * Returns the unwrapped values seen so far and (optionally) the terminal\n * event. Anything in the chunk after the terminal is discarded - its\n * producing side effects may have run, but downstream never sees it.\n */\nconst partitionChunk = <A, S>(\n  chunk: ReadonlyArray<Event<A, S>>,\n): { readonly values: Array<A>; readonly decision: Event<A, S> | undefined } => {\n  const values: Array<A> = []\n  for (let i = 0; i < chunk.length; i++) {\n    const event = chunk[i]!\n    if (event._tag === \"Value\") {\n      values.push(event.value)\n    } else {\n      return { values, decision: event }\n    }\n  }\n  return { values, decision: undefined }\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\ntype LoopBody<S, A, E, R> = (\n  state: S,\n) => Stream.Stream<Event<A, S>, E, R> | Effect.Effect<Stream.Stream<Event<A, S>, E, R>, E, R>\n\n/**\n * Drive a state-threaded loop body. Each iteration runs `body(state)` to get\n * a `Stream<Event<A, S>>`; values flow downstream, `next(s)` continues with\n * a new state, `stop` ends the loop. See the file header for the full\n * pull-based execution model.\n *\n * Dual: data-first `loop(initial, body)` and data-last `loop(body)(initial)`\n * (or `pipe(initial, loop(body))`) both work.\n */\nexport const loop: {\n  <S, A, E, R>(body: LoopBody<S, A, E, R>): (initial: S) => Stream.Stream<A, E, R>\n  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R>\n} = Function.dual(\n  2,\n  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R> =>\n    Stream.scoped(\n      Stream.fromPull(\n        Effect.gen(function* () {\n          const outerScope = yield* Effect.scope\n          let state = initial\n          let current: CurrentBody<S, A, E, R> | undefined\n          let done = false\n\n          const closeActive = (\n            active: CurrentBody<S, A, E, R>,\n            exit: Exit.Exit<unknown, unknown>,\n          ) => {\n            const isActive = current === active\n            if (isActive) current = undefined\n            // Scope.close is idempotent. Multiple paths can race to close the\n            // active body during cancellation/failure, so closing twice is safe.\n            return closeBody(active, exit)\n          }\n\n          yield* Scope.addFinalizerExit(outerScope, (exit) =>\n            current === undefined ? Effect.void : closeActive(current, exit),\n          )\n\n          const pull = Effect.gen(function* () {\n            while (true) {\n              if (done) return yield* Cause.done()\n\n              if (current === undefined) {\n                const result = body(state)\n                const stream = Effect.isEffect(result) ? Stream.unwrap(result) : result\n                const bodyScope = yield* Scope.fork(outerScope)\n                const bodyPull = yield* Channel.toPullScoped(\n                  Stream.toChannel(stream),\n                  bodyScope,\n                ).pipe(Effect.onError((cause) => Scope.close(bodyScope, Exit.failCause(cause))))\n                current = { scope: bodyScope, pull: bodyPull }\n              }\n\n              const active = current\n              const chunk = yield* active.pull.pipe(\n                Effect.catchIf(Cause.isDone, () =>\n                  closeActive(active, Exit.void).pipe(\n                    Effect.as(undefined as ReadonlyArray<Event<A, S>> | undefined),\n                  ),\n                ),\n                Effect.onError((cause) => closeActive(active, Exit.failCause(cause))),\n              )\n\n              if (chunk === undefined) {\n                done = true\n                return yield* Cause.done()\n              }\n\n              const { values, decision } = partitionChunk(chunk)\n\n              if (decision !== undefined) {\n                yield* closeActive(active, Exit.void)\n                if (decision._tag === \"Stop\") {\n                  done = true\n                } else if (decision._tag === \"Next\") {\n                  state = decision.state\n                }\n              }\n\n              // Emit the values seen so far if any. Chunks from a Stream pull\n              // are non-empty, so when `decision === undefined` every event was\n              // a `Value` and `values` is non-empty here. With a decision and\n              // no preceding values, fall through to the next iteration.\n              if (isNonEmpty(values)) return values\n            }\n          })\n\n          return pull\n        }),\n      ),\n    ),\n)\n\n// ---------------------------------------------------------------------------\n// loopWithState - same body protocol, plus a live state observable.\n// ---------------------------------------------------------------------------\n\n/**\n * Like `loop`, but exposes the current loop state as a `SubscriptionRef`\n * alongside the value stream.\n *\n * Allocates one `SubscriptionRef<S>` seeded with `initial`, then runs the\n * loop with a wrapped body that taps every `Next(s)` event into the ref\n * before forwarding it. The caller decides how to consume both channels:\n *\n *   - **Final state**: drain the stream, then `SubscriptionRef.get(state)`\n *     - the ref holds the state from the last `Next` (or `initial` if the\n *     loop ended without advancing).\n *   - **Live transitions**: `SubscriptionRef.changes(state)` is a\n *     `Stream<S>` of every state observed; subscribe alongside the value\n *     stream.\n *   - **Mid-iteration peek**: `SubscriptionRef.get(state)` at any time.\n *\n * The returned stream and ref are independent of each other - the ref\n * lives outside the stream's scope, so reading it after the stream\n * completes is safe.\n */\nexport const loopWithState = <S, A, E, R>(\n  initial: S,\n  body: LoopBody<S, A, E, R>,\n): Effect.Effect<{\n  readonly stream: Stream.Stream<A, E, R>\n  readonly state: SubscriptionRef.SubscriptionRef<S>\n}> =>\n  Effect.gen(function* () {\n    const stateRef = yield* SubscriptionRef.make(initial)\n\n    const tap = (stream: Stream.Stream<Event<A, S>, E, R>): Stream.Stream<Event<A, S>, E, R> =>\n      stream.pipe(\n        Stream.tap((event) =>\n          event._tag === \"Next\" ? SubscriptionRef.set(stateRef, event.state) : Effect.void,\n        ),\n      )\n\n    const wrappedBody: LoopBody<S, A, E, R> = (s) => {\n      const result = body(s)\n      return Effect.isEffect(result) ? Effect.map(result, tap) : tap(result)\n    }\n\n    return {\n      stream: loop(initial, wrappedBody),\n      state: stateRef,\n    }\n  })\n"],"mappings":"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"}

package/dist/loop/Loop.test.d.mts

@@ -0,0 +1 @@
+export { };