@effect-uai/ui 0.0.0-stage → 0.17.0

package/dist/Projection.mjs

@@ -0,0 +1,133 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { Effect, Match, Option, Schema, Stream } from "effect";
+import * as Turn from "@effect-uai/core/Turn";
+//#region src/Projection.ts
+var Projection_exports = /* @__PURE__ */ __exportAll({
+	Options: () => Options,
+	State: () => State,
+	initial: () => initial,
+	step: () => step,
+	toRunEvents: () => toRunEvents
+});
+const Options = Schema.Struct({
+	/**
+	* `"signal"` (default): only `reasoning-started`. `"summary"`: also
+	* forward summary deltas. `"full"`: also forward raw reasoning traces.
+	*/
+	reasoning: Schema.optionalKey(Schema.Literals([
+		"signal",
+		"summary",
+		"full"
+	])),
+	/** Forward raw tool-argument deltas (`tool-call-args-delta`). Default false. */
+	toolArgs: Schema.optionalKey(Schema.Boolean)
+});
+const State = Schema.Struct({
+	inStep: Schema.Boolean,
+	reasoningShown: Schema.Boolean,
+	/** Tool names by call id, for outputs that arrive as plain `function_call_output` items. */
+	tools: Schema.Record(Schema.String, Schema.String)
+});
+const initial = {
+	inStep: false,
+	reasoningShown: false,
+	tools: {}
+};
+const parseJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Json));
+const decodeJson = (raw) => Option.getOrElse(parseJson(raw), () => raw);
+const inStep = (s, events) => s.inStep ? [s, events] : [{
+	...s,
+	inStep: true,
+	reasoningShown: false
+}, [{ type: "step-started" }, ...events]];
+const reasoning = (options) => (s, e) => {
+	const mode = options?.reasoning ?? "signal";
+	const forward = mode === "full" || mode === "summary" && e.kind === "summary";
+	const [opened, prefix] = inStep(s, []);
+	const started = opened.reasoningShown ? [] : [{ type: "reasoning-started" }];
+	const delta = forward ? [{
+		type: "reasoning-delta",
+		text: e.text,
+		kind: e.kind
+	}] : [];
+	return [{
+		...opened,
+		reasoningShown: true
+	}, [
+		...prefix,
+		...started,
+		...delta
+	]];
+};
+const turnComplete = (s, turn) => {
+	const calls = Turn.getToolCalls(turn);
+	const ready = calls.map((call) => ({
+		type: "tool-call-ready",
+		callId: call.call_id,
+		name: call.name,
+		input: decodeJson(call.arguments)
+	}));
+	const [, events] = inStep(s, [...ready, {
+		type: "step-finished",
+		usage: turn.usage
+	}]);
+	const tools = {
+		...s.tools,
+		...Object.fromEntries(calls.map((c) => [c.call_id, c.name]))
+	};
+	return [{
+		...initial,
+		tools
+	}, events];
+};
+const outputResult = (config, s, o) => Effect.map(config.contract.toolOutput(o, s.tools[o.call_id] ?? ""), (event) => [s, [event]]);
+/** Map one loop event onto zero or more `RunEvent`s; tool values are encoded by the contract. */
+const step = (config) => (s, event) => Match.value(event).pipe(Match.when({ type: "function_call_output" }, (o) => outputResult(config, s, o)), Match.tags({
+	Partial: (e) => Effect.map(config.contract.toolEvent(e), (r) => [s, [r]]),
+	Output: (e) => Effect.map(config.contract.toolEvent(e), (r) => [s, [r]])
+}), Match.orElse((e) => Effect.succeed(turnStep(config)(s, e))));
+const turnStep = (options) => (s, event) => Match.value(event).pipe(Match.tagsExhaustive({
+	TextDelta: (e) => inStep(s, [{
+		type: "text-delta",
+		text: e.text
+	}]),
+	RefusalDelta: (e) => inStep(s, [{
+		type: "refusal-delta",
+		text: e.text
+	}]),
+	ReasoningDelta: (e) => reasoning(options)(s, e),
+	ToolCallStart: (e) => inStep(s, [{
+		type: "tool-call-started",
+		callId: e.call_id,
+		name: e.name
+	}]),
+	ToolCallArgsDelta: (e) => inStep(s, options?.toolArgs === true ? [{
+		type: "tool-call-args-delta",
+		callId: e.call_id,
+		delta: e.delta
+	}] : []),
+	CitationAdded: (e) => inStep(s, [{
+		type: "citation",
+		annotation: e.annotation
+	}]),
+	ImageOutput: (e) => inStep(s, [e.partialIndex === void 0 ? {
+		type: "image",
+		image: e.image
+	} : {
+		type: "image",
+		image: e.image,
+		partialIndex: e.partialIndex
+	}]),
+	UsageUpdate: () => [s, []],
+	WebSearchCall: () => [s, []],
+	TurnComplete: (e) => turnComplete(s, e.turn)
+}));
+/**
+* Stream operator: project a loop's events onto `RunEvent`s. A tool value the
+* contract can't encode fails the stream: a contract violation, not data to show.
+*/
+const toRunEvents = (config) => (self) => self.pipe(Stream.mapAccumEffect(() => initial, step(config)));
+//#endregion
+export { Options, State, initial, step, Projection_exports as t, toRunEvents };
+
+//# sourceMappingURL=Projection.mjs.map

