@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/dist/ActionRpc.mjs

@@ -1,37 +1,90 @@
 import { Anyone } from "./contract/caller.mjs";
-import { bindingErrors, bindingOf } from "./contract/declared.mjs";
-import { acquire, provideHandlers, servingOf } from "./contract/implementation.mjs";
+import { InvalidInput, Unauthenticated } from "./contract/errors.mjs";
+import { bindingErrors, bindingOf, eventErrors } from "./contract/declared.mjs";
+import { reservedList, reservedNames } from "./contract/names.mjs";
+import { Progressed, answerFrom, elementsFrom } from "./contract/progress.mjs";
+import { elementOf } from "./contract/stream.mjs";
+import { acquire, elementsOf } from "./contract/implementation.mjs";
+import { checked, checkedStream, decodeInput, inputParseOptions, sendingJson, watchInput } from "./contract/call.mjs";
+import { concealed } from "./contract/reported.mjs";
+import { acquireFeeds } from "./contract/feed.mjs";
+import { PushedOf, Subscription, SubscriptionOf, queuedPush } from "./contract/push.mjs";
 import { providerOf } from "./authentication/provider.mjs";
-import { checked, decodeInput } from "./contract/call.mjs";
-import { Cause, Effect, ErrorReporter, Layer, Predicate, Result, Schema, SchemaTransformation } from "effect";
+import { listed } from "./contract/listed.mjs";
+import { provideServed, servingOf } from "./contract/serving.mjs";
+import { watching } from "./contract/watch.mjs";
+import { transportOf } from "./rpc/watch.mjs";
+import { Cause, Effect, ErrorReporter, Layer, Match, Option, Predicate, Queue, Result, Schedule, Schema, SchemaTransformation, Stream } from "effect";
 import { HttpClientRequest, HttpServerRequest } from "effect/http";
 import { HttpApiBuilder } from "effect/http-api";
