@effect-uai/core 0.2.0 → 0.4.0

package/src/tool/HistoryCheck.ts

@@ -23,9 +23,7 @@ import { type ToolResult, cancelled } from "./Outcome.js"
  * `function_call_output` later in `history` (correlated by `call_id`).
  * Empty result = history is provider-submittable from this invariant.
  */
-export const findUnansweredCalls = (
-  history: ReadonlyArray<Item>,
-): ReadonlyArray<FunctionCall> => {
+export const findUnansweredCalls = (history: ReadonlyArray<Item>): ReadonlyArray<FunctionCall> => {
   const answered = new Set(history.filter(isFunctionCallOutput).map((o) => o.call_id))
   return history.filter(isFunctionCall).filter((c) => !answered.has(c.call_id))
 }
@@ -45,5 +43,4 @@ export const isReconciled = (history: ReadonlyArray<Item>): boolean =>
 export const cancelAllPending = (
   history: ReadonlyArray<Item>,
   reason?: string,
-): ReadonlyArray<ToolResult> =>
-  findUnansweredCalls(history).map((call) => cancelled(call, reason))
+): ReadonlyArray<ToolResult> => findUnansweredCalls(history).map((call) => cancelled(call, reason))

package/src/tool/Outcome.ts

@@ -11,7 +11,7 @@
  * and `unknown` would invite non-serializable values (Date, Map, BigInt,
  * fn). Recipes that want structured detail JSON.stringify themselves.
  */
-import { Match } from "effect"
+import { Data } from "effect"
 import type { FunctionCall, FunctionCallOutput } from "../domain/Items.js"
 import { functionCallOutput } from "../domain/Items.js"
 
@@ -19,42 +19,44 @@ import { functionCallOutput } from "../domain/Items.js"
 // ToolResult
 // ---------------------------------------------------------------------------
 
-export type ToolResult =
-  | {
-      readonly _tag: "Value"
-      readonly call_id: string
-      readonly tool: string
-      readonly value: unknown
-    }
-  | {
-      readonly _tag: "Failure"
-      readonly call_id: string
-      readonly tool: string
-      readonly kind: string
-      readonly reason?: string
-    }
+export type ToolResult = Data.TaggedEnum<{
+  Value: {
+    readonly call_id: string
+    readonly tool: string
+    readonly value: unknown
+  }
+  Failure: {
+    readonly call_id: string
+    readonly tool: string
+    readonly kind: string
+    readonly reason?: string
+  }
+}>
 
-export const isValue = (r: ToolResult): r is Extract<ToolResult, { _tag: "Value" }> =>
-  r._tag === "Value"
+/**
+ * Namespace of constructors, type guards, and matchers for `ToolResult`,
+ * provided by `Data.taggedEnum`. Use `ToolResult.$is("Value")` for type
+ * narrowing and `ToolResult.$match({ Value, Failure })` for exhaustive
+ * pattern matching. Synthetic-result helpers (`denied`, `cancelled`,
+ * `executionError`, `rejected`) below are kinder constructors than the
+ * raw `ToolResult.Failure(...)`.
+ */
+export const ToolResult = Data.taggedEnum<ToolResult>()
 
-export const isFailure = (r: ToolResult): r is Extract<ToolResult, { _tag: "Failure" }> =>
-  r._tag === "Failure"
+export const isValue = ToolResult.$is("Value")
+export const isFailure = ToolResult.$is("Failure")
 
 // Synthesizers. `denied` and `cancelled` are operationally distinct;
 // anything else is just a recipe-chosen `kind` via `rejected`.
 // ---------------------------------------------------------------------------
 
-export const rejected = (
-  call: FunctionCall,
-  kind: string,
-  reason?: string,
-): ToolResult => ({
-  _tag: "Failure",
-  call_id: call.call_id,
-  tool: call.name,
-  kind,
-  ...(reason !== undefined ? { reason } : {}),
-})
+export const rejected = (call: FunctionCall, kind: string, reason?: string): ToolResult =>
+  ToolResult.Failure({
+    call_id: call.call_id,
+    tool: call.name,
+    kind,
+    ...(reason !== undefined ? { reason } : {}),
+  })
 
 /** Explicit user/policy rejection. */
 export const denied = (call: FunctionCall, reason?: string): ToolResult =>
