effect-assistant 0.4.0 → 0.5.0

package/dist/Compaction.js

@@ -3,8 +3,8 @@ import { attachmentLine, isLibraryEvent } from "./AssistantEvent.js";
 import { fromEntries } from "./ToolApproval.js";
 import { toJsonText } from "./internal/schema.js";
 import { userText } from "./internal/history.js";
-import { fromEntries as fromEntries$1 } from "./AssistantActivity.js";
-import { fromEntries as fromEntries$2 } from "./BlockKit.js";
+import { fromEntries as fromEntries$1 } from "./BlockKit.js";
+import { fromEntries as fromEntries$2 } from "./AssistantActivity.js";
 import * as Predicate from "effect/Predicate";
 import * as Option from "effect/Option";
 //#region src/Compaction.ts
@@ -36,12 +36,12 @@ const inputTokens = (entries) => {
 const openItems = (entries, throughSeq) => {
 	const seqOf = (found) => entries.find(({ event }) => found(event))?.seq ?? Number.POSITIVE_INFINITY;
 	const opened = (seq) => seq <= throughSeq;
-	const blocks = [...fromEntries$2(entries)].flatMap(([messageId, state]) => {
+	const blocks = [...fromEntries$1(entries)].flatMap(([messageId, state]) => {
 		const shown = entries.find(({ event }) => isLibraryEvent(event) && Predicate.isTagged(event, "AssistantMessage") && event.id === messageId);
 		const message = shown?.event;
 		return state.open && shown !== void 0 && opened(shown.seq) && message !== void 0 && isLibraryEvent(message) && Predicate.isTagged(message, "AssistantMessage") ? [`- message ${messageId}, a ${message.block?.kind} block: ${message.text}`] : [];
 	});
-	const specialists = [...fromEntries$1(entries).specialists.values()].flatMap((run) => opened(seqOf((event) => isLibraryEvent(event) && Predicate.isTagged(event, "SpecialistStarted") && event.runId === run.runId)) ? [`- your ${run.specialist} specialist (${run.runId}), working on: ${run.goal}`] : []);
+	const specialists = [...fromEntries$2(entries).specialists.values()].flatMap((run) => opened(seqOf((event) => isLibraryEvent(event) && Predicate.isTagged(event, "SpecialistStarted") && event.runId === run.runId)) ? [`- your ${run.specialist} specialist (${run.runId}), working on: ${run.goal}`] : []);
 	const approvals = [...fromEntries(entries).values()].flatMap((approval) => approval.status === "pending" && opened(seqOf((event) => isLibraryEvent(event) && Predicate.isTagged(event, "ApprovalRequested") && event.callId === approval.request.callId)) ? [`- your call to ${approval.request.tool} (${approval.request.callId}): ${toJsonText(approval.request.params)}`] : []);
 	const sections = [
 		blocks.length > 0 ? `Blocks the user hasn't answered:\n${blocks.join("\n")}` : "",

package/dist/Timeline.d.ts

@@ -34,6 +34,8 @@ export declare const Block: Schema.Struct<{
   readonly props: Schema.Codec<Schema.Json, Schema.Json, never, never>;
   readonly status: Schema.Literals<readonly ["open", "answered", "closed"]>;
   readonly answer: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+  /** For a block that shows a tool's result (`Block.fromToolResult`): the result, as the tool's success schema encodes it. */
+  readonly result: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
 }>;
 /**
  * Represents a block on an assistant's message.
@@ -82,6 +84,8 @@ export declare const AssistantMessage: Schema.TaggedStruct<"AssistantMessage", {
     readonly props: Schema.Codec<Schema.Json, Schema.Json, never, never>;
     readonly status: Schema.Literals<readonly ["open", "answered", "closed"]>;
     readonly answer: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    /** For a block that shows a tool's result (`Block.fromToolResult`): the result, as the tool's success schema encodes it. */
+    readonly result: Schema.optional<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
   }>>;
 }>;
 /**

package/dist/Timeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Timeline.d.ts","names":[],"sources":["../src/Timeline.ts"],"mappings":";;;;;;;;;;;;;;;qBA4Ca,aAAW,OAAA;;;;;;;YAQZ,qBAAqB,YAAY;;;;;;;;;qBAUhC,OAAK,OAAA;;;;;;;;;;;;YAaN,eAAe,MAAM;;;;;;;;qBASpB,aAAW,OAAA;;;;;;;;;;;;;;;;;YAaZ,qBAAqB,YAAY;;;;;;;qBAQhC,kBAAgB,OAAA;;;;;;;;;;;;;;;;;YAajB,0BAA0B,iBAAiB;;;;;;;;;;;;;;;;YAiB3C,UAAU,KAAK;WAAqB,YAAY;;WAC7C,MAAM;WAAc;WAAqB;WAAqB,OAAO;;;;;;;;;;;;;;;;;;qBAmBvE,cAAY,OAAA;;;;;;;;;;;;;;;YAgBb,sBAAsB,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;YA2BnC,KAAK,kBAAkB,cAAc,mBAAmB,UAAU,UAAU;;;;;;;;qBAS3E,mBAAiB,OAAA;;;;;;;;;;YAWlB,2BAA2B,kBAAkB;;;;;;;;;;;qBAY5C,UAAQ,OAAA;;;;;;;;;;;;;YAWT,kBAAkB,SAAS;;;;;;;;;iBAUtB,SAAS;WACf;WACA,OAAO,cAAc,KAAK;WAC1B,UAAU;;WAEV;;WAEA;;;;;;;;;;;;;;;iBAgBM,OAAO;WACb;WACA,OAAO,cAAc,KAAK;WAC1B,UAAU;WACV;WACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAsEE,eAAe,eAAe,cAAc,+BACvD,SAAS,WACN,OAAO,MAAM,OAAO,yBAAyB,OAAO;;;;;;;;qBAS5C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA0CP,QAAS,QAAM,UAAY,SAAS,SAAO,QAAU,OAAO,YAAU,SAAS;;;;;;;;;;;;;;;;;;;;;;;qBAsC/E,OAAQ,QAAQ,GAAG,GAAC,SACtB,OAAO,OAAO,OAAO,SAAS,GAAG,OACzC,OAAO,OAAO,SAAS,SAAS,GAAG;;;;;;;;qBASzB,SAAU,QAAM,UAAY,SAAS;;;;;;;iBA2BjC,YAAY,aAAa,cAAc;;;;;WAK7C,OAAO;;;;;;;;YASN,MAAM,UAAU,cAAc;WAA2C,MAAM;;;;;;;;;;;;;;;;;qBAmC9E;GACV,SAAS,cAAc,YAA2B;GAClD,cAAc,aAAa,MAAM,uBAChC,SAAS,cAAc,WACvB,YAAY,WAAW,SACvB,UAAU,YAAY,QACrB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAmDC;GACV,SAAS,cAAc,YAA2B;GAClD,cAAc,aAAa,MAAM,uBAChC,SAAS,cAAc,WACvB,YAAY,WAAW,SACvB,UAAU,YAAY,QACrB,SAAS;;;;;;;;;iBAsPG,WAAW;;WAEjB,QAAQ,cAAc;;WAEtB,OAAO,OAAO,MAAM,MAAgB,SAAS,OAAO;;;;;;;;iBAS9C,eACf,aAAa,cAAc,uCACnB,YAAY;;;;;WAKX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAgFE;GACV,cAAc,aAAa,MAAM,uBAChC,YAAY,WAAW,SACvB,UAAU,eAAe,SACvB,GAAG,GAAG,SAAS,OAAO,OAAO,UAAyB,GAAG,OAAO,OAAO,OAAO,OAAO,uBAAuB,GAAG;GAClH,GAAG,GAAG,cAAc,aAAa,MAAM,uBACtC,SAAS,OAAO,OAAO,UAAyB,GAAG,IACnD,YAAY,WAAW,SACvB,UAAU,eAAe,QACxB,OAAO,OAAO,OAAO,uBAAuB,GAAG"}
+{"version":3,"file":"Timeline.d.ts","names":[],"sources":["../src/Timeline.ts"],"mappings":";;;;;;;;;;;;;;;qBA4Ca,aAAW,OAAA;;;;;;;YAQZ,qBAAqB,YAAY;;;;;;;;;qBAUhC,OAAK,OAAA;;;;;;;;;;;;;;YAeN,eAAe,MAAM;;;;;;;;qBASpB,aAAW,OAAA;;;;;;;;;;;;;;;;;YAaZ,qBAAqB,YAAY;;;;;;;qBAQhC,kBAAgB,OAAA;;;;;;;;;;;;;;;;;;;YAajB,0BAA0B,iBAAiB;;;;;;;;;;;;;;;;YAiB3C,UAAU,KAAK;WAAqB,YAAY;;WAC7C,MAAM;WAAc;WAAqB;WAAqB,OAAO;;;;;;;;;;;;;;;;;;qBAmBvE,cAAY,OAAA;;;;;;;;;;;;;;;YAgBb,sBAAsB,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;YA2BnC,KAAK,kBAAkB,cAAc,mBAAmB,UAAU,UAAU;;;;;;;;qBAS3E,mBAAiB,OAAA;;;;;;;;;;YAWlB,2BAA2B,kBAAkB;;;;;;;;;;;qBAY5C,UAAQ,OAAA;;;;;;;;;;;;;YAWT,kBAAkB,SAAS;;;;;;;;;iBAUtB,SAAS;WACf;WACA,OAAO,cAAc,KAAK;WAC1B,UAAU;;WAEV;;WAEA;;;;;;;;;;;;;;;iBAgBM,OAAO;WACb;WACA,OAAO,cAAc,KAAK;WAC1B,UAAU;WACV;WACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAsEE,eAAe,eAAe,cAAc,+BACvD,SAAS,WACN,OAAO,MAAM,OAAO,yBAAyB,OAAO;;;;;;;;qBAS5C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA0CP,QAAS,QAAM,UAAY,SAAS,SAAO,QAAU,OAAO,YAAU,SAAS;;;;;;;;;;;;;;;;;;;;;;;qBAsC/E,OAAQ,QAAQ,GAAG,GAAC,SACtB,OAAO,OAAO,OAAO,SAAS,GAAG,OACzC,OAAO,OAAO,SAAS,SAAS,GAAG;;;;;;;;qBASzB,SAAU,QAAM,UAAY,SAAS;;;;;;;iBA2BjC,YAAY,aAAa,cAAc;;;;;WAK7C,OAAO;;;;;;;;YASN,MAAM,UAAU,cAAc;WAA2C,MAAM;;;;;;;;;;;;;;;;;qBAmC9E;GACV,SAAS,cAAc,YAA2B;GAClD,cAAc,aAAa,MAAM,uBAChC,SAAS,cAAc,WACvB,YAAY,WAAW,SACvB,UAAU,YAAY,QACrB,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAmDC;GACV,SAAS,cAAc,YAA2B;GAClD,cAAc,aAAa,MAAM,uBAChC,SAAS,cAAc,WACvB,YAAY,WAAW,SACvB,UAAU,YAAY,QACrB,SAAS;;;;;;;;;iBAiQG,WAAW;;WAEjB,QAAQ,cAAc;;WAEtB,OAAO,OAAO,MAAM,MAAgB,SAAS,OAAO;;;;;;;;iBAS9C,eACf,aAAa,cAAc,uCACnB,YAAY;;;;;WAKX;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAgFE;GACV,cAAc,aAAa,MAAM,uBAChC,YAAY,WAAW,SACvB,UAAU,eAAe,SACvB,GAAG,GAAG,SAAS,OAAO,OAAO,UAAyB,GAAG,OAAO,OAAO,OAAO,OAAO,uBAAuB,GAAG;GAClH,GAAG,GAAG,cAAc,aAAa,MAAM,uBACtC,SAAS,OAAO,OAAO,UAAyB,GAAG,IACnD,YAAY,WAAW,SACvB,UAAU,eAAe,QACxB,OAAO,OAAO,OAAO,uBAAuB,GAAG"}

package/dist/Timeline.js

@@ -4,8 +4,8 @@ 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 { apply as apply$2 } from "./BlockKit.js";
+import { apply as apply$3, empty as empty$1 } from "./AssistantActivity.js";
 import * as Predicate from "effect/Predicate";
 import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
@@ -76,7 +76,9 @@ const Block = Schema.Struct({
 	kind: Schema.String,
 	props: Schema.Json,
 	status: BlockStatus,
-	answer: Schema.optional(Schema.Json)
+	answer: Schema.optional(Schema.Json),
+	/** For a block that shows a tool's result (`Block.fromToolResult`): the result, as the tool's success schema encodes it. */
+	result: Schema.optional(Schema.Json)
 });
 /**
 * Schema for a message the user sent. `at` is when it was stored, in epoch
@@ -388,6 +390,7 @@ const folding = (show) => {
 	let blocks = /* @__PURE__ */ new Map();
 	const items = /* @__PURE__ */ new Map();
 	const sent = /* @__PURE__ */ new Map();
+	const results = /* @__PURE__ */ new Map();
 	const blockOf = (message) => {
 		if (message.block === void 0) return void 0;
 		const state = blocks.get(message.id);
@@ -397,8 +400,14 @@ const folding = (show) => {
 			props: toJson(message.block.props),
 			status
 		};
-		return state?.answer === void 0 ? block : {
+		const { resultId } = message.block;
+		const result = resultId === void 0 ? void 0 : results.get(resultId);
+		const shown = result === void 0 ? block : {
 			...block,
+			result
+		};
+		return state?.answer === void 0 ? shown : {
+			...shown,
 			answer: toJson(state.answer.value)
 		};
 	};
@@ -453,7 +462,10 @@ const folding = (show) => {
 		},
 		ModelOutput: () => [],
 		ToolStarted: () => [],
-		ToolResult: () => [],
+		ToolResult: (result) => {
+			if (result.resultId !== void 0 && result.outcome === "success") results.set(result.resultId, result.full ?? result.result);
+			return [];
+		},
 		TurnStarted: () => [],
 		TurnCompleted: () => [],
 		SpecialistStarted: () => [],
@@ -497,7 +509,7 @@ const folding = (show) => {
 		};
 		const { event } = entry;
 		seq = entry.seq;
-		activity = apply$2(activity, entry);
+		activity = apply$3(activity, entry);
 		if (!isLibraryEvent(event)) {
 			const now = activityOf(activity);
 			return Option.match(eventItemOf(entry), {
@@ -520,7 +532,7 @@ const folding = (show) => {
 				}
 			});
 		}
-		blocks = apply$3(blocks, event);
+		blocks = apply$2(blocks, event);
 		const decidedBefore = approvals;
 		approvals = apply$1(approvals, entry);
 		const all = [...[...new Set(touched(event, entry.at))].flatMap((id) => {

package/dist/Timeline.js.map

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

package/dist/ToolResult.d.ts

@@ -0,0 +1,56 @@
+import * as Context from "effect/Context";
+import * as Schema from "effect/Schema";
+import * as Tool from "effect/ai/Tool";
+declare namespace ToolResult_d_exports {
+  export { ModelView, modelView };
+}
+type Schemas = {
+  readonly parameters: Schema.Top;
+  readonly success: Schema.Top;
+  readonly failure: Schema.Top;
+  readonly failureMode: Tool.FailureMode;
+};
+declare const ModelView_base: Context.ServiceClass<ModelView, "effect-assistant/ToolResult/ModelView", (success: any) => Schema.Json>;
+/**
+ * Annotation for what the model reads of a tool's success, set with {@link modelView}.
+ *
+ * @category annotations
+ * @since 0.5.0
+ */
+export declare class ModelView extends ModelView_base {}
+/**
+ * Sets what the model reads of a tool's success. The chat's log keeps the whole success.
+ *
+ * **Details**
+ *
+ * The view gets the success as the tool's success schema decodes it, and returns the JSON the
+ * model reads instead. Failures reach the model as they are.
+ *
+ * **Example** (Keeping image URLs out of the model's context)
+ *
+ * ```ts
+ * import * as Tool from "effect/ai/Tool"
+ * import * as Schema from "effect/Schema"
+ * import { ToolResult } from "effect-assistant"
+ *
+ * const Asset = Schema.Struct({ id: Schema.String, name: Schema.String, imageUrl: Schema.String })
+ *
+ * export const SearchAssets = ToolResult.modelView(
+ *   Tool.make("search_assets", {
+ *     parameters: Schema.Struct({ query: Schema.String }),
+ *     success: Schema.Struct({ items: Schema.Array(Asset) })
+ *   }),
+ *   (result) => ({ items: result.items.map(({ id, name }) => ({ id, name })) })
+ * )
+ * ```
+ *
+ * @category annotations
+ * @since 0.5.0
+ */
+export declare const modelView: {
+  <Config extends Schemas>(view: (success: Config["success"]["Type"]) => Schema.Json): <Name extends string, R>(tool: Tool.Tool<Name, Config, R>) => Tool.Tool<Name, Config, R>;
+  <Name extends string, Config extends Schemas, R>(tool: Tool.Tool<Name, Config, R>, view: (success: Config["success"]["Type"]) => Schema.Json): Tool.Tool<Name, Config, R>;
+};
+//#endregion
+export { ToolResult_d_exports };
+//# sourceMappingURL=ToolResult.d.ts.map

package/dist/ToolResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolResult.d.ts","names":[],"sources":["../src/ToolResult.ts"],"mappings":";;;;;;KAmBK;WACM,YAAY,OAAO;WACnB,SAAS,OAAO;WAChB,SAAS,OAAO;WAChB,aAAa,KAAK;;cASuC,gBAAA,QAAA,aAAA,qDAAA,iBAAQ,OAAO;;;;;;;qBAAtE,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAiClB;GACV,eAAe,SACd,OAAO,SAAS,8BAA8B,OAAO,QACnD,qBAAqB,GAAG,MAAM,KAAK,KAAK,MAAM,QAAQ,OAAO,KAAK,KAAK,MAAM,QAAQ;GACxF,qBAAqB,eAAe,SAAS,GAC5C,MAAM,KAAK,KAAK,MAAM,QAAQ,IAC9B,OAAO,SAAS,8BAA8B,OAAO,OACpD,KAAK,KAAK,MAAM,QAAQ"}

package/dist/ToolResult.js

@@ -0,0 +1,49 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import * as Context from "effect/Context";
+import { dual } from "effect/Function";
+//#region src/ToolResult.ts
+var ToolResult_exports = /* @__PURE__ */ __exportAll({
+	ModelView: () => ModelView,
+	modelView: () => modelView
+});
+/**
+* Annotation for what the model reads of a tool's success, set with {@link modelView}.
+*
+* @category annotations
+* @since 0.5.0
+*/
+var ModelView = class extends Context.Service()("effect-assistant/ToolResult/ModelView") {};
+/**
+* Sets what the model reads of a tool's success. The chat's log keeps the whole success.
+*
+* **Details**
+*
+* The view gets the success as the tool's success schema decodes it, and returns the JSON the
+* model reads instead. Failures reach the model as they are.
+*
+* **Example** (Keeping image URLs out of the model's context)
+*
+* ```ts
+* import * as Tool from "effect/ai/Tool"
+* import * as Schema from "effect/Schema"
+* import { ToolResult } from "effect-assistant"
+*
+* const Asset = Schema.Struct({ id: Schema.String, name: Schema.String, imageUrl: Schema.String })
+*
+* export const SearchAssets = ToolResult.modelView(
+*   Tool.make("search_assets", {
+*     parameters: Schema.Struct({ query: Schema.String }),
+*     success: Schema.Struct({ items: Schema.Array(Asset) })
+*   }),
+*   (result) => ({ items: result.items.map(({ id, name }) => ({ id, name })) })
+* )
+* ```
+*
+* @category annotations
+* @since 0.5.0
+*/
+const modelView = dual(2, (tool, view) => tool.annotate(ModelView, view));
+//#endregion
+export { ModelView, ToolResult_exports, modelView };
+
+//# sourceMappingURL=ToolResult.js.map

package/dist/ToolResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolResult.js","names":[],"sources":["../src/ToolResult.ts"],"sourcesContent":["/**\n * Shapes what the model reads of a tool's result.\n *\n * A tool's success goes into the chat's log in full. {@link modelView} gives the model a smaller\n * view of it, so fields only the app's UI needs (an image URL, a file id) stay out of its context\n * and out of what it might copy into its replies.\n *\n * A tool whose results the assistant's blocks show (`Block.fromToolResult`) also gets a `resultId`\n * in what the model reads. The model passes it in a `tool_result` block to show that result, and\n * the client draws it from the full result in the log.\n *\n * @since 0.5.0\n */\nimport type * as Tool from \"effect/ai/Tool\"\nimport * as Context from \"effect/Context\"\nimport { dual } from \"effect/Function\"\nimport type * as Schema from \"effect/Schema\"\n\n// The tool's schemas, as `Tool.Tool` constrains them.\ntype Schemas = {\n  readonly parameters: Schema.Top\n  readonly success: Schema.Top\n  readonly failure: Schema.Top\n  readonly failureMode: Tool.FailureMode\n}\n\n/**\n * Annotation for what the model reads of a tool's success, set with {@link modelView}.\n *\n * @category annotations\n * @since 0.5.0\n */\nexport class ModelView extends Context.Service<ModelView, (success: any) => Schema.Json>()(\n  \"effect-assistant/ToolResult/ModelView\"\n) {}\n\n/**\n * Sets what the model reads of a tool's success. The chat's log keeps the whole success.\n *\n * **Details**\n *\n * The view gets the success as the tool's success schema decodes it, and returns the JSON the\n * model reads instead. Failures reach the model as they are.\n *\n * **Example** (Keeping image URLs out of the model's context)\n *\n * ```ts\n * import * as Tool from \"effect/ai/Tool\"\n * import * as Schema from \"effect/Schema\"\n * import { ToolResult } from \"effect-assistant\"\n *\n * const Asset = Schema.Struct({ id: Schema.String, name: Schema.String, imageUrl: Schema.String })\n *\n * export const SearchAssets = ToolResult.modelView(\n *   Tool.make(\"search_assets\", {\n *     parameters: Schema.Struct({ query: Schema.String }),\n *     success: Schema.Struct({ items: Schema.Array(Asset) })\n *   }),\n *   (result) => ({ items: result.items.map(({ id, name }) => ({ id, name })) })\n * )\n * ```\n *\n * @category annotations\n * @since 0.5.0\n */\nexport const modelView: {\n  <Config extends Schemas>(\n    view: (success: Config[\"success\"][\"Type\"]) => Schema.Json\n  ): <Name extends string, R>(tool: Tool.Tool<Name, Config, R>) => Tool.Tool<Name, Config, R>\n  <Name extends string, Config extends Schemas, R>(\n    tool: Tool.Tool<Name, Config, R>,\n    view: (success: Config[\"success\"][\"Type\"]) => Schema.Json\n  ): Tool.Tool<Name, Config, R>\n} = dual(\n  2,\n  <Name extends string, Config extends Schemas, R>(\n    tool: Tool.Tool<Name, Config, R>,\n    view: (success: Config[\"success\"][\"Type\"]) => Schema.Json\n  ): Tool.Tool<Name, Config, R> => tool.annotate(ModelView, view)\n)\n"],"mappings":";;;;;;;;;;;;;;AAgCA,IAAa,YAAb,cAA+B,QAAQ,QAAkD,CAAC,CACxF,uCACF,CAAC,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BH,MAAa,YAQT,KACF,IAEE,MACA,SAC+B,KAAK,SAAS,WAAW,IAAI,CAChE"}

package/dist/index.d.ts

@@ -21,4 +21,5 @@ import { Memory_d_exports } from "./Memory.js";
 import { Skill_d_exports } from "./Skill.js";
 import { ToolApproval_d_exports } from "./ToolApproval.js";
 import { ToolDiscovery_d_exports } from "./ToolDiscovery.js";
-export { Assistant_d_exports as Assistant, AssistantActivity_d_exports as AssistantActivity, AssistantEngine_d_exports as AssistantEngine, AssistantEvent_d_exports as AssistantEvent, AssistantLoop_d_exports as AssistantLoop, AssistantToolCall_d_exports as AssistantToolCall, Block_d_exports as Block, BlockKit_d_exports as BlockKit, ChatId_d_exports as ChatId, ChatLog_d_exports as ChatLog, Chats_d_exports as Chats, Compaction_d_exports as Compaction, CurrentChat_d_exports as CurrentChat, InputId_d_exports as InputId, Instructions_d_exports as Instructions, Memory_d_exports as Memory, RunId_d_exports as RunId, Skill_d_exports as Skill, Specialist_d_exports as Specialist, Timeline_d_exports as Timeline, ToolApproval_d_exports as ToolApproval, ToolDiscovery_d_exports as ToolDiscovery, ToolFailure_d_exports as ToolFailure };
+import { ToolResult_d_exports } from "./ToolResult.js";
+export { Assistant_d_exports as Assistant, AssistantActivity_d_exports as AssistantActivity, AssistantEngine_d_exports as AssistantEngine, AssistantEvent_d_exports as AssistantEvent, AssistantLoop_d_exports as AssistantLoop, AssistantToolCall_d_exports as AssistantToolCall, Block_d_exports as Block, BlockKit_d_exports as BlockKit, ChatId_d_exports as ChatId, ChatLog_d_exports as ChatLog, Chats_d_exports as Chats, Compaction_d_exports as Compaction, CurrentChat_d_exports as CurrentChat, InputId_d_exports as InputId, Instructions_d_exports as Instructions, Memory_d_exports as Memory, RunId_d_exports as RunId, Skill_d_exports as Skill, Specialist_d_exports as Specialist, Timeline_d_exports as Timeline, ToolApproval_d_exports as ToolApproval, ToolDiscovery_d_exports as ToolDiscovery, ToolFailure_d_exports as ToolFailure, ToolResult_d_exports as ToolResult };

package/dist/index.js

@@ -9,16 +9,17 @@ import { Specialist_exports } from "./Specialist.js";
 import { ToolApproval_exports } from "./ToolApproval.js";
 import { AssistantToolCall_exports } from "./AssistantToolCall.js";
 import { ToolFailure_exports } from "./ToolFailure.js";
+import { ToolResult_exports } from "./ToolResult.js";
+import { Block_exports } from "./Block.js";
+import { BlockKit_exports } from "./BlockKit.js";
 import { Instructions_exports } from "./Instructions.js";
 import { AssistantEngine_exports } from "./AssistantEngine.js";
 import { Assistant_exports } from "./Assistant.js";
 import { AssistantActivity_exports } from "./AssistantActivity.js";
 import { AssistantLoop_exports } from "./AssistantLoop.js";
-import { Block_exports } from "./Block.js";
-import { BlockKit_exports } from "./BlockKit.js";
 import { Compaction_exports } from "./Compaction.js";
 import { Memory_exports } from "./Memory.js";
 import { Skill_exports } from "./Skill.js";
 import { Timeline_exports } from "./Timeline.js";
 import { ToolDiscovery_exports } from "./ToolDiscovery.js";
-export { Assistant_exports as Assistant, AssistantActivity_exports as AssistantActivity, AssistantEngine_exports as AssistantEngine, AssistantEvent_exports as AssistantEvent, AssistantLoop_exports as AssistantLoop, AssistantToolCall_exports as AssistantToolCall, Block_exports as Block, BlockKit_exports as BlockKit, ChatId_exports as ChatId, ChatLog_exports as ChatLog, Chats_exports as Chats, Compaction_exports as Compaction, CurrentChat_exports as CurrentChat, InputId_exports as InputId, Instructions_exports as Instructions, Memory_exports as Memory, RunId_exports as RunId, Skill_exports as Skill, Specialist_exports as Specialist, Timeline_exports as Timeline, ToolApproval_exports as ToolApproval, ToolDiscovery_exports as ToolDiscovery, ToolFailure_exports as ToolFailure };
+export { Assistant_exports as Assistant, AssistantActivity_exports as AssistantActivity, AssistantEngine_exports as AssistantEngine, AssistantEvent_exports as AssistantEvent, AssistantLoop_exports as AssistantLoop, AssistantToolCall_exports as AssistantToolCall, Block_exports as Block, BlockKit_exports as BlockKit, ChatId_exports as ChatId, ChatLog_exports as ChatLog, Chats_exports as Chats, Compaction_exports as Compaction, CurrentChat_exports as CurrentChat, InputId_exports as InputId, Instructions_exports as Instructions, Memory_exports as Memory, RunId_exports as RunId, Skill_exports as Skill, Specialist_exports as Specialist, Timeline_exports as Timeline, ToolApproval_exports as ToolApproval, ToolDiscovery_exports as ToolDiscovery, ToolFailure_exports as ToolFailure, ToolResult_exports as ToolResult };

package/dist/internal/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","names":[],"sources":["../../src/internal/loop.ts"],"mappings":";;;;;;;;;;;;;;;YAuBY,QACR,cACA,cACA,aACA;;qBAKS,eAAa,QAAA,UAAA,OAAA;WACW,UAAA,OAAO,OAAO,cAAc;;;qBAMpD,WAAS,QAAA,UAAA,OAAA,OAAA;;iBAKL;WACN,UAAU,cAAc,OAAO;WAC/B;;;iBAUM,YAAY;WAClB,uBAAuB;WACvB,UAAU,MAAe;WACzB,SAAS,OAAO,OAAO,cAAc,OAAO,WAAW;WACvD,aAAa,cAAc;;;iBAIrB,QAAQ,mBAAmB,YAAY;WAC7C;;;iBAKM;;WAEN,QAAQ;;;;;;WAMR;;;;WAIA;;;YA4HC,KAAK,GAAG,KAAK,KAAK;EAC5B;aAAkB,OAAO;;EACzB;aAAiB,OAAO;;EACxB,MAAM;;;qBAUK,QAAS,GAAC,OAAS,MAAI,KAAK;;qBAG5B,OAAQ,GAAC,OAAS,MAAI,OAAO,OAAO,YAAY;;qBAIhD,OAAQ,gBAAc,OAAO,OAAO,YAAY;;qBAOhD,OAAQ,GAAG,GAAG,GAAG,GAAC,SACpB,GAAC,OACH,OAAO,MAAM,OAAO,OAAO,KAAK,GAAG,IAAI,GAAG,OAChD,OAAO,OAAO,GAAG,GAAG;;qBAmBV,OAAQ,GAAG,GAAG,YAAY,YAAU,SACtC,YAAY,IAAE,OAChB,QAAQ,eAAe,OAAO,OAAO,YAAY,IAAI,IAAI,QAC/D,OAAO,OAAO,KAAK,OAAO,IAAI,QAAQ,UAAU,IAAI,cAAc,gBAAgB,IAAI;;qBA6E5E,MAAO,WAAS,SAClB,QAAQ,OAChB,OAAO,OAAO,OAAO,QAAQ,SAAS,cAAc,gBAAgB"}
+{"version":3,"file":"loop.d.ts","names":[],"sources":["../../src/internal/loop.ts"],"mappings":";;;;;;;;;;;;;;;YAuBY,QACR,cACA,cACA,aACA;;qBAKS,eAAa,QAAA,UAAA,OAAA;WACW,UAAA,OAAO,OAAO,cAAc;;;qBAMpD,WAAS,QAAA,UAAA,OAAA,OAAA;;iBAKL;WACN,UAAU,cAAc,OAAO;WAC/B;;;iBAUM,YAAY;WAClB,uBAAuB;WACvB,UAAU,MAAe;WACzB,SAAS,OAAO,OAAO,cAAc,OAAO,WAAW;WACvD,aAAa,cAAc;;;iBAIrB,QAAQ,mBAAmB,YAAY;WAC7C;;;iBAKM;;WAEN,QAAQ;;;;;;WAMR;;;;WAIA;;;YA6IC,KAAK,GAAG,KAAK,KAAK;EAC5B;aAAkB,OAAO;;EACzB;aAAiB,OAAO;;EACxB,MAAM;;;qBAUK,QAAS,GAAC,OAAS,MAAI,KAAK;;qBAG5B,OAAQ,GAAC,OAAS,MAAI,OAAO,OAAO,YAAY;;qBAIhD,OAAQ,gBAAc,OAAO,OAAO,YAAY;;qBAOhD,OAAQ,GAAG,GAAG,GAAG,GAAC,SACpB,GAAC,OACH,OAAO,MAAM,OAAO,OAAO,KAAK,GAAG,IAAI,GAAG,OAChD,OAAO,OAAO,GAAG,GAAG;;qBAmBV,OAAQ,GAAG,GAAG,YAAY,YAAU,SACtC,YAAY,IAAE,OAChB,QAAQ,eAAe,OAAO,OAAO,YAAY,IAAI,IAAI,QAC/D,OAAO,OAAO,KAAK,OAAO,IAAI,QAAQ,UAAU,IAAI,cAAc,gBAAgB,IAAI;;qBA6E5E,MAAO,WAAS,SAClB,QAAQ,OAChB,OAAO,OAAO,OAAO,QAAQ,SAAS,cAAc,gBAAgB"}

package/dist/internal/loop.js

@@ -2,7 +2,7 @@ import { ApprovalRequested, ModelOutput, ModelPart, ToolResult, ToolStarted } fr
 import { unansweredCalls } from "./history.js";
 import { chatSpan, toolOutput, toolSpan } from "./telemetry.js";
 import { empty, failed } from "./toolkit.js";
-import { isTurnEnding } from "./tools.js";
+import { isTurnEnding, isUserMessage } from "./tools.js";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Predicate from "effect/Predicate";
@@ -62,6 +62,11 @@ const awaitApproval = Effect.fnUntraced(function* (call) {
 		params: call.params
 	});
 });
+const unexplained = (call) => ToolResult.make({
+	callId: call.id,
+	tool: call.name,
+	...failed(`Not sent for approval: the user would see buttons without knowing what they approve. In one step, send them a message with send_user_message saying what ${call.name} will do (what, to whom, how many), and call ${call.name} again.`, "ApprovalNeedsMessage")
+});
 const runCalls = (tools, pending, history, then) => Stream.unwrap(Effect.gen(function* () {
 	const waits = yield* Effect.forEach(pending, ({ call, approved }) => approved ? Effect.succeed(false) : tools.needsApproval(call, history));
 	const started = pending.flatMap(({ call }, i) => waits[i] === true ? [] : [value(ToolStarted.make({
@@ -69,7 +74,8 @@ const runCalls = (tools, pending, history, then) => Stream.unwrap(Effect.gen(fun
 		tool: call.name
 	}))]);
 	return Stream.fromIterable(started).pipe(Stream.concat(Stream.unwrap(Effect.gen(function* () {
-		const done = yield* Effect.forEach(pending, ({ call }, i) => waits[i] === true ? awaitApproval(call) : runCall(tools, call), { concurrency: "unbounded" });
+		const explained = pending.some(({ call }) => isUserMessage(call));
+		const done = yield* Effect.forEach(pending, ({ call }, i) => waits[i] !== true ? runCall(tools, call) : explained ? awaitApproval(call) : Effect.succeed(unexplained(call)), { concurrency: "unbounded" });
 		return Stream.fromIterable(done.map(value)).pipe(Stream.concat(then({
 			failed: done.some(isFailure),
 			waiting: done.some((event) => Predicate.isTagged(event, "ApprovalRequested"))