@effect-uai/core 0.1.0

package/dist/tool/Tool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Tool.mjs","names":[],"sources":["../../src/tool/Tool.ts"],"sourcesContent":["import type { StandardJSONSchemaV1, StandardSchemaV1 } from \"@standard-schema/spec\"\nimport { Effect, Schema, Stream } from \"effect\"\nimport type { FunctionCall, FunctionCallOutput } from \"../domain/Items.js\"\nimport { functionCallOutput } from \"../domain/Items.js\"\n\nexport class ToolError extends Schema.TaggedErrorClass<ToolError>(\"@betalyra/effect-uai/ToolError\")(\n  \"ToolError\",\n  {\n    call_id: Schema.String,\n    tool: Schema.String,\n    message: Schema.String,\n    cause: Schema.optional(Schema.Unknown),\n  },\n) {}\n\n/**\n * Schemas accepted on `Tool.inputSchema`. Must implement both Standard\n * Schema validation and JSON Schema conversion (for rendering tool\n * descriptors to provider request bodies).\n *\n * Any Standard-Schema-compliant library that exposes both interfaces\n * works directly: Zod 4+, Valibot, ArkType, Effect Schema (after\n * `fromEffectSchema`), etc.\n */\nexport type ToolInputSchema<Input = unknown> = StandardSchemaV1<unknown, Input> &\n  StandardJSONSchemaV1<unknown, Input>\n\n/**\n * Convenience wrapper for Effect Schema users - adds both the\n * `validate` and `jsonSchema` extensions to a plain Effect Schema so it\n * can be used as a `Tool.inputSchema`.\n */\nexport const fromEffectSchema = <S extends Schema.Codec<any, any, never, any>>(\n  schema: S,\n): S & ToolInputSchema<S[\"Type\"]> =>\n  Schema.toStandardJSONSchemaV1(Schema.toStandardSchemaV1(schema)) as unknown as S &\n    ToolInputSchema<S[\"Type\"]>\n\nexport interface Tool<Name extends string, Input, Output, R = never> {\n  readonly name: Name\n  readonly description: string\n  readonly inputSchema: ToolInputSchema<Input>\n  readonly run: (input: Input) => Effect.Effect<Output, unknown, R>\n  /**\n   * Whether the provider should render this tool with its strict-mode\n   * flag (OpenAI's `strict: true`, etc). Default: true. The framework\n   * never rewrites the schema; if the rendered JSON Schema isn't\n   * compatible, the provider returns an error.\n   */\n  readonly strict?: boolean\n}\n\n/**\n * Provider-agnostic tool descriptor. Each provider maps `inputSchema`\n * to its own wire field (OpenAI → `parameters`, Anthropic →\n * `input_schema`). Built from a `Tool` by `Toolkit.toDescriptors`.\n */\nexport interface ToolDescriptor {\n  readonly name: string\n  readonly description: string\n  readonly inputSchema: Record<string, unknown>\n  readonly strict?: boolean\n}\n\nexport const make = <Name extends string, Input, Output, R = never>(\n  spec: Tool<Name, Input, Output, R>,\n): Tool<Name, Input, Output, R> => spec\n\n// ---------------------------------------------------------------------------\n// Streaming tools\n//\n// `run` returns a `Stream<Event>` instead of an `Effect<Output>`. Events\n// flow through to the consumer as `ToolEvent.Intermediate`s in real time;\n// at end-of-stream `finalize(events)` reduces them to the model-facing\n// `Output`. Sub-agents, slow downloads with progress, recipe streamers.\n// ---------------------------------------------------------------------------\n\nexport interface StreamingTool<Name extends string, Input, Event, Output, R = never> {\n  readonly _kind: \"streaming\"\n  readonly name: Name\n  readonly description: string\n  readonly inputSchema: ToolInputSchema<Input>\n  readonly run: (input: Input) => Stream.Stream<Event, unknown, R>\n  readonly finalize: (events: ReadonlyArray<Event>) => Output\n  readonly strict?: boolean\n}\n\nexport const streaming = <Name extends string, Input, Event, Output, R = never>(\n  spec: Omit<StreamingTool<Name, Input, Event, Output, R>, \"_kind\">,\n): StreamingTool<Name, Input, Event, Output, R> => ({ _kind: \"streaming\", ...spec })\n\nexport type AnyStreamingTool = StreamingTool<string, any, any, any, never>\nexport type AnyPlainTool = Tool<string, any, any, never>\nexport type AnyKindTool = AnyStreamingTool | AnyPlainTool\n\nexport const isStreamingTool = (t: AnyKindTool): t is AnyStreamingTool =>\n  \"_kind\" in t && t._kind === \"streaming\"\n\n/**\n * Render any-kind tools (mixed plain and streaming) to provider-agnostic\n * descriptors. Mirrors `Toolkit.toDescriptors` but accepts the union type\n * so a single list can carry both kinds.\n */\nexport const toDescriptors = (\n  tools: ReadonlyArray<AnyKindTool>,\n): ReadonlyArray<ToolDescriptor> =>\n  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\nconst toToolError = (call: FunctionCall, toolName: string, message: string) => (cause: unknown) =>\n  new ToolError({ call_id: call.call_id, tool: toolName, message, cause })\n\n/**\n * Decode and validate the JSON arguments of a function_call against the\n * tool's input schema, run the tool, and serialize the output into a\n * function_call_output item.\n */\nexport const execute = <Name extends string, Input, Output, R>(\n  tool: Tool<Name, Input, Output, R>,\n  call: FunctionCall,\n): Effect.Effect<FunctionCallOutput, ToolError, R> =>\n  Effect.gen(function* () {\n    const parsed = yield* Effect.try({\n      try: () => JSON.parse(call.arguments) as unknown,\n      catch: toToolError(call, tool.name, \"Failed to parse JSON arguments\"),\n    })\n\n    const result = yield* Effect.promise(() =>\n      Promise.resolve(tool.inputSchema[\"~standard\"].validate(parsed)),\n    )\n    if (result.issues !== undefined) {\n      return yield* new ToolError({\n        call_id: call.call_id,\n        tool: tool.name,\n        message: \"Tool input failed schema validation\",\n        cause: result.issues,\n      })\n    }\n\n    const output = yield* tool\n      .run(result.value)\n      .pipe(Effect.mapError(toToolError(call, tool.name, \"Tool execution failed\")))\n    return functionCallOutput(call.call_id, JSON.stringify(output))\n  })\n"],"mappings":";;;;;;;;;;;;;AAKA,IAAa,YAAb,cAA+B,OAAO,iBAA4B,iCAAiC,CACjG,aACA;CACE,SAAS,OAAO;CAChB,MAAM,OAAO;CACb,SAAS,OAAO;CAChB,OAAO,OAAO,SAAS,OAAO,QAAQ;CACvC,CACF,CAAC;;;;;;AAmBF,MAAa,oBACX,WAEA,OAAO,uBAAuB,OAAO,mBAAmB,OAAO,CAAC;AA6BlE,MAAa,QACX,SACiC;AAqBnC,MAAa,aACX,UACkD;CAAE,OAAO;CAAa,GAAG;CAAM;AAMnF,MAAa,mBAAmB,MAC9B,WAAW,KAAK,EAAE,UAAU;;;;;;AAO9B,MAAa,iBACX,UAEA,MAAM,KAAK,SAAS;CAClB,MAAM,cAAc,KAAK,YAAY,aAAa,WAAW,MAAM,EACjE,QAAQ,iBACT,CAAC;AACF,QAAO,KAAK,WAAW,KAAA,IACnB;EAAE,MAAM,KAAK;EAAM,aAAa,KAAK;EAAa;EAAa,QAAQ,KAAK;EAAQ,GACpF;EAAE,MAAM,KAAK;EAAM,aAAa,KAAK;EAAa;EAAa;EACnE;AAEJ,MAAM,eAAe,MAAoB,UAAkB,aAAqB,UAC9E,IAAI,UAAU;CAAE,SAAS,KAAK;CAAS,MAAM;CAAU;CAAS;CAAO,CAAC;;;;;;AAO1E,MAAa,WACX,MACA,SAEA,OAAO,IAAI,aAAa;CACtB,MAAM,SAAS,OAAO,OAAO,IAAI;EAC/B,WAAW,KAAK,MAAM,KAAK,UAAU;EACrC,OAAO,YAAY,MAAM,KAAK,MAAM,iCAAiC;EACtE,CAAC;CAEF,MAAM,SAAS,OAAO,OAAO,cAC3B,QAAQ,QAAQ,KAAK,YAAY,aAAa,SAAS,OAAO,CAAC,CAChE;AACD,KAAI,OAAO,WAAW,KAAA,EACpB,QAAO,OAAO,IAAI,UAAU;EAC1B,SAAS,KAAK;EACd,MAAM,KAAK;EACX,SAAS;EACT,OAAO,OAAO;EACf,CAAC;CAGJ,MAAM,SAAS,OAAO,KACnB,IAAI,OAAO,MAAM,CACjB,KAAK,OAAO,SAAS,YAAY,MAAM,KAAK,MAAM,wBAAwB,CAAC,CAAC;AAC/E,QAAO,mBAAmB,KAAK,SAAS,KAAK,UAAU,OAAO,CAAC;EAC/D"}