package/dist/Projection.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Projection.mjs","names":[],"sources":["../src/Projection.ts"],"sourcesContent":["/**\n * Project an effect-uai loop onto `RunEvent`s. The projection is a fold pair\n * (`initial`, `step`) because step boundaries need state; `toRunEvents` runs\n * it over a stream. To add app events (metrics, domain data), map them\n * yourself and delegate the rest to `step`.\n *\n * Never forwards `TurnComplete.turn` itself: it carries `providerData`\n * (encrypted reasoning, item ids) that must not reach a browser.\n */\nimport type * as Items from \"@effect-uai/core/Items\"\nimport type * as ToolEvent from \"@effect-uai/core/ToolEvent\"\nimport * as Turn from \"@effect-uai/core/Turn\"\nimport { Effect, Match, Option, Schema, Stream } from \"effect\"\nimport type { Json, RunEvent } from \"./RunEvent.js\"\nimport * as UiContract from \"./UiContract.js\"\n\n/** What an effect-uai loop emits: turn events, tool events, and plain tool outputs. */\nexport type Source = Turn.TurnEvent | ToolEvent.ToolEvent | Items.ToolCallOutput\n\nexport const Options = Schema.Struct({\n  /**\n   * `\"signal\"` (default): only `reasoning-started`. `\"summary\"`: also\n   * forward summary deltas. `\"full\"`: also forward raw reasoning traces.\n   */\n  reasoning: Schema.optionalKey(Schema.Literals([\"signal\", \"summary\", \"full\"])),\n  /** Forward raw tool-argument deltas (`tool-call-args-delta`). Default false. */\n  toolArgs: Schema.optionalKey(Schema.Boolean),\n})\nexport type Options = typeof Options.Type\n\n/** `Options` plus the contract whose tool schemas encode tool values and errors. */\nexport type Config = Options & {\n  readonly contract: Pick<UiContract.UiContract<any>, \"toolEvent\" | \"toolOutput\">\n}\n\nexport const State = Schema.Struct({\n  inStep: Schema.Boolean,\n  reasoningShown: Schema.Boolean,\n  /** Tool names by call id, for outputs that arrive as plain `function_call_output` items. */\n  tools: Schema.Record(Schema.String, Schema.String),\n})\nexport type State = typeof State.Type\n\nexport const initial: State = { inStep: false, reasoningShown: false, tools: {} }\n\ntype Step = readonly [State, ReadonlyArray<RunEvent>]\n\n// Tool arguments are a JSON string; hand the client the decoded value, falling\n// back to the raw string when it isn't JSON.\nconst parseJson = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Json))\nconst decodeJson = (raw: string): Json => Option.getOrElse(parseJson(raw), () => raw)\n\n// Content belongs to a step (one model turn); open one lazily on its first event.\nconst inStep = (s: State, events: ReadonlyArray<RunEvent>): Step =>\n  s.inStep\n    ? [s, events]\n    : [{ ...s, inStep: true, reasoningShown: false }, [{ type: \"step-started\" }, ...events]]\n\nconst reasoning =\n  (options: Options | undefined) =>\n  (s: State, e: Extract<Turn.TurnEvent, { _tag: \"ReasoningDelta\" }>): Step => {\n    const mode = options?.reasoning ?? \"signal\"\n    const forward = mode === \"full\" || (mode === \"summary\" && e.kind === \"summary\")\n    const [opened, prefix] = inStep(s, [])\n    const started: ReadonlyArray<RunEvent> = opened.reasoningShown\n      ? []\n      : [{ type: \"reasoning-started\" }]\n    const delta: ReadonlyArray<RunEvent> = forward\n      ? [{ type: \"reasoning-delta\", text: e.text, kind: e.kind }]\n      : []\n    return [{ ...opened, reasoningShown: true }, [...prefix, ...started, ...delta]]\n  }\n\nconst turnComplete = (s: State, turn: Turn.Turn): Step => {\n  const calls = Turn.getToolCalls(turn)\n  const ready = calls.map((call): RunEvent => ({\n    type: \"tool-call-ready\",\n    callId: call.call_id,\n    name: call.name,\n    input: decodeJson(call.arguments),\n  }))\n  const [, events] = inStep(s, [...ready, { type: \"step-finished\", usage: turn.usage }])\n  const tools = { ...s.tools, ...Object.fromEntries(calls.map((c) => [c.call_id, c.name])) }\n  return [{ ...initial, tools }, events]\n}\n\n// A history item already holds the encoded value; the contract shapes it for the wire.\nconst outputResult = (config: Config, s: State, o: Items.ToolCallOutput) =>\n  Effect.map(config.contract.toolOutput(o, s.tools[o.call_id] ?? \"\"), (event): Step => [s, [event]])\n\n/** Map one loop event onto zero or more `RunEvent`s; tool values are encoded by the contract. */\nexport const step =\n  (config: Config) =>\n  (s: State, event: Source): Effect.Effect<Step, Schema.SchemaError> =>\n    Match.value(event).pipe(\n      Match.when({ type: \"function_call_output\" }, (o) => outputResult(config, s, o)),\n      Match.tags({\n        Partial: (e) => Effect.map(config.contract.toolEvent(e), (r): Step => [s, [r]]),\n        Output: (e) => Effect.map(config.contract.toolEvent(e), (r): Step => [s, [r]]),\n      }),\n      Match.orElse((e) => Effect.succeed(turnStep(config)(s, e))),\n    )\n\nconst turnStep =\n  (options: Options) =>\n  (s: State, event: Turn.TurnEvent): Step =>\n    Match.value(event).pipe(\n      Match.tagsExhaustive({\n        TextDelta: (e) => inStep(s, [{ type: \"text-delta\", text: e.text }]),\n        RefusalDelta: (e) => inStep(s, [{ type: \"refusal-delta\", text: e.text }]),\n        ReasoningDelta: (e) => reasoning(options)(s, e),\n        ToolCallStart: (e) =>\n          inStep(s, [{ type: \"tool-call-started\", callId: e.call_id, name: e.name }]),\n        ToolCallArgsDelta: (e) =>\n          inStep(\n            s,\n            options?.toolArgs === true\n              ? [{ type: \"tool-call-args-delta\", callId: e.call_id, delta: e.delta }]\n              : [],\n          ),\n        CitationAdded: (e) => inStep(s, [{ type: \"citation\", annotation: e.annotation }]),\n        ImageOutput: (e) =>\n          inStep(s, [\n            e.partialIndex === undefined\n              ? { type: \"image\", image: e.image }\n              : { type: \"image\", image: e.image, partialIndex: e.partialIndex },\n          ]),\n        // Usage arrives on `step-finished`; search progress has no UI event yet.\n        UsageUpdate: (): Step => [s, []],\n        WebSearchCall: (): Step => [s, []],\n        TurnComplete: (e) => turnComplete(s, e.turn),\n      }),\n    )\n\n/**\n * Stream operator: project a loop's events onto `RunEvent`s. A tool value the\n * contract can't encode fails the stream: a contract violation, not data to show.\n */\nexport const toRunEvents =\n  (config: Config) =>\n  <E, R>(self: Stream.Stream<Source, E, R>): Stream.Stream<RunEvent, E | Schema.SchemaError, R> =>\n    self.pipe(Stream.mapAccumEffect(() => initial, step(config)))\n"],"mappings":"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"}

