@effect-uai/core 0.5.2 → 0.7.0

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

@@ -1,33 +1,33 @@
 import { t as AiError } from "../AiError-CAX_48RU.mjs";
-import { EmbedInput, EmbeddingFor, Usage } from "./Embedding.mjs";
+import { EmbedInput, EmbeddingFor, ResponseEncoding, Usage } from "./Embedding.mjs";
 import { Context, Effect } from "effect";
 
 //#region src/embedding-model/EmbeddingModel.d.ts
 declare namespace EmbeddingModel_d_exports {
-  export { CommonEmbedManyRequest, CommonEmbedRequest, EmbedEncoding, EmbedManyResponse, EmbedResponse, EmbeddingModel, EmbeddingModelService, embed, embedMany };
+  export { CommonEmbedManyRequest, CommonEmbedRequest, EmbedEncoding, EmbedManyResponse, EmbedResponse, EmbeddingModel, EmbeddingModelService, assertEncoding, embed, embedMany };
 }
 /**
- * Output representation requested from the provider.
+ * Output representation requested from the provider. Cross-provider dense
+ * quantization only, the same vector at different storage cost:
+ * - `float32`: universal default.
+ * - `int8`: ~4x smaller, minimal recall loss on most benchmarks. Supported
+ *   by Cohere, Voyage, Jina (binary only), Mixedbread.
+ * - `binary`: ~32x smaller, meaningful recall loss but pairs well with a
+ *   float32 reranker pass over a small candidate set.
  *
- * 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`, `multivector`) are a different vector
+ * *structure*, not a storage option, and are produced by Jina only. They
+ * live on `JinaEncoding`, not here (the same widening pattern `task` uses).
+ * The response `Embedding` union still carries all arms, see
+ * {@link ResponseEncoding}.
  *
- * 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. `JinaEmbedEncoding = "float32" | "binary" | "sparse" |
- * "multivector"`). On the generic `EmbeddingModel` path, callers can
- * pass any `EmbedEncoding` and the provider's API will reject mismatches at
- * runtime.
+ * Each provider's typed request narrows this to its supported set. On the
+ * generic `EmbeddingModel` path, a provider that emits float32 only (OpenAI,
+ * Gemini) rejects a non-float32 encoding with `AiError.Unsupported`
+ * (bucket 1) via {@link assertEncoding}, rather than silently returning a
+ * mislabeled float32 vector.
  */
-type EmbedEncoding = "float32" | "int8" | "binary" | "sparse" | "multivector";
+type EmbedEncoding = "float32" | "int8" | "binary";
 /**
  * Cross-provider single-embed request. Mirrors the shape of
  * `LanguageModel.CommonRequest`: cross-cutting fields here, vendor
@@ -81,12 +81,12 @@ type CommonEmbedManyRequest = Omit<CommonEmbedRequest, "input"> & {
  * narrowing. Defaults to `undefined` for back-compat with consumers that
  * use the bare `EmbedResponse` name.
  */
