@effect-uai/core 0.2.0 → 0.3.0

package/dist/tool/ToolEvent.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ToolEvent.mjs","names":[],"sources":["../../src/tool/ToolEvent.ts"],"sourcesContent":["/**\n * The event type emitted while handling tool calls.\n *\n *   - ApprovalRequested : gated calls waiting for approval\n *   - Intermediate      : per-element passthrough from a streaming tool's run\n *   - Output            : terminal result (carries a structured ToolResult)\n *\n * Recipes thread `ToolEvent.Output.result` through `nextStateFrom` and apply\n * `toFunctionCallOutput` when appending to history.\n */\nimport type { ToolResult } from \"./Outcome.js\"\n\nexport type ToolEvent =\n  | {\n      readonly _tag: \"ApprovalRequested\"\n      readonly call_id: string\n      readonly tool: string\n      readonly arguments: string\n    }\n  | {\n      readonly _tag: \"Intermediate\"\n      readonly call_id: string\n      readonly tool: string\n      readonly data: unknown\n    }\n  | { readonly _tag: \"Output\"; readonly result: ToolResult }\n\nexport const isApprovalRequested = (\n  e: ToolEvent,\n): e is Extract<ToolEvent, { _tag: \"ApprovalRequested\" }> => e._tag === \"ApprovalRequested\"\n\nexport const isIntermediate = (\n  e: ToolEvent,\n): e is Extract<ToolEvent, { _tag: \"Intermediate\" }> => e._tag === \"Intermediate\"\n\nexport const isOutput = (e: ToolEvent): e is Extract<ToolEvent, { _tag: \"Output\" }> =>\n  e._tag === \"Output\"\n"],"mappings":";AA2BA,MAAa,uBACX,MAC2D,EAAE,SAAS;AAExE,MAAa,kBACX,MACsD,EAAE,SAAS;AAEnE,MAAa,YAAY,MACvB,EAAE,SAAS"}
+{"version":3,"file":"ToolEvent.mjs","names":[],"sources":["../../src/tool/ToolEvent.ts"],"sourcesContent":["/**\n * The event type emitted while handling tool calls.\n *\n *   - ApprovalRequested : gated calls waiting for approval\n *   - Intermediate      : per-element passthrough from a streaming tool's run\n *   - Output            : terminal result (carries a structured ToolResult)\n *\n * Recipes thread `ToolEvent.Output.result` through `continueWith` and apply\n * `toFunctionCallOutput` when appending to history.\n */\nimport { Data } from \"effect\"\nimport type { ToolResult } from \"./Outcome.js\"\n\nexport type ToolEvent = Data.TaggedEnum<{\n  ApprovalRequested: {\n    readonly call_id: string\n    readonly tool: string\n    readonly arguments: string\n  }\n  Intermediate: {\n    readonly call_id: string\n    readonly tool: string\n    readonly data: unknown\n  }\n  Output: {\n    readonly result: ToolResult\n  }\n}>\n\n/**\n * Namespace of constructors, type guards, and matchers for `ToolEvent`,\n * provided by `Data.taggedEnum`. Use `ToolEvent.Output({ result })` to build\n * an event, `ToolEvent.$is(\"Output\")` for type narrowing,\n * `ToolEvent.$match({ ApprovalRequested, Intermediate, Output })` for\n * exhaustive pattern matching.\n */\nexport const ToolEvent = Data.taggedEnum<ToolEvent>()\n\nexport const isApprovalRequested = ToolEvent.$is(\"ApprovalRequested\")\nexport const isIntermediate = ToolEvent.$is(\"Intermediate\")\nexport const isOutput = ToolEvent.$is(\"Output\")\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,MAAa,YAAY,KAAK,YAAuB;AAErD,MAAa,sBAAsB,UAAU,IAAI,oBAAoB;AACrE,MAAa,iBAAiB,UAAU,IAAI,eAAe;AAC3D,MAAa,WAAW,UAAU,IAAI,SAAS"}

package/dist/tool/Toolkit.d.mts

@@ -1,19 +1,25 @@
-import { o as FunctionCall } from "../Items-D1C2686t.mjs";
-import { a as Tool, o as ToolDescriptor, t as AnyKindTool } from "../Tool-5wxOCuOh.mjs";
+import { o as FunctionCall } from "../Items-CB8Bo3FI.mjs";
+import { a as Tool, i as StreamingTool, o as ToolDescriptor, t as AnyKindTool } from "../Tool-DjVufH7i.mjs";
 import { Event } from "../loop/Loop.mjs";
-import { t as ToolResult } from "../Outcome-GiaNvt7i.mjs";
-import { t as ToolEvent } from "../ToolEvent-wTMgb2GO.mjs";
+import { ToolResult } from "./Outcome.mjs";
+import { ToolEvent } from "./ToolEvent.mjs";
 import { Stream } from "effect";
 
 //#region src/tool/Toolkit.d.ts
 declare namespace Toolkit_d_exports {
-  export { AnyTool, ExecuteOptions, Toolkit, ToolsR, executeAll, make, nextStateFrom, outputEvent, outputEvents, toDescriptors };
+  export { AnyTool, ExecuteOptions, ToolKindR, Toolkit, ToolsR, continueWith, executeAll, make, outputEvent, outputEvents, toDescriptors };
 }
 type AnyTool = Tool<string, any, any, any>;
 type Toolkit<Tools extends ReadonlyArray<AnyTool>> = {
   readonly tools: Tools;
 };
 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`.
+ */
+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;
 declare const make: <const Tools extends ReadonlyArray<AnyTool>>(tools: Tools) => Toolkit<Tools>;
 /**
  * Render every tool in a toolkit to a provider-agnostic descriptor.
@@ -21,14 +27,17 @@ declare const make: <const Tools extends ReadonlyArray<AnyTool>>(tools: Tools) =
  * Standard Schema converter (draft 2020-12).
  */
 declare const toDescriptors: <Tools extends ReadonlyArray<AnyTool>>(toolkit: Toolkit<Tools>) => ReadonlyArray<ToolDescriptor>;
-interface ExecuteOptions {
+type ExecuteOptions = {
   readonly concurrency?: number | "unbounded";
-}
+};
 /** Execute every provided call. Approval/rejection policy belongs upstream. */
-declare const executeAll: (tools: ReadonlyArray<AnyKindTool>, calls: ReadonlyArray<FunctionCall>, options?: ExecuteOptions) => Stream.Stream<ToolEvent>;
+declare const executeAll: <Tools extends ReadonlyArray<AnyKindTool<any>>>(tools: Tools, calls: ReadonlyArray<FunctionCall>, options?: ExecuteOptions) => Stream.Stream<ToolEvent, never, ToolKindR<Tools>>;
 declare const outputEvent: (result: ToolResult) => ToolEvent;
 declare const outputEvents: (results: ReadonlyArray<ToolResult>) => Stream.Stream<ToolEvent>;
-declare const nextStateFrom: <S>(stream: Stream.Stream<ToolEvent>, build: (results: ReadonlyArray<ToolResult>) => S) => Stream.Stream<Event<ToolEvent, S>>;
+declare const continueWith: {
+  <S>(build: (results: ReadonlyArray<ToolResult>) => S): <R>(stream: Stream.Stream<ToolEvent, never, R>) => Stream.Stream<Event<ToolEvent, S>, never, R>;
+  <S, R>(stream: Stream.Stream<ToolEvent, never, R>, build: (results: ReadonlyArray<ToolResult>) => S): Stream.Stream<Event<ToolEvent, S>, never, R>;
+};
 //#endregion
-export { AnyTool, ExecuteOptions, Toolkit, ToolsR, executeAll, make, nextStateFrom, outputEvent, outputEvents, Toolkit_d_exports as t, toDescriptors };
+export { AnyTool, ExecuteOptions, ToolKindR, Toolkit, ToolsR, continueWith, executeAll, make, outputEvent, outputEvents, Toolkit_d_exports as t, toDescriptors };
 //# sourceMappingURL=Toolkit.d.mts.map

package/dist/tool/Toolkit.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"Toolkit.d.mts","names":[],"sources":["../../src/tool/Toolkit.ts"],"mappings":";;;;;;;;;;;KAmBY,OAAA,GAAU,IAAA;AAAA,KAEV,OAAA,eAAsB,aAAA,CAAc,OAAA;EAAA,SACrC,KAAA,EAAO,KAAA;AAAA;AAAA,KAGN,MAAA,eAAqB,aAAA,CAAc,OAAA,KAC7C,KAAA,iBAAsB,IAAA,2BAA+B,CAAA;AAAA,cAE1C,IAAA,uBAA4B,aAAA,CAAc,OAAA,GAAU,KAAA,EAAO,KAAA,KAAQ,OAAA,CAAQ,KAAA;;;;;;cAS3E,aAAA,iBAA+B,aAAA,CAAc,OAAA,GACxD,OAAA,EAAS,OAAA,CAAQ,KAAA,MAChB,aAAA,CAAc,cAAA;AAAA,UAgBA,cAAA;EAAA,SACN,WAAA;AAAA;AArCX;AAAA,cAyCa,UAAA,GACX,KAAA,EAAO,aAAA,CAAc,WAAA,GACrB,KAAA,EAAO,aAAA,CAAc,YAAA,GACrB,OAAA,GAAU,cAAA,KACT,MAAA,CAAO,MAAA,CAAO,SAAA;AAAA,cAOJ,WAAA,GAAe,MAAA,EAAQ,UAAA,KAAa,SAAA;AAAA,cAEpC,YAAA,GACX,OAAA,EAAS,aAAA,CAAc,UAAA,MACtB,MAAA,CAAO,MAAA,CAAO,SAAA;AAAA,cAqHJ,aAAA,MACX,MAAA,EAAQ,MAAA,CAAO,MAAA,CAAO,SAAA,GACtB,KAAA,GAAQ,OAAA,EAAS,aAAA,CAAc,UAAA,MAAgB,CAAA,KAC9C,MAAA,CAAO,MAAA,CAAO,KAAA,CAAW,SAAA,EAAW,CAAA"}
+{"version":3,"file":"Toolkit.d.mts","names":[],"sources":["../../src/tool/Toolkit.ts"],"mappings":";;;;;;;;;;;KAgBY,OAAA,GAAU,IAAA;AAAA,KAEV,OAAA,eAAsB,aAAA,CAAc,OAAA;EAAA,SACrC,KAAA,EAAO,KAAA;AAAA;AAAA,KAGN,MAAA,eAAqB,aAAA,CAAc,OAAA,KAC7C,KAAA,iBAAsB,IAAA,2BAA+B,CAAA;;;;;;KAO3C,SAAA,eAAwB,aAAA,CAAc,WAAA,UAChD,KAAA,iBAAsB,aAAA,gCAClB,CAAA,GACA,KAAA,iBAAsB,IAAA,2BACpB,CAAA;AAAA,cAGK,IAAA,uBAA4B,aAAA,CAAc,OAAA,GAAU,KAAA,EAAO,KAAA,KAAQ,OAAA,CAAQ,KAAA;;;;;AArBxF;cA8Ba,aAAA,iBAA+B,aAAA,CAAc,OAAA,GACxD,OAAA,EAAS,OAAA,CAAQ,KAAA,MAChB,aAAA,CAAc,cAAA;AAAA,KAgBL,cAAA;EAAA,SACD,WAAA;AAAA;AA/CX;AAAA,cAmDa,UAAA,iBAA4B,aAAA,CAAc,WAAA,QACrD,KAAA,EAAO,KAAA,EACP,KAAA,EAAO,aAAA,CAAc,YAAA,GACrB,OAAA,GAAU,cAAA,KACT,MAAA,CAAO,MAAA,CAAO,SAAA,SAAkB,SAAA,CAAU,KAAA;AAAA,cAOhC,WAAA,GAAe,MAAA,EAAQ,UAAA,KAAa,SAAA;AAAA,cAEpC,YAAA,GAAgB,OAAA,EAAS,aAAA,CAAc,UAAA,MAAc,MAAA,CAAO,MAAA,CAAO,SAAA;AAAA,cAyHnE,YAAA;EAAA,IAET,KAAA,GAAQ,OAAA,EAAS,aAAA,CAAc,UAAA,MAAgB,CAAA,OAE/C,MAAA,EAAQ,MAAA,CAAO,MAAA,CAAO,SAAA,SAAkB,CAAA,MACrC,MAAA,CAAO,MAAA,CAAO,KAAA,CAAW,SAAA,EAAW,CAAA,UAAW,CAAA;EAAA,OAElD,MAAA,EAAQ,MAAA,CAAO,MAAA,CAAO,SAAA,SAAkB,CAAA,GACxC,KAAA,GAAQ,OAAA,EAAS,aAAA,CAAc,UAAA,MAAgB,CAAA,GAC9C,MAAA,CAAO,MAAA,CAAO,KAAA,CAAW,SAAA,EAAW,CAAA,UAAW,CAAA;AAAA"}

package/dist/tool/Toolkit.mjs

@@ -1,14 +1,14 @@
-import { t as __exportAll } from "../chunk-CfYAbeIz.mjs";
+import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
 import { nextAfterFold } from "../loop/Loop.mjs";
 import { isStreamingTool } from "./Tool.mjs";
 import { executionError, rejected } from "./Outcome.mjs";
 import { isOutput } from "./ToolEvent.mjs";
-import { Array, Effect, Ref, Stream } from "effect";
+import { Array, Effect, Function, Ref, Stream } from "effect";
 //#region src/tool/Toolkit.ts
 var Toolkit_exports = /* @__PURE__ */ __exportAll({
+	continueWith: () => continueWith,
 	executeAll: () => executeAll,
 	make: () => make,
-	nextStateFrom: () => nextStateFrom,
 	outputEvent: () => outputEvent,
 	outputEvents: () => outputEvents,
 	toDescriptors: () => toDescriptors
@@ -99,8 +99,8 @@ const runStreaming = (tool, call) => Stream.unwrap(Effect.gen(function* () {
 	_tag: "Output",
 	result: executionError(call, "Tool execution failed")
 })));
-const nextStateFrom = (stream, build) => nextAfterFold(stream, [], (acc, e) => isOutput(e) ? Array.append(acc, e.result) : acc, build);
+const continueWith = Function.dual(2, (stream, build) => nextAfterFold(stream, [], (acc, e) => isOutput(e) ? Array.append(acc, e.result) : acc, build));
 //#endregion
-export { executeAll, make, nextStateFrom, outputEvent, outputEvents, Toolkit_exports as t, toDescriptors };
+export { continueWith, executeAll, make, outputEvent, outputEvents, Toolkit_exports as t, toDescriptors };
 
 //# sourceMappingURL=Toolkit.mjs.map

package/dist/tool/Toolkit.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Toolkit.mjs","names":["Arr","Loop.nextAfterFold"],"sources":["../../src/tool/Toolkit.ts"],"sourcesContent":["import { Array as Arr, Effect, Ref, Stream } from \"effect\"\nimport * as Loop from \"../loop/Loop.js\"\nimport type { FunctionCall } from \"../domain/Items.js\"\nimport {\n  type AnyKindTool,\n  type AnyPlainTool,\n  type AnyStreamingTool,\n  isStreamingTool,\n  type Tool,\n  type ToolDescriptor,\n} from \"./Tool.js\"\nimport {\n  type ToolResult,\n  executionError,\n  rejected,\n} from \"./Outcome.js\"\nimport type { ToolEvent } from \"./ToolEvent.js\"\nimport { isOutput } from \"./ToolEvent.js\"\n\nexport type AnyTool = Tool<string, any, any, any>\n\nexport type Toolkit<Tools extends ReadonlyArray<AnyTool>> = {\n  readonly tools: Tools\n}\n\nexport type ToolsR<Tools extends ReadonlyArray<AnyTool>> =\n  Tools[number] extends Tool<any, any, any, infer R> ? R : never\n\nexport const make = <const Tools extends ReadonlyArray<AnyTool>>(tools: Tools): Toolkit<Tools> => ({\n  tools,\n})\n\n/**\n * Render every tool in a toolkit to a provider-agnostic descriptor.\n * `inputSchema` is the JSON Schema document produced by the tool's\n * Standard Schema converter (draft 2020-12).\n */\nexport const toDescriptors = <Tools extends ReadonlyArray<AnyTool>>(\n  toolkit: Toolkit<Tools>,\n): ReadonlyArray<ToolDescriptor> =>\n  toolkit.tools.map((tool) => {\n    const inputSchema = tool.inputSchema[\"~standard\"].jsonSchema.input({\n      target: \"draft-2020-12\",\n    })\n    return tool.strict !== undefined\n      ? { name: tool.name, description: tool.description, inputSchema, strict: tool.strict }\n      : { name: tool.name, description: tool.description, inputSchema }\n  })\n\n// ---------------------------------------------------------------------------\n// Tool executor. Streams `ToolEvent`s in real time and dispatches streaming\n// and plain tools uniformly. Policy stays outside this module: callers pass\n// only the calls they have already decided should run.\n// ---------------------------------------------------------------------------\n\nexport interface ExecuteOptions {\n  readonly concurrency?: number | \"unbounded\"\n}\n\n/** Execute every provided call. Approval/rejection policy belongs upstream. */\nexport const executeAll = (\n  tools: ReadonlyArray<AnyKindTool>,\n  calls: ReadonlyArray<FunctionCall>,\n  options?: ExecuteOptions,\n): Stream.Stream<ToolEvent> =>\n  Stream.fromIterable(calls).pipe(\n    Stream.flatMap((call) => runOne(tools, call), {\n      concurrency: options?.concurrency ?? \"unbounded\",\n    }),\n  )\n\nexport const outputEvent = (result: ToolResult): ToolEvent => ({ _tag: \"Output\", result })\n\nexport const outputEvents = (\n  results: ReadonlyArray<ToolResult>,\n): Stream.Stream<ToolEvent> => Stream.fromIterable(results.map(outputEvent))\n\nconst valueResult = (call: FunctionCall, tool: string, value: unknown): ToolResult => ({\n  _tag: \"Value\",\n  call_id: call.call_id,\n  tool,\n  value,\n})\n\nconst runOne = (\n  tools: ReadonlyArray<AnyKindTool>,\n  call: FunctionCall,\n): Stream.Stream<ToolEvent> => {\n  const tool = tools.find((t) => t.name === call.name)\n  if (tool === undefined) {\n    // Graceful: emit a synthetic Failure so OTHER calls in this turn\n    // still execute. LLMs hallucinate tool names; MCP tools come and go.\n    return Stream.succeed<ToolEvent>({\n      _tag: \"Output\",\n      result: rejected(call, \"unknown_tool\", `No tool registered with name \"${call.name}\"`),\n    })\n  }\n  if (isStreamingTool(tool)) return runStreaming(tool, call)\n  return runPlain(tool, call)\n}\n\nconst runPlain = (\n  tool: AnyPlainTool,\n  call: FunctionCall,\n): Stream.Stream<ToolEvent> =>\n  Stream.fromEffect(\n    Effect.gen(function* () {\n      const parsed = yield* Effect.try({\n        try: () => JSON.parse(call.arguments) as unknown,\n        catch: () => \"json_parse_error\" as const,\n      })\n      const validated = yield* Effect.tryPromise({\n        try: () => Promise.resolve(tool.inputSchema[\"~standard\"].validate(parsed)),\n        catch: () => \"validation_threw\" as const,\n      })\n      if (validated.issues !== undefined) {\n        return executionError(call, \"Tool input failed schema validation\")\n      }\n      const output = yield* tool.run(validated.value)\n      return valueResult(call, tool.name, output)\n    }).pipe(\n      Effect.catchCause(() => Effect.succeed(executionError(call, \"Tool execution failed\"))),\n      Effect.map((result) => ({ _tag: \"Output\", result }) satisfies ToolEvent),\n    ),\n  )\n\nconst runStreaming = (\n  tool: AnyStreamingTool,\n  call: FunctionCall,\n): Stream.Stream<ToolEvent> =>\n  Stream.unwrap(\n    Effect.gen(function* () {\n      const parsed = yield* Effect.try({\n        try: () => JSON.parse(call.arguments) as unknown,\n        catch: () => \"json_parse_error\" as const,\n      })\n      const validated = yield* Effect.tryPromise({\n        try: () => Promise.resolve(tool.inputSchema[\"~standard\"].validate(parsed)),\n        catch: () => \"validation_threw\" as const,\n      })\n      if (validated.issues !== undefined) {\n        return Stream.succeed<ToolEvent>({\n          _tag: \"Output\",\n          result: executionError(call, \"Tool input failed schema validation\"),\n        })\n      }\n\n      // Real-time: tap each event into a Ref as it flows; emit one\n      // Intermediate per event; then concat one synthetic Output element\n      // built from the accumulated Ref via `finalize`.\n      const ref = yield* Ref.make<Array<unknown>>([])\n      const intermediates = tool.run(validated.value).pipe(\n        Stream.tap((event) => Ref.update(ref, Arr.append(event))),\n        Stream.map(\n          (data) =>\n            ({\n              _tag: \"Intermediate\",\n              call_id: call.call_id,\n              tool: tool.name,\n              data,\n            }) satisfies ToolEvent,\n        ),\n      )\n      const output = Stream.fromEffect(\n        Ref.get(ref).pipe(\n          Effect.map(\n            (events) =>\n              ({\n                _tag: \"Output\",\n                result: valueResult(call, tool.name, tool.finalize(events)),\n              }) satisfies ToolEvent,\n          ),\n        ),\n      )\n      return intermediates.pipe(Stream.concat(output))\n    }),\n  ).pipe(\n    Stream.catchCause(() =>\n      Stream.succeed<ToolEvent>({\n        _tag: \"Output\",\n        result: executionError(call, \"Tool execution failed\"),\n      }),\n    ),\n  )\n\n// ---------------------------------------------------------------------------\n// `nextStateFrom` - bridge from a `Stream<ToolEvent>` to the loop's emit\n// shape. Drains the stream to the consumer in real-time, taps every\n// `Output` into an internal Ref, and at end-of-stream emits\n// `Loop.next(build(results))`. Recipe never sees the Ref.\n// ---------------------------------------------------------------------------\n\nexport const nextStateFrom = <S>(\n  stream: Stream.Stream<ToolEvent>,\n  build: (results: ReadonlyArray<ToolResult>) => S,\n): Stream.Stream<Loop.Event<ToolEvent, S>> =>\n  Loop.nextAfterFold(\n    stream,\n    [] as ReadonlyArray<ToolResult>,\n    (acc, e) => (isOutput(e) ? Arr.append(acc, e.result) : acc),\n    build,\n  )\n"],"mappings":"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"}
+{"version":3,"file":"Toolkit.mjs","names":["Arr","Loop.nextAfterFold"],"sources":["../../src/tool/Toolkit.ts"],"sourcesContent":["import { Array as Arr, Effect, Function, Ref, Stream } from \"effect\"\nimport * as Loop from \"../loop/Loop.js\"\nimport type { FunctionCall } from \"../domain/Items.js\"\nimport {\n  type AnyKindTool,\n  type AnyPlainTool,\n  type AnyStreamingTool,\n  isStreamingTool,\n  type StreamingTool,\n  type Tool,\n  type ToolDescriptor,\n} from \"./Tool.js\"\nimport { type ToolResult, executionError, rejected } from \"./Outcome.js\"\nimport type { ToolEvent } from \"./ToolEvent.js\"\nimport { isOutput } from \"./ToolEvent.js\"\n\nexport type AnyTool = Tool<string, any, any, any>\n\nexport type Toolkit<Tools extends ReadonlyArray<AnyTool>> = {\n  readonly tools: Tools\n}\n\nexport type ToolsR<Tools extends ReadonlyArray<AnyTool>> =\n  Tools[number] extends Tool<any, any, any, infer R> ? R : never\n\n/**\n * Union of every tool's `R` requirements in a mixed plain + streaming array.\n * Used by `executeAll` to surface the services tools need at the recipe\n * level, so the loop's stream type carries them through to `Effect.provide`.\n */\nexport type ToolKindR<Tools extends ReadonlyArray<AnyKindTool<any>>> =\n  Tools[number] extends StreamingTool<any, any, any, any, infer R>\n    ? R\n    : Tools[number] extends Tool<any, any, any, infer R>\n      ? R\n      : never\n\nexport const make = <const Tools extends ReadonlyArray<AnyTool>>(tools: Tools): Toolkit<Tools> => ({\n  tools,\n})\n\n/**\n * Render every tool in a toolkit to a provider-agnostic descriptor.\n * `inputSchema` is the JSON Schema document produced by the tool's\n * Standard Schema converter (draft 2020-12).\n */\nexport const toDescriptors = <Tools extends ReadonlyArray<AnyTool>>(\n  toolkit: Toolkit<Tools>,\n): ReadonlyArray<ToolDescriptor> =>\n  toolkit.tools.map((tool) => {\n    const inputSchema = tool.inputSchema[\"~standard\"].jsonSchema.input({\n      target: \"draft-2020-12\",\n    })\n    return tool.strict !== undefined\n      ? { name: tool.name, description: tool.description, inputSchema, strict: tool.strict }\n      : { name: tool.name, description: tool.description, inputSchema }\n  })\n\n// ---------------------------------------------------------------------------\n// Tool executor. Streams `ToolEvent`s in real time and dispatches streaming\n// and plain tools uniformly. Policy stays outside this module: callers pass\n// only the calls they have already decided should run.\n// ---------------------------------------------------------------------------\n\nexport type ExecuteOptions = {\n  readonly concurrency?: number | \"unbounded\"\n}\n\n/** Execute every provided call. Approval/rejection policy belongs upstream. */\nexport const executeAll = <Tools extends ReadonlyArray<AnyKindTool<any>>>(\n  tools: Tools,\n  calls: ReadonlyArray<FunctionCall>,\n  options?: ExecuteOptions,\n): Stream.Stream<ToolEvent, never, ToolKindR<Tools>> =>\n  Stream.fromIterable(calls).pipe(\n    Stream.flatMap((call) => runOne(tools, call), {\n      concurrency: options?.concurrency ?? \"unbounded\",\n    }),\n  )\n\nexport const outputEvent = (result: ToolResult): ToolEvent => ({ _tag: \"Output\", result })\n\nexport const outputEvents = (results: ReadonlyArray<ToolResult>): Stream.Stream<ToolEvent> =>\n  Stream.fromIterable(results.map(outputEvent))\n\nconst valueResult = (call: FunctionCall, tool: string, value: unknown): ToolResult => ({\n  _tag: \"Value\",\n  call_id: call.call_id,\n  tool,\n  value,\n})\n\nconst runOne = <R>(\n  tools: ReadonlyArray<AnyKindTool<R>>,\n  call: FunctionCall,\n): Stream.Stream<ToolEvent, never, R> => {\n  const tool = tools.find((t) => t.name === call.name)\n  if (tool === undefined) {\n    // Graceful: emit a synthetic Failure so OTHER calls in this turn\n    // still execute. LLMs hallucinate tool names; MCP tools come and go.\n    return Stream.succeed<ToolEvent>({\n      _tag: \"Output\",\n      result: rejected(call, \"unknown_tool\", `No tool registered with name \"${call.name}\"`),\n    })\n  }\n  if (isStreamingTool(tool)) return runStreaming(tool, call)\n  return runPlain(tool, call)\n}\n\nconst runPlain = <R>(\n  tool: AnyPlainTool<R>,\n  call: FunctionCall,\n): Stream.Stream<ToolEvent, never, R> =>\n  Stream.fromEffect(\n    Effect.gen(function* () {\n      const parsed = yield* Effect.try({\n        try: () => JSON.parse(call.arguments) as unknown,\n        catch: () => \"json_parse_error\" as const,\n      })\n      const validated = yield* Effect.tryPromise({\n        try: () => Promise.resolve(tool.inputSchema[\"~standard\"].validate(parsed)),\n        catch: () => \"validation_threw\" as const,\n      })\n      if (validated.issues !== undefined) {\n        return executionError(call, \"Tool input failed schema validation\")\n      }\n      const output = yield* tool.run(validated.value)\n      return valueResult(call, tool.name, output)\n    }).pipe(\n      Effect.catchCause(() => Effect.succeed(executionError(call, \"Tool execution failed\"))),\n      Effect.map((result) => ({ _tag: \"Output\", result }) satisfies ToolEvent),\n    ),\n  )\n\nconst runStreaming = <R>(\n  tool: AnyStreamingTool<R>,\n  call: FunctionCall,\n): Stream.Stream<ToolEvent, never, R> =>\n  Stream.unwrap(\n    Effect.gen(function* () {\n      const parsed = yield* Effect.try({\n        try: () => JSON.parse(call.arguments) as unknown,\n        catch: () => \"json_parse_error\" as const,\n      })\n      const validated = yield* Effect.tryPromise({\n        try: () => Promise.resolve(tool.inputSchema[\"~standard\"].validate(parsed)),\n        catch: () => \"validation_threw\" as const,\n      })\n      if (validated.issues !== undefined) {\n        return Stream.succeed<ToolEvent>({\n          _tag: \"Output\",\n          result: executionError(call, \"Tool input failed schema validation\"),\n        })\n      }\n\n      // Real-time: tap each event into a Ref as it flows; emit one\n      // Intermediate per event; then concat one synthetic Output element\n      // built from the accumulated Ref via `finalize`.\n      const ref = yield* Ref.make<Array<unknown>>([])\n      const intermediates = tool.run(validated.value).pipe(\n        Stream.tap((event) => Ref.update(ref, Arr.append(event))),\n        Stream.map(\n          (data) =>\n            ({\n              _tag: \"Intermediate\",\n              call_id: call.call_id,\n              tool: tool.name,\n              data,\n            }) satisfies ToolEvent,\n        ),\n      )\n      const output = Stream.fromEffect(\n        Ref.get(ref).pipe(\n          Effect.map(\n            (events) =>\n              ({\n                _tag: \"Output\",\n                result: valueResult(call, tool.name, tool.finalize(events)),\n              }) satisfies ToolEvent,\n          ),\n        ),\n      )\n      return intermediates.pipe(Stream.concat(output))\n    }),\n  ).pipe(\n    Stream.catchCause(() =>\n      Stream.succeed<ToolEvent>({\n        _tag: \"Output\",\n        result: executionError(call, \"Tool execution failed\"),\n      }),\n    ),\n  )\n\n// ---------------------------------------------------------------------------\n// `continueWith` - bridge from a `Stream<ToolEvent>` to the loop's emit\n// shape. Drains the stream to the consumer in real-time, taps every\n// `Output` into an internal Ref, and at end-of-stream emits\n// `Loop.next(build(results))`. Recipe never sees the Ref.\n//\n// Dual: data-first `continueWith(stream, build)` and data-last\n// `stream.pipe(continueWith(build))` both work.\n// ---------------------------------------------------------------------------\n\nexport const continueWith: {\n  <S>(\n    build: (results: ReadonlyArray<ToolResult>) => S,\n  ): <R>(\n    stream: Stream.Stream<ToolEvent, never, R>,\n  ) => Stream.Stream<Loop.Event<ToolEvent, S>, never, R>\n  <S, R>(\n    stream: Stream.Stream<ToolEvent, never, R>,\n    build: (results: ReadonlyArray<ToolResult>) => S,\n  ): Stream.Stream<Loop.Event<ToolEvent, S>, never, R>\n} = Function.dual(\n  2,\n  <S, R>(\n    stream: Stream.Stream<ToolEvent, never, R>,\n    build: (results: ReadonlyArray<ToolResult>) => S,\n  ): Stream.Stream<Loop.Event<ToolEvent, S>, never, R> =>\n    Loop.nextAfterFold(\n      stream,\n      [] as ReadonlyArray<ToolResult>,\n      (acc, e) => (isOutput(e) ? Arr.append(acc, e.result) : acc),\n      build,\n    ),\n)\n"],"mappings":"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"}

