@effect-uai/core 0.1.0

package/src/streaming/SSE.ts

@@ -0,0 +1,114 @@
+import { Stream } from "effect"
+
+/**
+ * One Server-Sent Event. Fields per the WHATWG spec:
+ * - `event`: optional event name (default "message" on the wire)
+ * - `data`: payload, with multiple `data:` lines joined by `\n`
+ * - `id`: optional last-event id
+ */
+export interface Event {
+  readonly event?: string
+  readonly data: string
+  readonly id?: string
+}
+
+// ---------------------------------------------------------------------------
+// Generic stream helpers (kept module-local for now; promote to a shared
+// Stream module once a third caller appears).
+// ---------------------------------------------------------------------------
+
+/** 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]
+}
+
+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
+}
+
+// ---------------------------------------------------------------------------
+// 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.
+ */
+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),
+  )
+
+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()
+
+/**
+ * Encode a `Stream<Event>` as `Stream<Uint8Array>` ready to send on an
+ * 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)))

package/src/structured-format/StructuredFormat.ts

@@ -0,0 +1,160 @@
+import type { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec"
+import { Data, Effect, Match, Schema, Stream, pipe } from "effect"
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Cross-validator schema constraint for structured outputs. Any schema
+ * implementing both Standard Schema (runtime validation) and Standard
+ * JSON Schema (wire encoding) works directly: Zod 4+, Valibot, ArkType,
+ * and Effect Schema after `fromEffectSchema`.
+ */
+export type StructuredSchema<Output = unknown> = StandardSchemaV1<unknown, Output> &
+  StandardJSONSchemaV1<unknown, Output>
+
+/**
+ * A schema-bound output the user wants the model to produce. Pairs the
+ * cross-validator schema with metadata providers need (name, description,
+ * strict-mode flag).
+ */
+export interface StructuredFormat<A> {
+  readonly name: string
+  readonly description?: string
+  readonly schema: StructuredSchema<A>
+  /**
+   * Provider strict-mode flag. OpenAI, Anthropic, and Mistral honour it
+   * (constrained decoding); other providers ignore.
+   */
+  readonly strict?: boolean
+}
+
+/** A single path-scoped validation problem. Library-agnostic shape. */
+export interface DecodeIssue {
+  readonly path: ReadonlyArray<string | number>
+  readonly message: string
+}
+
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+
+/**
+ * Schema validation failed. `raw` is the original text (or stringified
+ * value) that failed; `issues` is a flat list of per-field problems.
+ */
+export class StructuredDecodeError extends Data.TaggedError("StructuredDecodeError")<{
+  readonly raw: string
+  readonly issues: ReadonlyArray<DecodeIssue>
+}> {}
+
+/**
+ * `JSON.parse` threw on a string that was supposed to be JSON. Distinct
+ * from `StructuredDecodeError`: the bytes weren't even JSON.
+ */
+export class JsonParseError extends Data.TaggedError("StructuredJsonParseError")<{
+  readonly raw: string
+  readonly cause: unknown
+}> {}
+
+// ---------------------------------------------------------------------------
+// Constructors
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap an Effect `Schema` as a `StructuredFormat`. Effect Schema doesn't
+ * natively implement Standard Schema; this helper installs the
+ * `~standard` and JSON Schema interfaces.
+ */
+export const fromEffectSchema = <S extends Schema.Codec<any, any, never, any>>(
+  schema: S,
+  options?: {
+    readonly name?: string
+    readonly description?: string
+    readonly strict?: boolean
+  },
+): StructuredFormat<S["Type"]> => ({
+  name: options?.name ?? "output",
+  schema: Schema.toStandardJSONSchemaV1(Schema.toStandardSchemaV1(schema)),
+  ...(options?.description !== undefined && {
+    description: options.description,
+  }),
+  ...(options?.strict !== undefined && { strict: options.strict }),
+})
+
+// ---------------------------------------------------------------------------
+// Standard Schema → DecodeIssue
+// ---------------------------------------------------------------------------
+
+const propertyKeyToScalar = Match.type<PropertyKey>().pipe(
+  Match.when(Match.string, (s) => s),
+  Match.when(Match.number, (n) => n),
+  Match.when(Match.symbol, (s) => s.toString()),
+  Match.exhaustive,
+)
+
+const segmentToKey = Match.type<PropertyKey | StandardSchemaV1.PathSegment>().pipe(
+  Match.when(Match.string, (s) => s),
+  Match.when(Match.number, (n) => n),
+  Match.when(Match.symbol, (s) => s.toString()),
+  Match.orElse((segment) => propertyKeyToScalar(segment.key)),
+)
+
+const issueToDecode = (issue: StandardSchemaV1.Issue): DecodeIssue => ({
+  path: (issue.path ?? []).map(segmentToKey),
+  message: issue.message,
+})
+
+// ---------------------------------------------------------------------------
+// Decoding
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate an `unknown` against the format's schema. Returns the typed
+ * value or a `StructuredDecodeError`. Standard Schema's `validate` may
+ * be async; this function handles both sync and async results.
+ */
+export const decode =
+  <A>(format: StructuredFormat<A>) =>
+  (raw: unknown): Effect.Effect<A, StructuredDecodeError> =>
+    pipe(
+      Effect.promise(async () => format.schema["~standard"].validate(raw)),
+      Effect.flatMap((result) =>
+        result.issues === undefined
+          ? Effect.succeed(result.value)
+          : Effect.fail(
+              new StructuredDecodeError({
+                raw: typeof raw === "string" ? raw : JSON.stringify(raw),
+                issues: result.issues.map(issueToDecode),
+              }),
+            ),
+      ),
+    )
+
+/**
+ * Parse a JSON string then validate against the format's schema. Two
+ * failure modes: `JsonParseError` (bytes weren't JSON) and
+ * `StructuredDecodeError` (JSON didn't match the schema).
+ */
+export const parseJson =
+  <A>(format: StructuredFormat<A>) =>
+  (raw: string): Effect.Effect<A, JsonParseError | StructuredDecodeError> =>
+    pipe(
+      Effect.try({
+        try: () => JSON.parse(raw),
+        catch: (cause) => new JsonParseError({ raw, cause }),
+      }),
+      Effect.flatMap(decode(format)),
+    )
+
+/**
+ * Stream operator: each input string is JSON-parsed and validated.
+ * Failures surface in the stream's failure channel, distinguished by tag.
+ */
+export const decodeJsonLines =
+  <A>(format: StructuredFormat<A>) =>
+  <E, R>(
+    self: Stream.Stream<string, E, R>,
+  ): Stream.Stream<A, E | JsonParseError | StructuredDecodeError, R> =>
+    self.pipe(Stream.mapEffect(parseJson(format)))

