effect-assistant 0.2.0 → 0.4.0

package/dist/Timeline.js

@@ -0,0 +1,631 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { InputId } from "./InputId.js";
+import { Attachment, ToolOutcome, isLibraryEvent } from "./AssistantEvent.js";
+import { apply as apply$1 } from "./ToolApproval.js";
+import { decodeWith, tagOf } from "./internal/events.js";
+import { toJson } from "./internal/schema.js";
+import { apply as apply$2, empty as empty$1 } from "./AssistantActivity.js";
+import { apply as apply$3 } from "./BlockKit.js";
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import * as Option from "effect/Option";
+import * as Match from "effect/Match";
+import { dual } from "effect/Function";
+import * as SchemaTransformation from "effect/SchemaTransformation";
+//#region src/Timeline.ts
+/**
+* This module provides a chat's timeline: the chat as its user sees it. A chat client receives the
+* timeline and nothing else.
+*
+* A {@link Timeline} holds the chat's items: the messages with their blocks, the app's own events
+* it shows (each typed with its event, see {@link EventItem}), and the tool calls waiting for the
+* user's approval ({@link ApprovalItem}). It also holds the chat's
+* {@link Activity}, and whether the last turn failed or the chat was deleted. It never contains the
+* model's output, tool calls or results, what the model read, or why a turn failed. The server
+* streams {@link Change}s by piping the assistant's `subscribe` through {@link changes}, and the
+* client folds them with {@link fold} (or {@link apply}, from {@link empty}). On the server,
+* {@link fromEntries} builds a whole timeline from a chat's log, and {@link snapshot} the whole
+* timeline as one change.
+*
+* **Only the app events in `show` reach the timeline**, and none by default: an event that is only
+* for the assistant, like a summary of the chat, stays out. The RPC's schema, `Change([...])`,
+* names the same events and types the client's timeline with them.
+*
+* @since 0.3.0
+*/
+var Timeline_exports = /* @__PURE__ */ __exportAll({
+	Activity: () => Activity,
+	ApprovalItem: () => ApprovalItem,
+	AssistantMessage: () => AssistantMessage,
+	Block: () => Block,
+	BlockStatus: () => BlockStatus,
+	Change: () => Change,
+	SpecialistWorking: () => SpecialistWorking,
+	UserMessage: () => UserMessage,
+	apply: () => apply,
+	changes: () => changes,
+	empty: () => empty,
+	fold: () => fold,
+	fromEntries: () => fromEntries,
+	isIdle: () => isIdle,
+	snapshot: () => snapshot
+});
+/**
+* Schema for the status of a block. A block is `"open"` while it accepts an answer, `"answered"`
+* once the user has used it, and `"closed"` when it closed without an answer because the user
+* answered in words or moved on.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const BlockStatus = Schema.Literals([
+	"open",
+	"answered",
+	"closed"
+]);
+/**
+* Schema for a block on an assistant's message. It holds the block's kind, its props (JSON, as
+* the block's props schema encodes them), its status, and the user's answer (JSON, as the block's
+* answer schema encodes it).
+*
+* @category schemas
+* @since 0.1.0
+*/
+const Block = Schema.Struct({
+	kind: Schema.String,
+	props: Schema.Json,
+	status: BlockStatus,
+	answer: Schema.optional(Schema.Json)
+});
+/**
+* Schema for a message the user sent. `at` is when it was stored, in epoch
+* milliseconds.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const UserMessage = Schema.TaggedStruct("UserMessage", {
+	id: InputId,
+	text: Schema.String,
+	attachments: Schema.optional(Schema.Array(Attachment)),
+	at: Schema.Finite
+});
+/**
+* Schema for a message the assistant sent the user, including its block if it has one.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const AssistantMessage = Schema.TaggedStruct("AssistantMessage", {
+	id: Schema.String,
+	text: Schema.String,
+	at: Schema.Finite,
+	block: Schema.optional(Block)
+});
+/**
+* Schema for a tool call that waits, or waited, for the user's approval, as an item on the
+* timeline.
+*
+* **Details**
+*
+* It is only the yes or no: the assistant's own message tells the user what it asks them to
+* approve, so the item carries no params. `id` is the call's id, which the decision is for (see
+* `ToolApproval.approve`), and `tool` the tool's name, for a label. `status` is where the call stands
+* (`ToolApproval.Status`); `reason` is the user's, when they rejected it with one; `outcome` is how
+* the approved call went, once it ran. `at` is when the call started waiting, in epoch
+* milliseconds. A change updates the item in place as the call is decided and run.
+*
+* @category schemas
+* @since 0.4.0
+*/
+const ApprovalItem = Schema.TaggedStruct("ToolApproval", {
+	id: Schema.String,
+	tool: Schema.String,
+	status: Schema.Literals([
+		"pending",
+		"approved",
+		"rejected",
+		"expired"
+	]),
+	reason: Schema.optional(Schema.String),
+	outcome: Schema.optional(ToolOutcome),
+	at: Schema.Finite
+});
+/**
+* Schema for a specialist that is working for the assistant. It holds the specialist's name and
+* when it started, in epoch milliseconds.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const SpecialistWorking = Schema.Struct({
+	specialist: Schema.String,
+	since: Schema.Finite
+});
+/**
+* Schema for what is working in the chat.
+*
+* `working` is true while the assistant runs a turn, or when a turn is about to start for
+* something that arrived. `specialists` lists the specialists that are working. When the chat is
+* idle, nothing is working, even if a workflow is waiting on a timer or on the user.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const Activity = Schema.Struct({
+	working: Schema.Boolean,
+	specialists: Schema.Array(SpecialistWorking)
+});
+const eventItem = (schema) => Schema.Struct({
+	_tag: Schema.Literal(tagOf(schema)),
+	id: Schema.String,
+	at: Schema.Finite,
+	event: schema
+});
+function makeChange(events = []) {
+	const AnyItem = Schema.toCodecJson(Schema.Union([
+		UserMessage,
+		AssistantMessage,
+		ApprovalItem,
+		...events.map(eventItem)
+	]));
+	const decodeItem = Schema.decodeUnknownOption(AnyItem);
+	const encodeItem = Schema.encodeUnknownSync(AnyItem);
+	return Schema.Struct({
+		seq: Schema.Int,
+		items: Schema.Array(Schema.Json).pipe(Schema.decodeTo(Schema.Array(Schema.toType(AnyItem)), SchemaTransformation.transform({
+			decode: (json) => json.flatMap((item) => Option.toArray(decodeItem(item))),
+			encode: (items) => items.map((item) => encodeItem(item))
+		}))),
+		activity: Activity,
+		failed: Schema.Boolean,
+		deleted: Schema.Boolean
+	});
+}
+/**
+* Creates the schema for the changes to a chat's timeline, with items for the given app events,
+* in JSON.
+*
+* **Details**
+*
+* It is the success schema of the RPC that streams a chat's timeline: name the events the chat's
+* users see, the same ones the handler passes to {@link changes} as `show`. Tool calls waiting for
+* approval are always in it, as {@link ApprovalItem}s. Each item decodes its
+* event with that event's schema, so the client gets `Change<Events>` typed with them and folds it
+* with {@link fold}, no definition needed. `Change()` carries no app events.
+*
+* A handler whose changes show an event the schema doesn't name doesn't compile.
+*
+* **Example** (An RPC that streams a chat's timeline, with the budget notice)
+*
+* ```ts
+* import { ChatId, Timeline } from "effect-assistant"
+* import * as Rpc from "effect/rpc/Rpc"
+* import * as Schema from "effect/Schema"
+*
+* class DailyBudgetReached extends Schema.TaggedClass<DailyBudgetReached>()("DailyBudgetReached", {}) {}
+*
+* const Subscribe = Rpc.make("Subscribe", {
+*   payload: { chatId: ChatId.ChatId },
+*   success: Timeline.Change([DailyBudgetReached]),
+*   stream: true
+* })
+* ```
+*
+* @category schemas
+* @since 0.3.0
+*/
+const Change = makeChange;
+/**
+* The timeline of a chat before anything has happened in it, with no items and nothing working.
+* Use it as the starting point when folding changes with {@link apply}.
+*
+* @category constructors
+* @since 0.1.0
+*/
+const empty = {
+	seq: 0,
+	items: [],
+	activity: {
+		working: false,
+		specialists: []
+	},
+	failed: false,
+	deleted: false
+};
+/**
+* Returns the timeline after a change.
+*
+* **Details**
+*
+* Each item in the change replaces the item with the same id, in place, and new items are added
+* after the rest. The change's activity, `failed`, and `deleted` replace the timeline's. Applying a
+* change twice changes nothing, so a client that resubscribes from the start can fold again and get
+* the same timeline.
+*
+* The timeline is typed with the change's events, as its RPC's schema decoded them (see
+* {@link Change}). To fold a stream of changes, use {@link fold}: in
+* `Stream.scan(() => Timeline.empty, Timeline.apply)`, TypeScript fixes the state's type from
+* `empty` before it sees the changes' events, so that form needs the timeline's type written out.
+*
+* **Example** (Folding changes into your own state)
+*
+* ```ts
+* import { Timeline } from "effect-assistant"
+*
+* interface State<Events> {
+*   readonly timeline: Timeline.Timeline<Events>
+*   readonly unread: number
+* }
+*
+* const next = <Events>(state: State<Events>, change: Timeline.Change<Events>): State<Events> => ({
+*   timeline: Timeline.apply(state.timeline, change),
+*   unread: state.unread + change.items.length
+* })
+* ```
+*
+* @category combinators
+* @since 0.1.0
+*/
+const apply = (timeline, change) => {
+	const changed = new Map(change.items.map((item) => [item.id, item]));
+	const known = new Set(timeline.items.map((item) => item.id));
+	return {
+		seq: Math.max(timeline.seq, change.seq),
+		items: [...timeline.items.map((item) => changed.get(item.id) ?? item), ...change.items.filter((item) => !known.has(item.id))],
+		activity: change.activity,
+		failed: change.failed,
+		deleted: change.deleted
+	};
+};
+/**
+* Returns the timelines a stream of changes folds to, from {@link empty}, typed with the changes'
+* events.
+*
+* **Example** (A chat's timeline on the client)
+*
+* ```ts
+* import { Timeline } from "effect-assistant"
+* import * as Schema from "effect/Schema"
+* import * as Stream from "effect/Stream"
+*
+* class DailyBudgetReached extends Schema.TaggedClass<DailyBudgetReached>()("DailyBudgetReached", {}) {}
+*
+* // The stream of an RPC whose success schema is `Timeline.Change([DailyBudgetReached])`.
+* declare const changes: Stream.Stream<Timeline.Change<DailyBudgetReached>>
+*
+* const timelines = changes.pipe(Timeline.fold) // Stream<Timeline.Timeline<DailyBudgetReached>>
+* ```
+*
+* @category combinators
+* @since 0.3.0
+*/
+const fold = (changes) => changes.pipe(Stream.scan(() => empty, apply));
+/**
+* Returns whether nothing is working in the chat: no turn is running or about to start, and no
+* specialist is working.
+*
+* @category guards
+* @since 0.1.0
+*/
+const isIdle = (timeline) => !timeline.activity.working && timeline.activity.specialists.length === 0;
+function snapshotWith(entries, _definition, options) {
+	const timeline = folding(options?.show ?? []);
+	for (const entry of entries) timeline.step(entry);
+	return timeline.snapshot;
+}
+/**
+* Returns a chat's whole timeline as one change, built from the entries of its log.
+*
+* **When to use**
+*
+* Use it on the server for an RPC that returns a whole chat at once: its success schema is
+* {@link Change} with the same events as `show`, and the client applies it to {@link empty}.
+*
+* **Details**
+*
+* Only the app's events in `show` become items; without it, the timeline has none.
+*
+* @category constructors
+* @since 0.3.0
+*/
+const snapshot = snapshotWith;
+function fromEntriesWith(entries, _definition, options) {
+	const timeline = folding(options?.show ?? []);
+	for (const entry of entries) timeline.step(entry);
+	return timeline.snapshot;
+}
+/**
+* Returns a chat's timeline, built from the entries of its log.
+*
+* **When to use**
+*
+* Use it in server-side code that reads a whole chat. A client gets the timeline as a stream from
+* {@link changes} instead, and an RPC that returns a whole chat sends a {@link snapshot}.
+*
+* **Details**
+*
+* Only the app's events in `show` become items, typed with their schemas; without it, the timeline
+* has none.
+*
+* **Example** (Building a chat's timeline from its log)
+*
+* ```ts
+* import { type ChatId, ChatLog, Timeline } from "effect-assistant"
+* import * as Effect from "effect/Effect"
+*
+* const timelineOf = (chatId: ChatId.ChatId) =>
+*   ChatLog.ChatLog.use((log) => log.read(chatId)).pipe(
+*     Effect.map((entries) => Timeline.fromEntries(entries))
+*   )
+* ```
+*
+* @see {@link changes} for a stream of changes instead of a whole timeline
+*
+* @category constructors
+* @since 0.1.0
+*/
+const fromEntries = fromEntriesWith;
+const activityOf = (activity) => ({
+	working: activity.turnSince !== void 0 || activity.queued,
+	specialists: [...activity.specialists.values()].map((run) => ({
+		specialist: run.specialist,
+		since: run.since
+	}))
+});
+const sameActivity = (a, b) => a.working === b.working && a.specialists.length === b.specialists.length && a.specialists.every((run, i) => {
+	const other = b.specialists[i];
+	return other !== void 0 && run.specialist === other.specialist && run.since === other.since;
+});
+const folding = (show) => {
+	const shown = new Map(show.map((schema) => [tagOf(schema), schema]));
+	let approvals = /* @__PURE__ */ new Map();
+	let seq = 0;
+	let failed = false;
+	let deleted = false;
+	let activity = empty$1;
+	let blocks = /* @__PURE__ */ new Map();
+	const items = /* @__PURE__ */ new Map();
+	const sent = /* @__PURE__ */ new Map();
+	const blockOf = (message) => {
+		if (message.block === void 0) return void 0;
+		const state = blocks.get(message.id);
+		const status = state === void 0 || state.open ? "open" : state.answer === void 0 ? "closed" : "answered";
+		const block = {
+			kind: message.block.kind,
+			props: toJson(message.block.props),
+			status
+		};
+		return state?.answer === void 0 ? block : {
+			...block,
+			answer: toJson(state.answer.value)
+		};
+	};
+	const itemOf = (message, at) => {
+		const block = blockOf(message);
+		return block === void 0 ? AssistantMessage.make({
+			id: message.id,
+			text: message.text,
+			at
+		}) : AssistantMessage.make({
+			id: message.id,
+			text: message.text,
+			at,
+			block
+		});
+	};
+	const touched = (event, at) => Match.value(event).pipe(Match.tagsExhaustive({
+		UserMessage: (message) => {
+			items.set(message.id, message.attachments === void 0 ? UserMessage.make({
+				id: message.id,
+				text: message.text,
+				at
+			}) : UserMessage.make({
+				id: message.id,
+				text: message.text,
+				attachments: message.attachments,
+				at
+			}));
+			failed = false;
+			return [message.id];
+		},
+		AssistantMessage: (message) => {
+			sent.set(message.id, message);
+			items.set(message.id, itemOf(message, at));
+			failed = false;
+			return [message.id, ...message.closes ?? []];
+		},
+		BlockAnswer: (answer) => {
+			failed = false;
+			return [answer.messageId];
+		},
+		BlocksClosed: (closed) => closed.messageIds,
+		ApprovalRequested: () => [],
+		ApprovalDecision: () => {
+			failed = false;
+			return [];
+		},
+		ApprovalsExpired: () => [],
+		TurnFailed: () => {
+			failed = true;
+			return [];
+		},
+		ModelOutput: () => [],
+		ToolStarted: () => [],
+		ToolResult: () => [],
+		TurnStarted: () => [],
+		TurnCompleted: () => [],
+		SpecialistStarted: () => [],
+		SpecialistFinished: () => [],
+		ChatDeleted: () => {
+			deleted = true;
+			return [];
+		}
+	}));
+	const eventItemOf = (entry) => {
+		const schema = shown.get(entry.event._tag);
+		if (schema === void 0) return Option.none();
+		const event = Schema.is(schema)(entry.event) ? Option.some(entry.event) : decodeWith(schema, entry.event);
+		return Option.map(event, (decoded) => ({
+			_tag: decoded._tag,
+			id: `app-event:${entry.seq}`,
+			at: entry.at,
+			event: decoded
+		}));
+	};
+	const callsOf = (event) => Predicate.isTagged(event, "ApprovalsExpired") ? event.callIds : Predicate.isTagged(event, "ApprovalRequested") || Predicate.isTagged(event, "ApprovalDecision") || Predicate.isTagged(event, "ToolResult") ? [event.callId] : [];
+	const approvalItems = (event, before) => callsOf(event).flatMap((callId) => {
+		const state = approvals.get(callId);
+		if (state === void 0 || state === before.get(callId)) return [];
+		const item = ApprovalItem.make({
+			id: callId,
+			tool: state.request.tool,
+			status: state.status,
+			reason: state.reason,
+			outcome: state.outcome,
+			at: state.at
+		});
+		items.set(callId, item);
+		return [item];
+	});
+	const step = (entry) => {
+		const previous = {
+			activity: activityOf(activity),
+			failed,
+			deleted
+		};
+		const { event } = entry;
+		seq = entry.seq;
+		activity = apply$2(activity, entry);
+		if (!isLibraryEvent(event)) {
+			const now = activityOf(activity);
+			return Option.match(eventItemOf(entry), {
+				onNone: () => sameActivity(previous.activity, now) ? void 0 : {
+					seq,
+					items: [],
+					activity: now,
+					failed,
+					deleted
+				},
+				onSome: (item) => {
+					items.set(item.id, item);
+					return {
+						seq,
+						items: [item],
+						activity: now,
+						failed,
+						deleted
+					};
+				}
+			});
+		}
+		blocks = apply$3(blocks, event);
+		const decidedBefore = approvals;
+		approvals = apply$1(approvals, entry);
+		const all = [...[...new Set(touched(event, entry.at))].flatMap((id) => {
+			const message = sent.get(id);
+			const current = items.get(id);
+			if (message === void 0 || current === void 0) return current === void 0 ? [] : [current];
+			const next = itemOf(message, current.at);
+			items.set(id, next);
+			return [next];
+		}), ...approvalItems(event, decidedBefore)];
+		const now = activityOf(activity);
+		return all.length === 0 && failed === previous.failed && deleted === previous.deleted && sameActivity(previous.activity, now) ? void 0 : {
+			seq,
+			items: all,
+			activity: now,
+			failed,
+			deleted
+		};
+	};
+	return {
+		step,
+		get snapshot() {
+			return {
+				seq,
+				items: [...items.values()],
+				activity: activityOf(activity),
+				failed,
+				deleted
+			};
+		}
+	};
+};
+const merge = (changes) => {
+	const last = changes.at(-1);
+	if (last === void 0) return void 0;
+	const items = /* @__PURE__ */ new Map();
+	for (const change of changes) for (const item of change.items) items.set(item.id, item);
+	return {
+		seq: last.seq,
+		items: [...items.values()],
+		activity: last.activity,
+		failed: last.failed,
+		deleted: last.deleted
+	};
+};
+function changesWith(entries, _definition, options) {
+	const after = options?.after ?? 0;
+	return entries.pipe(Stream.mapAccumArray(() => folding(options?.show ?? []), (timeline, chunk) => {
+		const changed = chunk.flatMap((entry) => {
+			const change = timeline.step(entry);
+			return change === void 0 || entry.seq <= after ? [] : [change];
+		});
+		const merged = merge(changed);
+		return [timeline, merged === void 0 ? [] : [merged]];
+	}));
+}
+/**
+* Returns the stream of changes to a chat's timeline that its entries produce, for a chat client.
+*
+* **Details**
+*
+* The entries must stream from the start of the chat's log, as `assistant.subscribe(chatId)` does
+* without `after`. The fold reads every entry, because a message depends on earlier entries: its
+* block is answered or closed later. `after` only skips emitting the changes up to that `seq`, so a
+* client that has the timeline up to a `seq` receives only what changed since. Pass `after` here,
+* not to `subscribe`: a subscription that starts after a `seq` gives the fold an incomplete log,
+* and the changes it produces are wrong.
+*
+* Each chunk of entries becomes one change; the stored entries, for example, arrive as one chunk.
+*
+* **Only the app's events in `show` reach the client.** Each one becomes an item between the
+* messages (see {@link EventItem}); the app's other events, like a summary of the chat for the
+* model, are left out. Without `show`, none are shown. The changes are typed with the events shown,
+* so the RPC's success schema names the same ones (`Timeline.Change([...])`), and a handler that
+* shows one the schema doesn't name doesn't compile. A timeline shows a turn as working once it
+* starts, or from the user's input.
+*
+* **Example** (Streaming a chat's timeline to a client, with the one app event its user sees)
+*
+* ```ts
+* import { Assistant, type ChatId, Timeline } from "effect-assistant"
+* import * as Schema from "effect/Schema"
+* import * as Stream from "effect/Stream"
+*
+* class Summary extends Schema.TaggedClass<Summary>()("Summary", { text: Schema.String, throughSeq: Schema.Int }) {}
+* class DailyBudgetReached extends Schema.TaggedClass<DailyBudgetReached>()("DailyBudgetReached", {}) {}
+*
+* const MyAssistant = Assistant.make("my-assistant", { events: [Summary, DailyBudgetReached] })
+*
+* // The summary is for the model: only the budget notice reaches the user.
+* const watch = (chatId: ChatId.ChatId, after: number) =>
+*   Stream.unwrap(
+*     MyAssistant.useSync((assistant) =>
+*       assistant.subscribe(chatId).pipe(Timeline.changes(MyAssistant, { show: [DailyBudgetReached], after }))
+*     )
+*   )
+* ```
+*
+* @see {@link fold} for folding the changes into a timeline on the client
+*
+* @category utils
+* @since 0.3.0
+*/
+const changes = dual((args) => Stream.isStream(args[0]), changesWith);
+//#endregion
+export { Activity, ApprovalItem, AssistantMessage, Block, BlockStatus, Change, SpecialistWorking, Timeline_exports, UserMessage, apply, changes, empty, fold, fromEntries, isIdle, snapshot };
+
+//# sourceMappingURL=Timeline.js.map