package/dist/tool/Toolkit.test.d.mts

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

package/dist/tool/Toolkit.test.mjs

@@ -0,0 +1,113 @@
+import { fromEffectSchema, make } from "./Tool.mjs";
+import { isValue } from "./Outcome.mjs";
+import { isOutput } from "./ToolEvent.mjs";
+import { executeAll, make as make$1, toDescriptors } from "./Toolkit.mjs";
+import { i as it, n as globalExpect, r as describe, t as import_dist } from "../dist-DV5ISja1.mjs";
+import { Context, Effect, Layer, Schema, Stream } from "effect";
+//#region src/tool/Toolkit.test.ts
+describe("Toolkit.toDescriptors", () => {
+	const GetWeatherInput = Schema.Struct({ city: Schema.String });
+	const getWeather = make({
+		name: "get_weather",
+		description: "Look up the current temperature for a city.",
+		inputSchema: fromEffectSchema(GetWeatherInput),
+		run: ({ city }) => Effect.succeed({
+			city,
+			tempC: 18
+		})
+	});
+	it("renders the input schema as a JSON Schema document", () => {
+		const [desc] = toDescriptors(make$1([getWeather]));
+		globalExpect(desc?.name).toBe("get_weather");
+		globalExpect(desc?.description).toBe("Look up the current temperature for a city.");
+		globalExpect(desc?.inputSchema).toMatchObject({
+			type: "object",
+			properties: { city: { type: "string" } },
+			required: ["city"]
+		});
+	});
+	it("includes strict flag only when set on the tool", () => {
+		const [s, l] = toDescriptors(make$1([make({
+			name: "strict_one",
+			description: "",
+			inputSchema: fromEffectSchema(GetWeatherInput),
+			run: () => Effect.succeed({}),
+			strict: true
+		}), make({
+			name: "loose_one",
+			description: "",
+			inputSchema: fromEffectSchema(GetWeatherInput),
+			run: () => Effect.succeed({})
+		})]));
+		globalExpect(s?.strict).toBe(true);
+		globalExpect(l).not.toHaveProperty("strict");
+	});
+});
+describe("Toolkit.executeAll - tools with R requirements", () => {
+	class WeatherApiKey extends Context.Service()("test/WeatherApiKey") {}
+	class GeoApiKey extends Context.Service()("test/GeoApiKey") {}
+	const Empty = Schema.Struct({});
+	const getWeather = make({
+		name: "get_weather",
+		description: "",
+		inputSchema: fromEffectSchema(Empty),
+		run: () => Effect.gen(function* () {
+			const { key } = yield* WeatherApiKey;
+			return {
+				source: "weather",
+				key
+			};
+		})
+	});
+	const getCoords = make({
+		name: "get_coords",
+		description: "",
+		inputSchema: fromEffectSchema(Empty),
+		run: () => Effect.gen(function* () {
+			const { key } = yield* GeoApiKey;
+			return {
+				source: "geo",
+				key
+			};
+		})
+	});
+	const call = (name, id) => ({
+		type: "function_call",
+		call_id: id,
+		name,
+		arguments: "{}"
+	});
+	it("propagates each tool's R into the resulting Stream's requirements", () => {
+		(0, import_dist.expectTypeOf)(executeAll([getWeather, getCoords], [])).toEqualTypeOf();
+	});
+	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 = 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");
+		globalExpect(w !== void 0 && isValue(w) && w.value).toEqual({
+			source: "weather",
+			key: "weather-123"
+		});
+		globalExpect(g !== void 0 && isValue(g) && g.value).toEqual({
+			source: "geo",
+			key: "geo-456"
+		});
+	});
+	it("with no service-needing tools, R is never", () => {
+		const plain = make({
+			name: "plain",
+			description: "",
+			inputSchema: fromEffectSchema(Empty),
+			run: () => Effect.succeed(0)
+		});
+		(0, import_dist.expectTypeOf)(executeAll([plain], [])).toEqualTypeOf();
+	});
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=Toolkit.test.mjs.map