package/src/testing/MockProvider.ts

@@ -0,0 +1,161 @@
+import { Duration, Effect, Layer, Ref, Schedule, Stream } from "effect"
+import * as AiError from "../domain/AiError.js"
+import type { Item } from "../domain/Items.js"
+import { LanguageModel, type LanguageModelService } from "../language-model/LanguageModel.js"
+import type { Turn, TurnEvent } from "../domain/Turn.js"
+
+export interface MockOptions {
+  /**
+   * If set, deltas of each scripted turn are spaced by this duration via
+   * `Schedule.spaced`. Combine with `TestClock.adjust` for deterministic
+   * timing in tests.
+   */
+  readonly deltaInterval?: Duration.Input
+}
+
+/**
+ * A scripted mock provider. Pre-canned `Turn` outputs are returned in order,
+ * one per call to `streamTurn`. Each scripted turn is split into synthetic
+ * deltas (text → tool_call_start → tool_call_args_delta → ... → turn_complete)
+ * so streaming consumers can see realistic delta shapes.
+ */
+export interface MockRecorder {
+  readonly calls: ReadonlyArray<{
+    readonly history: ReadonlyArray<Item>
+    readonly turn: Turn
+  }>
+}
+
+const turnToDeltas = (turn: Turn): ReadonlyArray<TurnEvent> => {
+  const deltas: TurnEvent[] = []
+  for (const item of turn.items) {
+    if (item.type === "message" && item.role === "assistant") {
+      for (const block of item.content) {
+        if (block.type === "output_text") {
+          deltas.push({ type: "text_delta", text: block.text })
+        }
+      }
+    } else if (item.type === "function_call") {
+      deltas.push({
+        type: "tool_call_start",
+        call_id: item.call_id,
+        name: item.name,
+      })
+      deltas.push({
+        type: "tool_call_args_delta",
+        call_id: item.call_id,
+        delta: item.arguments,
+      })
+    } else if (item.type === "reasoning" && item.summary !== undefined) {
+      deltas.push({ type: "reasoning_delta", text: item.summary, kind: "summary" })
+    }
+  }
+  deltas.push({ type: "turn_complete", turn })
+  return deltas
+}
+
+const pacedDeltas = (turn: Turn, options?: MockOptions): Stream.Stream<TurnEvent> => {
+  const base = Stream.fromIterable(turnToDeltas(turn))
+  return options?.deltaInterval === undefined
+    ? base
+    : base.pipe(Stream.schedule(Schedule.spaced(options.deltaInterval)))
+}
+
+const makeService = (
+  scriptedTurns: ReadonlyArray<Turn>,
+  options?: MockOptions,
+  recordCall?: (history: ReadonlyArray<Item>, turn: Turn) => Effect.Effect<void>,
+) =>
+  Effect.gen(function* () {
+    const cursor = yield* Ref.make(0)
+    return LanguageModel.of({
+      streamTurn: (request) =>
+        Stream.unwrap(
+          Effect.gen(function* () {
+            const i = yield* Ref.getAndUpdate(cursor, (n) => n + 1)
+            if (i >= scriptedTurns.length) {
+              return Stream.fail(
+                new AiError.InvalidRequest({
+                  provider: "mock",
+                  raw: `MockProvider exhausted: ${scriptedTurns.length} turns scripted, but call ${i + 1} was made`,
+                }),
+              )
+            }
+            const turn = scriptedTurns[i]!
+            if (recordCall !== undefined) {
+              yield* recordCall(request.history, turn)
+            }
+            return pacedDeltas(turn, options)
+          }),
+        ),
+    })
+  })
+
+export const layer = (
+  scriptedTurns: ReadonlyArray<Turn>,
+  options?: MockOptions,
+): Layer.Layer<LanguageModel> => Layer.effect(LanguageModel, makeService(scriptedTurns, options))
+
+/**
+ * Synchronous constructor that returns the `LanguageModelService` value
+ * directly, plus a recorder. Use this when you want to swap models
+ * mid-stream via `Effect.provideService` instead of providing one model
+ * for the whole program via `Layer`.
+ */
+export const make = (
+  scriptedTurns: ReadonlyArray<Turn>,
+  options?: MockOptions,
+): {
+  readonly service: LanguageModelService
+  readonly recorder: Effect.Effect<MockRecorder>
+} => {
+  const cursor = Ref.makeUnsafe(0)
+  const callsRef = Ref.makeUnsafe<ReadonlyArray<{ history: ReadonlyArray<Item>; turn: Turn }>>([])
+  const service: LanguageModelService = {
+    streamTurn: (request) =>
+      Stream.unwrap(
+        Effect.gen(function* () {
+          const i = yield* Ref.getAndUpdate(cursor, (n) => n + 1)
+          if (i >= scriptedTurns.length) {
+            return Stream.fail(
+              new AiError.InvalidRequest({
+                provider: "mock",
+                raw: `MockProvider exhausted: ${scriptedTurns.length} turns scripted, but call ${i + 1} was made`,
+              }),
+            )
+          }
+          const turn = scriptedTurns[i]!
+          yield* Ref.update(callsRef, (xs) => [...xs, { history: request.history, turn }])
+          return pacedDeltas(turn, options)
+        }),
+      ),
+  }
+  return {
+    service,
+    recorder: Ref.get(callsRef).pipe(Effect.map((calls) => ({ calls }))),
+  }
+}
+
+/**
+ * Same as `layer`, but also exposes a recorder that captures every call
+ * (history + returned turn).
+ */
+export const layerWithRecorder = (
+  scriptedTurns: ReadonlyArray<Turn>,
+  options?: MockOptions,
+): {
+  readonly layer: Layer.Layer<LanguageModel>
+  readonly recorder: Effect.Effect<MockRecorder>
+} => {
+  const callsRef = Ref.makeUnsafe<ReadonlyArray<{ history: ReadonlyArray<Item>; turn: Turn }>>([])
+  const live = Layer.effect(
+    LanguageModel,
+    makeService(scriptedTurns, options, (history, turn) =>
+      Ref.update(callsRef, (xs) => [...xs, { history, turn }]),
+    ),
+  )
+  return {
+    layer: live,
+    recorder: Ref.get(callsRef).pipe(Effect.map((calls) => ({ calls }))),
+  }
+}