@@ -73,15 +75,13 @@ export const executionError = (call: FunctionCall, reason: string): ToolResult =
 // ---------------------------------------------------------------------------
 
 export const toFunctionCallOutput = (r: ToolResult): FunctionCallOutput =>
-  Match.value(r).pipe(
-    Match.tag("Value", (v) => functionCallOutput(v.call_id, JSON.stringify(v.value))),
-    Match.tag("Failure", (f) =>
+  ToolResult.$match(r, {
+    Value: (v) => functionCallOutput(v.call_id, JSON.stringify(v.value)),
+    Failure: (f) =>
       functionCallOutput(
         f.call_id,
         JSON.stringify(
           f.reason !== undefined ? { kind: f.kind, reason: f.reason } : { kind: f.kind },
         ),
       ),
-    ),
-    Match.exhaustive,
-  )
+  })

package/src/tool/Resolvers.test.ts

@@ -14,12 +14,7 @@ import { Effect, Queue, Schema, Stream } from "effect"
 import { describe, expect, it } from "vitest"
 import * as Items from "../domain/Items.js"
 import { findUnansweredCalls, cancelAllPending, isReconciled } from "./HistoryCheck.js"
-import {
-  type ToolResult,
-  isFailure,
-  isValue,
-  toFunctionCallOutput,
-} from "./Outcome.js"
+import { type ToolResult, isFailure, isValue, toFunctionCallOutput } from "./Outcome.js"
 import {
   type ApprovalMapEntry,
   type ToolCallDecision,
@@ -28,12 +23,7 @@ import {
 } from "./Resolvers.js"
 import { fromEffectSchema, make as makeTool, streaming } from "./Tool.js"
 import { executeAll, outputEvent, outputEvents } from "./Toolkit.js"
-import {
-  type ToolEvent,
-  isApprovalRequested,
-  isIntermediate,
-  isOutput,
-} from "./ToolEvent.js"
+import { type ToolEvent, isApprovalRequested, isIntermediate, isOutput } from "./ToolEvent.js"
 
 // ---------------------------------------------------------------------------
 // Three demo tools covering the matrix:
@@ -96,12 +86,10 @@ const calls = [
   fc("c3", "delete_database", { name: "prod" }),
 ]
 
-const resultsFrom = (
-  collected: ReadonlyArray<ToolEvent>,
-): ReadonlyArray<ToolResult> => collected.filter(isOutput).map((e) => e.result)
+const resultsFrom = (collected: ReadonlyArray<ToolEvent>): ReadonlyArray<ToolResult> =>
+  collected.filter(isOutput).map((e) => e.result)
 
-const byCallId = (results: ReadonlyArray<ToolResult>) =>
-  new Map(results.map((r) => [r.call_id, r]))
+const byCallId = (results: ReadonlyArray<ToolResult>) => new Map(results.map((r) => [r.call_id, r]))
 
 const eventsFromApprovalMap = (approvals: ReadonlyMap<string, ApprovalMapEntry>) => {
   const plan = fromApprovalMap(isSensitive, approvals)(calls)
@@ -123,9 +111,7 @@ describe("fromApprovalMap + executeAll", () => {
       ["c2", { decision: "approve" }],
       ["c3", { decision: "approve" }],
     ])
-    const collected = await Effect.runPromise(
-      Stream.runCollect(eventsFromApprovalMap(approvals)),
-    )
+    const collected = await Effect.runPromise(Stream.runCollect(eventsFromApprovalMap(approvals)))
     const by = byCallId(resultsFrom(collected))
     expect(by.get("c1")).toMatchObject({ _tag: "Value", value: { count: 3 } })
     expect(by.get("c2")).toMatchObject({
@@ -146,14 +132,10 @@ describe("fromApprovalMap + executeAll", () => {
       ["c2", { decision: "deny", reason: "spam concern" }],
       ["c3", { decision: "deny", reason: "prod is sacred" }],
     ])
-    const collected = await Effect.runPromise(
-      Stream.runCollect(eventsFromApprovalMap(approvals)),
-    )
+    const collected = await Effect.runPromise(Stream.runCollect(eventsFromApprovalMap(approvals)))
 
     // bulk_email never ran.
-    expect(
-      collected.filter(isIntermediate).filter((e) => e.tool === "bulk_email"),
-    ).toHaveLength(0)
+    expect(collected.filter(isIntermediate).filter((e) => e.tool === "bulk_email")).toHaveLength(0)
 
     const by = byCallId(resultsFrom(collected))
     expect(by.get("c2")).toMatchObject({
@@ -169,9 +151,7 @@ describe("fromApprovalMap + executeAll", () => {
   })
 
   it("cancellation: missing verdicts → Failure(cancelled)", async () => {
-    const collected = await Effect.runPromise(
-      Stream.runCollect(eventsFromApprovalMap(new Map())),
-    )
+    const collected = await Effect.runPromise(Stream.runCollect(eventsFromApprovalMap(new Map())))
     const by = byCallId(resultsFrom(collected))
     expect(by.get("c1")).toMatchObject({ _tag: "Value", value: { count: 3 } })
     expect(by.get("c2")).toMatchObject({ _tag: "Failure", kind: "cancelled" })
@@ -183,9 +163,7 @@ describe("fromApprovalMap + executeAll", () => {
       ["c2", { decision: "approve" }],
       // c3 omitted → cancelled
     ])
-    const collected = await Effect.runPromise(
-      Stream.runCollect(eventsFromApprovalMap(approvals)),
-    )
+    const collected = await Effect.runPromise(Stream.runCollect(eventsFromApprovalMap(approvals)))
     const by = byCallId(resultsFrom(collected))
     expect(by.get("c1")).toMatchObject({ _tag: "Value", value: { count: 3 } })
     expect(by.get("c2")).toMatchObject({ _tag: "Value", value: { status: "sent" } })
@@ -370,9 +348,7 @@ describe("toFunctionCallOutput", () => {
 
 describe("executeAll", () => {
   it("runs all calls passed to it", async () => {
-    const collected = await Effect.runPromise(
-      Stream.runCollect(executeAll(allTools, calls)),
-    )
+    const collected = await Effect.runPromise(Stream.runCollect(executeAll(allTools, calls)))
     expect(collected.filter(isOutput)).toHaveLength(3)
     expect(collected.filter(isOutput).every((e) => isValue(e.result))).toBe(true)
   })

package/src/tool/Resolvers.ts

@@ -10,7 +10,7 @@ import type { FunctionCall } from "../domain/Items.js"
 import { type ToolResult, cancelled, denied } from "./Outcome.js"
 import type { ToolEvent } from "./ToolEvent.js"
 
-export interface ToolCallPlan {
+export type ToolCallPlan = {
   readonly approved: ReadonlyArray<FunctionCall>
   readonly rejected: ReadonlyArray<ToolResult>
 }
@@ -29,9 +29,7 @@ export const reject = (result: ToolResult): ToolCallDecision => ({
   result,
 })
 
-export const splitToolCallDecisions = (
-  decisions: ReadonlyArray<ToolCallDecision>,
-): ToolCallPlan =>
+export const splitToolCallDecisions = (decisions: ReadonlyArray<ToolCallDecision>): ToolCallPlan =>
   decisions.reduce<ToolCallPlan>(
     (acc, decision) =>
       decision._tag === "Approved"
@@ -51,7 +49,7 @@ export const approvalRequested = (call: FunctionCall): ToolEvent => ({
 // Verdict queue (WebSocket-style transport).
 // ---------------------------------------------------------------------------
 
-export interface Verdict {
+export type Verdict = {
   readonly call_id: string
   readonly decision: "approve" | "deny"
   readonly reason?: string
@@ -63,10 +61,7 @@ export interface Verdict {
  * one `ToolCallDecision` when their matching verdict arrives.
  */
 export const fromVerdictQueue =
-  (
-    predicate: (call: FunctionCall) => boolean,
-    verdicts: Queue.Dequeue<Verdict>,
-  ) =>
+  (predicate: (call: FunctionCall) => boolean, verdicts: Queue.Dequeue<Verdict>) =>
   (
     calls: ReadonlyArray<FunctionCall>,
   ): Effect.Effect<
@@ -131,10 +126,7 @@ export type ApprovalMapEntry =
   | { readonly decision: "deny"; readonly reason?: string }
 
 export const fromApprovalMap =
-  (
-    predicate: (call: FunctionCall) => boolean,
-    approvals: ReadonlyMap<string, ApprovalMapEntry>,
-  ) =>
+  (predicate: (call: FunctionCall) => boolean, approvals: ReadonlyMap<string, ApprovalMapEntry>) =>
   (calls: ReadonlyArray<FunctionCall>): ToolCallPlan =>
     splitToolCallDecisions(
       calls.map((call) => {
@@ -144,4 +136,3 @@ export const fromApprovalMap =
         return v.decision === "approve" ? approve(call) : reject(denied(call, v.reason))
       }),
     )
-

package/src/tool/Tool.ts

@@ -36,7 +36,7 @@ export const fromEffectSchema = <S extends Schema.Codec<any, any, never, any>>(
   Schema.toStandardJSONSchemaV1(Schema.toStandardSchemaV1(schema)) as unknown as S &
     ToolInputSchema<S["Type"]>
 
-export interface Tool<Name extends string, Input, Output, R = never> {
+export type Tool<Name extends string, Input, Output, R = never> = {
   readonly name: Name
   readonly description: string
   readonly inputSchema: ToolInputSchema<Input>
@@ -55,7 +55,7 @@ export interface Tool<Name extends string, Input, Output, R = never> {
  * to its own wire field (OpenAI → `parameters`, Anthropic →
  * `input_schema`). Built from a `Tool` by `Toolkit.toDescriptors`.
  */
-export interface ToolDescriptor {
+export type ToolDescriptor = {
   readonly name: string
   readonly description: string
   readonly inputSchema: Record<string, unknown>
@@ -75,7 +75,7 @@ export const make = <Name extends string, Input, Output, R = never>(
 // `Output`. Sub-agents, slow downloads with progress, recipe streamers.
 // ---------------------------------------------------------------------------
 
-export interface StreamingTool<Name extends string, Input, Event, Output, R = never> {
+export type StreamingTool<Name extends string, Input, Event, Output, R = never> = {
   readonly _kind: "streaming"
   readonly name: Name
   readonly description: string
@@ -89,11 +89,11 @@ export const streaming = <Name extends string, Input, Event, Output, R = never>(
   spec: Omit<StreamingTool<Name, Input, Event, Output, R>, "_kind">,
 ): StreamingTool<Name, Input, Event, Output, R> => ({ _kind: "streaming", ...spec })
 
-export type AnyStreamingTool = StreamingTool<string, any, any, any, never>
-export type AnyPlainTool = Tool<string, any, any, never>
-export type AnyKindTool = AnyStreamingTool | AnyPlainTool
+export type AnyStreamingTool<R = any> = StreamingTool<string, any, any, any, R>
+export type AnyPlainTool<R = any> = Tool<string, any, any, R>
+export type AnyKindTool<R = any> = AnyStreamingTool<R> | AnyPlainTool<R>
 
-export const isStreamingTool = (t: AnyKindTool): t is AnyStreamingTool =>
+export const isStreamingTool = <R>(t: AnyKindTool<R>): t is AnyStreamingTool<R> =>
   "_kind" in t && t._kind === "streaming"
 
 /**
@@ -101,8 +101,8 @@ export const isStreamingTool = (t: AnyKindTool): t is AnyStreamingTool =>
  * descriptors. Mirrors `Toolkit.toDescriptors` but accepts the union type
  * so a single list can carry both kinds.
  */
-export const toDescriptors = (
-  tools: ReadonlyArray<AnyKindTool>,
+export const toDescriptors = <R>(
+  tools: ReadonlyArray<AnyKindTool<R>>,
 ): ReadonlyArray<ToolDescriptor> =>
   tools.map((tool) => {
     const inputSchema = tool.inputSchema["~standard"].jsonSchema.input({

package/src/tool/ToolEvent.ts

@@ -5,33 +5,37 @@
  *   - Intermediate      : per-element passthrough from a streaming tool's run
  *   - Output            : terminal result (carries a structured ToolResult)
  *
- * Recipes thread `ToolEvent.Output.result` through `nextStateFrom` and apply
+ * Recipes thread `ToolEvent.Output.result` through `continueWith` and apply
  * `toFunctionCallOutput` when appending to history.
  */
+import { Data } from "effect"
 import type { ToolResult } from "./Outcome.js"
 
-export type ToolEvent =
-  | {
-      readonly _tag: "ApprovalRequested"
-      readonly call_id: string
-      readonly tool: string
-      readonly arguments: string
-    }
-  | {
-      readonly _tag: "Intermediate"
-      readonly call_id: string
-      readonly tool: string
-      readonly data: unknown
-    }
-  | { readonly _tag: "Output"; readonly result: ToolResult }
+export type ToolEvent = Data.TaggedEnum<{
+  ApprovalRequested: {
+    readonly call_id: string
+    readonly tool: string
+    readonly arguments: string
+  }
+  Intermediate: {
+    readonly call_id: string
+    readonly tool: string
+    readonly data: unknown
+  }
+  Output: {
+    readonly result: ToolResult
+  }
+}>
 
-export const isApprovalRequested = (
-  e: ToolEvent,
-): e is Extract<ToolEvent, { _tag: "ApprovalRequested" }> => e._tag === "ApprovalRequested"
-
-export const isIntermediate = (
-  e: ToolEvent,
-): e is Extract<ToolEvent, { _tag: "Intermediate" }> => e._tag === "Intermediate"
+/**
+ * Namespace of constructors, type guards, and matchers for `ToolEvent`,
+ * provided by `Data.taggedEnum`. Use `ToolEvent.Output({ result })` to build
+ * an event, `ToolEvent.$is("Output")` for type narrowing,
+ * `ToolEvent.$match({ ApprovalRequested, Intermediate, Output })` for
+ * exhaustive pattern matching.
+ */
+export const ToolEvent = Data.taggedEnum<ToolEvent>()
 
-export const isOutput = (e: ToolEvent): e is Extract<ToolEvent, { _tag: "Output" }> =>
-  e._tag === "Output"
+export const isApprovalRequested = ToolEvent.$is("ApprovalRequested")
+export const isIntermediate = ToolEvent.$is("Intermediate")
+export const isOutput = ToolEvent.$is("Output")

package/src/tool/Toolkit.test.ts

@@ -1,5 +1,8 @@
-import { Effect, Schema } from "effect"
-import { describe, expect, it } from "vitest"
+import { Context, Effect, Layer, Schema, Stream } from "effect"
+import { describe, expect, expectTypeOf, it } from "vitest"
+import type { FunctionCall } from "../domain/Items.js"
+import { isOutput } from "./ToolEvent.js"
+import { isValue } from "./Outcome.js"
 import * as Tool from "./Tool.js"
 import * as Toolkit from "./Toolkit.js"
 
@@ -43,3 +46,95 @@ describe("Toolkit.toDescriptors", () => {
     expect(l).not.toHaveProperty("strict")
   })
 })
+
+describe("Toolkit.executeAll - tools with R requirements", () => {
+  // Two distinct services, modelling the "typed per-tool context" use case
+  // (cf. AI SDK 7's `toolsContext`). In Effect each tool declares its R, the
+  // compiler enforces it, and `executeAll` surfaces the union for the caller
+  // to provide via Layer.
+  type WeatherApiKeyShape = { readonly key: string }
+  class WeatherApiKey extends Context.Service<WeatherApiKey, WeatherApiKeyShape>()(
+    "test/WeatherApiKey",
+  ) {}
+
+  type GeoApiKeyShape = { readonly key: string }
+  class GeoApiKey extends Context.Service<GeoApiKey, GeoApiKeyShape>()("test/GeoApiKey") {}
+
+  const Empty = Schema.Struct({})
+
+  const getWeather = Tool.make({
+    name: "get_weather",
+    description: "",
+    inputSchema: Tool.fromEffectSchema(Empty),
+    run: () =>
+      Effect.gen(function* () {
+        const { key } = yield* WeatherApiKey
+        return { source: "weather", key }
+      }),
+  })
+
+  const getCoords = Tool.make({
+    name: "get_coords",
+    description: "",
+    inputSchema: Tool.fromEffectSchema(Empty),
+    run: () =>
+      Effect.gen(function* () {
+        const { key } = yield* GeoApiKey
+        return { source: "geo", key }
+      }),
+  })
+
+  const call = (name: string, id: string): FunctionCall => ({
+    type: "function_call",
+    call_id: id,
+    name,
+    arguments: "{}",
+  })
+
+  it("propagates each tool's R into the resulting Stream's requirements", () => {
+    const stream = Toolkit.executeAll([getWeather, getCoords], [])
+    expectTypeOf(stream).toEqualTypeOf<
+      Stream.Stream<import("./ToolEvent.js").ToolEvent, never, WeatherApiKey | GeoApiKey>
+    >()
+  })
+
+  it("runs each tool with its own service injected", async () => {
+    const layer = Layer.mergeAll(
+      Layer.succeed(WeatherApiKey, { key: "weather-123" }),
+      Layer.succeed(GeoApiKey, { key: "geo-456" }),
+    )
+
+    const program = Toolkit.executeAll(
+      [getWeather, getCoords],
+      [call("get_weather", "c1"), call("get_coords", "c2")],
+    ).pipe(Stream.runCollect, Effect.provide(layer))
+
+    const events = await Effect.runPromise(program)
+    const outputs = Array.from(events).filter(isOutput)
+    const byCall = new Map(outputs.map((e) => [e.result.call_id, e.result]))
+
+    const w = byCall.get("c1")
+    const g = byCall.get("c2")
+    expect(w !== undefined && isValue(w) && w.value).toEqual({
+      source: "weather",
+      key: "weather-123",
+    })
+    expect(g !== undefined && isValue(g) && g.value).toEqual({
+      source: "geo",
+      key: "geo-456",
+    })
+  })
+
+  it("with no service-needing tools, R is never", () => {
+    const plain = Tool.make({
+      name: "plain",
+      description: "",
+      inputSchema: Tool.fromEffectSchema(Empty),
+      run: () => Effect.succeed(0),
+    })
+    const stream = Toolkit.executeAll([plain], [])
+    expectTypeOf(stream).toEqualTypeOf<
+      Stream.Stream<import("./ToolEvent.js").ToolEvent, never, never>
+    >()
+  })
+})

package/src/tool/Toolkit.ts

@@ -1,4 +1,4 @@
-import { Array as Arr, Effect, Ref, Stream } from "effect"
+import { Array as Arr, Effect, Function, Ref, Stream } from "effect"
 import * as Loop from "../loop/Loop.js"
 import type { FunctionCall } from "../domain/Items.js"
 import {
@@ -6,14 +6,11 @@ import {
   type AnyPlainTool,
   type AnyStreamingTool,
   isStreamingTool,
+  type StreamingTool,
   type Tool,
   type ToolDescriptor,
 } from "./Tool.js"
-import {
-  type ToolResult,
-  executionError,
-  rejected,
-} from "./Outcome.js"
+import { type ToolResult, executionError, rejected } from "./Outcome.js"
 import type { ToolEvent } from "./ToolEvent.js"
 import { isOutput } from "./ToolEvent.js"
 
@@ -26,6 +23,18 @@ export type Toolkit<Tools extends ReadonlyArray<AnyTool>> = {
 export type ToolsR<Tools extends ReadonlyArray<AnyTool>> =
   Tools[number] extends Tool<any, any, any, infer R> ? R : never
 
+/**
+ * Union of every tool's `R` requirements in a mixed plain + streaming array.
+ * Used by `executeAll` to surface the services tools need at the recipe
+ * level, so the loop's stream type carries them through to `Effect.provide`.
+ */
+export type ToolKindR<Tools extends ReadonlyArray<AnyKindTool<any>>> =
+  Tools[number] extends StreamingTool<any, any, any, any, infer R>
+    ? R
+    : Tools[number] extends Tool<any, any, any, infer R>
+      ? R
+      : never
+
 export const make = <const Tools extends ReadonlyArray<AnyTool>>(tools: Tools): Toolkit<Tools> => ({
   tools,
 })
@@ -53,16 +62,16 @@ export const toDescriptors = <Tools extends ReadonlyArray<AnyTool>>(
 // only the calls they have already decided should run.
 // ---------------------------------------------------------------------------
 
-export interface ExecuteOptions {
+export type ExecuteOptions = {
   readonly concurrency?: number | "unbounded"
 }
 
 /** Execute every provided call. Approval/rejection policy belongs upstream. */
-export const executeAll = (
-  tools: ReadonlyArray<AnyKindTool>,
+export const executeAll = <Tools extends ReadonlyArray<AnyKindTool<any>>>(
+  tools: Tools,
   calls: ReadonlyArray<FunctionCall>,
   options?: ExecuteOptions,
-): Stream.Stream<ToolEvent> =>
+): Stream.Stream<ToolEvent, never, ToolKindR<Tools>> =>
   Stream.fromIterable(calls).pipe(
     Stream.flatMap((call) => runOne(tools, call), {
       concurrency: options?.concurrency ?? "unbounded",
@@ -71,9 +80,8 @@ export const executeAll = (
 
 export const outputEvent = (result: ToolResult): ToolEvent => ({ _tag: "Output", result })
 
-export const outputEvents = (
-  results: ReadonlyArray<ToolResult>,
-): Stream.Stream<ToolEvent> => Stream.fromIterable(results.map(outputEvent))
+export const outputEvents = (results: ReadonlyArray<ToolResult>): Stream.Stream<ToolEvent> =>
+  Stream.fromIterable(results.map(outputEvent))
 
 const valueResult = (call: FunctionCall, tool: string, value: unknown): ToolResult => ({
   _tag: "Value",
@@ -82,10 +90,10 @@ const valueResult = (call: FunctionCall, tool: string, value: unknown): ToolResu
   value,
 })
 
-const runOne = (
-  tools: ReadonlyArray<AnyKindTool>,
+const runOne = <R>(
+  tools: ReadonlyArray<AnyKindTool<R>>,
   call: FunctionCall,
-): Stream.Stream<ToolEvent> => {
+): Stream.Stream<ToolEvent, never, R> => {
   const tool = tools.find((t) => t.name === call.name)
   if (tool === undefined) {
     // Graceful: emit a synthetic Failure so OTHER calls in this turn
@@ -99,10 +107,10 @@ const runOne = (
   return runPlain(tool, call)
 }
 
-const runPlain = (
-  tool: AnyPlainTool,
+const runPlain = <R>(
+  tool: AnyPlainTool<R>,
   call: FunctionCall,
-): Stream.Stream<ToolEvent> =>
+): Stream.Stream<ToolEvent, never, R> =>
   Stream.fromEffect(
     Effect.gen(function* () {
       const parsed = yield* Effect.try({
@@ -124,10 +132,10 @@ const runPlain = (
     ),
   )
 
-const runStreaming = (
-  tool: AnyStreamingTool,
+const runStreaming = <R>(
+  tool: AnyStreamingTool<R>,
   call: FunctionCall,
-): Stream.Stream<ToolEvent> =>
+): Stream.Stream<ToolEvent, never, R> =>
   Stream.unwrap(
     Effect.gen(function* () {
       const parsed = yield* Effect.try({
@@ -184,19 +192,35 @@ const runStreaming = (
   )
 
 // ---------------------------------------------------------------------------
-// `nextStateFrom` - bridge from a `Stream<ToolEvent>` to the loop's emit
+// `continueWith` - bridge from a `Stream<ToolEvent>` to the loop's emit
 // shape. Drains the stream to the consumer in real-time, taps every
 // `Output` into an internal Ref, and at end-of-stream emits
 // `Loop.next(build(results))`. Recipe never sees the Ref.
+//
+// Dual: data-first `continueWith(stream, build)` and data-last
+// `stream.pipe(continueWith(build))` both work.
 // ---------------------------------------------------------------------------
 
-export const nextStateFrom = <S>(
-  stream: Stream.Stream<ToolEvent>,
-  build: (results: ReadonlyArray<ToolResult>) => S,
-): Stream.Stream<Loop.Event<ToolEvent, S>> =>
-  Loop.nextAfterFold(
-    stream,
-    [] as ReadonlyArray<ToolResult>,
-    (acc, e) => (isOutput(e) ? Arr.append(acc, e.result) : acc),
-    build,
-  )
+export const continueWith: {
+  <S>(
+    build: (results: ReadonlyArray<ToolResult>) => S,
+  ): <R>(
+    stream: Stream.Stream<ToolEvent, never, R>,
+  ) => Stream.Stream<Loop.Event<ToolEvent, S>, never, R>
+  <S, R>(
+    stream: Stream.Stream<ToolEvent, never, R>,
+    build: (results: ReadonlyArray<ToolResult>) => S,
+  ): Stream.Stream<Loop.Event<ToolEvent, S>, never, R>
+} = Function.dual(
+  2,
+  <S, R>(
+    stream: Stream.Stream<ToolEvent, never, R>,
+    build: (results: ReadonlyArray<ToolResult>) => S,
+  ): Stream.Stream<Loop.Event<ToolEvent, S>, never, R> =>
+    Loop.nextAfterFold(
+      stream,
+      [] as ReadonlyArray<ToolResult>,
+      (acc, e) => (isOutput(e) ? Arr.append(acc, e.result) : acc),
+      build,
+    ),
+)