package/dist/Run.d.mts

@@ -0,0 +1,44 @@
+import { Envelope, InputId, RunEvent, RunId, StreamId } from "./RunEvent.mjs";
+import { Cause, Effect, Schema, Stream } from "effect";
+import * as Duration from "effect/Duration";
+declare namespace Run_d_exports {
+  export { SequenceState, StartOptions, coalesce, complete, failed, sequence, start, stopWhen };
+}
+type StartOptions = {
+  readonly runId: RunId;
+  /** Client input ids the run answers. */
+  readonly inputs?: ReadonlyArray<InputId>;
+  /** Role label when a stream carries several kinds of run. */
+  readonly name?: string;
+};
+/** Prepend `run-started`. */
+declare const start: (options: StartOptions) => <E, R>(self: Stream.Stream<RunEvent, E, R>) => Stream.Stream<RunEvent, E, R>;
+/** End the run at its first terminal; append `run-completed` if it ends without one. */
+declare const complete: <E, R>(self: Stream.Stream<RunEvent, E, R>) => Stream.Stream<RunEvent, E, R>;
+/** End the run with `run-stopped` when `signal` completes (e.g. a stop `Deferred`). */
+declare const stopWhen: (signal: Effect.Effect<void>) => <E, R>(self: Stream.Stream<RunEvent, E, R>) => Stream.Stream<RunEvent, E, R>;
+/** A `run-failed` for a failed stream: `reason` is the error's `_tag`, else `"internal"`. */
+declare const failed: (cause: Cause.Cause<unknown>) => RunEvent;
+declare const SequenceState: Schema.Struct<{
+  readonly seq: Schema.Int;
+  /** Id of the run currently open on this stream. */
+  readonly runId: Schema.optionalKey<Schema.brand<Schema.String, "RunId">>;
+}>;
+type SequenceState = typeof SequenceState.Type;
+/**
+ * Wrap events in envelopes with a per-stream `seq` (starting after `from`,
+ * default 0) and the current run's id, taken from the last `run-started`.
+ */
+declare const sequence: (streamId: StreamId, options?: {
+  readonly from?: number;
+}) => <E, R>(self: Stream.Stream<RunEvent, E, R>) => Stream.Stream<Envelope, E, R>;
+/**
+ * Merge consecutive text, reasoning and tool-argument deltas that arrive
+ * within `window`; every other event passes through unchanged and in order.
+ * Bounds frames on the wire and rows in a durable log; adds up to `window`
+ * latency.
+ */
+declare const coalesce: (window: Duration.Input) => <E, R>(self: Stream.Stream<RunEvent, E, R>) => Stream.Stream<RunEvent, E, R>;
+//#endregion
+export { SequenceState, StartOptions, coalesce, complete, failed, sequence, start, stopWhen, Run_d_exports as t };
+//# sourceMappingURL=Run.d.mts.map