package/dist/tool/Toolkit.test.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Toolkit.test.mjs","names":["Tool.make","Tool.fromEffectSchema","Toolkit.toDescriptors","Toolkit.make","Toolkit.executeAll"],"sources":["../../src/tool/Toolkit.test.ts"],"sourcesContent":["import { Context, Effect, Layer, Schema, Stream } from \"effect\"\nimport { describe, expect, expectTypeOf, it } from \"vitest\"\nimport type { FunctionCall } from \"../domain/Items.js\"\nimport { isOutput } from \"./ToolEvent.js\"\nimport { isValue } from \"./Outcome.js\"\nimport * as Tool from \"./Tool.js\"\nimport * as Toolkit from \"./Toolkit.js\"\n\ndescribe(\"Toolkit.toDescriptors\", () => {\n  const GetWeatherInput = Schema.Struct({ city: Schema.String })\n\n  const getWeather = Tool.make({\n    name: \"get_weather\",\n    description: \"Look up the current temperature for a city.\",\n    inputSchema: Tool.fromEffectSchema(GetWeatherInput),\n    run: ({ city }) => Effect.succeed({ city, tempC: 18 }),\n  })\n\n  it(\"renders the input schema as a JSON Schema document\", () => {\n    const [desc] = Toolkit.toDescriptors(Toolkit.make([getWeather]))\n    expect(desc?.name).toBe(\"get_weather\")\n    expect(desc?.description).toBe(\"Look up the current temperature for a city.\")\n    expect(desc?.inputSchema).toMatchObject({\n      type: \"object\",\n      properties: { city: { type: \"string\" } },\n      required: [\"city\"],\n    })\n  })\n\n  it(\"includes strict flag only when set on the tool\", () => {\n    const strictTool = Tool.make({\n      name: \"strict_one\",\n      description: \"\",\n      inputSchema: Tool.fromEffectSchema(GetWeatherInput),\n      run: () => Effect.succeed({}),\n      strict: true,\n    })\n    const looseTool = Tool.make({\n      name: \"loose_one\",\n      description: \"\",\n      inputSchema: Tool.fromEffectSchema(GetWeatherInput),\n      run: () => Effect.succeed({}),\n    })\n    const [s, l] = Toolkit.toDescriptors(Toolkit.make([strictTool, looseTool]))\n    expect(s?.strict).toBe(true)\n    expect(l).not.toHaveProperty(\"strict\")\n  })\n})\n\ndescribe(\"Toolkit.executeAll - tools with R requirements\", () => {\n  // Two distinct services, modelling the \"typed per-tool context\" use case\n  // (cf. AI SDK 7's `toolsContext`). In Effect each tool declares its R, the\n  // compiler enforces it, and `executeAll` surfaces the union for the caller\n  // to provide via Layer.\n  type WeatherApiKeyShape = { readonly key: string }\n  class WeatherApiKey extends Context.Service<WeatherApiKey, WeatherApiKeyShape>()(\n    \"test/WeatherApiKey\",\n  ) {}\n\n  type GeoApiKeyShape = { readonly key: string }\n  class GeoApiKey extends Context.Service<GeoApiKey, GeoApiKeyShape>()(\"test/GeoApiKey\") {}\n\n  const Empty = Schema.Struct({})\n\n  const getWeather = Tool.make({\n    name: \"get_weather\",\n    description: \"\",\n    inputSchema: Tool.fromEffectSchema(Empty),\n    run: () =>\n      Effect.gen(function* () {\n        const { key } = yield* WeatherApiKey\n        return { source: \"weather\", key }\n      }),\n  })\n\n  const getCoords = Tool.make({\n    name: \"get_coords\",\n    description: \"\",\n    inputSchema: Tool.fromEffectSchema(Empty),\n    run: () =>\n      Effect.gen(function* () {\n        const { key } = yield* GeoApiKey\n        return { source: \"geo\", key }\n      }),\n  })\n\n  const call = (name: string, id: string): FunctionCall => ({\n    type: \"function_call\",\n    call_id: id,\n    name,\n    arguments: \"{}\",\n  })\n\n  it(\"propagates each tool's R into the resulting Stream's requirements\", () => {\n    const stream = Toolkit.executeAll([getWeather, getCoords], [])\n    expectTypeOf(stream).toEqualTypeOf<\n      Stream.Stream<import(\"./ToolEvent.js\").ToolEvent, never, WeatherApiKey | GeoApiKey>\n    >()\n  })\n\n  it(\"runs each tool with its own service injected\", async () => {\n    const layer = Layer.mergeAll(\n      Layer.succeed(WeatherApiKey, { key: \"weather-123\" }),\n      Layer.succeed(GeoApiKey, { key: \"geo-456\" }),\n    )\n\n    const program = Toolkit.executeAll(\n      [getWeather, getCoords],\n      [call(\"get_weather\", \"c1\"), call(\"get_coords\", \"c2\")],\n    ).pipe(Stream.runCollect, Effect.provide(layer))\n\n    const events = await Effect.runPromise(program)\n    const outputs = Array.from(events).filter(isOutput)\n    const byCall = new Map(outputs.map((e) => [e.result.call_id, e.result]))\n\n    const w = byCall.get(\"c1\")\n    const g = byCall.get(\"c2\")\n    expect(w !== undefined && isValue(w) && w.value).toEqual({\n      source: \"weather\",\n      key: \"weather-123\",\n    })\n    expect(g !== undefined && isValue(g) && g.value).toEqual({\n      source: \"geo\",\n      key: \"geo-456\",\n    })\n  })\n\n  it(\"with no service-needing tools, R is never\", () => {\n    const plain = Tool.make({\n      name: \"plain\",\n      description: \"\",\n      inputSchema: Tool.fromEffectSchema(Empty),\n      run: () => Effect.succeed(0),\n    })\n    const stream = Toolkit.executeAll([plain], [])\n    expectTypeOf(stream).toEqualTypeOf<\n      Stream.Stream<import(\"./ToolEvent.js\").ToolEvent, never, never>\n    >()\n  })\n})\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@effect-uai/core",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Low-level primitives (loop, conversation, items, tools, streaming codecs) for building AI agents with Effect.",
   "keywords": [
     "agents",
@@ -20,6 +20,12 @@
     "url": "https://github.com/betalyra/effect-uai",
     "directory": "packages/core"
   },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
   "type": "module",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