package/dist/tool/ToolEvent.d.mts

@@ -0,0 +1,2 @@
+import { i as isOutput, n as isApprovalRequested, r as isIntermediate, t as ToolEvent } from "../ToolEvent-B2N10hr3.mjs";
+export { ToolEvent, isApprovalRequested, isIntermediate, isOutput };

package/dist/tool/ToolEvent.mjs

@@ -0,0 +1,8 @@
+//#region src/tool/ToolEvent.ts
+const isApprovalRequested = (e) => e._tag === "ApprovalRequested";
+const isIntermediate = (e) => e._tag === "Intermediate";
+const isOutput = (e) => e._tag === "Output";
+//#endregion
+export { isApprovalRequested, isIntermediate, isOutput };
+
+//# sourceMappingURL=ToolEvent.mjs.map

package/dist/tool/ToolEvent.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolEvent.mjs","names":[],"sources":["../../src/tool/ToolEvent.ts"],"sourcesContent":["/**\n * The event type emitted by `Toolkit.executeAllWithResolver`.\n *\n *   - ApprovalRequested : gated calls before resolver returns\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"}

package/dist/tool/Toolkit.d.mts

@@ -0,0 +1,34 @@
+import { o as FunctionCall } from "../Items-D1C2686t.mjs";
+import { a as Tool, o as ToolDescriptor, t as AnyKindTool } from "../Tool-5wxOCuOh.mjs";
+import { t as Event } from "../Loop-CzSJo1h8.mjs";
+import { n as ToolResult, t as ToolDecision } from "../Outcome-C2JYknCu.mjs";
+import { t as ToolEvent } from "../ToolEvent-B2N10hr3.mjs";
+import { Effect, Stream } from "effect";
+
+//#region src/tool/Toolkit.d.ts
+declare namespace Toolkit_d_exports {
+  export { AnyTool, ExecuteOptions, Resolver, Toolkit, ToolsR, executeAll, executeAllWithResolver, make, nextStateFrom, 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;
+declare const make: <const Tools extends ReadonlyArray<AnyTool>>(tools: Tools) => Toolkit<Tools>;
+/**
+ * Render every tool in a toolkit to a provider-agnostic descriptor.
+ * `inputSchema` is the JSON Schema document produced by the tool's
+ * Standard Schema converter (draft 2020-12).
+ */
+declare const toDescriptors: <Tools extends ReadonlyArray<AnyTool>>(toolkit: Toolkit<Tools>) => ReadonlyArray<ToolDescriptor>;
+type Resolver = (call: FunctionCall) => Effect.Effect<ToolDecision>;
+interface ExecuteOptions {
+  readonly concurrency?: number | "unbounded";
+}
+declare const executeAllWithResolver: (tools: ReadonlyArray<AnyKindTool>, calls: ReadonlyArray<FunctionCall>, resolve: Resolver, options?: ExecuteOptions) => Stream.Stream<ToolEvent>;
+/** No-resolver shortcut: every call gets `Execute`. */
+declare const executeAll: (tools: ReadonlyArray<AnyKindTool>, calls: ReadonlyArray<FunctionCall>, options?: ExecuteOptions) => Stream.Stream<ToolEvent>;
+declare const nextStateFrom: <S>(stream: Stream.Stream<ToolEvent>, build: (results: ReadonlyArray<ToolResult>) => S) => Stream.Stream<Event<ToolEvent, S>>;
+//#endregion
+export { AnyTool, ExecuteOptions, Resolver, Toolkit, ToolsR, executeAll, executeAllWithResolver, make, nextStateFrom, Toolkit_d_exports as t, toDescriptors };
+//# sourceMappingURL=Toolkit.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Toolkit.d.mts","names":[],"sources":["../../src/tool/Toolkit.ts"],"mappings":";;;;;;;;;;;KAqBY,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,KAmBL,QAAA,IAAY,IAAA,EAAM,YAAA,KAAiB,MAAA,CAAO,MAAA,CAAO,YAAA;AAAA,UAE5C,cAAA;EAAA,SACN,WAAA;AAAA;AAAA,cAGE,sBAAA,GACX,KAAA,EAAO,aAAA,CAAc,WAAA,GACrB,KAAA,EAAO,aAAA,CAAc,YAAA,GACrB,OAAA,EAAS,QAAA,EACT,OAAA,GAAU,cAAA,KACT,MAAA,CAAO,MAAA,CAAO,SAAA;;cAYJ,UAAA,GACX,KAAA,EAAO,aAAA,CAAc,WAAA,GACrB,KAAA,EAAO,aAAA,CAAc,YAAA,GACrB,OAAA,GAAU,cAAA,KACT,MAAA,CAAO,MAAA,CAAO,SAAA;AAAA,cAmIJ,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"}