package/dist/Run.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Run.d.mts","names":[],"sources":["../src/Run.ts"],"mappings":";;;;;;KAmCY;WACD,OAAO;;WAEP,SAAS,cAAc;;WAEvB;;;cAIE,QAAK,SACN,kBACT,GAAG,GAAC,MAAQ,OAAO,OAAO,UAAU,GAAG,OAAK,OAAO,OAAO,UAAU,GAAG;;cAY7D,WAAY,GAAG,GAAC,MACrB,OAAO,OAAO,UAAU,GAAG,OAChC,OAAO,OAAO,UAAU,GAAG;;cAcjB,WAAQ,QACV,OAAO,kBACf,GAAG,GAAC,MAAQ,OAAO,OAAO,UAAU,GAAG,OAAK,OAAO,OAAO,UAAU,GAAG;;cAS7D,SAAM,OAAW,MAAM,mBAAiB;cAWxC,eAAa,OAAA;;;;;KAKd,uBAAuB,cAAc;;;;;cAiBpC,WAAQ,UACR,UAAQ;WAAuB;OACzC,GAAG,GAAC,MAAQ,OAAO,OAAO,UAAU,GAAG,OAAK,OAAO,OAAO,UAAU,GAAG;;;;;;;cAuC7D,WAAQ,QACV,SAAS,WACjB,GAAG,GAAC,MAAQ,OAAO,OAAO,UAAU,GAAG,OAAK,OAAO,OAAO,UAAU,GAAG"}