@@ -32,14 +38,30 @@
       "types": "./dist/domain/AiError.d.mts",
       "import": "./dist/domain/AiError.mjs"
     },
+    "./Image": {
+      "types": "./dist/domain/Image.d.mts",
+      "import": "./dist/domain/Image.mjs"
+    },
     "./Items": {
       "types": "./dist/domain/Items.d.mts",
       "import": "./dist/domain/Items.mjs"
     },
+    "./Media": {
+      "types": "./dist/domain/Media.d.mts",
+      "import": "./dist/domain/Media.mjs"
+    },
     "./Turn": {
       "types": "./dist/domain/Turn.d.mts",
       "import": "./dist/domain/Turn.mjs"
     },
+    "./Embedding": {
+      "types": "./dist/embedding-model/Embedding.d.mts",
+      "import": "./dist/embedding-model/Embedding.mjs"
+    },
+    "./EmbeddingModel": {
+      "types": "./dist/embedding-model/EmbeddingModel.d.mts",
+      "import": "./dist/embedding-model/EmbeddingModel.mjs"
+    },
     "./LanguageModel": {
       "types": "./dist/language-model/LanguageModel.d.mts",
       "import": "./dist/language-model/LanguageModel.mjs"
@@ -48,9 +70,9 @@
       "types": "./dist/loop/Loop.d.mts",
       "import": "./dist/loop/Loop.mjs"
     },
