@effect-uai/core 0.10.0 → 0.11.0

package/src/sandbox/Sandbox.ts

@@ -520,7 +520,7 @@ export class SandboxPortExposure extends Context.Service<SandboxPortExposure, vo
 export const create = (
   request: CommonCreateRequest,
 ): Effect.Effect<SandboxInstance, SandboxError.SandboxError, Sandbox | Scope.Scope> =>
-  Effect.flatMap(Sandbox.asEffect(), (s) => s.create(request))
+  Effect.flatMap(Sandbox, (s) => s.create(request))
 
 /**
  * Re-acquire an existing sandbox by id. Same scope semantics as
@@ -529,14 +529,14 @@ export const create = (
 export const attach = (
   id: SandboxId,
 ): Effect.Effect<SandboxInstance, SandboxError.SandboxError, Sandbox | Scope.Scope> =>
-  Effect.flatMap(Sandbox.asEffect(), (s) => s.attach(id))
+  Effect.flatMap(Sandbox, (s) => s.attach(id))
 
 /** Enumerate sandboxes for the configured account / project. */
 export const list: Effect.Effect<
   ReadonlyArray<SandboxRef>,
   SandboxError.SandboxError,
   Sandbox
-> = Effect.flatMap(Sandbox.asEffect(), (s) => s.list)
+> = Effect.flatMap(Sandbox, (s) => s.list)
 
 /**
  * Escape hatch for destroying a sandbox from outside its owning
@@ -544,7 +544,7 @@ export const list: Effect.Effect<
  * automatically.
  */
 export const destroy = (id: SandboxId): Effect.Effect<void, SandboxError.SandboxError, Sandbox> =>
-  Effect.flatMap(Sandbox.asEffect(), (s) => s.destroy(id))
+  Effect.flatMap(Sandbox, (s) => s.destroy(id))
 
 /**
  * Create a snapshot of a live sandbox. Requires
@@ -557,8 +557,8 @@ export const snapshot = (
   name?: string,
 ): Effect.Effect<SnapshotId, SandboxError.SandboxError, Sandbox | SandboxSnapshots> =>
   Effect.gen(function* () {
-    const s = yield* Sandbox.asEffect()
-    yield* SandboxSnapshots.asEffect()
+    const s = yield* Sandbox
+    yield* SandboxSnapshots
     return yield* s.snapshots.create(from, name)
   })
 
@@ -570,8 +570,8 @@ export const createVolume = (
   options?: { readonly quotaBytes?: number },
 ): Effect.Effect<VolumeId, SandboxError.SandboxError, Sandbox | SandboxVolumes> =>
   Effect.gen(function* () {
-    const s = yield* Sandbox.asEffect()
-    yield* SandboxVolumes.asEffect()
+    const s = yield* Sandbox
+    yield* SandboxVolumes
     return yield* s.volumes.create(name, options)
   })
 
@@ -580,8 +580,8 @@ export const destroyVolume = (
   id: VolumeId,
 ): Effect.Effect<void, SandboxError.SandboxError, Sandbox | SandboxVolumes> =>
   Effect.gen(function* () {
-    const s = yield* Sandbox.asEffect()
-    yield* SandboxVolumes.asEffect()
+    const s = yield* Sandbox
+    yield* SandboxVolumes
     return yield* s.volumes.destroy(id)
   })
 
@@ -591,8 +591,8 @@ export const listVolumes: Effect.Effect<
   SandboxError.SandboxError,
   Sandbox | SandboxVolumes
 > = Effect.gen(function* () {
-  const s = yield* Sandbox.asEffect()
-  yield* SandboxVolumes.asEffect()
+  const s = yield* Sandbox
+  yield* SandboxVolumes
   return yield* s.volumes.list
 })
 
@@ -601,8 +601,8 @@ export const destroySnapshot = (
   id: SnapshotId,
 ): Effect.Effect<void, SandboxError.SandboxError, Sandbox | SandboxSnapshots> =>
   Effect.gen(function* () {
-    const s = yield* Sandbox.asEffect()
-    yield* SandboxSnapshots.asEffect()
+    const s = yield* Sandbox
+    yield* SandboxSnapshots
     return yield* s.snapshots.destroy(id)
   })
 
@@ -612,8 +612,8 @@ export const listSnapshots: Effect.Effect<
   SandboxError.SandboxError,
   Sandbox | SandboxSnapshots
 > = Effect.gen(function* () {
-  const s = yield* Sandbox.asEffect()
-  yield* SandboxSnapshots.asEffect()
+  const s = yield* Sandbox
+  yield* SandboxSnapshots
   return yield* s.snapshots.list
 })
 
@@ -633,7 +633,7 @@ export const exposePort = (
   Sandbox | SandboxPortExposure
 > =>
   Effect.gen(function* () {
-    const s = yield* Sandbox.asEffect()
-    yield* SandboxPortExposure.asEffect()
+    const s = yield* Sandbox
+    yield* SandboxPortExposure
     return yield* s.ports.expose(instance, port)
   })

package/src/speech-synthesizer/SpeechSynthesizer.ts

@@ -169,13 +169,13 @@ export class MultiSpeakerTts extends Context.Service<MultiSpeakerTts, void>()(
 export const synthesize = (
   request: CommonSynthesizeRequest,
 ): Effect.Effect<AudioBlob, AiError.AiError, SpeechSynthesizer> =>
-  Effect.flatMap(SpeechSynthesizer.asEffect(), (s) => s.synthesize(request))
+  Effect.flatMap(SpeechSynthesizer, (s) => s.synthesize(request))
 
 /** Full text in, audio chunks out. */
 export const streamSynthesis = (
   request: CommonSynthesizeRequest,
 ): Stream.Stream<AudioChunk, AiError.AiError, SpeechSynthesizer> =>