package/dist/Run.mjs

@@ -0,0 +1,117 @@
+import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
+import { RunId, isTerminal } from "./RunEvent.mjs";
+import { Array, Cause, Effect, Predicate, Schema, Stream } from "effect";
+//#region src/Run.ts
+/**
+* Server-side stream operators for runs. Each does one thing; a run pipes
+* the ones it needs:
+*
+*   agent(history).pipe(
+*     Projection.toRunEvents({ contract }),
+*     Run.coalesce("30 millis"),
+*     Stream.catchCause((cause) => Stream.succeed(Run.failed(cause))),
+*     Run.stopWhen(Deferred.await(stop)), // durable runs
+*     Run.start({ runId, inputs }),
+*     Run.complete,
+*     Run.sequence(streamId),
+*   )
+*
+* In this order they keep the protocol's rule: `run-started` first, exactly
+* one terminal last. Direct mode needs no stop: when the client goes away,
+* the server interrupts the stream (Effect's `HttpServer`, or
+* `HttpRouter.toWebHandler` behind a framework's route).
+*/
+var Run_exports = /* @__PURE__ */ __exportAll({
+	SequenceState: () => SequenceState,
+	coalesce: () => coalesce,
+	complete: () => complete,
+	failed: () => failed,
+	sequence: () => sequence,
+	start: () => start,
+	stopWhen: () => stopWhen
+});
+/** Prepend `run-started`. */
+const start = (options) => (self) => {
+	const started = {
+		type: "run-started",
+		runId: options.runId,
+		inputs: options.inputs ?? [],
+		protocol: 2,
+		...options.name !== void 0 ? { name: options.name } : {}
+	};
+	return Stream.make(started).pipe(Stream.concat(self));
+};
+/** End the run at its first terminal; append `run-completed` if it ends without one. */
+const complete = (self) => self.pipe(Stream.takeUntil(isTerminal), Stream.mapAccum(() => false, (ended, event) => [ended || isTerminal(event), [event]], { onHalt: (ended) => ended ? [] : [{ type: "run-completed" }] }));
+/** End the run with `run-stopped` when `signal` completes (e.g. a stop `Deferred`). */
+const stopWhen = (signal) => (self) => self.pipe(Stream.merge(Stream.fromEffect(Effect.as(signal, { type: "run-stopped" })), { haltStrategy: "left" }), Stream.takeUntil((event) => event.type === "run-stopped"));
+/** A `run-failed` for a failed stream: `reason` is the error's `_tag`, else `"internal"`. */
+const failed = (cause) => {
+	const error = Cause.squash(cause);
+	return {
+		type: "run-failed",
+		reason: Predicate.hasProperty(error, "_tag") && Predicate.isString(error._tag) ? error._tag : "internal"
+	};
+};
+const SequenceState = Schema.Struct({
+	seq: Schema.Int,
+	/** Id of the run currently open on this stream. */
+	runId: Schema.optionalKey(RunId)
+});
+const sequenceStep = (streamId) => (s, event) => {
+	const runId = event.type === "run-started" ? event.runId : s.runId;
+	const seq = s.seq + 1;
+	const envelope = runId === void 0 ? {
+		streamId,
+		seq,
+		event
+	} : {
+		streamId,
+		seq,
+		runId,
+		event
+	};
+	return [runId === void 0 || isTerminal(event) ? { seq } : {
+		seq,
+		runId
+	}, [envelope]];
+};
+/**
+* Wrap events in envelopes with a per-stream `seq` (starting after `from`,
+* default 0) and the current run's id, taken from the last `run-started`.
+*/
+const sequence = (streamId, options) => (self) => self.pipe(Stream.mapAccum(() => ({ seq: options?.from ?? 0 }), sequenceStep(streamId)));
+const merge = (a, b) => {
+	if (a.type === "text-delta" && b.type === "text-delta") return {
+		...a,
+		text: a.text + b.text
+	};
+	if (a.type === "refusal-delta" && b.type === "refusal-delta") return {
+		...a,
+		text: a.text + b.text
+	};
+	if (a.type === "reasoning-delta" && b.type === "reasoning-delta" && a.kind === b.kind) return {
+		...a,
+		text: a.text + b.text
+	};
+	if (a.type === "tool-call-args-delta" && b.type === "tool-call-args-delta" && a.callId === b.callId) return {
+		...a,
+		delta: a.delta + b.delta
+	};
+};
+const mergeAdjacent = (group) => Array.reduce(group, Array.empty(), (acc, event) => {
+	const last = acc.at(-1);
+	const merged = last === void 0 ? void 0 : merge(last, event);
+	return merged === void 0 ? [...acc, event] : [...acc.slice(0, -1), merged];
+});
+/**
+* Merge consecutive text, reasoning and tool-argument deltas that arrive
+* within `window`; every other event passes through unchanged and in order.
+* Bounds frames on the wire and rows in a durable log; adds up to `window`
+* latency.
+*/
+const coalesce = (window) => (self) => self.pipe(Stream.groupedWithin(1024, window), Stream.flatMap((group) => Stream.fromIterable(mergeAdjacent(group))));
+//#endregion
+export { SequenceState, coalesce, complete, failed, sequence, start, stopWhen, Run_exports as t };
+
+//# sourceMappingURL=Run.mjs.map