package/src/tool/HistoryCheck.ts

@@ -0,0 +1,49 @@
+/**
+ * History-consistency primitives. Useful even WITHOUT HITL.
+ *
+ * Every provider rejects a new request if any prior `function_call` lacks
+ * a matching `function_call_output`. Multi-turn flows that can be
+ * interrupted, restarted, or branched (HITL, mid-stream abort, persisted
+ * checkpoints, stateless HTTP servers) need to detect orphans and
+ * synthesize closing outputs before submitting.
+ *
+ * Recipe author calls these at known transition points (right before the
+ * next provider request). Not invoked from inside the loop.
+ */
+import {
+  type FunctionCall,
+  type Item,
+  isFunctionCall,
+  isFunctionCallOutput,
+} from "../domain/Items.js"
+import { type ToolResult, cancelled } from "./Outcome.js"
+
+/**
+ * Return every `function_call` in `history` that does not have a matching
+ * `function_call_output` later in `history` (correlated by `call_id`).
+ * Empty result = history is provider-submittable from this invariant.
+ */
+export const findUnansweredCalls = (
+  history: ReadonlyArray<Item>,
+): ReadonlyArray<FunctionCall> => {
+  const answered = new Set(history.filter(isFunctionCallOutput).map((o) => o.call_id))
+  return history.filter(isFunctionCall).filter((c) => !answered.has(c.call_id))
+}
+
+/** Cheap predicate: is this history submittable to a provider? */
+export const isReconciled = (history: ReadonlyArray<Item>): boolean =>
+  findUnansweredCalls(history).length === 0
+
+/**
+ * Synthesize cancellation results for every unanswered call. Caller maps
+ * via `toFunctionCallOutput` and appends to history before submitting.
+ *
+ * Use when: a new user message arrives mid-approval; an approval timer
+ * fires; a persisted checkpoint contains orphans (crash recovery); a
+ * stateless HTTP server reconstructed history from a stale checkpoint.
+ */
+export const cancelAllPending = (
+  history: ReadonlyArray<Item>,
+  reason?: string,
+): ReadonlyArray<ToolResult> =>
+  findUnansweredCalls(history).map((call) => cancelled(call, reason))