-  Stream.unwrap(Effect.map(SpeechSynthesizer.asEffect(), (s) => s.streamSynthesis(request)))
+  Stream.unwrap(Effect.map(SpeechSynthesizer, (s) => s.streamSynthesis(request)))
 
 /**
  * Incremental synthesis. Dual-arity: pipeable (data-last) and direct
@@ -205,8 +205,8 @@ export const streamSynthesisFrom: {
   <E, R>(textIn: Stream.Stream<string, E, R>, request: CommonStreamSynthesizeRequest) =>
     Stream.unwrap(
       Effect.gen(function* () {
-        const s = yield* SpeechSynthesizer.asEffect()
-        yield* TtsIncrementalText.asEffect()
+        const s = yield* SpeechSynthesizer
+        yield* TtsIncrementalText
         return s.streamSynthesisFrom(textIn, request)
       }),
     ),
@@ -220,8 +220,8 @@ export const synthesizeDialogue = (
   request: CommonSynthesizeDialogueRequest,
 ): Effect.Effect<AudioBlob, AiError.AiError, SpeechSynthesizer | MultiSpeakerTts> =>
   Effect.gen(function* () {
-    const s = yield* SpeechSynthesizer.asEffect()
-    yield* MultiSpeakerTts.asEffect()
+    const s = yield* SpeechSynthesizer
+    yield* MultiSpeakerTts
     return yield* s.synthesizeDialogue(request)
   })
 
@@ -233,8 +233,8 @@ export const streamSynthesizeDialogue = (
 ): Stream.Stream<AudioChunk, AiError.AiError, SpeechSynthesizer | MultiSpeakerTts> =>
   Stream.unwrap(
     Effect.gen(function* () {
-      const s = yield* SpeechSynthesizer.asEffect()
-      yield* MultiSpeakerTts.asEffect()
+      const s = yield* SpeechSynthesizer
+      yield* MultiSpeakerTts
       return s.streamSynthesizeDialogue(request)
     }),
   )

package/src/streaming/JSONL.test.ts

@@ -8,6 +8,18 @@ const bytesOf = (...chunks: ReadonlyArray<string>) =>
 
 const collect = <A, E>(s: Stream.Stream<A, E>) => Effect.runPromise(Stream.runCollect(s))
 
+const runUntilEnd = <A, E>(s: Stream.Stream<A, E>) =>
+  Effect.runPromise(
+    s.pipe(
+      Stream.result,
+      Stream.runCollect,
+      Effect.map((results) => ({
+        seen: results.filter(Result.isSuccess).map((r) => r.success),
+        failures: results.filter(Result.isFailure).map((r) => r.failure),
+      })),
+    ),
+  )
+
 const collectResult = <A, E>(s: Stream.Stream<A, E>) =>
   Effect.runPromise(Effect.result(Stream.runCollect(s)))
 
@@ -33,6 +45,13 @@ describe("JSONL.fromBytes", () => {
     const out = await collect(JSONL.fromBytes(bytesOf("a\n\n\nb\n")))
     expect(out).toEqual(["a", "b"])
   })
+
+  it("discards a buffered partial line when the upstream fails mid-stream", async () => {
+    const failing = Stream.concat(bytesOf('{"n":1}\n{"n":2'), Stream.fail("boom" as const))
+    const { seen, failures } = await runUntilEnd(JSONL.fromBytes(failing))
+    expect(seen).toEqual(['{"n":1}'])
+    expect(failures).toEqual(["boom"])
+  })
 })
 
 describe("JSONL.parse", () => {

package/src/streaming/JSONL.ts

@@ -1,58 +1,26 @@
-import { Data, Effect, Schema, Stream } from "effect"
+import { Channel, Data, Effect, Schema, Stream } from "effect"
 
 export class JsonParseError extends Data.TaggedError("JsonParseError")<{
   readonly line: string
   readonly cause: unknown
 }> {}
 
-// ---------------------------------------------------------------------------
-// Generic stream helpers (kept module-local; see SSE.ts for the same shape).
-// ---------------------------------------------------------------------------
-
-const decodeText = <E, R>(self: Stream.Stream<Uint8Array, E, R>): Stream.Stream<string, E, R> =>
-  self.pipe(
-    Stream.mapAccum(
-      (): TextDecoder => new TextDecoder("utf-8"),
-      (decoder, chunk: Uint8Array) => [decoder, [decoder.decode(chunk, { stream: true })]] as const,
-      {
-        onHalt: (decoder: TextDecoder) => {
-          const tail = decoder.decode()
-          return tail.length > 0 ? [tail] : []
-        },
-      },
-    ),
-  )
-
-const splitOn =
-  (separator: string) =>
-  <E, R>(self: Stream.Stream<string, E, R>): Stream.Stream<string, E, R> =>
-    self.pipe(
-      Stream.mapAccum(
-        (): string => "",
-        (buffer, chunk: string) => {
-          const parts = (buffer + chunk).split(separator)
-          const tail = parts[parts.length - 1] ?? ""
-          return [tail, parts.slice(0, -1)] as const
-        },
-        { onHalt: (tail: string) => (tail.length > 0 ? [tail] : []) },
-      ),
-    )
-
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 
 /**
  * Decode a `Stream<Uint8Array>` into a `Stream<string>` of newline-delimited
- * lines. Empty lines are skipped. Buffers across chunk boundaries.
+ * lines. Empty lines are skipped. Buffers across chunk boundaries; a final
+ * line without a trailing newline is emitted at clean stream end, while a
+ * buffered partial line is discarded if the stream fails.
  */
 export const fromBytes = <E, R>(
   self: Stream.Stream<Uint8Array, E, R>,
 ): Stream.Stream<string, E, R> =>
   self.pipe(
-    decodeText,
-    Stream.map((s) => s.replace(/\r/g, "")),
-    splitOn("\n"),
+    Stream.decodeText,
+    Stream.pipeThroughChannel(Channel.splitLines()),
     Stream.filter((line) => line.length > 0),
   )
 