package/dist/tool/Toolkit.mjs

@@ -0,0 +1,105 @@
+import { t as __exportAll } from "../chunk-CfYAbeIz.mjs";
+import { nextAfterFold } from "../loop/Loop.mjs";
+import { isStreamingTool } from "./Tool.mjs";
+import { execute, executionError, rejected } from "./Outcome.mjs";
+import { isOutput } from "./ToolEvent.mjs";
+import { Array, Effect, Match, Ref, Stream } from "effect";
+//#region src/tool/Toolkit.ts
+var Toolkit_exports = /* @__PURE__ */ __exportAll({
+	executeAll: () => executeAll,
+	executeAllWithResolver: () => executeAllWithResolver,
+	make: () => make,
+	nextStateFrom: () => nextStateFrom,
+	toDescriptors: () => toDescriptors
+});
+const make = (tools) => ({ tools });
+/**
+* Render every tool in a toolkit to a provider-agnostic descriptor.
+* `inputSchema` is the JSON Schema document produced by the tool's
+* Standard Schema converter (draft 2020-12).
+*/
+const toDescriptors = (toolkit) => toolkit.tools.map((tool) => {
+	const inputSchema = tool.inputSchema["~standard"].jsonSchema.input({ target: "draft-2020-12" });
+	return tool.strict !== void 0 ? {
+		name: tool.name,
+		description: tool.description,
+		inputSchema,
+		strict: tool.strict
+	} : {
+		name: tool.name,
+		description: tool.description,
+		inputSchema
+	};
+});
+const executeAllWithResolver = (tools, calls, resolve, options) => Stream.fromIterable(calls).pipe(Stream.flatMap((call) => Stream.unwrap(resolve(call).pipe(Effect.map((decision) => dispatch(tools, call, decision)))), { concurrency: options?.concurrency ?? "unbounded" }));
+/** No-resolver shortcut: every call gets `Execute`. */
+const executeAll = (tools, calls, options) => executeAllWithResolver(tools, calls, () => Effect.succeed(execute), options);
+const dispatch = (tools, call, decision) => Match.value(decision).pipe(Match.tag("Execute", () => runOne(tools, call)), Match.tag("Reject", (d) => Stream.succeed({
+	_tag: "Output",
+	result: d.result
+})), Match.exhaustive);
+const valueResult = (call, tool, value) => ({
+	_tag: "Value",
+	call_id: call.call_id,
+	tool,
+	value
+});
+const runOne = (tools, call) => {
+	const tool = tools.find((t) => t.name === call.name);
+	if (tool === void 0) return Stream.succeed({
+		_tag: "Output",
+		result: rejected(call, "unknown_tool", `No tool registered with name "${call.name}"`)
+	});
+	if (isStreamingTool(tool)) return runStreaming(tool, call);
+	return runPlain(tool, call);
+};
+const runPlain = (tool, call) => Stream.fromEffect(Effect.gen(function* () {
+	const parsed = yield* Effect.try({
+		try: () => JSON.parse(call.arguments),
+		catch: () => "json_parse_error"
+	});
+	const validated = yield* Effect.tryPromise({
+		try: () => Promise.resolve(tool.inputSchema["~standard"].validate(parsed)),
+		catch: () => "validation_threw"
+	});
+	if (validated.issues !== void 0) return executionError(call, "Tool input failed schema validation");
+	const output = yield* tool.run(validated.value);
+	return valueResult(call, tool.name, output);
+}).pipe(Effect.catchCause(() => Effect.succeed(executionError(call, "Tool execution failed"))), Effect.map((result) => ({
+	_tag: "Output",
+	result
+}))));
+const runStreaming = (tool, call) => Stream.unwrap(Effect.gen(function* () {
+	const parsed = yield* Effect.try({
+		try: () => JSON.parse(call.arguments),
+		catch: () => "json_parse_error"
+	});
+	const validated = yield* Effect.tryPromise({
+		try: () => Promise.resolve(tool.inputSchema["~standard"].validate(parsed)),
+		catch: () => "validation_threw"
+	});
+	if (validated.issues !== void 0) return Stream.succeed({
+		_tag: "Output",
+		result: executionError(call, "Tool input failed schema validation")
+	});
+	const ref = yield* Ref.make([]);
+	const intermediates = tool.run(validated.value).pipe(Stream.tap((event) => Ref.update(ref, Array.append(event))), Stream.map((data) => ({
+		_tag: "Intermediate",
+		call_id: call.call_id,
+		tool: tool.name,
+		data
+	})));
+	const output = Stream.fromEffect(Ref.get(ref).pipe(Effect.map((events) => ({
+		_tag: "Output",
+		result: valueResult(call, tool.name, tool.finalize(events))
+	}))));
+	return intermediates.pipe(Stream.concat(output));
+})).pipe(Stream.catchCause(() => Stream.succeed({
+	_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);
+//#endregion
+export { executeAll, executeAllWithResolver, make, nextStateFrom, Toolkit_exports as t, toDescriptors };
+
+//# sourceMappingURL=Toolkit.mjs.map

package/dist/tool/Toolkit.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Toolkit.mjs","names":["executeDecision","Arr","Loop.nextAfterFold"],"sources":["../../src/tool/Toolkit.ts"],"sourcesContent":["import { Array as Arr, Effect, Match, 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 ToolDecision,\n  type ToolResult,\n  execute as executeDecision,\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// Resolver-based executor. Streams `ToolEvent`s in real time, dispatches\n// streaming and plain tools uniformly, and lets the caller decide what\n// happens to each call (Execute or Reject) before execution.\n//\n// `executeAllWithResolver` is the general primitive. `executeAllStream` is\n// the no-resolver shortcut.\n// ---------------------------------------------------------------------------\n\nexport type Resolver = (call: FunctionCall) => Effect.Effect<ToolDecision>\n\nexport interface ExecuteOptions {\n  readonly concurrency?: number | \"unbounded\"\n}\n\nexport const executeAllWithResolver = (\n  tools: ReadonlyArray<AnyKindTool>,\n  calls: ReadonlyArray<FunctionCall>,\n  resolve: Resolver,\n  options?: ExecuteOptions,\n): Stream.Stream<ToolEvent> =>\n  Stream.fromIterable(calls).pipe(\n    Stream.flatMap(\n      (call) =>\n        Stream.unwrap(\n          resolve(call).pipe(Effect.map((decision) => dispatch(tools, call, decision))),\n        ),\n      { concurrency: options?.concurrency ?? \"unbounded\" },\n    ),\n  )\n\n/** No-resolver shortcut: every call gets `Execute`. */\nexport const executeAll = (\n  tools: ReadonlyArray<AnyKindTool>,\n  calls: ReadonlyArray<FunctionCall>,\n  options?: ExecuteOptions,\n): Stream.Stream<ToolEvent> =>\n  executeAllWithResolver(tools, calls, () => Effect.succeed(executeDecision), options)\n\nconst dispatch = (\n  tools: ReadonlyArray<AnyKindTool>,\n  call: FunctionCall,\n  decision: ToolDecision,\n): Stream.Stream<ToolEvent> =>\n  Match.value(decision).pipe(\n    Match.tag(\"Execute\", () => runOne(tools, call)),\n    Match.tag(\"Reject\", (d) =>\n      Stream.succeed<ToolEvent>({ _tag: \"Output\", result: d.result }),\n    ),\n    Match.exhaustive,\n  )\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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"}

package/package.json

@@ -0,0 +1,127 @@
+{
+  "name": "@effect-uai/core",
+  "version": "0.1.0",
+  "description": "Low-level primitives (loop, conversation, items, tools, streaming codecs) for building AI agents with Effect.",
+  "keywords": [
+    "agents",
+    "ai",
+    "effect",
+    "llm",
+    "streaming"
+  ],
+  "homepage": "https://github.com/betalyra/effect-uai/tree/main/packages/core",
+  "bugs": {
+    "url": "https://github.com/betalyra/effect-uai/issues"
+  },
+  "license": "MIT",
+  "author": "Betalyra",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/betalyra/effect-uai",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./AiError": {
+      "types": "./dist/domain/AiError.d.mts",
+      "import": "./dist/domain/AiError.mjs"
+    },
+    "./Items": {
+      "types": "./dist/domain/Items.d.mts",
+      "import": "./dist/domain/Items.mjs"
+    },
+    "./Turn": {
+      "types": "./dist/domain/Turn.d.mts",
+      "import": "./dist/domain/Turn.mjs"
+    },
+    "./LanguageModel": {
+      "types": "./dist/language-model/LanguageModel.d.mts",
+      "import": "./dist/language-model/LanguageModel.mjs"
+    },
+    "./Loop": {
+      "types": "./dist/loop/Loop.d.mts",
+      "import": "./dist/loop/Loop.mjs"
+    },
+    "./Match": {
+      "types": "./dist/match/Match.d.mts",
+      "import": "./dist/match/Match.mjs"
+    },
+    "./Tool": {
+      "types": "./dist/tool/Tool.d.mts",
+      "import": "./dist/tool/Tool.mjs"
+    },
+    "./Toolkit": {
+      "types": "./dist/tool/Toolkit.d.mts",
+      "import": "./dist/tool/Toolkit.mjs"
+    },
+    "./Outcome": {
+      "types": "./dist/tool/Outcome.d.mts",
+      "import": "./dist/tool/Outcome.mjs"
+    },
+    "./ToolEvent": {
+      "types": "./dist/tool/ToolEvent.d.mts",
+      "import": "./dist/tool/ToolEvent.mjs"
+    },
+    "./Resolvers": {
+      "types": "./dist/tool/Resolvers.d.mts",
+      "import": "./dist/tool/Resolvers.mjs"
+    },
+    "./HistoryCheck": {
+      "types": "./dist/tool/HistoryCheck.d.mts",
+      "import": "./dist/tool/HistoryCheck.mjs"
+    },
+    "./JSONL": {
+      "types": "./dist/streaming/JSONL.d.mts",
+      "import": "./dist/streaming/JSONL.mjs"
+    },
+    "./Lines": {
+      "types": "./dist/streaming/Lines.d.mts",
+      "import": "./dist/streaming/Lines.mjs"
+    },
+    "./SSE": {
+      "types": "./dist/streaming/SSE.d.mts",
+      "import": "./dist/streaming/SSE.mjs"
+    },
+    "./StructuredFormat": {
+      "types": "./dist/structured-format/StructuredFormat.d.mts",
+      "import": "./dist/structured-format/StructuredFormat.mjs"
+    },
+    "./Metrics": {
+      "types": "./dist/observability/Metrics.d.mts",
+      "import": "./dist/observability/Metrics.mjs"
+    },
+    "./testing/MockProvider": {
+      "types": "./dist/testing/MockProvider.d.mts",
+      "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"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/domain/AiError.ts

@@ -0,0 +1,93 @@
+import { Data, Duration } from "effect"
+
+export type Scope = "rpm" | "tpm" | "rpd" | "tpd"
+
+export class RateLimited extends Data.TaggedError("RateLimited")<{
+  provider: string
+  retryAfter?: Duration.Duration
+  scope?: Scope
+  requestId?: string
+  raw: unknown
+}> {}
+
+export class Unavailable extends Data.TaggedError("Unavailable")<{
+  provider: string
+  retryAfter?: Duration.Duration
+  status?: number
+  requestId?: string
+  raw: unknown
+}> {}
+
+export class Timeout extends Data.TaggedError("Timeout")<{
+  provider: string
+  requestId?: string
+  raw: unknown
+}> {}
+
+export class ContentFiltered extends Data.TaggedError("ContentFiltered")<{
+  provider: string
+  reason?: string
+  requestId?: string
+  raw: unknown
+}> {}
+
+export class ContextLengthExceeded extends Data.TaggedError("ContextLengthExceeded")<{
+  provider: string
+  modelLimit?: number
+  requested?: number
+  raw: unknown
+}> {}
+
+export class InvalidRequest extends Data.TaggedError("InvalidRequest")<{
+  provider: string
+  param?: string
+  requestId?: string
+  raw: unknown
+}> {}
+
+export type AuthSubtype = "auth" | "permission" | "billing" | "quota"
+
+export class AuthFailed extends Data.TaggedError("AuthFailed")<{
+  provider: string
+  subtype: AuthSubtype
+  raw: unknown
+}> {}
+
+export class Cancelled extends Data.TaggedError("Cancelled")<{
+  provider: string
+}> {}
+
+/**
+ * The model errored mid-generation. Distinct from `Unavailable` (transport
+ * problem before generation started) and from `IncompleteTurn` (provider
+ * stream ended without a terminal event). The provider's own error message,
+ * if any, is on `message`.
+ */
+export class GenerationFailed extends Data.TaggedError("GenerationFailed")<{
+  provider: string
+  code?: string
+  message?: string
+  requestId?: string
+  raw: unknown
+}> {}
+
+/**
+ * The provider's delta stream ended without a terminal `turn_complete`.
+ * Indicates a misbehaving provider or a connection that dropped mid-flight.
+ * Non-terminal deltas seen so far have already been emitted downstream.
+ */
+export class IncompleteTurn extends Data.TaggedError("IncompleteTurn")<{
+  raw?: unknown
+}> {}
+
+export type AiError =
+  | RateLimited
+  | Unavailable
+  | Timeout
+  | ContentFiltered
+  | ContextLengthExceeded
+  | InvalidRequest
+  | AuthFailed
+  | Cancelled
+  | IncompleteTurn
+  | GenerationFailed