package/dist/Run.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"Run.mjs","names":["Arr"],"sources":["../src/Run.ts"],"sourcesContent":["/**\n * Server-side stream operators for runs. Each does one thing; a run pipes\n * the ones it needs:\n *\n *   agent(history).pipe(\n *     Projection.toRunEvents({ contract }),\n *     Run.coalesce(\"30 millis\"),\n *     Stream.catchCause((cause) => Stream.succeed(Run.failed(cause))),\n *     Run.stopWhen(Deferred.await(stop)), // durable runs\n *     Run.start({ runId, inputs }),\n *     Run.complete,\n *     Run.sequence(streamId),\n *   )\n *\n * In this order they keep the protocol's rule: `run-started` first, exactly\n * one terminal last. Direct mode needs no stop: when the client goes away,\n * the server interrupts the stream (Effect's `HttpServer`, or\n * `HttpRouter.toWebHandler` behind a framework's route).\n */\nimport { Array as Arr, Cause, Effect, Predicate, Schema, Stream } from \"effect\"\nimport type * as Duration from \"effect/Duration\"\nimport {\n  type Envelope,\n  type InputId,\n  isTerminal,\n  PROTOCOL_VERSION,\n  RunId,\n  type RunEvent,\n  type StreamId,\n} from \"./RunEvent.js\"\n\n// ---------------------------------------------------------------------------\n// A run's frame: start, stop, failure, completion\n// ---------------------------------------------------------------------------\n\nexport type StartOptions = {\n  readonly runId: RunId\n  /** Client input ids the run answers. */\n  readonly inputs?: ReadonlyArray<InputId>\n  /** Role label when a stream carries several kinds of run. */\n  readonly name?: string\n}\n\n/** Prepend `run-started`. */\nexport const start =\n  (options: StartOptions) =>\n  <E, R>(self: Stream.Stream<RunEvent, E, R>): Stream.Stream<RunEvent, E, R> => {\n    const started: RunEvent = {\n      type: \"run-started\",\n      runId: options.runId,\n      inputs: options.inputs ?? [],\n      protocol: PROTOCOL_VERSION,\n      ...(options.name !== undefined ? { name: options.name } : {}),\n    }\n    return Stream.make(started).pipe(Stream.concat(self))\n  }\n\n/** End the run at its first terminal; append `run-completed` if it ends without one. */\nexport const complete = <E, R>(\n  self: Stream.Stream<RunEvent, E, R>,\n): Stream.Stream<RunEvent, E, R> =>\n  self.pipe(\n    Stream.takeUntil(isTerminal),\n    Stream.mapAccum(\n      () => false,\n      (ended, event): readonly [boolean, ReadonlyArray<RunEvent>] => [\n        ended || isTerminal(event),\n        [event],\n      ],\n      { onHalt: (ended): ReadonlyArray<RunEvent> => (ended ? [] : [{ type: \"run-completed\" }]) },\n    ),\n  )\n\n/** End the run with `run-stopped` when `signal` completes (e.g. a stop `Deferred`). */\nexport const stopWhen =\n  (signal: Effect.Effect<void>) =>\n  <E, R>(self: Stream.Stream<RunEvent, E, R>): Stream.Stream<RunEvent, E, R> =>\n    self.pipe(\n      Stream.merge(Stream.fromEffect(Effect.as(signal, { type: \"run-stopped\" } as const)), {\n        haltStrategy: \"left\",\n      }),\n      Stream.takeUntil((event) => event.type === \"run-stopped\"),\n    )\n\n/** A `run-failed` for a failed stream: `reason` is the error's `_tag`, else `\"internal\"`. */\nexport const failed = (cause: Cause.Cause<unknown>): RunEvent => {\n  const error = Cause.squash(cause)\n  const reason =\n    Predicate.hasProperty(error, \"_tag\") && Predicate.isString(error._tag) ? error._tag : \"internal\"\n  return { type: \"run-failed\", reason }\n}\n\n// ---------------------------------------------------------------------------\n// sequence\n// ---------------------------------------------------------------------------\n\nexport const SequenceState = Schema.Struct({\n  seq: Schema.Int,\n  /** Id of the run currently open on this stream. */\n  runId: Schema.optionalKey(RunId),\n})\nexport type SequenceState = typeof SequenceState.Type\n\nconst sequenceStep =\n  (streamId: StreamId) =>\n  (s: SequenceState, event: RunEvent): readonly [SequenceState, ReadonlyArray<Envelope>] => {\n    const runId = event.type === \"run-started\" ? event.runId : s.runId\n    const seq = s.seq + 1\n    const envelope: Envelope =\n      runId === undefined ? { streamId, seq, event } : { streamId, seq, runId, event }\n    const next: SequenceState = runId === undefined || isTerminal(event) ? { seq } : { seq, runId }\n    return [next, [envelope]]\n  }\n\n/**\n * Wrap events in envelopes with a per-stream `seq` (starting after `from`,\n * default 0) and the current run's id, taken from the last `run-started`.\n */\nexport const sequence =\n  (streamId: StreamId, options?: { readonly from?: number }) =>\n  <E, R>(self: Stream.Stream<RunEvent, E, R>): Stream.Stream<Envelope, E, R> =>\n    self.pipe(\n      Stream.mapAccum((): SequenceState => ({ seq: options?.from ?? 0 }), sequenceStep(streamId)),\n    )\n\n// ---------------------------------------------------------------------------\n// coalesce\n// ---------------------------------------------------------------------------\n\nconst merge = (a: RunEvent, b: RunEvent): RunEvent | undefined => {\n  if (a.type === \"text-delta\" && b.type === \"text-delta\") return { ...a, text: a.text + b.text }\n  if (a.type === \"refusal-delta\" && b.type === \"refusal-delta\")\n    return { ...a, text: a.text + b.text }\n  if (a.type === \"reasoning-delta\" && b.type === \"reasoning-delta\" && a.kind === b.kind) {\n    return { ...a, text: a.text + b.text }\n  }\n  if (\n    a.type === \"tool-call-args-delta\" &&\n    b.type === \"tool-call-args-delta\" &&\n    a.callId === b.callId\n  ) {\n    return { ...a, delta: a.delta + b.delta }\n  }\n  return undefined\n}\n\nconst mergeAdjacent = (group: ReadonlyArray<RunEvent>): ReadonlyArray<RunEvent> =>\n  Arr.reduce(group, Arr.empty<RunEvent>(), (acc: ReadonlyArray<RunEvent>, event) => {\n    const last = acc.at(-1)\n    const merged = last === undefined ? undefined : merge(last, event)\n    return merged === undefined ? [...acc, event] : [...acc.slice(0, -1), merged]\n  })\n\n/**\n * Merge consecutive text, reasoning and tool-argument deltas that arrive\n * within `window`; every other event passes through unchanged and in order.\n * Bounds frames on the wire and rows in a durable log; adds up to `window`\n * latency.\n */\nexport const coalesce =\n  (window: Duration.Input) =>\n  <E, R>(self: Stream.Stream<RunEvent, E, R>): Stream.Stream<RunEvent, E, R> =>\n    self.pipe(\n      Stream.groupedWithin(1024, window),\n      Stream.flatMap((group) => Stream.fromIterable(mergeAdjacent(group))),\n    )\n"],"mappings":"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"}