-    "./Match": {
-      "types": "./dist/match/Match.d.mts",
-      "import": "./dist/match/Match.mjs"
+    "./Vector": {
+      "types": "./dist/math/Vector.d.mts",
+      "import": "./dist/math/Vector.mjs"
     },
     "./Tool": {
       "types": "./dist/tool/Tool.d.mts",
@@ -101,25 +123,19 @@
       "import": "./dist/testing/MockProvider.mjs"
     }
   },
-  "files": [
-    "dist",
-    "src",
-    "README.md",
-    "LICENSE"
-  ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "@standard-schema/spec": "^1.1.0"
   },
-  "peerDependencies": {
-    "effect": "4.0.0-beta.57"
-  },
   "devDependencies": {
     "effect": "4.0.0-beta.57",
     "typescript": "^6.0.3"
   },
+  "peerDependencies": {
+    "effect": "4.0.0-beta.57"
+  },
   "scripts": {
     "build": "tsdown",
     "typecheck": "tsc --noEmit"

package/src/domain/Image.ts

@@ -0,0 +1,75 @@
+import { Schema } from "effect"
+import type { MediaBase64, MediaBytes, MediaSource, MediaUrl } from "./Media.js"
+
+/**
+ * Image MIME types AI providers typically accept. The first four are the
+ * universal subset (Cohere v4, Voyage multimodal, Jina v4, Google
+ * `gemini-embedding-2`); HEIC / HEIF are Google-specific. The
+ * `(string & {})` tail keeps autocomplete on the literals while still
+ * accepting any string, so a newly-supported format works without an
+ * SDK update.
+ */
+export type ImageMimeType =
+  | "image/png"
+  | "image/jpeg"
+  | "image/webp"
+  | "image/gif"
+  | "image/heic"
+  | "image/heif"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})
+
+const ImageMimeTypeSchema = Schema.String as unknown as Schema.Schema<ImageMimeType>
+
+export type ImageUrlSource = MediaUrl<ImageMimeType>
+export type ImageBase64Source = MediaBase64<ImageMimeType>
+export type ImageBytesSource = MediaBytes<ImageMimeType>
+
+/**
+ * Where an image lives. Provider layers normalize across these:
+ * `bytes` becomes a base64 data URI for OpenAI / Anthropic, an
+ * `inlineData` part for Gemini, and a separate field for Cohere /
+ * Voyage. URL constraints (must be HTTPS, must be public, …) are
+ * provider-specific and validated at the layer, not in the type.
+ */
+export type ImageSource = MediaSource<ImageMimeType>
+
+export const ImageUrlSource = Schema.TaggedStruct("url", {
+  url: Schema.String,
+  mimeType: Schema.optional(ImageMimeTypeSchema),
+})
+
+export const ImageBase64Source = Schema.TaggedStruct("base64", {
+  base64: Schema.String,
+  mimeType: ImageMimeTypeSchema,
+})
+
+export const ImageBytesSource = Schema.TaggedStruct("bytes", {
+  bytes: Schema.Uint8Array,
+  mimeType: ImageMimeTypeSchema,
+})
+
+export const ImageSource: Schema.Schema<ImageSource> = Schema.Union([
+  ImageUrlSource,
+  ImageBase64Source,
+  ImageBytesSource,
+]) as unknown as Schema.Schema<ImageSource>
+
+export const imageUrl = (url: string, mimeType?: ImageMimeType): ImageUrlSource =>
+  mimeType !== undefined ? { _tag: "url", url, mimeType } : { _tag: "url", url }
+
+export const imageBase64 = (base64: string, mimeType: ImageMimeType): ImageBase64Source => ({
+  _tag: "base64",
+  base64,
+  mimeType,
+})
+
+export const imageBytes = (bytes: Uint8Array, mimeType: ImageMimeType): ImageBytesSource => ({
+  _tag: "bytes",
+  bytes,
+  mimeType,
+})
+
+export const isImageUrl = Schema.is(ImageUrlSource)
+export const isImageBase64 = Schema.is(ImageBase64Source)
+export const isImageBytes = Schema.is(ImageBytesSource)