-type EmbedResponse<E extends EmbedEncoding | undefined = undefined> = {
+type EmbedResponse<E extends ResponseEncoding | undefined = undefined> = {
   readonly embedding: EmbeddingFor<E>;
   readonly usage: Usage;
 };
 /** Batch-embed response. Same encoding rule as {@link EmbedResponse}. */
-type EmbedManyResponse<E extends EmbedEncoding | undefined = undefined> = {
+type EmbedManyResponse<E extends ResponseEncoding | undefined = undefined> = {
   readonly embeddings: ReadonlyArray<EmbeddingFor<E>>;
   readonly usage: Usage;
 };
@@ -108,6 +108,19 @@ declare const embed: <E extends EmbedEncoding | undefined = undefined>(request:
 declare const embedMany: <E extends EmbedEncoding | undefined = undefined>(request: Omit<CommonEmbedManyRequest, "encoding"> & {
   readonly encoding?: E;
 }) => Effect.Effect<EmbedManyResponse<E>, AiError, EmbeddingModel>;
+/**
+ * Guard a requested `encoding` against a provider's supported set. Returns
+ * `void` when the encoding is unset or supported, and fails
+ * `AiError.Unsupported` (bucket 1) otherwise.
+ *
+ * Used by the generic-tag registration of providers that emit a strict
+ * subset of `EmbedEncoding`: OpenAI / Gemini pass `["float32"]`, Jina passes
+ * `["float32", "binary"]`. Without this guard, a non-supported encoding on
+ * the generic path silently returns a float32 vector mislabeled as the
+ * requested type (the `as`-cast lie), which breaks downstream storage and
+ * vector math.
+ */
+declare const assertEncoding: (encoding: EmbedEncoding | undefined, supported: ReadonlyArray<EmbedEncoding>, provider: string) => Effect.Effect<void, AiError>;
 //#endregion
-export { CommonEmbedManyRequest, CommonEmbedRequest, EmbedEncoding, EmbedManyResponse, EmbedResponse, EmbeddingModel, EmbeddingModelService, embed, embedMany, EmbeddingModel_d_exports as t };
+export { CommonEmbedManyRequest, CommonEmbedRequest, EmbedEncoding, EmbedManyResponse, EmbedResponse, EmbeddingModel, EmbeddingModelService, assertEncoding, embed, embedMany, EmbeddingModel_d_exports as t };
 //# sourceMappingURL=EmbeddingModel.d.mts.map

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

@@ -1 +1 @@
-{"version":3,"file":"EmbeddingModel.d.mts","names":[],"sources":["../../src/embedding-model/EmbeddingModel.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAyBA;;;;;AAYA;;KAZY,aAAA;;;;;;;;;;;KAYA,kBAAA;EAAA,SACD,KAAA,EAAO,UAAA;;;;;WAKP,KAAA;EA6BqB;;;;;;;EAAA,SArBrB,IAAA;EAqBgC;AAU3C;;;;EAV2C,SAfhC,UAAA;EA0BW;;;;;EAAA,SApBX,QAAA,GAAW,aAAA;AAAA;;;;;;KAQV,sBAAA,GAAyB,IAAA,CAAK,kBAAA;EAAA,SAC/B,MAAA,EAAQ,aAAA,CAAc,UAAA;AAAA;;;;;;;;KAUrB,aAAA,WAAwB,aAAA;EAAA,SACzB,SAAA,EAAW,YAAA,CAAa,CAAA;EAAA,SACxB,KAAA,EAAO,KAAA;AAAA;;KAIN,iBAAA,WAA4B,aAAA;EAAA,SAC7B,UAAA,EAAY,aAAA,CAAc,YAAA,CAAa,CAAA;EAAA,SACvC,KAAA,EAAO,KAAA;AAAA;AAAA,KAGN,qBAAA;EAAA,SACD,KAAA,aAAkB,aAAA,0BACzB,OAAA,EAAS,IAAA,CAAK,kBAAA;IAAA,SAA6C,QAAA,GAAW,CAAA;EAAA,MACnE,MAAA,CAAO,MAAA,CAAO,aAAA,CAAc,CAAA,GAAI,OAAA;EAAA,SAC5B,SAAA,aAAsB,aAAA,0BAC7B,OAAA,EAAS,IAAA,CAAK,sBAAA;IAAA,SAAiD,QAAA,GAAW,CAAA;EAAA,MACvE,MAAA,CAAO,MAAA,CAAO,iBAAA,CAAkB,CAAA,GAAI,OAAA;AAAA;AAAA,cAC1C,mBAAA;cAEY,cAAA,SAAuB,mBAAA;;cAKvB,KAAA,aAAmB,aAAA,0BAC9B,OAAA,EAAS,IAAA,CAAK,kBAAA;EAAA,SAA6C,QAAA,GAAW,CAAA;AAAA,MACrE,MAAA,CAAO,MAAA,CAAO,aAAA,CAAc,CAAA,GAAI,OAAA,EAAiB,cAAA;;cAIvC,SAAA,aAAuB,aAAA,0BAClC,OAAA,EAAS,IAAA,CAAK,sBAAA;EAAA,SAAiD,QAAA,GAAW,CAAA;AAAA,MACzE,MAAA,CAAO,MAAA,CAAO,iBAAA,CAAkB,CAAA,GAAI,OAAA,EAAiB,cAAA"}
+{"version":3,"file":"EmbeddingModel.d.mts","names":[],"sources":["../../src/embedding-model/EmbeddingModel.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAyBA;;;;;AAYA;KAZY,aAAA;;;;;;;;;;;KAYA,kBAAA;EAAA,SACD,KAAA,EAAO,UAAA;EAiCgB;;;;EAAA,SA5BvB,KAAA;EA6BQ;;;;;;;EAAA,SArBR,IAAA;EAqBgC;;AAU3C;;;EAV2C,SAfhC,UAAA;EA0BwB;;;;;EAAA,SApBxB,QAAA,GAAW,aAAA;AAAA;;;;;;KAQV,sBAAA,GAAyB,IAAA,CAAK,kBAAA;EAAA,SAC/B,MAAA,EAAQ,aAAA,CAAc,UAAA;AAAA;;;;;;;;KAUrB,aAAA,WAAwB,gBAAA;EAAA,SACzB,SAAA,EAAW,YAAA,CAAa,CAAA;EAAA,SACxB,KAAA,EAAO,KAAA;AAAA;;KAIN,iBAAA,WAA4B,gBAAA;EAAA,SAC7B,UAAA,EAAY,aAAA,CAAc,YAAA,CAAa,CAAA;EAAA,SACvC,KAAA,EAAO,KAAA;AAAA;AAAA,KAGN,qBAAA;EAAA,SACD,KAAA,aAAkB,aAAA,0BACzB,OAAA,EAAS,IAAA,CAAK,kBAAA;IAAA,SAA6C,QAAA,GAAW,CAAA;EAAA,MACnE,MAAA,CAAO,MAAA,CAAO,aAAA,CAAc,CAAA,GAAI,OAAA;EAAA,SAC5B,SAAA,aAAsB,aAAA,0BAC7B,OAAA,EAAS,IAAA,CAAK,sBAAA;IAAA,SAAiD,QAAA,GAAW,CAAA;EAAA,MACvE,MAAA,CAAO,MAAA,CAAO,iBAAA,CAAkB,CAAA,GAAI,OAAA;AAAA;AAAA,cAC1C,mBAAA;cAEY,cAAA,SAAuB,mBAAA;;cAKvB,KAAA,aAAmB,aAAA,0BAC9B,OAAA,EAAS,IAAA,CAAK,kBAAA;EAAA,SAA6C,QAAA,GAAW,CAAA;AAAA,MACrE,MAAA,CAAO,MAAA,CAAO,aAAA,CAAc,CAAA,GAAI,OAAA,EAAiB,cAAA;;cAIvC,SAAA,aAAuB,aAAA,0BAClC,OAAA,EAAS,IAAA,CAAK,sBAAA;EAAA,SAAiD,QAAA,GAAW,CAAA;AAAA,MACzE,MAAA,CAAO,MAAA,CAAO,iBAAA,CAAkB,CAAA,GAAI,OAAA,EAAiB,cAAA;;;;;;;;;;;;;cAe3C,cAAA,GACX,QAAA,EAAU,aAAA,cACV,SAAA,EAAW,aAAA,CAAc,aAAA,GACzB,QAAA,aACC,MAAA,CAAO,MAAA,OAAa,OAAA"}

package/dist/embedding-model/EmbeddingModel.mjs

@@ -1,8 +1,10 @@
 import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
+import { Unsupported } from "../domain/AiError.mjs";
 import { Context, Effect } from "effect";
 //#region src/embedding-model/EmbeddingModel.ts
 var EmbeddingModel_exports = /* @__PURE__ */ __exportAll({
 	EmbeddingModel: () => EmbeddingModel,
+	assertEncoding: () => assertEncoding,
 	embed: () => embed,
 	embedMany: () => embedMany
 });
@@ -11,7 +13,24 @@ var EmbeddingModel = class extends Context.Service()("@betalyra/effect-uai/Embed
 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));
+/**
+* Guard a requested `encoding` against a provider's supported set. Returns
+* `void` when the encoding is unset or supported, and fails
+* `AiError.Unsupported` (bucket 1) otherwise.
+*
+* Used by the generic-tag registration of providers that emit a strict
+* subset of `EmbedEncoding`: OpenAI / Gemini pass `["float32"]`, Jina passes
+* `["float32", "binary"]`. Without this guard, a non-supported encoding on
+* the generic path silently returns a float32 vector mislabeled as the
+* requested type (the `as`-cast lie), which breaks downstream storage and
+* vector math.
+*/
+const assertEncoding = (encoding, supported, provider) => encoding === void 0 || supported.includes(encoding) ? Effect.void : Effect.fail(new Unsupported({
+	provider,
+	capability: "encoding",
+	reason: `${provider} emits ${supported.join(" / ")} only; encoding="${encoding}" is unavailable.`
+}));
 //#endregion
-export { EmbeddingModel, embed, embedMany, EmbeddingModel_exports as t };
+export { EmbeddingModel, assertEncoding, embed, embedMany, EmbeddingModel_exports as t };
 
 //# sourceMappingURL=EmbeddingModel.mjs.map

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

@@ -1 +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 { EmbeddingFor, 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. `JinaEmbedEncoding = \"float32\" | \"binary\" | \"sparse\" |\n * \"multivector\"`). On the generic `EmbeddingModel` path, callers can\n * pass any `EmbedEncoding` and the provider's API will reject mismatches at\n * runtime.\n */\nexport type EmbedEncoding = \"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 EmbedEncoding}. Dense float32 is the\n   * default; provider layers reject unsupported values up front with\n   * `InvalidRequest`.\n   */\n  readonly encoding?: EmbedEncoding\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\n/**\n * Single-embed response. The `embedding` type is determined by the\n * request's `encoding` field via `EmbeddingFor<E>` — callers that don't\n * specify an encoding get a `Float32Embedding` directly with no runtime\n * narrowing. Defaults to `undefined` for back-compat with consumers that\n * use the bare `EmbedResponse` name.\n */\nexport type EmbedResponse<E extends EmbedEncoding | undefined = undefined> = {\n  readonly embedding: EmbeddingFor<E>\n  readonly usage: Usage\n}\n\n/** Batch-embed response. Same encoding rule as {@link EmbedResponse}. */\nexport type EmbedManyResponse<E extends EmbedEncoding | undefined = undefined> = {\n  readonly embeddings: ReadonlyArray<EmbeddingFor<E>>\n  readonly usage: Usage\n}\n\nexport type EmbeddingModelService = {\n  readonly embed: <E extends EmbedEncoding | undefined = undefined>(\n    request: Omit<CommonEmbedRequest, \"encoding\"> & { readonly encoding?: E },\n  ) => Effect.Effect<EmbedResponse<E>, AiError.AiError>\n  readonly embedMany: <E extends EmbedEncoding | undefined = undefined>(\n    request: Omit<CommonEmbedManyRequest, \"encoding\"> & { readonly encoding?: E },\n  ) => Effect.Effect<EmbedManyResponse<E>, 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 = <E extends EmbedEncoding | undefined = undefined>(\n  request: Omit<CommonEmbedRequest, \"encoding\"> & { readonly encoding?: E },\n): Effect.Effect<EmbedResponse<E>, 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 = <E extends EmbedEncoding | undefined = undefined>(\n  request: Omit<CommonEmbedManyRequest, \"encoding\"> & { readonly encoding?: E },\n): Effect.Effect<EmbedManyResponse<E>, AiError.AiError, EmbeddingModel> =>\n  Effect.flatMap(EmbeddingModel.asEffect(), (m) => m.embedMany(request))\n"],"mappings":";;;;;;;;AAsGA,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"}
+{"version":3,"file":"EmbeddingModel.mjs","names":["AiError.Unsupported"],"sources":["../../src/embedding-model/EmbeddingModel.ts"],"sourcesContent":["import { Context, Effect } from \"effect\"\nimport * as AiError from \"../domain/AiError.js\"\nimport type { EmbeddingFor, EmbedInput, ResponseEncoding, Usage } from \"./Embedding.js\"\n\n/**\n * Output representation requested from the provider. Cross-provider dense\n * quantization only, the same vector at different storage cost:\n * - `float32`: universal default.\n * - `int8`: ~4x smaller, minimal recall loss on most benchmarks. Supported\n *   by Cohere, Voyage, Jina (binary only), Mixedbread.\n * - `binary`: ~32x smaller, meaningful recall loss but pairs well with a\n *   float32 reranker pass over a small candidate set.\n *\n * Non-dense representations (`sparse`, `multivector`) are a different vector\n * *structure*, not a storage option, and are produced by Jina only. They\n * live on `JinaEncoding`, not here (the same widening pattern `task` uses).\n * The response `Embedding` union still carries all arms, see\n * {@link ResponseEncoding}.\n *\n * Each provider's typed request narrows this to its supported set. On the\n * generic `EmbeddingModel` path, a provider that emits float32 only (OpenAI,\n * Gemini) rejects a non-float32 encoding with `AiError.Unsupported`\n * (bucket 1) via {@link assertEncoding}, rather than silently returning a\n * mislabeled float32 vector.\n */\nexport type EmbedEncoding = \"float32\" | \"int8\" | \"binary\"\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 EmbedEncoding}. Dense float32 is the\n   * default; provider layers reject unsupported values up front with\n   * `InvalidRequest`.\n   */\n  readonly encoding?: EmbedEncoding\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\n/**\n * Single-embed response. The `embedding` type is determined by the\n * request's `encoding` field via `EmbeddingFor<E>` — callers that don't\n * specify an encoding get a `Float32Embedding` directly with no runtime\n * narrowing. Defaults to `undefined` for back-compat with consumers that\n * use the bare `EmbedResponse` name.\n */\nexport type EmbedResponse<E extends ResponseEncoding | undefined = undefined> = {\n  readonly embedding: EmbeddingFor<E>\n  readonly usage: Usage\n}\n\n/** Batch-embed response. Same encoding rule as {@link EmbedResponse}. */\nexport type EmbedManyResponse<E extends ResponseEncoding | undefined = undefined> = {\n  readonly embeddings: ReadonlyArray<EmbeddingFor<E>>\n  readonly usage: Usage\n}\n\nexport type EmbeddingModelService = {\n  readonly embed: <E extends EmbedEncoding | undefined = undefined>(\n    request: Omit<CommonEmbedRequest, \"encoding\"> & { readonly encoding?: E },\n  ) => Effect.Effect<EmbedResponse<E>, AiError.AiError>\n  readonly embedMany: <E extends EmbedEncoding | undefined = undefined>(\n    request: Omit<CommonEmbedManyRequest, \"encoding\"> & { readonly encoding?: E },\n  ) => Effect.Effect<EmbedManyResponse<E>, 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 = <E extends EmbedEncoding | undefined = undefined>(\n  request: Omit<CommonEmbedRequest, \"encoding\"> & { readonly encoding?: E },\n): Effect.Effect<EmbedResponse<E>, 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 = <E extends EmbedEncoding | undefined = undefined>(\n  request: Omit<CommonEmbedManyRequest, \"encoding\"> & { readonly encoding?: E },\n): Effect.Effect<EmbedManyResponse<E>, AiError.AiError, EmbeddingModel> =>\n  Effect.flatMap(EmbeddingModel.asEffect(), (m) => m.embedMany(request))\n\n/**\n * Guard a requested `encoding` against a provider's supported set. Returns\n * `void` when the encoding is unset or supported, and fails\n * `AiError.Unsupported` (bucket 1) otherwise.\n *\n * Used by the generic-tag registration of providers that emit a strict\n * subset of `EmbedEncoding`: OpenAI / Gemini pass `[\"float32\"]`, Jina passes\n * `[\"float32\", \"binary\"]`. Without this guard, a non-supported encoding on\n * the generic path silently returns a float32 vector mislabeled as the\n * requested type (the `as`-cast lie), which breaks downstream storage and\n * vector math.\n */\nexport const assertEncoding = (\n  encoding: EmbedEncoding | undefined,\n  supported: ReadonlyArray<EmbedEncoding>,\n  provider: string,\n): Effect.Effect<void, AiError.AiError> =>\n  encoding === undefined || supported.includes(encoding)\n    ? Effect.void\n    : Effect.fail(\n        new AiError.Unsupported({\n          provider,\n          capability: \"encoding\",\n          reason: `${provider} emits ${supported.join(\" / \")} only; encoding=\"${encoding}\" is unavailable.`,\n        }),\n      )\n"],"mappings":";;;;;;;;;;AAsGA,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;;;;;;;;;;;;;AAcxE,MAAa,kBACX,UACA,WACA,aAEA,aAAa,KAAA,KAAa,UAAU,SAAS,SAAS,GAClD,OAAO,OACP,OAAO,KACL,IAAIA,YAAoB;CACtB;CACA,YAAY;CACZ,QAAQ,GAAG,SAAS,SAAS,UAAU,KAAK,MAAM,CAAC,mBAAmB,SAAS;CAChF,CAAC,CACH"}

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

@@ -5,7 +5,7 @@ describe("EmbedResponse<E> conditional narrowing", () => {
 	it("defaults to Float32Embedding when E is undefined", () => {
 		(0, import_dist.expectTypeOf)().toEqualTypeOf();
 	});
-	it("maps each EmbedEncoding literal to the matching Embedding variant", () => {
+	it("maps each encoding literal to the matching Embedding variant", () => {
 		(0, import_dist.expectTypeOf)().toEqualTypeOf();
 		(0, import_dist.expectTypeOf)().toEqualTypeOf();
 		(0, import_dist.expectTypeOf)().toEqualTypeOf();
@@ -38,13 +38,25 @@ describe("embed / embedMany free exports preserve E in their return type", () =>
 			encoding: "int8"
 		})).toEqualTypeOf();
 	});
-	it("embedMany with encoding: multivector returns EmbedManyResponse<multivector>", () => {
+	it("embedMany with encoding: binary returns EmbedManyResponse<binary>", () => {
 		(0, import_dist.expectTypeOf)(embedMany({
 			inputs: ["x"],
 			model: "m",
-			encoding: "multivector"
+			encoding: "binary"
 		})).toEqualTypeOf();
 	});
+	it("rejects non-dense encodings on the generic path (trimmed EmbedEncoding)", () => {
+		embedMany({
+			inputs: ["x"],
+			model: "m",
+			encoding: "multivector"
+		});
+		embed({
+			input: "x",
+			model: "m",
+			encoding: "sparse"
+		});
+	});
 	it("when the request is widened to CommonEmbedRequest, the response is the open union", () => {
 		(0, import_dist.expectTypeOf)(embed({
 			input: "x",

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

@@ -1 +1 @@
-{"version":3,"file":"EmbeddingModel.test.mjs","names":[],"sources":["../../src/embedding-model/EmbeddingModel.test.ts"],"sourcesContent":["import { Effect } from \"effect\"\nimport { describe, expectTypeOf, it } from \"vitest\"\nimport type * as AiError from \"../domain/AiError.js\"\nimport type {\n  BinaryEmbedding,\n  Float32Embedding,\n  Int8Embedding,\n  MultivectorEmbedding,\n  SparseEmbedding,\n} from \"./Embedding.js\"\nimport {\n  type EmbedEncoding,\n  embed,\n  embedMany,\n  type EmbedManyResponse,\n  type EmbedResponse,\n  EmbeddingModel,\n} from \"./EmbeddingModel.js\"\n\n// Type-level tests only. The actual narrowing happens at the type system\n// boundary — the runtime impl is exercised in provider-specific test files.\ndescribe(\"EmbedResponse<E> conditional narrowing\", () => {\n  it(\"defaults to Float32Embedding when E is undefined\", () => {\n    expectTypeOf<EmbedResponse>().toEqualTypeOf<{\n      readonly embedding: Float32Embedding\n      readonly usage: import(\"./Embedding.js\").Usage\n    }>()\n  })\n\n  it(\"maps each EmbedEncoding literal to the matching Embedding variant\", () => {\n    expectTypeOf<EmbedResponse<\"float32\">[\"embedding\"]>().toEqualTypeOf<Float32Embedding>()\n    expectTypeOf<EmbedResponse<\"int8\">[\"embedding\"]>().toEqualTypeOf<Int8Embedding>()\n    expectTypeOf<EmbedResponse<\"binary\">[\"embedding\"]>().toEqualTypeOf<BinaryEmbedding>()\n    expectTypeOf<EmbedResponse<\"sparse\">[\"embedding\"]>().toEqualTypeOf<SparseEmbedding>()\n    expectTypeOf<EmbedResponse<\"multivector\">[\"embedding\"]>().toEqualTypeOf<MultivectorEmbedding>()\n  })\n\n  it(\"falls back to the open Embedding union when E is the full EmbedEncoding\", () => {\n    expectTypeOf<EmbedResponse<EmbedEncoding>[\"embedding\"]>().toEqualTypeOf<\n      Float32Embedding | Int8Embedding | BinaryEmbedding | SparseEmbedding | MultivectorEmbedding\n    >()\n  })\n})\n\ndescribe(\"EmbedManyResponse<E> mirrors EmbedResponse<E>\", () => {\n  it(\"defaults to ReadonlyArray<Float32Embedding>\", () => {\n    expectTypeOf<EmbedManyResponse[\"embeddings\"]>().toEqualTypeOf<ReadonlyArray<Float32Embedding>>()\n  })\n\n  it(\"narrows per encoding\", () => {\n    expectTypeOf<EmbedManyResponse<\"int8\">[\"embeddings\"]>().toEqualTypeOf<\n      ReadonlyArray<Int8Embedding>\n    >()\n  })\n})\n\ndescribe(\"embed / embedMany free exports preserve E in their return type\", () => {\n  it(\"embed with no encoding returns EmbedResponse<undefined> = Float32\", () => {\n    const result = embed({ input: \"x\", model: \"m\" })\n    expectTypeOf(result).toEqualTypeOf<\n      Effect.Effect<EmbedResponse<undefined>, AiError.AiError, EmbeddingModel>\n    >()\n  })\n\n  it(\"embed with encoding: int8 returns EmbedResponse<int8>\", () => {\n    const result = embed({ input: \"x\", model: \"m\", encoding: \"int8\" })\n    expectTypeOf(result).toEqualTypeOf<\n      Effect.Effect<EmbedResponse<\"int8\">, AiError.AiError, EmbeddingModel>\n    >()\n  })\n\n  it(\"embedMany with encoding: multivector returns EmbedManyResponse<multivector>\", () => {\n    const result = embedMany({ inputs: [\"x\"], model: \"m\", encoding: \"multivector\" })\n    expectTypeOf(result).toEqualTypeOf<\n      Effect.Effect<EmbedManyResponse<\"multivector\">, AiError.AiError, EmbeddingModel>\n    >()\n  })\n\n  it(\"when the request is widened to CommonEmbedRequest, the response is the open union\", () => {\n    // Demonstrates the documented case: annotating the request type erases\n    // the literal `encoding` and the response falls back to `Embedding`.\n    const req: { input: string; model: string; encoding?: EmbedEncoding } = {\n      input: \"x\",\n      model: \"m\",\n      encoding: \"int8\",\n    }\n    const result = embed(req)\n    expectTypeOf(result).toEqualTypeOf<\n      Effect.Effect<EmbedResponse<EmbedEncoding>, AiError.AiError, EmbeddingModel>\n    >()\n  })\n})\n"],"mappings":";;;AAqBA,SAAS,gDAAgD;AACvD,IAAG,0DAA0D;AAC3D,GAAA,GAAA,YAAA,eAA6B,CAAC,eAG1B;GACJ;AAEF,IAAG,2EAA2E;AAC5E,GAAA,GAAA,YAAA,eAAqD,CAAC,eAAiC;AACvF,GAAA,GAAA,YAAA,eAAkD,CAAC,eAA8B;AACjF,GAAA,GAAA,YAAA,eAAoD,CAAC,eAAgC;AACrF,GAAA,GAAA,YAAA,eAAoD,CAAC,eAAgC;AACrF,GAAA,GAAA,YAAA,eAAyD,CAAC,eAAqC;GAC/F;AAEF,IAAG,iFAAiF;AAClF,GAAA,GAAA,YAAA,eAAyD,CAAC,eAEvD;GACH;EACF;AAEF,SAAS,uDAAuD;AAC9D,IAAG,qDAAqD;AACtD,GAAA,GAAA,YAAA,eAA+C,CAAC,eAAgD;GAChG;AAEF,IAAG,8BAA8B;AAC/B,GAAA,GAAA,YAAA,eAAuD,CAAC,eAErD;GACH;EACF;AAEF,SAAS,wEAAwE;AAC/E,IAAG,2EAA2E;AAE5E,GAAA,GAAA,YAAA,cADe,MAAM;GAAE,OAAO;GAAK,OAAO;GAAK,CAC5B,CAAC,CAAC,eAElB;GACH;AAEF,IAAG,+DAA+D;AAEhE,GAAA,GAAA,YAAA,cADe,MAAM;GAAE,OAAO;GAAK,OAAO;GAAK,UAAU;GAAQ,CAC9C,CAAC,CAAC,eAElB;GACH;AAEF,IAAG,qFAAqF;AAEtF,GAAA,GAAA,YAAA,cADe,UAAU;GAAE,QAAQ,CAAC,IAAI;GAAE,OAAO;GAAK,UAAU;GAAe,CAC5D,CAAC,CAAC,eAElB;GACH;AAEF,IAAG,2FAA2F;AAS5F,GAAA,GAAA,YAAA,cADe,MAAM;GAJnB,OAAO;GACP,OAAO;GACP,UAAU;GAEY,CACL,CAAC,CAAC,eAElB;GACH;EACF"}
+{"version":3,"file":"EmbeddingModel.test.mjs","names":[],"sources":["../../src/embedding-model/EmbeddingModel.test.ts"],"sourcesContent":["import { Effect } from \"effect\"\nimport { describe, expectTypeOf, it } from \"vitest\"\nimport type * as AiError from \"../domain/AiError.js\"\nimport type {\n  BinaryEmbedding,\n  Float32Embedding,\n  Int8Embedding,\n  MultivectorEmbedding,\n  SparseEmbedding,\n} from \"./Embedding.js\"\nimport {\n  type EmbedEncoding,\n  embed,\n  embedMany,\n  type EmbedManyResponse,\n  type EmbedResponse,\n  EmbeddingModel,\n} from \"./EmbeddingModel.js\"\n\n// Type-level tests only. The actual narrowing happens at the type system\n// boundary — the runtime impl is exercised in provider-specific test files.\ndescribe(\"EmbedResponse<E> conditional narrowing\", () => {\n  it(\"defaults to Float32Embedding when E is undefined\", () => {\n    expectTypeOf<EmbedResponse>().toEqualTypeOf<{\n      readonly embedding: Float32Embedding\n      readonly usage: import(\"./Embedding.js\").Usage\n    }>()\n  })\n\n  it(\"maps each encoding literal to the matching Embedding variant\", () => {\n    expectTypeOf<EmbedResponse<\"float32\">[\"embedding\"]>().toEqualTypeOf<Float32Embedding>()\n    expectTypeOf<EmbedResponse<\"int8\">[\"embedding\"]>().toEqualTypeOf<Int8Embedding>()\n    expectTypeOf<EmbedResponse<\"binary\">[\"embedding\"]>().toEqualTypeOf<BinaryEmbedding>()\n    expectTypeOf<EmbedResponse<\"sparse\">[\"embedding\"]>().toEqualTypeOf<SparseEmbedding>()\n    expectTypeOf<EmbedResponse<\"multivector\">[\"embedding\"]>().toEqualTypeOf<MultivectorEmbedding>()\n  })\n\n  it(\"falls back to the open Embedding union when E is the full EmbedEncoding\", () => {\n    expectTypeOf<EmbedResponse<EmbedEncoding>[\"embedding\"]>().toEqualTypeOf<\n      Float32Embedding | Int8Embedding | BinaryEmbedding | SparseEmbedding | MultivectorEmbedding\n    >()\n  })\n})\n\ndescribe(\"EmbedManyResponse<E> mirrors EmbedResponse<E>\", () => {\n  it(\"defaults to ReadonlyArray<Float32Embedding>\", () => {\n    expectTypeOf<EmbedManyResponse[\"embeddings\"]>().toEqualTypeOf<ReadonlyArray<Float32Embedding>>()\n  })\n\n  it(\"narrows per encoding\", () => {\n    expectTypeOf<EmbedManyResponse<\"int8\">[\"embeddings\"]>().toEqualTypeOf<\n      ReadonlyArray<Int8Embedding>\n    >()\n  })\n})\n\ndescribe(\"embed / embedMany free exports preserve E in their return type\", () => {\n  it(\"embed with no encoding returns EmbedResponse<undefined> = Float32\", () => {\n    const result = embed({ input: \"x\", model: \"m\" })\n    expectTypeOf(result).toEqualTypeOf<\n      Effect.Effect<EmbedResponse<undefined>, AiError.AiError, EmbeddingModel>\n    >()\n  })\n\n  it(\"embed with encoding: int8 returns EmbedResponse<int8>\", () => {\n    const result = embed({ input: \"x\", model: \"m\", encoding: \"int8\" })\n    expectTypeOf(result).toEqualTypeOf<\n      Effect.Effect<EmbedResponse<\"int8\">, AiError.AiError, EmbeddingModel>\n    >()\n  })\n\n  it(\"embedMany with encoding: binary returns EmbedManyResponse<binary>\", () => {\n    const result = embedMany({ inputs: [\"x\"], model: \"m\", encoding: \"binary\" })\n    expectTypeOf(result).toEqualTypeOf<\n      Effect.Effect<EmbedManyResponse<\"binary\">, AiError.AiError, EmbeddingModel>\n    >()\n  })\n\n  it(\"rejects non-dense encodings on the generic path (trimmed EmbedEncoding)\", () => {\n    // `sparse` / `multivector` are Jina-only representation kinds, not part\n    // of the cross-provider request set. Requesting them on the generic\n    // helper is a compile error; they're reachable only via the typed\n    // `JinaEmbedding` tag.\n    // @ts-expect-error \"multivector\" is not an EmbedEncoding\n    embedMany({ inputs: [\"x\"], model: \"m\", encoding: \"multivector\" })\n    // @ts-expect-error \"sparse\" is not an EmbedEncoding\n    embed({ input: \"x\", model: \"m\", encoding: \"sparse\" })\n  })\n\n  it(\"when the request is widened to CommonEmbedRequest, the response is the open union\", () => {\n    // Demonstrates the documented case: annotating the request type erases\n    // the literal `encoding` and the response falls back to `Embedding`.\n    const req: { input: string; model: string; encoding?: EmbedEncoding } = {\n      input: \"x\",\n      model: \"m\",\n      encoding: \"int8\",\n    }\n    const result = embed(req)\n    expectTypeOf(result).toEqualTypeOf<\n      Effect.Effect<EmbedResponse<EmbedEncoding>, AiError.AiError, EmbeddingModel>\n    >()\n  })\n})\n"],"mappings":";;;AAqBA,SAAS,gDAAgD;AACvD,IAAG,0DAA0D;AAC3D,GAAA,GAAA,YAAA,eAA6B,CAAC,eAG1B;GACJ;AAEF,IAAG,sEAAsE;AACvE,GAAA,GAAA,YAAA,eAAqD,CAAC,eAAiC;AACvF,GAAA,GAAA,YAAA,eAAkD,CAAC,eAA8B;AACjF,GAAA,GAAA,YAAA,eAAoD,CAAC,eAAgC;AACrF,GAAA,GAAA,YAAA,eAAoD,CAAC,eAAgC;AACrF,GAAA,GAAA,YAAA,eAAyD,CAAC,eAAqC;GAC/F;AAEF,IAAG,iFAAiF;AAClF,GAAA,GAAA,YAAA,eAAyD,CAAC,eAEvD;GACH;EACF;AAEF,SAAS,uDAAuD;AAC9D,IAAG,qDAAqD;AACtD,GAAA,GAAA,YAAA,eAA+C,CAAC,eAAgD;GAChG;AAEF,IAAG,8BAA8B;AAC/B,GAAA,GAAA,YAAA,eAAuD,CAAC,eAErD;GACH;EACF;AAEF,SAAS,wEAAwE;AAC/E,IAAG,2EAA2E;AAE5E,GAAA,GAAA,YAAA,cADe,MAAM;GAAE,OAAO;GAAK,OAAO;GAAK,CAC5B,CAAC,CAAC,eAElB;GACH;AAEF,IAAG,+DAA+D;AAEhE,GAAA,GAAA,YAAA,cADe,MAAM;GAAE,OAAO;GAAK,OAAO;GAAK,UAAU;GAAQ,CAC9C,CAAC,CAAC,eAElB;GACH;AAEF,IAAG,2EAA2E;AAE5E,GAAA,GAAA,YAAA,cADe,UAAU;GAAE,QAAQ,CAAC,IAAI;GAAE,OAAO;GAAK,UAAU;GAAU,CACvD,CAAC,CAAC,eAElB;GACH;AAEF,IAAG,iFAAiF;AAMlF,YAAU;GAAE,QAAQ,CAAC,IAAI;GAAE,OAAO;GAAK,UAAU;GAAe,CAAC;AAEjE,QAAM;GAAE,OAAO;GAAK,OAAO;GAAK,UAAU;GAAU,CAAC;GACrD;AAEF,IAAG,2FAA2F;AAS5F,GAAA,GAAA,YAAA,cADe,MAAM;GAJnB,OAAO;GACP,OAAO;GACP,UAAU;GAEY,CACL,CAAC,CAAC,eAElB;GACH;EACF"}

package/dist/index.d.mts

@@ -1,29 +1,35 @@
+import { t as Capabilities_d_exports } from "./capabilities/Capabilities.mjs";
 import { n as AiError_d_exports } from "./AiError-CAX_48RU.mjs";
 import { a as Media_d_exports } from "./Media-D_CpcM1Z.mjs";
-import { o as Audio_d_exports } from "./Audio-BfCTGnH3.mjs";
+import { o as Audio_d_exports } from "./Audio-DPlTsNdz.mjs";
 import { o as Image_d_exports } from "./Image-HNmMpMTh.mjs";
-import { f as Items_d_exports } from "./Items-BH8xUkoR.mjs";
+import { u as Items_d_exports } from "./Items-D8UaXQx_.mjs";
 import { t as Music_d_exports } from "./domain/Music.mjs";
 import { t as Transcript_d_exports } from "./domain/Transcript.mjs";
 import { a as StructuredFormat_d_exports } from "./StructuredFormat-BbN4dosH.mjs";
-import { a as Turn_d_exports } from "./Turn-0CwCAyVe.mjs";
+import { t as Turn_d_exports } from "./domain/Turn.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-87ViKCCO.mjs";
+import { l as Tool_d_exports } from "./Tool-CiFXYjmR.mjs";
 import { t as LanguageModel_d_exports } from "./language-model/LanguageModel.mjs";
 import { t as MusicGenerator_d_exports } from "./music-generator/MusicGenerator.mjs";
+import { t as Memory_d_exports } from "./sandbox/Memory.mjs";
+import { o as SandboxError_d_exports } from "./SandboxError-BvKypkJm.mjs";
+import { t as Sandbox_d_exports } from "./sandbox/Sandbox.mjs";
+import { t as SandboxImage_d_exports } from "./sandbox/SandboxImage.mjs";
+import { t as SandboxNetwork_d_exports } from "./sandbox/SandboxNetwork.mjs";
 import { t as SpeechSynthesizer_d_exports } from "./speech-synthesizer/SpeechSynthesizer.mjs";
 import { t as Transcriber_d_exports } from "./transcriber/Transcriber.mjs";
 import { t as Vector_d_exports } from "./math/Vector.mjs";
 import { t as Loop_d_exports } from "./loop/Loop.mjs";
 import { t as Retry_d_exports } from "./retry/Retry.mjs";
-import { t as Outcome_d_exports } from "./tool/Outcome.mjs";
+import { t as ToolResult_d_exports } from "./tool/ToolResult.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 Approval_d_exports } from "./tool/Approval.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, Audio_d_exports as Audio, 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, Music_d_exports as Music, MusicGenerator_d_exports as MusicGenerator, Outcome_d_exports as Outcome, Resolvers_d_exports as Resolvers, Retry_d_exports as Retry, SSE_d_exports as SSE, SpeechSynthesizer_d_exports as SpeechSynthesizer, StructuredFormat_d_exports as StructuredFormat, Tool_d_exports as Tool, ToolEvent_d_exports as ToolEvent, Toolkit_d_exports as Toolkit, Transcriber_d_exports as Transcriber, Transcript_d_exports as Transcript, Turn_d_exports as Turn, Vector_d_exports as Vector };
+export { AiError_d_exports as AiError, Approval_d_exports as Approval, Audio_d_exports as Audio, Capabilities_d_exports as Capabilities, 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, Memory_d_exports as Memory, Metrics_d_exports as Metrics, Music_d_exports as Music, MusicGenerator_d_exports as MusicGenerator, Retry_d_exports as Retry, SSE_d_exports as SSE, Sandbox_d_exports as Sandbox, SandboxError_d_exports as SandboxError, SandboxImage_d_exports as SandboxImage, SandboxNetwork_d_exports as SandboxNetwork, SpeechSynthesizer_d_exports as SpeechSynthesizer, StructuredFormat_d_exports as StructuredFormat, Tool_d_exports as Tool, ToolEvent_d_exports as ToolEvent, ToolResult_d_exports as ToolResult, Toolkit_d_exports as Toolkit, Transcriber_d_exports as Transcriber, Transcript_d_exports as Transcript, Turn_d_exports as Turn, Vector_d_exports as Vector };

package/dist/index.mjs

@@ -1,5 +1,6 @@
 import { t as AiError_exports } from "./domain/AiError.mjs";
 import { t as Audio_exports } from "./domain/Audio.mjs";
+import { t as Capabilities_exports } from "./capabilities/Capabilities.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";
@@ -11,19 +12,24 @@ 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 MusicGenerator_exports } from "./music-generator/MusicGenerator.mjs";
+import { t as Memory_exports } from "./sandbox/Memory.mjs";
+import { t as Sandbox_exports } from "./sandbox/Sandbox.mjs";
+import { t as SandboxError_exports } from "./sandbox/SandboxError.mjs";
+import { t as SandboxImage_exports } from "./sandbox/SandboxImage.mjs";
+import { t as SandboxNetwork_exports } from "./sandbox/SandboxNetwork.mjs";
 import { t as SpeechSynthesizer_exports } from "./speech-synthesizer/SpeechSynthesizer.mjs";
 import { t as Transcriber_exports } from "./transcriber/Transcriber.mjs";
 import { t as Vector_exports } from "./math/Vector.mjs";
 import { t as Loop_exports } from "./loop/Loop.mjs";
 import { t as Retry_exports } from "./retry/Retry.mjs";
 import { t as Tool_exports } from "./tool/Tool.mjs";
-import { t as Outcome_exports } from "./tool/Outcome.mjs";
+import { t as ToolResult_exports } from "./tool/ToolResult.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 Approval_exports } from "./tool/Approval.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, Audio_exports as Audio, 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, Music_exports as Music, MusicGenerator_exports as MusicGenerator, Outcome_exports as Outcome, Resolvers_exports as Resolvers, Retry_exports as Retry, SSE_exports as SSE, SpeechSynthesizer_exports as SpeechSynthesizer, StructuredFormat_exports as StructuredFormat, Tool_exports as Tool, ToolEvent_exports as ToolEvent, Toolkit_exports as Toolkit, Transcriber_exports as Transcriber, Transcript_exports as Transcript, Turn_exports as Turn, Vector_exports as Vector };
+export { AiError_exports as AiError, Approval_exports as Approval, Audio_exports as Audio, Capabilities_exports as Capabilities, 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, Memory_exports as Memory, Metrics_exports as Metrics, Music_exports as Music, MusicGenerator_exports as MusicGenerator, Retry_exports as Retry, SSE_exports as SSE, Sandbox_exports as Sandbox, SandboxError_exports as SandboxError, SandboxImage_exports as SandboxImage, SandboxNetwork_exports as SandboxNetwork, SpeechSynthesizer_exports as SpeechSynthesizer, StructuredFormat_exports as StructuredFormat, Tool_exports as Tool, ToolEvent_exports as ToolEvent, ToolResult_exports as ToolResult, Toolkit_exports as Toolkit, Transcriber_exports as Transcriber, Transcript_exports as Transcript, Turn_exports as Turn, Vector_exports as Vector };

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

@@ -1,8 +1,8 @@
 import { t as AiError } from "../AiError-CAX_48RU.mjs";
-import { d as Item } from "../Items-BH8xUkoR.mjs";
+import { o as HistoryItem } from "../Items-D8UaXQx_.mjs";
 import { i as StructuredFormat } from "../StructuredFormat-BbN4dosH.mjs";
-import { i as TurnEvent, r as Turn } from "../Turn-0CwCAyVe.mjs";
-import { o as ToolDescriptor } from "../Tool-87ViKCCO.mjs";
+import { Turn, TurnEvent } from "../domain/Turn.mjs";
+import { o as ToolDescriptor } from "../Tool-CiFXYjmR.mjs";
 import { Context, Effect, Stream } from "effect";
 
 //#region src/language-model/LanguageModel.d.ts
@@ -16,7 +16,7 @@ declare namespace LanguageModel_d_exports {
  * ...) lives in that provider's own request interface, which extends this.
  */
 type CommonRequest = {
-  readonly history: ReadonlyArray<Item>;
+  readonly history: ReadonlyArray<HistoryItem>;
   /**
    * Model identifier. Each provider narrows this to its typed literal union,
    * so code that yields a typed provider tag gets autocompletion.
@@ -32,7 +32,7 @@ type CommonRequest = {
   readonly maxOutputTokens?: number;
   /**
    * Schema-bound JSON output. The provider constrains the wire to match the
-   * schema; pair with `Turn.toStructured` for runtime validation. Supported
+   * schema; pair with `Turn.decodeStructured` for runtime validation. Supported
    * across all current providers (OpenAI Responses json_schema, Anthropic
    * `output_config`, Gemini `responseJsonSchema`).
    */

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

@@ -1 +1 @@
-{"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;EAdA;;;;;;EAAA,SAqBA,UAAA,GAAa,gBAAA;AAAA;AAAA,KAGZ,oBAAA;EAAA,SACD,UAAA,GAAa,OAAA,EAAS,aAAA,KAAkB,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,OAAA;EAbjE;;;;;;;;AAYX;EAZW,SAuBA,IAAA,GAAO,OAAA,EAAS,aAAA,KAAkB,MAAA,CAAO,MAAA,CAAO,IAAA,EAAM,OAAA;AAAA;AAAA,cAChE,kBAAA;cAEY,aAAA,SAAsB,kBAAA;;;;cAOtB,UAAA,GACX,OAAA,EAAS,aAAA,KACR,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,OAAA,EAAiB,aAAA;;;;;;;cAShC,IAAA,GAAQ,OAAA,EAAS,aAAA,KAAgB,MAAA,CAAO,MAAA,CAAO,IAAA,EAAM,OAAA,EAAiB,aAAA;;;;;;;cAStE,cAAA,QACL,UAAA,GAAa,OAAA,EAAS,GAAA,KAAQ,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,OAAA,OAC5D,OAAA,EAAS,GAAA,KAAM,MAAA,CAAO,MAAA,CAAO,IAAA,EAAM,OAAA"}
+{"version":3,"file":"LanguageModel.d.mts","names":[],"sources":["../../src/language-model/LanguageModel.ts"],"mappings":";;;;;;;;;;;;;;;;;KAaY,aAAA;EAAA,SACD,OAAA,EAAS,aAAA,CAAc,WAAA;;;;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;EAdA;;;;;;EAAA,SAqBA,UAAA,GAAa,gBAAA;AAAA;AAAA,KAGZ,oBAAA;EAAA,SACD,UAAA,GAAa,OAAA,EAAS,aAAA,KAAkB,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,OAAA;EAbjE;;;;;;;;AAYX;EAZW,SAuBA,IAAA,GAAO,OAAA,EAAS,aAAA,KAAkB,MAAA,CAAO,MAAA,CAAO,IAAA,EAAM,OAAA;AAAA;AAAA,cAChE,kBAAA;cAEY,aAAA,SAAsB,kBAAA;;;;cAOtB,UAAA,GACX,OAAA,EAAS,aAAA,KACR,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,OAAA,EAAiB,aAAA;;;;;;;cAShC,IAAA,GAAQ,OAAA,EAAS,aAAA,KAAgB,MAAA,CAAO,MAAA,CAAO,IAAA,EAAM,OAAA,EAAiB,aAAA;;;;;;;cAStE,cAAA,QACL,UAAA,GAAa,OAAA,EAAS,GAAA,KAAQ,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,OAAA,OAC5D,OAAA,EAAS,GAAA,KAAM,MAAA,CAAO,MAAA,CAAO,IAAA,EAAM,OAAA"}

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

@@ -1 +1 @@
-{"version":3,"file":"LanguageModel.mjs","names":["Arr","AiError.IncompleteTurn"],"sources":["../../src/language-model/LanguageModel.ts"],"sourcesContent":["import { Array as Arr, Context, Effect, Option, 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   * Drain a single turn and return the assembled `Turn` from the\n   * terminal `TurnComplete` event. Fails with `IncompleteTurn` if the\n   * stream ends without one.\n   *\n   * Most providers derive this from `streamTurn` via\n   * {@link turnFromStream}; providers with a native non-streaming\n   * endpoint may override with a cheaper direct call.\n   */\n  readonly turn: (request: CommonRequest) => Effect.Effect<Turn, 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 * Drain a single turn and return the assembled `Turn`. Delegates to the\n * service's `turn` method — providers with a native complete endpoint\n * can override; the rest get the default streamTurn-drain via\n * {@link turnFromStream}.\n */\nexport const turn = (request: CommonRequest): Effect.Effect<Turn, AiError.AiError, LanguageModel> =>\n  Effect.flatMap(LanguageModel.asEffect(), (m) => m.turn(request))\n\n/**\n * Build a `turn` implementation from a `streamTurn` implementation.\n * Providers without a native non-streaming endpoint use this to\n * populate the service's `turn` field. Generic over the request type so\n * provider-typed services (with their narrowed request) can reuse it.\n */\nexport const turnFromStream =\n  <Req>(streamTurn: (request: Req) => Stream.Stream<TurnEvent, AiError.AiError>) =>\n  (request: Req): Effect.Effect<Turn, AiError.AiError> =>\n    streamTurn(request).pipe(\n      Stream.runCollect,\n      Effect.flatMap((events) =>\n        Arr.findLast(events, isTurnComplete).pipe(\n          Option.match({\n            onNone: () => Effect.fail(new AiError.IncompleteTurn({})),\n            onSome: (e) => Effect.succeed(e.turn),\n          }),\n        ),\n      ),\n    )\n"],"mappings":";;;;;;;;;;;AAoDA,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;;;;;;;AAQnF,MAAa,QAAQ,YACnB,OAAO,QAAQ,cAAc,UAAU,GAAG,MAAM,EAAE,KAAK,QAAQ,CAAC;;;;;;;AAQlE,MAAa,kBACL,gBACL,YACC,WAAW,QAAQ,CAAC,KAClB,OAAO,YACP,OAAO,SAAS,WACdA,MAAI,SAAS,QAAQ,eAAe,CAAC,KACnC,OAAO,MAAM;CACX,cAAc,OAAO,KAAK,IAAIC,eAAuB,EAAE,CAAC,CAAC;CACzD,SAAS,MAAM,OAAO,QAAQ,EAAE,KAAK;CACtC,CAAC,CACH,CACF,CACF"}
+{"version":3,"file":"LanguageModel.mjs","names":["Arr","AiError.IncompleteTurn"],"sources":["../../src/language-model/LanguageModel.ts"],"sourcesContent":["import { Array as Arr, Context, Effect, Option, Stream } from \"effect\"\nimport * as AiError from \"../domain/AiError.js\"\nimport type { HistoryItem } 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<HistoryItem>\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.decodeStructured` 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   * Drain a single turn and return the assembled `Turn` from the\n   * terminal `TurnComplete` event. Fails with `IncompleteTurn` if the\n   * stream ends without one.\n   *\n   * Most providers derive this from `streamTurn` via\n   * {@link turnFromStream}; providers with a native non-streaming\n   * endpoint may override with a cheaper direct call.\n   */\n  readonly turn: (request: CommonRequest) => Effect.Effect<Turn, 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 * Drain a single turn and return the assembled `Turn`. Delegates to the\n * service's `turn` method — providers with a native complete endpoint\n * can override; the rest get the default streamTurn-drain via\n * {@link turnFromStream}.\n */\nexport const turn = (request: CommonRequest): Effect.Effect<Turn, AiError.AiError, LanguageModel> =>\n  Effect.flatMap(LanguageModel.asEffect(), (m) => m.turn(request))\n\n/**\n * Build a `turn` implementation from a `streamTurn` implementation.\n * Providers without a native non-streaming endpoint use this to\n * populate the service's `turn` field. Generic over the request type so\n * provider-typed services (with their narrowed request) can reuse it.\n */\nexport const turnFromStream =\n  <Req>(streamTurn: (request: Req) => Stream.Stream<TurnEvent, AiError.AiError>) =>\n  (request: Req): Effect.Effect<Turn, AiError.AiError> =>\n    streamTurn(request).pipe(\n      Stream.runCollect,\n      Effect.flatMap((events) =>\n        Arr.findLast(events, isTurnComplete).pipe(\n          Option.match({\n            onNone: () => Effect.fail(new AiError.IncompleteTurn({})),\n            onSome: (e) => Effect.succeed(e.turn),\n          }),\n        ),\n      ),\n    )\n"],"mappings":";;;;;;;;;;;AAoDA,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;;;;;;;AAQnF,MAAa,QAAQ,YACnB,OAAO,QAAQ,cAAc,UAAU,GAAG,MAAM,EAAE,KAAK,QAAQ,CAAC;;;;;;;AAQlE,MAAa,kBACL,gBACL,YACC,WAAW,QAAQ,CAAC,KAClB,OAAO,YACP,OAAO,SAAS,WACdA,MAAI,SAAS,QAAQ,eAAe,CAAC,KACnC,OAAO,MAAM;CACX,cAAc,OAAO,KAAK,IAAIC,eAAuB,EAAE,CAAC,CAAC;CACzD,SAAS,MAAM,OAAO,QAAQ,EAAE,KAAK;CACtC,CAAC,CACH,CACF,CACF"}

package/dist/loop/Loop.d.mts

@@ -1,26 +1,26 @@
 import { l as IncompleteTurn } from "../AiError-CAX_48RU.mjs";
-import { i as TurnEvent, r as Turn } from "../Turn-0CwCAyVe.mjs";
+import { Turn, TurnEvent } from "../domain/Turn.mjs";
 import { Data, Effect, Stream, SubscriptionRef } from "effect";
 
 //#region src/loop/Loop.d.ts
 declare namespace Loop_d_exports {
-  export { Event, loop, loopFrom, loopWithState, next, nextAfter, nextAfterFold, onTurnComplete, stop, stopAfter, stopEvent, stopWith, stopWithAfter, value };
+  export { Step, loop, loopOver, loopWithState, next, onTurnComplete, stop, 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 with no carried state.
- * `StopWith` also ends the loop but carries a final state that `loopFrom`
+ * `StopWith` also ends the loop but carries a final state that `loopOver`
  * will thread to the next input and `loopWithState` will write to its
  * `SubscriptionRef` before the loop ends. Plain `loop` has no next
  * iteration to apply it to and treats `StopWith` like `Stop`.
  *
- * `Stop` is intentionally `{}` so the bare `stopEvent` / `stop` helpers
- * don't constrain `S` from a body's stream type — every body has a `Stop`
+ * `Stop` is intentionally `{}` so the bare `stop()` helper doesn't
+ * constrain `S` from a body's stream type — every body has a `Stop`
  * variant in its union, and forcing `S` to flow through it would break
- * inference whenever the body never uses `next` / `stopWith`.
+ * inference whenever the body never uses `next` / `stop(state)`.
  */
-type Event<A, S> = Data.TaggedEnum<{
+type Step<A, S> = Data.TaggedEnum<{
   Value: {
     readonly value: A;
   };
@@ -33,80 +33,27 @@ type Event<A, S> = Data.TaggedEnum<{
   };
 }>;
 /** 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>;
+declare const value: <A>(a: A) => Step<A, never>;
 /**
- * The terminal `Stop` event with no carried state. Use `stop` (the Stream)
- * to end a loop body without communicating a final state.
+ * End the current iteration and continue with a new state. Emits a single
+ * terminal `Next` step as a one-element stream, so it slots directly into a
+ * loop body or after a run of values: `values.pipe(Stream.concat(next(s)))`.
  */
-declare const stopEvent: Event<never, never>;
+declare const next: <S>(state: S) => Stream.Stream<Step<never, S>>;
 /**
- * Terminal event that ends the loop AND carries a final state. For
- * `loopFrom` this is the natural "this input is done, here's the state to
- * carry forward to the next input" signal — symmetric with `next(s)` but
- * ending the inner loop instead of continuing it. For `loopWithState` the
- * carried state is written to the `SubscriptionRef` before the loop ends.
+ * End the loop. Called with no argument it emits a bare `Stop`; called with
+ * a state it emits `StopWith(state)` — `loopOver` threads that final state
+ * to the next input and `loopWithState` writes it to its `SubscriptionRef`
+ * before the loop ends. Either way it returns a single-element stream, so
+ * return it directly from a loop body.
  */
-declare const stopWith: <S>(state: S) => Event<never, S>;
+declare const stop: <S = never>(state?: S) => Stream.Stream<Step<never, S>>;
 /**
- * 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."
- *
- * Dual: data-first `nextAfter(stream, state)` and data-last
- * `stream.pipe(nextAfter(state))` both work.
- */
-declare const nextAfter: {
-  <S>(state: S): <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>;
-  <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."
- *
- * Unary on the stream — already pipe-compatible via `stream.pipe(stopAfter)`.
- */
-declare const stopAfter: <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, never>, E, R>;
-/**
- * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate with
- * `stopWith(state)`. The natural "emit final outputs, advance state, end
- * this input's inner loop" shape for `loopFrom`.
- *
- * Dual: data-first `stopWithAfter(stream, state)` and data-last
- * `stream.pipe(stopWithAfter(state))` both work.
- */
-declare const stopWithAfter: {
-  <S>(state: S): <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>;
-  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, 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.
- *
- * Dual: data-first `nextAfterFold(stream, initial, reduce, build)` and
- * data-last `stream.pipe(nextAfterFold(initial, reduce, build))` both work.
- */
-declare const nextAfterFold: {
-  <A, B, S>(initial: B, reduce: (acc: B, a: A) => B, build: (b: B) => S): <E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>;
-  <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>>`.
+ * Lift a provider's `Stream<TurnEvent>` into a loop body's `Stream<Step<TurnEvent | A, S>>`.
  * Each delta passes through as `value(delta)` (including the terminal
  * `TurnComplete`, 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
+ * steps (typically tool outputs followed by `next(state)` or `stop()`) is
  * concatenated.
  *
  * Pre-pipe transforms (`Stream.tap` / `Stream.map` / `Stream.filter`) on
@@ -120,14 +67,14 @@ declare const nextAfterFold: {
  * `deltas.pipe(onTurnComplete(then))` both work.
  */
 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>;
-  <S, A, E, R, E2 = never, R2 = never>(deltas: Stream.Stream<TurnEvent, E, R>, then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>): Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>;
+  <S, A, E2 = never, R2 = never>(then: (turn: Turn) => Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>): <E, R>(deltas: Stream.Stream<TurnEvent, E, R>) => Stream.Stream<Step<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>;
+  <S, A, E, R, E2 = never, R2 = never>(deltas: Stream.Stream<TurnEvent, E, R>, then: (turn: Turn) => Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>): Stream.Stream<Step<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>;
+type LoopBody<S, A, E, R> = (state: S) => Stream.Stream<Step<A, S>, E, R> | Effect.Effect<Stream.Stream<Step<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
+ * a `Stream<Step<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)`
@@ -137,40 +84,40 @@ 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>;
 };
-type LoopFromBody<S, I, A, E, R> = (state: S, input: I) => Stream.Stream<Event<A, S>, E, R> | Effect.Effect<Stream.Stream<Event<A, S>, E, R>, E, R>;
+type LoopOverBody<S, I, A, E, R> = (state: S, input: I) => Stream.Stream<Step<A, S>, E, R> | Effect.Effect<Stream.Stream<Step<A, S>, E, R>, E, R>;
 /**
  * Input-driven sibling of `loop`. For each item pulled from the input
  * stream, runs an inner seed-driven `loop` whose body is
  * `(s) => body(s, item)`. State is threaded across input items.
  *
- * **Per-input semantics — the body emits standard `Event<A, S>`:**
+ * **Per-input semantics — the body emits standard `Step<A, S>`:**
  *   - `value(a)`: emit `a` downstream
  *   - `next(s)`: re-run the body with the SAME input and new state `s`
  *     (multi-turn within one input — e.g. multiple model turns + tool
  *     calls for one document)
- *   - `stop`: end this input's inner loop, advance to the next input
+ *   - `stop()`: end this input's inner loop, advance to the next input
  *     (state preserved)
- *   - body stream ending without a decision: same as `stop` (advance)
+ *   - body stream ending without a decision: same as `stop()` (advance)
  *
  * **Outer termination:** the input stream ending. To halt programmatically
  * from within, end the input stream upstream (`Stream.takeWhile`, a
- * `SubscriptionRef` gate, etc.). Reserving `stop` for per-item
+ * `SubscriptionRef` gate, etc.). Reserving `stop()` for per-item
  * advancement is what makes the common "stream of documents, multi-turn
  * conversation per document" shape readable.
  *
- * Dual: data-first `loopFrom(input, initial, body)` and data-last
- * `input.pipe(loopFrom(initial, body))` both work.
+ * Dual: data-first `loopOver(input, initial, body)` and data-last
+ * `input.pipe(loopOver(initial, body))` both work.
  */
-declare const loopFrom: {
-  <S, I, A, E, R>(initial: S, body: LoopFromBody<S, I, A, E, R>): <EI, RI>(input: Stream.Stream<I, EI, RI>) => Stream.Stream<A, E | EI, R | RI>;
-  <S, I, A, E, R, EI, RI>(input: Stream.Stream<I, EI, RI>, initial: S, body: LoopFromBody<S, I, A, E, R>): Stream.Stream<A, E | EI, R | RI>;
+declare const loopOver: {
+  <S, I, A, E, R>(initial: S, body: LoopOverBody<S, I, A, E, R>): <EI, RI>(input: Stream.Stream<I, EI, RI>) => Stream.Stream<A, E | EI, R | RI>;
+  <S, I, A, E, R, EI, RI>(input: Stream.Stream<I, EI, RI>, initial: S, body: LoopOverBody<S, I, A, E, R>): Stream.Stream<A, E | EI, R | RI>;
 };
 /**
  * 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
+ * loop with a wrapped body that taps every `Next(s)` step into the ref
  * before forwarding it. The caller decides how to consume both channels:
  *
  *   - **Final state**: drain the stream, then `SubscriptionRef.get(state)`
@@ -190,5 +137,5 @@ declare const loopWithState: <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>
   readonly state: SubscriptionRef.SubscriptionRef<S>;
 }>;
 //#endregion
-export { Event, loop, loopFrom, loopWithState, next, nextAfter, nextAfterFold, onTurnComplete, stop, stopAfter, stopEvent, stopWith, stopWithAfter, Loop_d_exports as t, value };
+export { Step, loop, loopOver, loopWithState, next, onTurnComplete, stop, Loop_d_exports as t, value };
 //# sourceMappingURL=Loop.d.mts.map