-import { Rpc, RpcClient, RpcGroup, RpcSerialization, RpcServer } from "effect/rpc";
-//#region src/rpc/ActionRpc.ts
-function make(actions, options = {}) {
-	const bound = bindingOf("ActionRpc binding", actions, options);
-	const group = RpcGroup.make(...actions.map((action) => Rpc.make(action.name, {
+import { Rpc, RpcClient, RpcGroup, RpcMiddleware, RpcSchema, RpcServer } from "effect/rpc";
+// src/rpc/ActionRpc.ts
+/**
+* What the stream rpc of an action declaring `progress` sends: a `Progress` for each value its
+* handler reports, then a `Final` with its answer.
+*/
+const ProgressedOf = (progress, success) => Schema.Union([Schema.TaggedStruct("Progress", { value: progress }), Schema.TaggedStruct("Final", { value: success })]);
+const elementedOf = (element, progress) => Schema.Union([Schema.TaggedStruct("Element", { value: element }), ...progress === void 0 ? [] : [Schema.TaggedStruct("Progress", { value: progress })]]);
+/** Whether `action`'s rpc is a stream rpc: it answers a stream, or declares `progress`. */
+const streams = (action) => action.progress !== void 0 || elementOf(action.success) !== void 0;
+/** What `action`'s rpc answers, or each element it streams where it is a stream rpc. */
+const sentOf = (action) => {
+	const element = elementOf(action.success);
+	if (element !== void 0) return elementedOf(element, action.progress);
+	return action.progress === void 0 ? action.success : ProgressedOf(action.progress, action.success);
+};
+const authenticatedKey = "effect-actions/ActionRpc/Authenticated";
+const nativeOf = (group) => group;
+const authenticatedOf = (authentication) => RpcMiddleware.Service()(authenticatedKey, { error: Schema.Union([Unauthenticated, ...authentication.error]) });
+/** The middleware authenticating `rpc`, wherever among its middleware it runs. */
+const authenticatedIn = (rpc) => [...rpc.middlewares].find(({ key }) => key === authenticatedKey);
+function make(contracts, options = {}) {
+	const { actions, events } = listed(contracts);
+	const bound = bindingOf("ActionRpc binding", actions, events, options);
+	const rpcOf = (action) => Rpc.make(action.name, {
 		payload: action.input,
-		success: action.success,
-		error: Schema.Union(bindingErrors(action, bound))
-	})));
+		success: sentOf(action),
+		error: Schema.Union(bindingErrors(action, bound)),
+		stream: streams(action)
+	});
+	const given = options.rpcs === void 0 ? RpcGroup.make() : nativeOf(options.rpcs);
+	for (const tag of given.requests.keys()) if (reservedNames.includes(tag) || contracts.some((contract) => contract.name === tag)) throw new Error(`ActionRpc binding: the rpc "${tag}" of rpcs is named after an action, an event type or a name the client keeps, ${reservedList} (rename it)`);
+	const rpcs = bound.authentication === void 0 ? given : given.middleware(authenticatedOf(bound.authentication));
+	const group = RpcGroup.make(...actions.map(rpcOf), ...events.map((event) => Rpc.make(event.name, {
+		payload: SubscriptionOf(event),
+		success: PushedOf(event),
+		error: Schema.Union(eventErrors(event, bound)),
+		stream: true
+	}))).merge(rpcs);
 	return {
 		actions,
+		events,
 		...bound,
+		rpcs,
 		group
 	};
 }
-const credentialFromRpcHeaders = (security, headers) => HttpApiBuilder.securityDecode(security).pipe(Effect.provideService(HttpServerRequest.HttpServerRequest, HttpServerRequest.fromClientRequest(HttpClientRequest.get("/", { headers }))), Effect.provideService(HttpServerRequest.ParsedSearchParams, {}));
-const authenticationStepOf = (authentication) => Effect.map(providerOf(authentication), (provider) => (effect, { headers }) => credentialFromRpcHeaders(authentication.security, headers).pipe(Effect.flatMap(provider.authenticate), Effect.flatMap((actor) => Effect.provideService(effect, authentication.identity, actor))));
-var InternalError = class extends Error {
-	[ErrorReporter.ignore] = true;
-	constructor() {
-		super("Internal server error");
+const withRequestOf = (headers) => (effect) => effect.pipe(Effect.provideService(HttpServerRequest.HttpServerRequest, HttpServerRequest.fromClientRequest(HttpClientRequest.get("/", { headers }))), Effect.provideService(HttpServerRequest.ParsedSearchParams, {}));
+/** `call` inside `steps`, the first innermost, each given the call's options. */
+const throughSteps = (steps, call, options) => {
+	let wrapped = call;
+	for (const step of steps) {
+		const inner = wrapped;
+		wrapped = Effect.suspend(() => step(inner, options));
 	}
+	return wrapped;
 };
+/**
+* The step authenticating a call with `authentication`'s provider: the identity its verification
+* answers is provided to the call, the verification run as `verifying` runs it.
+*/
+const authenticatingOf = (authentication) => Effect.map(providerOf(authentication), (provider) => {
+	const verify = Effect.flatMap(HttpApiBuilder.securityDecode(authentication.security), provider.authenticate);
+	return (verifying) => (effect, options) => Effect.flatMap(verifying(verify, options), (actor) => Effect.provideService(effect, authentication.identity, actor));
+});
 var DeclaredFailure = class {
-	json;
 	[ErrorReporter.ignore] = true;
+	json;
 	constructor(json) {
 		this.json = json;
 	}
@@ -39,18 +92,32 @@ var DeclaredFailure = class {
 		return Predicate.isString(this.json) ? this.json : JSON.stringify(this.json);
 	}
 };
-const DeclaredFromJson = Schema.Json.pipe(Schema.decodeTo(Schema.instanceOf(DeclaredFailure), SchemaTransformation.transform({
+const asJson = () => Schema.link()(Schema.Json, SchemaTransformation.transform({
 	decode: (json) => new DeclaredFailure(json),
 	encode: (failure) => failure.json
-})));
+}));
+const Declared = Schema.instanceOf(DeclaredFailure, {
+	toCodecJson: asJson,
+	toCodecIso: asJson
+});
+const streamOf = (name) => Rpc.make(name, {
+	payload: Schema.Json,
+	success: Schema.Json,
+	error: Declared,
+	stream: true
+});
+const erasedOf = (actions, events) => RpcGroup.make(...actions.map((action) => streams(action) ? streamOf(action.name) : Rpc.make(action.name, {
+	payload: Schema.Json,
+	success: Schema.Json,
+	error: Declared
+})), ...events.map((event) => streamOf(event.name)));
 const callBoundaryOf = (error) => {
 	const encode = Schema.encodeUnknownEffect(Schema.toCodecJson(error));
-	const internal = (cause) => Effect.logError(cause).pipe(Effect.andThen(ErrorReporter.report(cause)), Effect.andThen(Effect.die(new InternalError())));
 	return (effect) => Effect.catchCause(effect, (cause) => {
-		if (Cause.hasDies(cause)) return internal(cause);
+		if (Cause.hasDies(cause)) return concealed(cause);
 		const failure = Cause.findFail(cause);
 		return Result.isSuccess(failure) ? encode(failure.success.error).pipe(Effect.matchCauseEffect({
-			onFailure: (unencoded) => internal(Cause.combine(cause, unencoded)),
+			onFailure: (unencoded) => concealed(Cause.combine(cause, unencoded)),
 			onSuccess: (encoded) => Effect.fail(new DeclaredFailure(encoded))
 		})) : Effect.failCause(cause);
 	});
@@ -61,42 +128,227 @@ const handlerOf = (action, run, steps, error) => {
 	const boundary = callBoundaryOf(error);
 	return (payload, options) => {
 		const call = Effect.suspend(() => decode(payload)).pipe(Effect.flatMap(run), Effect.flatMap(encode));
-		const wrapped = steps.reduce((inner, step) => Effect.suspend(() => step(inner, {
+		const wrapped = throughSteps(steps, call, {
+			...options,
+			payload
+		});
+		return boundary(wrapped);
+	};
+};
+/**
+* The handler of the stream rpc of an action declaring `progress` or answering a stream: its call
+* authenticates before its stream starts, then runs in the call's scope, what `sending` sends sent
+* one at a time, so a caller reading slowly holds up the call, whose progress then drops the
+* oldest values. A failure ends the stream as a call's ends it.
+*/
+const streamingHandlerOf = (action, sending, steps, error) => {
+	const decode = decodeInput(action);
+	const boundary = callBoundaryOf(error);
+	const encodeProgress = Schema.encodeUnknownEffect(Schema.toCodecJson(action.progress ?? Schema.Never));
+	return (payload, options) => {
+		const call = Effect.gen(function* () {
+			const input = yield* decode(payload);
+			const sent = yield* Queue.bounded(1);
+			const send = (each) => Effect.asVoid(Queue.offer(sent, each));
+			yield* sending(input, { progress: (value) => Effect.flatMap(Effect.orDie(encodeProgress(value)), (json) => send(Progressed.Progress({ value: json }))) }, send).pipe(boundary, Queue.into(sent), Effect.forkScoped({ startImmediately: true }));
+			return sent;
+		});
+		const wrapped = throughSteps(steps, call, {
+			...options,
+			payload
+		});
+		return boundary(wrapped);
+	};
+};
+/** Each value `run` reports sent as a `Progress`, then its answer as a `Final`. */
+const sendingAnswer = (success, run) => {
+	const encode = Schema.encodeUnknownEffect(Schema.toCodecJson(success));
+	return (input, reporting, send) => run(input, reporting).pipe(Effect.flatMap(encode), Effect.flatMap((value) => send(Progressed.Final({ value }))));
+};
+/** Each element of the stream `run` answers sent as an `Element`, beside its progress. */
+const sendingElements = (element, run) => {
+	const encode = Schema.encodeUnknownEffect(Schema.toCodecJson(element));
+	return (input, reporting, send) => Stream.runForEach(elementsOf(run(input, reporting)), (each) => Effect.flatMap(encode(each), (value) => send(Progressed.Element({ value }))));
+};
+/** The key a protocol sets to its `SubscriptionKeeper` on its `RpcServer.Protocol` service. */
+const subscriptionKeeper = Symbol.for("effect-actions/ActionRpc/subscriptionKeeper");
+const keeperOf = (protocol) => {
+	return Predicate.hasProperty(protocol, subscriptionKeeper) ? protocol[subscriptionKeeper] : void 0;
+};
+/**
+* The handler of one event type's stream rpc: the subscription's request authenticates and is
+* admitted before its stream starts, so a refusal fails the call; the feed is then read from the
+* call, in its scope, into a bounded queue, each element encoded, and read on through a source's
+* failure, before its first `Checked` too. A later refusal ends the stream as a declared failure.
+* Over a protocol with a `keeper`, the admitted subscription is kept, and every position sent.
+*/
+const subscriptionHandlerOf = (feed, steps, error, keeper) => {
+	const decode = Schema.decodeUnknownEffect(Subscription, inputParseOptions);
+	const decodeEventInput = decodeInput(feed.event);
+	const sent = Schema.toCodecJson(PushedOf(feed.event));
+	const encode = Schema.encodeEffect(sent);
+	const decodeSent = Schema.decodeUnknownOption(sent);
+	const boundary = callBoundaryOf(error);
+	return (payload, options) => {
+		const call = Effect.gen(function* () {
+			const { input, cursor } = yield* Effect.mapError(decode(payload), InvalidInput.fromSchemaError);
+			const open = yield* feed.stream(yield* decodeEventInput(input));
+			if (keeper === void 0) return yield* queuedPush(open, cursor, encode, { ending: boundary });
+			yield* keeper.keep({
+				clientId: options.client.id,
+				requestId: options.requestId,
+				tag: feed.event.name,
+				payload,
+				headers: Object.entries(options.headers),
+				resumeFrom: (values) => {
+					const reached = values.flatMap((value) => Option.toArray(decodeSent(value))).map((pushed) => Match.value(pushed).pipe(Match.tag("Failed", () => null), Match.orElse((positioned) => positioned.cursor))).findLast(Predicate.isNotNull);
+					return reached === void 0 ? void 0 : {
+						input,
+						cursor: reached
+					};
+				}
+			});
+			return yield* queuedPush(open, cursor, encode, {
+				ending: boundary,
+				inOrder: true
+			});
+		});
+		const wrapped = throughSteps(steps, call, {
 			...options,
 			payload
-		})), call);
+		});
 		return boundary(wrapped);
 	};
 };
+/**
+* The key a protocol answering each call once sets to `true` on its `RpcServer.Protocol`
+* service, as the Cloudflare package's stub protocol does, since Effect's protocol has no flag of
+* its own for it: `layer` refuses to serve a streaming action, an event type or a native stream
+* rpc on it, where a stream is answered with a defect at its first element and one with none
+* waits for good.
+*/
+const unaryProtocol = Symbol.for("effect-actions/ActionRpc/unary");
+const verifyingNative = (verify, { headers }) => withRequestOf(headers)(verify).pipe(Effect.catchCauseIf(Cause.hasDies, concealed));
+const requested = (effect, { headers }) => withRequestOf(headers)(effect);
+const isUnary = (protocol) => Predicate.hasProperty(protocol, unaryProtocol) && protocol[unaryProtocol] === true;
 function layer(binding, served, options = {}) {
-	const { apps, actions, authentication } = servingOf("RPC binding", binding, served, options);
+	const selected = servingOf("RPC binding", binding, served, options);
+	const { apps, actions, events, eventTypes } = selected;
 	const middleware = options.middleware ?? [];
-	const jsonGroup = RpcGroup.make(...actions.map((action) => Rpc.make(action.name, {
-		payload: Schema.Json,
-		success: Schema.Json,
-		error: DeclaredFromJson
-	})));
+	const jsonGroup = erasedOf(actions, eventTypes);
+	const natives = [...nativeOf(binding.rpcs).requests.values()];
+	const authentication = natives.length === 0 ? selected.authentication : binding.authentication;
 	const handlers = Layer.unwrap(Effect.gen(function* () {
-		const { codecFor } = yield* RpcServer.Protocol;
-		if (codecFor !== RpcSerialization.json.codecFor) return yield* Effect.die(/* @__PURE__ */ new Error("ActionRpc serves a protocol speaking JSON: RpcSerialization.layerJson, layerNdjson, layerJsonRpc or layerNdJsonRpc, not another codec, such as schema-binary's"));
+		const unauthenticated = authentication === void 0 ? void 0 : natives.find((rpc) => authenticatedIn(rpc) === void 0);
+		if (unauthenticated !== void 0) return yield* Effect.die(/* @__PURE__ */ new Error(`ActionRpc.layer: the native rpc ${unauthenticated._tag} of a protected binding runs without its authentication: add it to the group ActionRpc.make is given as its rpcs, not to the binding's rpcs after`));
+		const protocol = yield* RpcServer.Protocol;
+		const keeper = keeperOf(protocol);
+		if (isUnary(protocol)) {
+			const streamed = [...actions.filter(streams), ...eventTypes].map(({ name }) => name);
+			const nativeStreams = natives.flatMap((rpc) => RpcSchema.isStreamSchema(rpc.successSchema) ? [rpc._tag] : []);
+			if (streamed.length + nativeStreams.length > 0) return yield* Effect.die(/* @__PURE__ */ new Error(`ActionRpc.layer serves a protocol answering each call once, and ${[...streamed, ...nativeStreams].join(", ")} stream: serve them over a socket or HTTP, and on this protocol the others, ${nativeStreams.length > 0 ? "from a binding whose rpcs do not stream, " : ""}listed in actions`));
+		}
 		const listedMiddleware = yield* Effect.forEach(middleware, (key) => Effect.service(key));
-		const authenticate = authentication === void 0 ? void 0 : yield* authenticationStepOf(authentication);
-		const bound = yield* acquire(apps);
-		const byName = Object.fromEntries(bound.map(([action, run]) => [action.name, handlerOf(action, run, action.caller === Anyone || authenticate === void 0 ? listedMiddleware : [...listedMiddleware, authenticate], Schema.Union(bindingErrors(action, binding)))]));
-		return jsonGroup.toLayer(byName);
-	})).pipe(provideHandlers(apps));
-	return RpcServer.layer(jsonGroup, { disableFatalDefects: true }).pipe(Layer.provide(handlers));
+		const authenticating = authentication === void 0 ? void 0 : yield* authenticatingOf(authentication);
+		const bound = yield* acquire(apps, authentication);
+		const feeds = yield* acquireFeeds(events);
+		const stepsOf = (caller) => caller === Anyone || authenticating === void 0 ? [...listedMiddleware, requested] : [
+			...listedMiddleware,
+			authenticating((verify) => verify),
+			requested
+		];
+		const handlerFor = (action, run, steps, error) => {
+			const element = elementOf(action.success);
+			if (element !== void 0) return streamingHandlerOf(action, sendingElements(element, run), steps, error);
+			return action.progress === void 0 ? handlerOf(action, run, steps, error) : streamingHandlerOf(action, sendingAnswer(action.success, run), steps, error);
+		};
+		const byName = {
+			...Object.fromEntries(bound.map(([action, run]) => [action.name, handlerFor(action, run, stepsOf(action.caller), Schema.Union(bindingErrors(action, binding)))])),
+			...Object.fromEntries(feeds.map((feed) => [feed.event.name, subscriptionHandlerOf(feed, stepsOf(feed.event.caller), Schema.Union(eventErrors(feed.event, binding)), keeper)]))
+		};
+		const servedActions = jsonGroup.toLayer(byName);
+		const authenticated = natives.map(authenticatedIn).find(Predicate.isNotUndefined);
+		if (authenticated === void 0 || authenticating === void 0) return servedActions;
+		const authenticate = authenticating(verifyingNative);
+		return Layer.merge(servedActions, Layer.succeed(authenticated)(authenticate));
+	})).pipe(provideServed(selected));
+	return RpcServer.layer(jsonGroup.merge(binding.rpcs), { disableFatalDefects: true }).pipe(Layer.provide(handlers));
 }
+const isDeclared = (failure) => failure instanceof DeclaredFailure;
+/** Fail with the declared failure a wrapper holds, decoded by `error`, or die where it does not. */
+const failedOf = (error) => {
+	const decode = Schema.decodeUnknownEffect(Schema.toCodecJson(error));
+	return (failure) => Effect.flatMap(Effect.orDie(decode(failure.json)), Effect.fail);
+};
+/**
+* A client's method of `action`, calling `method`, its rpc of `erasedOf`, with its input's JSON:
+* what the server sends, its answer or each element it streams, and its declared failure, decoded
+* by the action's schemas; one that does not decode is a defect, as the native client makes it.
+*/
+const actionMethodOf = (action, binding, method) => {
+	const decode = Schema.decodeUnknownEffect(Schema.toCodecJson(sentOf(action)));
+	const failed = failedOf(Schema.Union(bindingErrors(action, binding)));
+	const sent = (json) => Effect.orDie(decode(json));
+	if (!streams(action)) {
+		const call = method;
+		return checked(action, sendingJson, (json) => call(json).pipe(Effect.catchIf(isDeclared, failed), Effect.flatMap(sent)));
+	}
+	const call = method;
+	const progressed = (json) => call(json).pipe(Stream.catchIf(isDeclared, (failure) => Stream.fromEffect(failed(failure))), Stream.mapEffect(sent));
+	return elementOf(action.success) === void 0 ? checked(action, sendingJson, (json, onProgress) => answerFrom(progressed(json), onProgress)) : checkedStream(action, sendingJson, (json, onProgress) => elementsFrom(progressed(json), onProgress));
+};
+/**
+* A client's subscription to `event`, calling `method`, its stream rpc of `erasedOf`, with its
+* input's JSON and the cursor it resumes from: what the server sends, and its declared failure,
+* decoded by the event's schemas; one that does not decode is a defect, as for an action.
+*/
+const eventMethodOf = (event, binding, method) => {
+	const decode = Schema.decodeUnknownEffect(Schema.toCodecJson(PushedOf(event)));
+	const failed = failedOf(Schema.Union(eventErrors(event, binding)));
+	const call = method;
+	return (input) => (cursor) => call({
+		input,
+		cursor
+	}).pipe(Stream.catchIf(isDeclared, (failure) => Stream.fromEffect(failed(failure))), Stream.mapEffect((json) => Effect.orDie(decode(json))));
+};
 function client(binding, options) {
-	const group = binding.group;
-	return Effect.map(RpcClient.make(group, options), (client) => {
-		const native = client;
-		return Object.fromEntries(binding.actions.map((action) => {
-			const method = native[action.name];
-			if (method === void 0) throw new Error(`No client method for ${action.name} (use the binding \`ActionRpc.make\` returned, whose group holds this action's rpc)`);
-			return [action.name, checked(action, (payload) => method(payload))];
+	const actions = new Map(binding.actions.map((action) => [action.name, action]));
+	const events = new Map(binding.events.map((event) => [event.name, event]));
+	const clients = Effect.all([RpcClient.make(erasedOf(binding.actions, binding.events).merge(nativeOf(binding.rpcs)), options), Effect.map(Effect.service(RpcClient.Protocol), ({ supportsAck }) => !supportsAck)]);
+	return Effect.map(clients, ([native, silenceEnds]) => {
+		const rpcs = Object.entries(native);
+		const methods = Object.fromEntries(rpcs.filter(([tag]) => !events.has(tag)).map(([tag, method]) => {
+			const action = actions.get(tag);
+			return [tag, action === void 0 ? method : actionMethodOf(action, binding, method)];
+		}));
+		if (events.size === 0) return methods;
+		const feeds = new Map(rpcs.flatMap(([tag, method]) => {
+			const event = events.get(tag);
+			return event === void 0 ? [] : [[tag, eventMethodOf(event, binding, method)]];
 		}));
+		const watch = (event, input, watchOptions) => {
+			const feed = feeds.get(event.name);
+			if (feed === void 0) return Stream.die(/* @__PURE__ */ new Error(`ActionRpc.client: the binding holds no event type ${event.name} (watch one the binding ActionRpc.make returned lists)`));
+			return Stream.unwrap(Effect.map(watchInput(event, input), ({ json }) => watching(transportOf(event, feed(json), silenceEnds), watchOptions)));
+		};
+		return {
+			...methods,
+			watch
+		};
 	});
 }
-//#endregion
-export { client, layer, make };
+/**
+* A socket client's `retryPolicy`, for `RpcClient.layerProtocolSocket`, that stops connecting
+* again once the server closes the socket with one of `codes`, such as a refusal of its upgrade:
+* until then it is Effect's own default, `Schedule.min([Schedule.exponential(500, 1.5),
+* Schedule.spaced(5000)])`, which Effect does not export. A page refused with its code stops, its
+* calls and streams failing with an `RpcClientError` whose `reason` is that `SocketCloseError`,
+* its `code` the one it closed with.
+*
+* **Gotchas**
+*
+* - A client without it connects again after a refusal as after any close, every five seconds for good.
+* - Any other socket error, a drop included, is retried as Effect's default retries it.
+*/
+const reconnectUntil = (...codes) => Schedule.min([Schedule.exponential(500, 1.5), Schedule.spaced(5e3)]).pipe(Schedule.setInputType(), Schedule.while(({ input: { reason } }) => !(Predicate.isTagged(reason, "SocketCloseError") && Predicate.hasProperty(reason, "code") && codes.some((code) => code === reason.code))));
+export { client, layer, make, reconnectUntil, subscriptionKeeper, unaryProtocol };

package/dist/ActionToolkit.d.mts

@@ -1,12 +1,13 @@
+import { Codec } from "./contract/codec.mjs";
 import { BuiltIns } from "./contract/errors.mjs";
-import { ActionOf, BuildError, BuildServices, Holding, Known, Member, Offered, OptionalUnless, RequestOf, SelectedOf, Served, Serving } from "./contract/implementation.mjs";
+import { ActionOf, BuildError, BuildServices, Holding, Known, Member, Offered, OptionalUnless, RequestOf, SelectedOf, ServedActions, Serving } from "./contract/implementation.mjs";
+import { ToolSuccess } from "./contract/stream.mjs";
 import { Any } from "./Action.mjs";
 import { Effect, Layer, Schema } from "effect";
 import { Prompt, Tool, Toolkit } from "effect/ai";
-//#region src/toolkit/ActionToolkit.d.ts
 type NativeTool<A extends Any, R> = Tool.Tool<A["name"], {
   readonly parameters: Schema.toCodecJson<A["input"]>;
-  readonly success: Schema.toCodecJson<A["success"]>;
+  readonly success: A["progress"] extends Codec ? Schema.toCodecJson<Schema.Union<readonly [ProgressOf<A["progress"]>, ToolSuccess<A["success"]>]>> : Schema.toCodecJson<ToolSuccess<A["success"]>>;
   readonly failure: Schema.toCodecJson<Schema.Union<ReadonlyArray<A["error"][number] | BuiltIns>>>;
   readonly failureMode: "return";
 }, R>;
@@ -48,7 +49,7 @@ export interface Options<A extends Any> {
    * Each keeps its implementation's authorization and builder. Defaults to every action of them,
    * one added to an implementation later included.
    */
-  readonly actions?: ReadonlyArray<A> | undefined;
+  readonly actions?: readonly A[] | undefined;
   /**
    * Whether a model's call needs approval before it runs: a boolean, or an Effect of one, for
    * each call, with Effect's native approval context. `LanguageModel` asks for approval
@@ -64,6 +65,19 @@ export interface Options<A extends Any> {
    */
   readonly needsApproval?: (call: ToolCall<A>, context: Tool.NeedsApprovalContext) => boolean | Effect.Effect<boolean, unknown>;
 }
+/** A value an action reported, as a toolkit's preliminary result holds it. */
+declare class Reported<A> {
+  readonly _tag = "Progress";
+  readonly value: A;
+  constructor(value: A);
+}
+/** A preliminary result of a tool whose action declares `progress`: one value it reported. */
+declare const ProgressOf: (progress: Codec) => Schema.decodeTo<Schema.declare<Reported<unknown>, Reported<unknown>>, Schema.TaggedStruct<"Progress", {
+  readonly value: Codec;
+}>, never, never>;
+type ProgressOf<P> = P extends Codec ? Schema.decodeTo<Schema.declare<Reported<P["Type"]>>, Schema.TaggedStruct<"Progress", {
+  readonly value: P;
+}>> : never;
 /**
  * Project implementations into Effect's native AI toolkit: one tool per action, keyed by its
  * name, of the listed `actions` or, without them, of every action of the implementations.
@@ -74,11 +88,13 @@ export interface Options<A extends Any> {
  *
  * **Gotchas**
  *
+ * - An action answering a stream, `Action.Stream`, answers its elements collected into one array once the stream ends, its tool's success that array.
+ * - An action declaring `progress` streams each value as a result with `preliminary: true` before its success, its `result` `{ _tag: "Progress", value }`, so its tool's success schema is that or `success`; a model reads the success alone.
  * - A success is a result with `isFailure: false`, `result` the value and `encodedResult` its JSON; a declared error a result with `isFailure: true` and `result` the error, which the model reads, never a raised failure; a refusal as `Action.Unauthenticated` and `Action.Forbidden` say.
  * - Arguments that do not decode are a result with `isFailure: true` whose `result` is an `AiError` with `reason` a `ToolParameterValidationError`, never `InvalidInput`, and neither `authorize` nor the handler runs; undeclared arguments are dropped and the call runs.
  * - A defect, or a failure the action's errors reject, is the call's defect; a success or an error that does not encode fails the call with an `AiError`, `Failed to encode result for tool …`.
  */
-export declare function make<const Apps extends Served, const O extends Options<ActionOf<Member<Apps>>> = {}>(implementations: Apps, ...options: OptionalUnless<O, Options<ActionOf<Member<Apps>>> & O & NoInfer<Known<O, Options<Any>>>>): Tools<{ readonly [T in ToolFor<Member<Apps>, Offered<O, ActionOf<Member<Apps>>>> as T["name"]]: T; }, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>>;
+export declare function make<const Apps extends ServedActions, const O extends Options<ActionOf<Member<Apps>>> = {}>(implementations: Apps, ...options: OptionalUnless<O, Options<ActionOf<Member<Apps>>> & O & NoInfer<Known<O, Options<Any>>>>): Tools<{ readonly [T in ToolFor<Member<Apps>, Offered<O, ActionOf<Member<Apps>>>> as T["name"]]: T; }, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>>;
 /** A tool call a model asked to have approved, which no answer has resolved yet. */
 export interface Approval {
   /** What a `tool-approval-response` names to answer it. */
@@ -103,6 +119,5 @@ export interface Approval {
  * Guide: `docs/ActionToolkit.md` in this package; in an application:
  * `examples/kitchen-sink/src/assistant/handlers.ts`.
  */
-export declare const openApprovals: ({ content: messages }: Prompt.Prompt) => ReadonlyArray<Approval>;
-//#endregion
+export declare const openApprovals: ({ content: messages }: Prompt.Prompt) => readonly Approval[];
 export {};

package/dist/ActionToolkit.mjs

@@ -1,10 +1,12 @@
-import { assertOnce, heldOnce } from "./contract/names.mjs";
 import { projectedErrors } from "./contract/declared.mjs";
+import { assertOnce, heldOnce } from "./contract/names.mjs";
+import { progressSink } from "./contract/progress.mjs";
+import { toolSuccessOf } from "./contract/stream.mjs";
+import { Implementation, acquire, answeringWhole, provideHandlers, select, toList } from "./contract/implementation.mjs";
 import { hintsOf } from "./contract/hints.mjs";
-import { Implementation, acquire, provideHandlers, select, toList } from "./contract/implementation.mjs";
-import { Effect, Schema } from "effect";
+import { Effect, Schema, SchemaGetter } from "effect";
 import { Tool, Toolkit } from "effect/ai";
-//#region src/toolkit/ActionToolkit.ts
+// src/toolkit/ActionToolkit.ts
 const annotateIfGiven = (tool, key, value) => value === void 0 ? tool : tool.annotate(key, value);
 const annotateFromContract = (tool, action) => {
 	const { readOnlyHint, destructiveHint, idempotentHint, openWorldHint } = hintsOf(action);
@@ -12,13 +14,32 @@ const annotateFromContract = (tool, action) => {
 	const hinted = tool.annotate(Tool.Readonly, readOnlyHint).annotate(Tool.Destructive, destructiveHint).annotate(Tool.Idempotent, idempotentHint).annotate(Tool.OpenWorld, openWorldHint);
 	return annotateIfGiven(annotateIfGiven(hinted, Tool.Title, title), Tool.Meta, _meta === void 0 ? void 0 : { ..._meta });
 };
-const jsonToolOf = (action) => Tool.make(action.name, {
-	description: action.description,
-	parameters: Schema.toCodecJson(action.input),
-	success: Schema.toCodecJson(action.success),
-	failure: Schema.toCodecJson(Schema.Union(projectedErrors(action))),
-	failureMode: "return"
-});
+/** A value an action reported, as a toolkit's preliminary result holds it. */
+var Reported = class {
+	_tag = "Progress";
+	value;
+	constructor(value) {
+		this.value = value;
+	}
+};
+/** A preliminary result of a tool whose action declares `progress`: one value it reported. */
+const ProgressOf = (progress) => Schema.TaggedStruct("Progress", { value: progress }).pipe(Schema.decodeTo(Schema.declare((input) => input instanceof Reported), {
+	decode: SchemaGetter.transform(({ value }) => new Reported(value)),
+	encode: SchemaGetter.transform((reported) => ({
+		_tag: "Progress",
+		value: reported.value
+	}))
+}));
+const jsonToolOf = (action) => {
+	const success = toolSuccessOf(action.success);
+	return Tool.make(action.name, {
+		description: action.description,
+		parameters: Schema.toCodecJson(action.input),
+		success: Schema.toCodecJson(action.progress === void 0 ? success : Schema.Union([ProgressOf(action.progress), success])),
+		failure: Schema.toCodecJson(Schema.Union(projectedErrors(action))),
+		failureMode: "return"
+	});
+};
 function make(apps, options) {
 	const served = select(toList(apps), options?.actions);
 	const needsApproval = options?.needsApproval;
@@ -29,12 +50,15 @@ function make(apps, options) {
 			action,
 			input
 		}, context);
-		return Effect.isEffect(decided) ? Effect.catch(decided, () => Effect.succeed(true)) : decided;
+		return Effect.isEffect(decided) ? Effect.orElseSucceed(decided, () => true) : decided;
 	}), { id: `${Implementation.runKey(app)}/${action.name}` });
 	const toolkit = Toolkit.make(...served.flatMap((app) => app.actions.map((action) => annotateFromContract(toolOf(action, app), action))));
 	return {
 		toolkit,
-		layer: toolkit.toLayer(Effect.map(acquire(served), (bound) => Object.fromEntries(bound.map(([action, run]) => [action.name, run])))).pipe(provideHandlers(served))
+		layer: toolkit.toLayer(Effect.map(acquire(served, void 0), (bound) => Object.fromEntries(bound.map(([action, handler]) => {
+			const run = answeringWhole(action, handler);
+			return [action.name, (input, { preliminary }) => run(input, progressSink((value) => preliminary(new Reported(value))))];
+		})))).pipe(provideHandlers(served))
 	};
 }
 /**
@@ -64,5 +88,4 @@ const openApprovals = ({ content: messages }) => {
 		}];
 	});
 };
-//#endregion
 export { make, openApprovals };