package/src/tool/Outcome.ts

@@ -0,0 +1,101 @@
+/**
+ * Pre-execution decision (`ToolDecision`) and post-execution result
+ * (`ToolResult`) for the resolver-based executor.
+ *
+ *   - Resolver returns ToolDecision (Execute | Reject(result)) per call.
+ *   - Executor emits ToolResult (Value | Failure) per call.
+ *
+ * Wire conversion stays at the recipe boundary via `toFunctionCallOutput`
+ * so recipes can inspect, redact, or audit values before serialization.
+ *
+ * `output` and `reason` are `string`, not `unknown`: the wire wants strings,
+ * and `unknown` would invite non-serializable values (Date, Map, BigInt,
+ * fn). Recipes that want structured detail JSON.stringify themselves.
+ */
+import { Match } from "effect"
+import type { FunctionCall, FunctionCallOutput } from "../domain/Items.js"
+import { functionCallOutput } from "../domain/Items.js"
+
+// ---------------------------------------------------------------------------
+// ToolResult
+// ---------------------------------------------------------------------------
+
+export type ToolResult =
+  | {
+      readonly _tag: "Value"
+      readonly call_id: string
+      readonly tool: string
+      readonly value: unknown
+    }
+  | {
+      readonly _tag: "Failure"
+      readonly call_id: string
+      readonly tool: string
+      readonly kind: string
+      readonly reason?: string
+    }
+
+export const isValue = (r: ToolResult): r is Extract<ToolResult, { _tag: "Value" }> =>
+  r._tag === "Value"
+
+export const isFailure = (r: ToolResult): r is Extract<ToolResult, { _tag: "Failure" }> =>
+  r._tag === "Failure"
+
+// ---------------------------------------------------------------------------
+// ToolDecision
+// ---------------------------------------------------------------------------
+
+export type ToolDecision =
+  | { readonly _tag: "Execute" }
+  | { readonly _tag: "Reject"; readonly result: ToolResult }
+
+export const execute: ToolDecision = { _tag: "Execute" }
+
+export const reject = (result: ToolResult): ToolDecision => ({ _tag: "Reject", result })
+
+// ---------------------------------------------------------------------------
+// Synthesizers. `denied` and `cancelled` are operationally distinct;
+// anything else is just a recipe-chosen `kind` via `rejected`.
+// ---------------------------------------------------------------------------
+
+export const rejected = (
+  call: FunctionCall,
+  kind: string,
+  reason?: string,
+): ToolResult => ({
+  _tag: "Failure",
+  call_id: call.call_id,
+  tool: call.name,
+  kind,
+  ...(reason !== undefined ? { reason } : {}),
+})
+
+/** Explicit user/policy rejection. */
+export const denied = (call: FunctionCall, reason?: string): ToolResult =>
+  rejected(call, "denied", reason)
+
+/** Implicit non-answer (follow-up, inactivity, abort). */
+export const cancelled = (call: FunctionCall, reason?: string): ToolResult =>
+  rejected(call, "cancelled", reason)
+
+/** Tool's own execution failed (parse error, schema, runtime crash). */
+export const executionError = (call: FunctionCall, reason: string): ToolResult =>
+  rejected(call, "execution_error", reason)
+
+// ---------------------------------------------------------------------------
+// Wire conversion - the one place structured → string happens.
+// ---------------------------------------------------------------------------
+
+export const toFunctionCallOutput = (r: ToolResult): FunctionCallOutput =>
+  Match.value(r).pipe(
+    Match.tag("Value", (v) => functionCallOutput(v.call_id, JSON.stringify(v.value))),
+    Match.tag("Failure", (f) =>
+      functionCallOutput(
+        f.call_id,
+        JSON.stringify(
+          f.reason !== undefined ? { kind: f.kind, reason: f.reason } : { kind: f.kind },
+        ),
+      ),
+    ),
+    Match.exhaustive,
+  )