package/src/streaming/SSE.test.ts

@@ -1,4 +1,4 @@
-import { Effect, Stream } from "effect"
+import { Cause, Deferred, Effect, Exit, Fiber, Result, Stream } from "effect"
 import { describe, expect, it } from "vitest"
 import * as SSE from "./SSE.js"
 
@@ -8,6 +8,21 @@ const bytesOf = (...chunks: ReadonlyArray<string>) =>
 
 const collect = <A, E>(s: Stream.Stream<A, E>) => Effect.runPromise(Stream.runCollect(s))
 
+const runUntilEnd = <A, E>(s: Stream.Stream<A, E>) =>
+  Effect.runPromise(
+    s.pipe(
+      Stream.result,
+      Stream.runCollect,
+      Effect.map((results) => ({
+        seen: results.filter(Result.isSuccess).map((r) => r.success),
+        failures: results.filter(Result.isFailure).map((r) => r.failure),
+      })),
+    ),
+  )
+
+const failuresOf = (exit: Exit.Exit<unknown, unknown>): ReadonlyArray<unknown> =>
+  Exit.isFailure(exit) ? exit.cause.reasons.filter(Cause.isFailReason).map((r) => r.error) : []
+
 describe("SSE.fromBytes", () => {
   it("parses a single complete event", async () => {
     const out = await collect(SSE.fromBytes(bytesOf("event: foo\ndata: hello\n\n")))
@@ -39,9 +54,77 @@ describe("SSE.fromBytes", () => {
     expect(out).toEqual([{ id: "42", data: "x" }])
   })
 
-  it("flushes a trailing event without a closing blank line", async () => {
+  it("parses a data field with no space after the colon", async () => {
+    const out = await collect(SSE.fromBytes(bytesOf("data:x\n\n")))
+    expect(out).toEqual([{ data: "x" }])
+  })
+
+  it("ignores an id containing a NUL character", async () => {
+    const out = await collect(SSE.fromBytes(bytesOf("id: a\u0000b\ndata: x\n\n")))
+    expect(out).toEqual([{ data: "x" }])
+  })
+
+  it("discards a trailing event without a closing blank line", async () => {
     const out = await collect(SSE.fromBytes(bytesOf("data: tail")))
-    expect(out).toEqual([{ data: "tail" }])
+    expect(out).toEqual([])
+  })
+
+  it("discards buffered partial data when the upstream fails mid-stream", async () => {
+    const failing = Stream.concat(
+      bytesOf("data: good\n\ndata: partial-tr"),
+      Stream.fail("boom" as const),
+    )
+    const { seen, failures } = await runUntilEnd(SSE.fromBytes(failing))
+    expect(seen).toEqual([{ data: "good" }])
+    expect(failures).toEqual(["boom"])
+  })
+
+  it("discards a partial multi-byte char in the text decoder when the upstream fails", async () => {
+    const partialSquid = enc.encode("data: 🦑\n\n").slice(0, 8)
+    const failing = Stream.concat(
+      Stream.fromIterable([enc.encode("data: ok\n\n"), partialSquid]),
+      Stream.fail("boom" as const),
+    )
+    const { seen, failures } = await runUntilEnd(SSE.fromBytes(failing))
+    expect(seen).toEqual([{ data: "ok" }])
+    expect(failures).toEqual(["boom"])
+  })
+
+  it("discards buffered partial data when the stream is interrupted", async () => {
+    const { seen, exit } = await Effect.runPromise(
+      Effect.gen(function* () {
+        const seen: Array<SSE.Event> = []
+        const latch = yield* Deferred.make<void>()
+        const hanging = Stream.concat(bytesOf("data: good\n\ndata: partial"), Stream.never)
+        const fiber = yield* Stream.runForEach(SSE.fromBytes(hanging), (e) =>
+          Effect.sync(() => {
+            seen.push(e)
+          }).pipe(Effect.andThen(Deferred.succeed(latch, void 0))),
+        ).pipe(Effect.forkChild)
+        yield* Deferred.await(latch)
+        yield* Fiber.interrupt(fiber)
+        const exit = yield* Fiber.await(fiber)
+        return { seen, exit }
+      }),
+    )
+    expect(seen).toEqual([{ data: "good" }])
+    expect(Exit.isFailure(exit)).toBe(true)
+    expect(failuresOf(exit)).toEqual([])
+  })
+
+  it("ignores retry directives", async () => {
+    const out = await collect(SSE.fromBytes(bytesOf("retry: 3000\n\ndata: a\n\n")))
+    expect(out).toEqual([{ data: "a" }])
+  })
+
+  it("treats an explicit 'event: message' as the default event", async () => {
+    const out = await collect(SSE.fromBytes(bytesOf("event: message\ndata: x\n\n")))
+    expect(out).toEqual([{ data: "x" }])
+  })
+
+  it("does not dispatch events with no data", async () => {
+    const out = await collect(SSE.fromBytes(bytesOf("event: ping\n\ndata: x\n\n")))
+    expect(out).toEqual([{ data: "x" }])
   })
 
   it("ignores empty blocks between events", async () => {

package/src/streaming/SSE.ts

@@ -1,8 +1,9 @@
 import { Stream } from "effect"
+import { Sse } from "effect/unstable/encoding"
 
 /**
  * One Server-Sent Event. Fields per the WHATWG spec:
- * - `event`: optional event name (default "message" on the wire)
+ * - `event`: optional event name (absent for the default "message")
  * - `data`: payload, with multiple `data:` lines joined by `\n`
  * - `id`: optional last-event id
  */
@@ -12,98 +13,44 @@ export type Event = {
   readonly id?: string
 }
 
-// ---------------------------------------------------------------------------
-// Generic stream helpers (kept module-local for now; promote to a shared
-// Stream module once a third caller appears).
-// ---------------------------------------------------------------------------
+const toEvent = (wire: Sse.Event): Event => ({
+  data: wire.data,
+  ...(wire.event !== "message" && { event: wire.event }),
+  ...(wire.id !== undefined && { id: wire.id }),
+})
 
-/** Decode `Uint8Array` chunks as UTF-8, handling multi-byte boundaries. */
-const decodeText = <E, R>(self: Stream.Stream<Uint8Array, E, R>): Stream.Stream<string, E, R> =>
-  self.pipe(
-    Stream.mapAccum(
-      (): TextDecoder => new TextDecoder("utf-8"),
-      (decoder, chunk: Uint8Array) => [decoder, [decoder.decode(chunk, { stream: true })]] as const,
-      {
-        onHalt: (decoder: TextDecoder) => {
-          const tail = decoder.decode()
-          return tail.length > 0 ? [tail] : []
-        },
-      },
-    ),
-  )
-
-/** Split a text stream on a separator, buffering across chunk boundaries. */
-const splitOn =
-  (separator: string) =>
-  <E, R>(self: Stream.Stream<string, E, R>): Stream.Stream<string, E, R> =>
-    self.pipe(
-      Stream.mapAccum(
-        (): string => "",
-        (buffer, chunk: string) => {
-          const parts = (buffer + chunk).split(separator)
-          const tail = parts[parts.length - 1] ?? ""
-          return [tail, parts.slice(0, -1)] as const
-        },
-        { onHalt: (tail: string) => (tail.length > 0 ? [tail] : []) },
-      ),
-    )
-
-// ---------------------------------------------------------------------------
-// Parser
-// ---------------------------------------------------------------------------
-
-const parseField = (line: string): readonly [string, string] => {
-  const colon = line.indexOf(":")
-  if (colon < 0) return [line, ""]
-  const value = line.slice(colon + 1)
-  return [line.slice(0, colon), value.startsWith(" ") ? value.slice(1) : value]
+type ParserState = {
+  readonly parser: Sse.Parser
+  readonly out: Array<Event>
 }
 
-const parseBlock = (block: string): Event | null => {
-  const lines = block.split("\n").filter((l) => l.length > 0 && !l.startsWith(":"))
-  if (lines.length === 0) return null
-
-  const fields = lines.map(parseField)
-  const dataLines = fields.filter(([f]) => f === "data").map(([, v]) => v)
-  const event = fields.find(([f]) => f === "event")?.[1]
-  const id = fields.find(([f]) => f === "id")?.[1]
-
-  const out: { event?: string; data: string; id?: string } = {
-    data: dataLines.join("\n"),
-  }
-  if (event !== undefined) out.event = event
-  if (id !== undefined) out.id = id
-  return out as Event
+const makeParserState = (): ParserState => {
+  const out: Array<Event> = []
+  const parser = Sse.makeParser((event) => {
+    // `retry:` reconnection hints have no representation in `Event`
+    if (event._tag === "Event") out.push(toEvent(event))
+  })
+  return { parser, out }
 }
 
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
 /**
  * Decode a `Stream<Uint8Array>` (e.g. an HTTP response body) into a
- * `Stream<SSE.Event>`. Handles partial UTF-8 sequences, CRLF/LF line
- * endings, and events split across chunk boundaries.
+ * `Stream<SSE.Event>`, using the spec parser from `effect/unstable/encoding`.
+ * An event is dispatched only once its terminating blank line arrives, so a
+ * partial event at stream end (clean or failed) is discarded per the spec
+ * rather than surfaced as a truncated frame.
  */
 export const fromBytes = <E, R>(
   self: Stream.Stream<Uint8Array, E, R>,
 ): Stream.Stream<Event, E, R> =>
   self.pipe(
-    decodeText,
-    Stream.map((s) => s.replace(/\r/g, "")), // SSE allows CRLF; normalize to LF
-    splitOn("\n\n"),
-    Stream.map(parseBlock),
-    Stream.filter((ev): ev is Event => ev !== null),
+    Stream.decodeText,
+    Stream.mapAccum(makeParserState, (state, text: string) => {
+      state.parser.feed(text)
+      return [state, state.out.splice(0)] as const
+    }),
   )
 
-const eventToString = (ev: Event): string => {
-  const parts: string[] = []
-  if (ev.event !== undefined) parts.push(`event: ${ev.event}`)
-  if (ev.id !== undefined) parts.push(`id: ${ev.id}`)
-  for (const line of ev.data.split("\n")) parts.push(`data: ${line}`)
-  return parts.join("\n") + "\n\n"
-}
-
 const encoder = new TextEncoder()
 
 /**
@@ -111,4 +58,13 @@ const encoder = new TextEncoder()
  * HTTP response with `Content-Type: text/event-stream`.
  */
 export const toBytes = <E, R>(self: Stream.Stream<Event, E, R>): Stream.Stream<Uint8Array, E, R> =>
-  Stream.map(self, (ev) => encoder.encode(eventToString(ev)))
+  Stream.map(self, (ev) =>
+    encoder.encode(
+      Sse.encoder.write({
+        _tag: "Event",
+        event: ev.event ?? "message",
+        id: ev.id,
+        data: ev.data,
+      }),
+    ),
+  )

package/src/tool/Tool.test.ts

@@ -1,5 +1,5 @@
 import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec"
-import { Effect } from "effect"
+import { Context, Effect, Schema } from "effect"
 import { describe, expect, expectTypeOf, it } from "vitest"
 import type * as Items from "../domain/Items.js"
 import * as Tool from "./Tool.js"
@@ -156,3 +156,153 @@ describe("Tool.decodeArgs", () => {
     expect(exit._tag).toBe("Failure")
   })
 })
+
+describe("Effect Schema inputSchema", () => {
+  const Recipient = Schema.Struct({ to: Schema.String })
+
+  const sendEmail = Tool.make({
+    name: "send_email",
+    description: "Send an email to a single recipient.",
+    inputSchema: Recipient,
+    run: ({ to }) => Effect.succeed(`queued: ${to}`),
+  })
+
+  const callWith = (args: string): Items.ToolCall => ({
+    type: "function_call",
+    call_id: "call_1",
+    name: "send_email",
+    arguments: args,
+  })
+
+  it("runs with the input inferred from the schema's Type", async () => {
+    const result = await Effect.runPromise(sendEmail.run({ to: "x@y.z" }, () => Effect.void))
+    expect(result).toBe("queued: x@y.z")
+  })
+
+  it("type: Input is the schema's Type", () => {
+    type InputOf<T> = T extends Tool.Tool<string, infer I, any, any, any> ? I : never
+    expectTypeOf<InputOf<typeof sendEmail>>().toEqualTypeOf<{ readonly to: string }>()
+  })
+
+  it("type: E and R are inferred from run through the Effect Schema overload", () => {
+    class Mailer extends Context.Service<
+      Mailer,
+      { readonly send: (to: string) => Effect.Effect<string> }
+    >()("test/Mailer") {}
+
+    const tool = Tool.make({
+      name: "send_email",
+      description: "send",
+      inputSchema: Recipient,
+      run: ({ to }) =>
+        Effect.gen(function* () {
+          const mailer = yield* Mailer
+          if (to === "") return yield* Effect.fail("empty" as const)
+          return yield* mailer.send(to)
+        }),
+    })
+
+    expectTypeOf<Tool.ToolE<typeof tool>>().toEqualTypeOf<"empty">()
+    expectTypeOf<Tool.ToolR<typeof tool>>().toEqualTypeOf<Mailer>()
+  })
+
+  it("decodes valid JSON arguments to the typed input", async () => {
+    const input = await Effect.runPromise(Tool.decodeArgs(sendEmail, callWith('{"to":"x@y.z"}')))
+    expect(input).toEqual({ to: "x@y.z" })
+    expectTypeOf(input).toEqualTypeOf<{ readonly to: string }>()
+  })
+
+  it("fails with ToolValidationError when the arguments don't satisfy the schema", async () => {
+    const exit = await Effect.runPromiseExit(Tool.decodeArgs(sendEmail, callWith('{"to":42}')))
+    expect(exit._tag).toBe("Failure")
+  })
+
+  it("renders a JSON Schema descriptor from the wrapped schema", () => {
+    const [descriptor] = Tool.toDescriptors([sendEmail])
+    expect(descriptor?.name).toBe("send_email")
+    expect(descriptor?.inputSchema).toMatchObject({
+      type: "object",
+      properties: { to: { type: "string" } },
+      required: ["to"],
+    })
+  })
+
+  it("accepts an already-wrapped fromEffectSchema value unchanged", async () => {
+    const wrapped = Tool.make({
+      name: "send_email",
+      description: "Send an email to a single recipient.",
+      inputSchema: Tool.fromEffectSchema(Recipient),
+      run: ({ to }) => Effect.succeed(`queued: ${to}`),
+    })
+    expect(Tool.toDescriptors([wrapped])).toEqual(Tool.toDescriptors([sendEmail]))
+    const input = await Effect.runPromise(Tool.decodeArgs(wrapped, callWith('{"to":"x@y.z"}')))
+    expectTypeOf(input).toEqualTypeOf<{ readonly to: string }>()
+  })
+
+  it("signal: decode-only kinds accept an Effect Schema directly", async () => {
+    const escalate = Tool.signal({
+      name: "escalate",
+      description: "Escalate to a human.",
+      inputSchema: Schema.Struct({ reason: Schema.String }),
+    })
+    const input = await Effect.runPromise(
+      Tool.decodeArgs(escalate, {
+        type: "function_call",
+        call_id: "call_2",
+        name: "escalate",
+        arguments: '{"reason":"stuck"}',
+      }),
+    )
+    expect(input).toEqual({ reason: "stuck" })
+    expectTypeOf(input).toEqualTypeOf<{ readonly reason: string }>()
+  })
+})
+
+describe("provider-hosted tools", () => {
+  const localTool = Tool.make({
+    name: "send_email",
+    description: "Send an email.",
+    inputSchema: Tool.fromEffectSchema(Schema.Struct({ to: Schema.String })),
+    run: ({ to }) => Effect.succeed(`sent: ${to}`),
+  })
+  const signalTool = Tool.signal({
+    name: "escalate",
+    description: "Escalate to a human.",
+    inputSchema: Schema.Struct({ reason: Schema.String }),
+  })
+  const hostedTool = Tool.provider({
+    name: "web_search",
+    description: "Search the web.",
+    inputSchema: Tool.noInput,
+    provider: "gemini",
+    config: { kind: "google_search" },
+  })
+  const toolkit = { send_email: localTool, escalate: signalTool, web_search: hostedTool }
+
+  it("descriptorsOf excludes provider-hosted tools", () => {
+    const descriptors = Tool.descriptorsOf(toolkit)
+    expect(descriptors.map((d) => d.name)).toEqual(["send_email", "escalate"])
+  })
+
+  it("toDescriptors drops a ProviderTool from a mixed array", () => {
+    expect(Tool.toDescriptors([localTool, hostedTool]).map((d) => d.name)).toEqual(["send_email"])
+  })
+
+  it("providerToolsOf returns only the provider-hosted tools", () => {
+    const provider = Tool.providerToolsOf(toolkit)
+    expect(provider).toHaveLength(1)
+    expect(provider[0]?.name).toBe("web_search")
+    expect(provider[0]?.provider).toBe("gemini")
+    expect(provider[0]?.config).toEqual({ kind: "google_search" })
+  })
+
+  it("providerToolsOf on an absent toolkit is empty", () => {
+    expect(Tool.providerToolsOf(undefined)).toEqual([])
+  })
+
+  it("isProviderTool narrows the tool kind", () => {
+    expect(Tool.isProviderTool(hostedTool)).toBe(true)
+    expect(Tool.isProviderTool(localTool)).toBe(false)
+    expect(Tool.isProviderTool(signalTool)).toBe(false)
+  })
+})