package/src/domain/Items.ts

@@ -1,4 +1,5 @@
 import { Schema } from "effect"
+import { ImageSource } from "./Image.js"
 
 // ---------------------------------------------------------------------------
 // Content blocks (inside Message.content)
@@ -10,39 +11,13 @@ export const InputText = Schema.Struct({
 })
 export type InputText = typeof InputText.Type
 
-/**
- * Where an image lives. `url` covers HTTP(S) URLs (the model fetches
- * them); `base64` covers inline bytes embedded in the request. Provider
- * encoders dispatch on `_tag`. File-id / uploaded-asset references are
- * provider-specific and stay out of this union for now.
- */
-export const ImageUrlSource = Schema.Struct({
-  _tag: Schema.Literal("url"),
-  url: Schema.String,
-})
-export type ImageUrlSource = typeof ImageUrlSource.Type
-
-/**
- * Inline image bytes. `data` is **already base64-encoded** (matches what
- * the wire formats expect; no double-encoding needed downstream).
- * `media_type` is the MIME type, e.g. `"image/png"`.
- */
-export const ImageBase64Source = Schema.Struct({
-  _tag: Schema.Literal("base64"),
-  media_type: Schema.String,
-  data: Schema.String,
-})
-export type ImageBase64Source = typeof ImageBase64Source.Type
-
-export const ImageSource = Schema.Union([ImageUrlSource, ImageBase64Source])
-export type ImageSource = typeof ImageSource.Type
-
-export const isImageUrlSource = (s: ImageSource): s is ImageUrlSource => s._tag === "url"
-export const isImageBase64Source = (s: ImageSource): s is ImageBase64Source => s._tag === "base64"
-
 /**
  * User-provided image content block. Pair with `InputText` inside a
  * `Message.content` array to ask "what's in this image?" style questions.
+ *
+ * `source` is the cross-modality `ImageSource` from `domain/Image.ts` -
+ * url, base64, or raw bytes. Provider codecs encode bytes to whatever
+ * wire format the provider wants.
  */
 export const InputImage = Schema.Struct({
   type: Schema.Literal("input_image"),
@@ -91,11 +66,10 @@ export type FilePath = typeof FilePath.Type
 export const Annotation = Schema.Union([UrlCitation, FileCitation, ContainerFileCitation, FilePath])
 export type Annotation = typeof Annotation.Type
 
-export const isUrlCitation = (a: Annotation): a is UrlCitation => a.type === "url_citation"
-export const isFileCitation = (a: Annotation): a is FileCitation => a.type === "file_citation"
-export const isContainerFileCitation = (a: Annotation): a is ContainerFileCitation =>
-  a.type === "container_file_citation"
-export const isFilePath = (a: Annotation): a is FilePath => a.type === "file_path"
+export const isUrlCitation = Schema.is(UrlCitation)
+export const isFileCitation = Schema.is(FileCitation)
+export const isContainerFileCitation = Schema.is(ContainerFileCitation)
+export const isFilePath = Schema.is(FilePath)
 
 export const OutputText = Schema.Struct({
   type: Schema.Literal("output_text"),
@@ -183,18 +157,15 @@ export type Item = typeof Item.Type
 // Type guards
 // ---------------------------------------------------------------------------
 
-export const isInputText = (block: ContentBlock): block is InputText => block.type === "input_text"
-export const isInputImage = (block: ContentBlock): block is InputImage =>
-  block.type === "input_image"
-export const isOutputText = (block: ContentBlock): block is OutputText =>
-  block.type === "output_text"
-export const isRefusal = (block: ContentBlock): block is Refusal => block.type === "refusal"
-
-export const isMessage = (item: Item): item is Message => item.type === "message"
-export const isFunctionCall = (item: Item): item is FunctionCall => item.type === "function_call"
-export const isFunctionCallOutput = (item: Item): item is FunctionCallOutput =>
-  item.type === "function_call_output"
-export const isReasoning = (item: Item): item is Reasoning => item.type === "reasoning"
+export const isInputText = Schema.is(InputText)
+export const isInputImage = Schema.is(InputImage)
+export const isOutputText = Schema.is(OutputText)
+export const isRefusal = Schema.is(Refusal)
+
+export const isMessage = Schema.is(Message)
+export const isFunctionCall = Schema.is(FunctionCall)
+export const isFunctionCallOutput = Schema.is(FunctionCallOutput)
+export const isReasoning = Schema.is(Reasoning)
 
 // ---------------------------------------------------------------------------
 // Usage and stop reason

package/src/domain/Media.ts

@@ -0,0 +1,61 @@
+/**
+ * Cross-modality media reference shape.
+ *
+ * Every "media at rest" reference - image, audio, video, document - is one
+ * of three variants:
+ *
+ *   - `url`    : a remote address (HTTP, GCS, etc.). The model fetches it.
+ *               `mimeType` is optional - servers usually set Content-Type.
+ *               Some providers (Gemini `fileData`) want it explicit.
+ *
+ *   - `base64` : an inline base64-encoded payload. Always carries a
+ *               `mimeType` so the consumer knows how to decode.
+ *
+ *   - `bytes`  : raw `Uint8Array`. Provider layers normalize to base64 or
+ *               multipart upload at the wire boundary - users don't need
+ *               to encode themselves.
+ *
+ * Per-modality files (`Image.ts`, future `Audio.ts` / `Video.ts` /
+ * `Document.ts`) instantiate this shape with their typed MIME union to
+ * get autocomplete on common formats while keeping the structural type
+ * uniform across modalities.
+ *
+ * Streaming media (live mic feed, streaming TTS playback) is *not*
+ * modeled here. Streams carry effect parameters (`Stream<A, E, R>`) and
+ * lifecycle (Scope, cancellation) that don't apply to media at rest. The
+ * complementary type lives alongside this one as `*Stream` in each
+ * per-modality file when those modalities land.
+ *
+ * Provider-uploaded asset references (OpenAI Files `file_id`, Gemini
+ * Files API URIs, Anthropic file IDs) are also out of scope here -
+ * they're a separate union (`FileRef`) added when needed.
+ */
+
+export type MediaUrl<M extends string = string> = {
+  readonly _tag: "url"
+  readonly url: string
+  readonly mimeType?: M
+}
+
+export type MediaBase64<M extends string = string> = {
+  readonly _tag: "base64"
+  readonly base64: string
+  readonly mimeType: M
+}
+
+export type MediaBytes<M extends string = string> = {
+  readonly _tag: "bytes"
+  readonly bytes: Uint8Array
+  readonly mimeType: M
+}
+
+export type MediaSource<M extends string = string> = MediaUrl<M> | MediaBase64<M> | MediaBytes<M>
+
+export const isMediaUrl = <M extends string>(s: MediaSource<M>): s is MediaUrl<M> =>
+  s._tag === "url"
+
+export const isMediaBase64 = <M extends string>(s: MediaSource<M>): s is MediaBase64<M> =>
+  s._tag === "base64"
+
+export const isMediaBytes = <M extends string>(s: MediaSource<M>): s is MediaBytes<M> =>
+  s._tag === "bytes"