effect-assistant 0.0.0-stage → 0.2.0

package/dist/AssistantEvent.js

@@ -0,0 +1,473 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { ChatId } from "./ChatId.js";
+import { InputId, make } from "./InputId.js";
+import { RunId } from "./RunId.js";
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+import * as Response from "effect/ai/Response";
+//#region src/AssistantEvent.ts
+/**
+* Defines the events that can happen in a chat.
+*
+* A chat is an append-only log of these events, and the log is the source of truth. A chat client
+* receives the part of the log its user sees (`ChatView`), and the model's history is rebuilt
+* from the log before every model call. Besides the library's events ({@link AssistantEvent}), a
+* log holds the application's own events ({@link StoredAppEvent}).
+*
+* @since 0.1.0
+*/
+var AssistantEvent_exports = /* @__PURE__ */ __exportAll({
+	AppTag: () => AppTag,
+	AssistantEvent: () => AssistantEvent,
+	AssistantMessage: () => AssistantMessage,
+	Attachment: () => Attachment,
+	BlockAnswer: () => BlockAnswer,
+	BlocksClosed: () => BlocksClosed,
+	ChatDeleted: () => ChatDeleted,
+	Entry: () => Entry,
+	Input: () => Input,
+	MessageBlock: () => MessageBlock,
+	ModelOutput: () => ModelOutput,
+	ModelPart: () => ModelPart,
+	SpecialistFinished: () => SpecialistFinished,
+	SpecialistStarted: () => SpecialistStarted,
+	StoredAppEvent: () => StoredAppEvent,
+	ToolCallPart: () => ToolCallPart,
+	ToolOutcome: () => ToolOutcome,
+	ToolResult: () => ToolResult,
+	ToolStarted: () => ToolStarted,
+	TurnCompleted: () => TurnCompleted,
+	TurnFailed: () => TurnFailed,
+	TurnStarted: () => TurnStarted,
+	UserInput: () => UserInput,
+	UserMessage: () => UserMessage,
+	assistantTexts: () => assistantTexts,
+	attachmentLine: () => attachmentLine,
+	formatSize: () => formatSize,
+	isInput: () => isInput,
+	isLibraryEvent: () => isLibraryEvent,
+	isTurnEnd: () => isTurnEnd,
+	isUserInput: () => isUserInput,
+	isWaking: () => isWaking,
+	maxAttachments: () => 10,
+	textWithAttachments: () => textWithAttachments
+});
+/**
+* Schema for a file the user attached to a message, kept by reference.
+*
+* The file itself is stored elsewhere, so the log never holds its bytes.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const Attachment = Schema.Struct({
+	fileId: Schema.String.check(Schema.isMaxLength(64)),
+	name: Schema.String.check(Schema.isMaxLength(255)),
+	mediaType: Schema.String.check(Schema.isMaxLength(127)),
+	/** In bytes. */
+	size: Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0))
+});
+/**
+* The maximum number of files one message can carry.
+*
+* Each attached file is a line in every prompt after the message.
+*
+* @category utils
+* @since 0.1.0
+*/
+const maxAttachments = 10;
+/**
+* Formats a byte count for people and the model, such as `2.1 MB`.
+*
+* @category utils
+* @since 0.1.0
+*/
+const formatSize = (bytes) => bytes < 1024 ? `${bytes} B` : bytes < 1048576 ? `${(bytes / 1024).toFixed(1)} KB` : bytes < 1073741824 ? `${(bytes / 1048576).toFixed(1)} MB` : `${(bytes / 1073741824).toFixed(1)} GB`;
+/**
+* Returns the line the model reads for an attachment.
+*
+* The line names the file and never holds its content.
+*
+* @category utils
+* @since 0.1.0
+*/
+const attachmentLine = (attachment) => `[attached: ${attachment.name}, ${attachment.mediaType}, ${formatSize(attachment.size)}, id ${attachment.fileId}]`;
+/**
+* Returns a message's text followed by a line for each attached file.
+*
+* @category utils
+* @since 0.1.0
+*/
+const textWithAttachments = (text, attachments) => attachments === void 0 || attachments.length === 0 ? text : [text, ...attachments.map(attachmentLine)].filter((part) => part.length > 0).join("\n");
+/**
+* Represents text the user typed, and the files they attached.
+*
+* `id` defaults to a new one. Pass the client's own id so that a retried send stores the message
+* once.
+*
+* @category schemas
+* @since 0.1.0
+*/
+var UserMessage = class extends Schema.TaggedClass()("UserMessage", {
+	id: InputId.pipe(Schema.withConstructorDefault(make())),
+	text: Schema.String,
+	attachments: Schema.optional(Schema.Array(Attachment).check(Schema.isMaxLength(10)))
+}) {};
+/**
+* Represents the user's answer to a block.
+*
+* It holds the id of the message the block was on, and the value in the block's answer schema
+* (in its JSON form). A chat UI shows it inside the block rather than as a message.
+*
+* @category schemas
+* @since 0.1.0
+*/
+var BlockAnswer = class extends Schema.TaggedClass()("BlockAnswer", {
+	id: InputId,
+	messageId: Schema.String,
+	kind: Schema.String,
+	value: Schema.Unknown
+}) {};
+/**
+* Represents a specialist run that finished working on a brief.
+*
+* Unless the assistant stopped the run, it is an input, and a turn reads its report and decides
+* what to tell the user. Its id is fixed per run and brief, so it is stored once.
+*
+* @category schemas
+* @since 0.1.0
+*/
+var SpecialistFinished = class extends Schema.TaggedClass()("SpecialistFinished", {
+	id: InputId,
+	runId: RunId,
+	specialist: Schema.String,
+	/** Which brief this answers: 1 for the first, then one more per follow-up. */
+	brief: Schema.Int,
+	goal: Schema.String,
+	status: Schema.Literals([
+		"answered",
+		"failed",
+		"stopped",
+		"cut_off"
+	]),
+	report: Schema.optional(Schema.String),
+	error: Schema.optional(Schema.String)
+}) {};
+/**
+* Schema for every input `Assistant.submit` accepts.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const Input = Schema.Union([
+	UserMessage,
+	BlockAnswer,
+	SpecialistFinished
+]);
+/**
+* Schema for the inputs from the chat's user, which are messages and block answers.
+*
+* A turn owes each one a reply. It is also what a chat client usually may submit, since the app's
+* events come from the server.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const UserInput = Schema.Union([UserMessage, BlockAnswer]);
+/**
+* Represents the UI shown with a message, as a block kind from the assistant's `BlockKit` and its
+* props.
+*
+* @category schemas
+* @since 0.1.0
+*/
+var MessageBlock = class extends Schema.Class("effect-assistant/MessageBlock")({
+	kind: Schema.String,
+	props: Schema.Unknown
+}) {};
+/**
+* Represents a message the assistant sent the user with `send_user_message`, optionally with a
+* block.
+*
+* @category schemas
+* @since 0.1.0
+*/
+var AssistantMessage = class extends Schema.TaggedClass()("AssistantMessage", {
+	id: Schema.String,
+	text: Schema.String,
+	block: Schema.optional(MessageBlock),
+	/** Earlier messages whose block the user answered by typing instead. Their blocks close. */
+	closes: Schema.optional(Schema.Array(Schema.String))
+}) {};
+/**
+* Schema for a tool call the model made.
+*
+* It is `effect/ai`'s tool call part (`Response.ToolCallPart`) for any tool, with its params in
+* JSON, as the model wrote them.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const ToolCallPart = Schema.Struct({
+	...Response.ToolCallPart("", Schema.Json).fields,
+	name: Schema.String
+}).annotate({ identifier: "ToolCallPart" });
+/**
+* Schema for what the log keeps of a model call.
+*
+* It uses `effect/ai`'s response parts for text, reasoning (with the provider's metadata, such as
+* a thinking block's signature), and tool calls.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const ModelPart = Schema.Union([
+	Response.TextPart,
+	Response.ReasoningPart,
+	ToolCallPart
+]);
+/**
+* Represents what one model call wrote, as response parts for text, reasoning, and tool calls.
+*
+* `Prompt.fromResponseParts` turns the parts into history.
+*
+* @category schemas
+* @since 0.1.0
+*/
+var ModelOutput = class extends Schema.TaggedClass()("ModelOutput", {
+	parts: Schema.Array(ModelPart),
+	/**
+	* The last entry the model had read when it wrote this. Inputs after it
+	* arrived while the model was working. A turn has handled what its
+	* outputs had read.
+	*/
+	seenThroughSeq: Schema.optional(Schema.Int),
+	/** The model that wrote it, as the provider's id for it or the name the context gave it. */
+	model: Schema.optional(Schema.String),
+	/** The provider's id for the response, when it gives one. */
+	responseId: Schema.optional(Schema.String),
+	/** The call's token usage, with input (including the cache's reads and writes) and output. */
+	usage: Schema.optional(Response.Usage),
+	/** How long the call took, in milliseconds. */
+	durationMillis: Schema.optional(Schema.Finite)
+}) {};
+/**
+* Represents a tool call that is about to run.
+*
+* It is stored before the tool runs, so after a crash the log says which calls may have done
+* something. Those calls run again with the same call id (see `AssistantToolCall`).
+*
+* @category schemas
+* @since 0.1.0
+*/
+var ToolStarted = class extends Schema.TaggedClass()("ToolStarted", {
+	callId: Schema.String,
+	tool: Schema.String
+}) {};
+/**
+* Schema for how a tool call went, either `"success"` or `"failure"`, which the model reads as an
+* error.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const ToolOutcome = Schema.Literals(["success", "failure"]);
+/**
+* Represents the result of one tool call, as the model reads it.
+*
+* It holds the tool's success or failure in its encoded (JSON) form, and which of the two it is. A
+* failure includes its reason when it has one, which is a `ToolFailure`'s `reason` or the
+* failure's tag.
+*
+* @category schemas
+* @since 0.1.0
+*/
+var ToolResult = class extends Schema.TaggedClass()("ToolResult", {
+	callId: Schema.String,
+	tool: Schema.String,
+	outcome: ToolOutcome,
+	result: Schema.Json,
+	reason: Schema.optional(Schema.String)
+}) {};
+/**
+* Represents the start of a turn.
+*
+* @category schemas
+* @since 0.1.0
+*/
+var TurnStarted = class extends Schema.TaggedClass()("TurnStarted", {
+	/** The assistant that runs it. */
+	assistant: Schema.String,
+	/**
+	* The id of the turn's trace, when a tracer records it (not Effect's own, which exports nothing).
+	*/
+	traceId: Schema.optional(Schema.String)
+}) {};
+/**
+* Represents a turn that finished.
+*
+* `throughSeq` is the last entry the turn read. Inputs after it still need a turn.
+*
+* @category schemas
+* @since 0.1.0
+*/
+var TurnCompleted = class extends Schema.TaggedClass()("TurnCompleted", { throughSeq: Schema.Int }) {};
+/**
+* Represents a turn that failed.
+*
+* `throughSeq` covers everything stored when the turn failed, so a failing input isn't retried
+* forever.
+*
+* @category schemas
+* @since 0.1.0
+*/
+var TurnFailed = class extends Schema.TaggedClass()("TurnFailed", {
+	throughSeq: Schema.Int,
+	message: Schema.String
+}) {};
+/**
+* Represents a specialist run that started working, either spawned or continued by a follow-up
+* message.
+*
+* The model doesn't see it, since the call that started the run says so, and the run's report
+* arrives as a {@link SpecialistFinished}.
+*
+* @category schemas
+* @since 0.1.0
+*/
+var SpecialistStarted = class extends Schema.TaggedClass()("SpecialistStarted", {
+	runId: RunId,
+	specialist: Schema.String,
+	/** The goal it's working on. */
+	goal: Schema.String
+}) {};
+/**
+* Represents the deletion of a chat.
+*
+* The chat stores nothing after it, the work running in the chat stopped, and its subscribers'
+* streams end here. Its log stays.
+*
+* @category schemas
+* @since 0.1.0
+*/
+var ChatDeleted = class extends Schema.TaggedClass()("ChatDeleted", {}) {};
+/**
+* Represents blocks that closed without an answer, like the ones `BlockKit.closeStale` closes
+* from a turn once the user moved on.
+*
+* The model doesn't see it.
+*
+* @category schemas
+* @since 0.1.0
+*/
+var BlocksClosed = class extends Schema.TaggedClass()("BlocksClosed", { messageIds: Schema.Array(Schema.String) }) {};
+/**
+* Schema for every event the library defines.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const AssistantEvent = Schema.Union([
+	UserMessage,
+	BlockAnswer,
+	AssistantMessage,
+	ModelOutput,
+	ToolStarted,
+	ToolResult,
+	TurnStarted,
+	TurnCompleted,
+	TurnFailed,
+	SpecialistStarted,
+	SpecialistFinished,
+	BlocksClosed,
+	ChatDeleted
+]);
+const libraryTags = new Set(AssistantEvent.members.map((member) => member.fields._tag.schema.literal));
+/**
+* Schema for the tag of one of the application's own events.
+*
+* It accepts any tag but the library's, and it is branded, so narrowing an entry's event to one
+* of the library's events (`Predicate.isTagged(event, "UserMessage")`) never leaves an app event
+* in.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const AppTag = Schema.String.pipe(Schema.brand("~effect-assistant/AppTag"));
+/**
+* Schema for one of the application's own events as it is stored, with its `_tag` and its fields
+* in JSON.
+*
+* An assistant made with `events: [AppEvent.make(Summary)]` decodes it to a `Summary` in
+* `CurrentChat`'s `entries` and in its `subscribe`.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const StoredAppEvent = Schema.StructWithRest(Schema.Struct({ _tag: AppTag }), [Schema.Record(Schema.String, Schema.Json)]).check(Schema.makeFilter((event) => !libraryTags.has(event._tag) || `${event._tag} is one of the library's events`));
+/**
+* Returns whether an event is one of the library's, not one of the app's own.
+*
+* @category guards
+* @since 0.1.0
+*/
+const isLibraryEvent = (event) => libraryTags.has(event._tag);
+/**
+* Schema for a stored event with its position in the chat.
+*
+* `seq` starts at 1 and has no gaps. `at` is the time the event was stored, in epoch
+* milliseconds.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const Entry = Schema.Struct({
+	chatId: ChatId,
+	seq: Schema.Int,
+	at: Schema.Finite,
+	event: Schema.Union([AssistantEvent, StoredAppEvent])
+});
+/**
+* Returns whether an event is one of the library's inputs, which are a user message, a block
+* answer, or a finished specialist run.
+*
+* The application's events that wake a turn are inputs too, but only their assistant knows which
+* (see `AppEvent`).
+*
+* @category guards
+* @since 0.1.0
+*/
+const isInput = (event) => Predicate.isTagged(event, "UserMessage") || Predicate.isTagged(event, "BlockAnswer") || Predicate.isTagged(event, "SpecialistFinished");
+/**
+* Returns whether an input starts a turn, which every input does except a run the assistant
+* stopped itself.
+*
+* @category guards
+* @since 0.1.0
+*/
+const isWaking = (input) => !(Predicate.isTagged(input, "SpecialistFinished") && input.status === "stopped");
+/**
+* Returns whether an input came from the chat's user, and so is owed a reply.
+*
+* @category guards
+* @since 0.1.0
+*/
+const isUserInput = (input) => Predicate.isTagged(input, "UserMessage") || Predicate.isTagged(input, "BlockAnswer");
+/**
+* Returns whether an event ends a turn, and so says how far the assistant has read.
+*
+* @category guards
+* @since 0.1.0
+*/
+const isTurnEnd = (event) => Predicate.isTagged(event, "TurnCompleted") || Predicate.isTagged(event, "TurnFailed");
+/**
+* Returns the text of every message the user was shown, in order.
+*
+* @category utils
+* @since 0.1.0
+*/
+const assistantTexts = (entries) => entries.flatMap(({ event }) => isLibraryEvent(event) && Predicate.isTagged(event, "AssistantMessage") ? [event.text] : []);
+//#endregion
+export { AppTag, AssistantEvent, AssistantEvent_exports, AssistantMessage, Attachment, BlockAnswer, BlocksClosed, ChatDeleted, Entry, Input, MessageBlock, ModelOutput, ModelPart, SpecialistFinished, SpecialistStarted, StoredAppEvent, ToolCallPart, ToolOutcome, ToolResult, ToolStarted, TurnCompleted, TurnFailed, TurnStarted, UserInput, UserMessage, assistantTexts, attachmentLine, formatSize, isInput, isLibraryEvent, isTurnEnd, isUserInput, isWaking, maxAttachments, textWithAttachments };
+
+//# sourceMappingURL=AssistantEvent.js.map

package/dist/AssistantEvent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssistantEvent.js","names":["makeInputId"],"sources":["../src/AssistantEvent.ts"],"sourcesContent":["/**\n * Defines the events that can happen in a chat.\n *\n * A chat is an append-only log of these events, and the log is the source of truth. A chat client\n * receives the part of the log its user sees (`ChatView`), and the model's history is rebuilt\n * from the log before every model call. Besides the library's events ({@link AssistantEvent}), a\n * log holds the application's own events ({@link StoredAppEvent}).\n *\n * @since 0.1.0\n */\nimport * as Response from \"effect/ai/Response\"\nimport * as Predicate from \"effect/Predicate\"\nimport * as Schema from \"effect/Schema\"\nimport { ChatId } from \"./ChatId.ts\"\nimport { InputId, make as makeInputId } from \"./InputId.ts\"\nimport { RunId } from \"./RunId.ts\"\n\n/**\n * Schema for a file the user attached to a message, kept by reference.\n *\n * The file itself is stored elsewhere, so the log never holds its bytes.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const Attachment = Schema.Struct({\n  fileId: Schema.String.check(Schema.isMaxLength(64)),\n  name: Schema.String.check(Schema.isMaxLength(255)),\n  mediaType: Schema.String.check(Schema.isMaxLength(127)),\n  /** In bytes. */\n  size: Schema.Finite.check(Schema.isGreaterThanOrEqualTo(0))\n})\n\n/**\n * The maximum number of files one message can carry.\n *\n * Each attached file is a line in every prompt after the message.\n *\n * @category utils\n * @since 0.1.0\n */\nexport const maxAttachments = 10\n\n/**\n * Represents a file the user attached to a message.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Attachment = typeof Attachment.Type\n\n/**\n * Formats a byte count for people and the model, such as `2.1 MB`.\n *\n * @category utils\n * @since 0.1.0\n */\nexport const formatSize = (bytes: number): string =>\n  bytes < 1024\n    ? `${bytes} B`\n    : bytes < 1024 * 1024\n      ? `${(bytes / 1024).toFixed(1)} KB`\n      : bytes < 1024 * 1024 * 1024\n        ? `${(bytes / (1024 * 1024)).toFixed(1)} MB`\n        : `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`\n\n/**\n * Returns the line the model reads for an attachment.\n *\n * The line names the file and never holds its content.\n *\n * @category utils\n * @since 0.1.0\n */\nexport const attachmentLine = (attachment: Attachment): string =>\n  `[attached: ${attachment.name}, ${attachment.mediaType}, ${formatSize(attachment.size)}, id ${attachment.fileId}]`\n\n/**\n * Returns a message's text followed by a line for each attached file.\n *\n * @category utils\n * @since 0.1.0\n */\nexport const textWithAttachments = (text: string, attachments: ReadonlyArray<Attachment> | undefined): string =>\n  attachments === undefined || attachments.length === 0\n    ? text\n    : [text, ...attachments.map(attachmentLine)].filter((part) => part.length > 0).join(\"\\n\")\n\n/**\n * Represents text the user typed, and the files they attached.\n *\n * `id` defaults to a new one. Pass the client's own id so that a retried send stores the message\n * once.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport class UserMessage extends Schema.TaggedClass<UserMessage>()(\"UserMessage\", {\n  id: InputId.pipe(Schema.withConstructorDefault(makeInputId())),\n  text: Schema.String,\n  attachments: Schema.optional(Schema.Array(Attachment).check(Schema.isMaxLength(maxAttachments)))\n}) {}\n\n/**\n * Represents the user's answer to a block.\n *\n * It holds the id of the message the block was on, and the value in the block's answer schema\n * (in its JSON form). A chat UI shows it inside the block rather than as a message.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport class BlockAnswer extends Schema.TaggedClass<BlockAnswer>()(\"BlockAnswer\", {\n  id: InputId,\n  messageId: Schema.String,\n  kind: Schema.String,\n  value: Schema.Unknown\n}) {}\n\n/**\n * Represents a specialist run that finished working on a brief.\n *\n * Unless the assistant stopped the run, it is an input, and a turn reads its report and decides\n * what to tell the user. Its id is fixed per run and brief, so it is stored once.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport class SpecialistFinished extends Schema.TaggedClass<SpecialistFinished>()(\"SpecialistFinished\", {\n  id: InputId,\n  runId: RunId,\n  specialist: Schema.String,\n  /** Which brief this answers: 1 for the first, then one more per follow-up. */\n  brief: Schema.Int,\n  goal: Schema.String,\n  status: Schema.Literals([\"answered\", \"failed\", \"stopped\", \"cut_off\"]),\n  report: Schema.optional(Schema.String),\n  error: Schema.optional(Schema.String)\n}) {}\n\n/**\n * Schema for every input `Assistant.submit` accepts.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const Input = Schema.Union([UserMessage, BlockAnswer, SpecialistFinished])\n\n/**\n * Represents an input to an assistant.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Input = typeof Input.Type\n\n/**\n * Schema for the inputs from the chat's user, which are messages and block answers.\n *\n * A turn owes each one a reply. It is also what a chat client usually may submit, since the app's\n * events come from the server.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const UserInput = Schema.Union([UserMessage, BlockAnswer])\n\n/**\n * Represents an input from the chat's user.\n *\n * @category models\n * @since 0.1.0\n */\nexport type UserInput = typeof UserInput.Type\n\n/**\n * Represents the UI shown with a message, as a block kind from the assistant's `BlockKit` and its\n * props.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport class MessageBlock extends Schema.Class<MessageBlock>(\"effect-assistant/MessageBlock\")({\n  kind: Schema.String,\n  props: Schema.Unknown\n}) {}\n\n/**\n * Represents a message the assistant sent the user with `send_user_message`, optionally with a\n * block.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport class AssistantMessage extends Schema.TaggedClass<AssistantMessage>()(\"AssistantMessage\", {\n  id: Schema.String,\n  text: Schema.String,\n  block: Schema.optional(MessageBlock),\n  /** Earlier messages whose block the user answered by typing instead. Their blocks close. */\n  closes: Schema.optional(Schema.Array(Schema.String))\n}) {}\n\n/**\n * Schema for a tool call the model made.\n *\n * It is `effect/ai`'s tool call part (`Response.ToolCallPart`) for any tool, with its params in\n * JSON, as the model wrote them.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const ToolCallPart = Schema.Struct({\n  ...Response.ToolCallPart(\"\", Schema.Json).fields,\n  name: Schema.String\n}).annotate({ identifier: \"ToolCallPart\" })\n\n/**\n * Represents a tool call the model made.\n *\n * @category models\n * @since 0.1.0\n */\nexport type ToolCallPart = typeof ToolCallPart.Type\n\n/**\n * Schema for what the log keeps of a model call.\n *\n * It uses `effect/ai`'s response parts for text, reasoning (with the provider's metadata, such as\n * a thinking block's signature), and tool calls.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const ModelPart = Schema.Union([Response.TextPart, Response.ReasoningPart, ToolCallPart])\n\n/**\n * Represents a part of a model call's output.\n *\n * @category models\n * @since 0.1.0\n */\nexport type ModelPart = typeof ModelPart.Type\n\n/**\n * Represents what one model call wrote, as response parts for text, reasoning, and tool calls.\n *\n * `Prompt.fromResponseParts` turns the parts into history.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport class ModelOutput extends Schema.TaggedClass<ModelOutput>()(\"ModelOutput\", {\n  parts: Schema.Array(ModelPart),\n  /**\n   * The last entry the model had read when it wrote this. Inputs after it\n   * arrived while the model was working. A turn has handled what its\n   * outputs had read.\n   */\n  seenThroughSeq: Schema.optional(Schema.Int),\n  /** The model that wrote it, as the provider's id for it or the name the context gave it. */\n  model: Schema.optional(Schema.String),\n  /** The provider's id for the response, when it gives one. */\n  responseId: Schema.optional(Schema.String),\n  /** The call's token usage, with input (including the cache's reads and writes) and output. */\n  usage: Schema.optional(Response.Usage),\n  /** How long the call took, in milliseconds. */\n  durationMillis: Schema.optional(Schema.Finite)\n}) {}\n\n/**\n * Represents a tool call that is about to run.\n *\n * It is stored before the tool runs, so after a crash the log says which calls may have done\n * something. Those calls run again with the same call id (see `AssistantToolCall`).\n *\n * @category schemas\n * @since 0.1.0\n */\nexport class ToolStarted extends Schema.TaggedClass<ToolStarted>()(\"ToolStarted\", {\n  callId: Schema.String,\n  tool: Schema.String\n}) {}\n\n/**\n * Schema for how a tool call went, either `\"success\"` or `\"failure\"`, which the model reads as an\n * error.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const ToolOutcome = Schema.Literals([\"success\", \"failure\"])\n\n/**\n * Represents how a tool call went.\n *\n * @category models\n * @since 0.1.0\n */\nexport type ToolOutcome = typeof ToolOutcome.Type\n\n/**\n * Represents the result of one tool call, as the model reads it.\n *\n * It holds the tool's success or failure in its encoded (JSON) form, and which of the two it is. A\n * failure includes its reason when it has one, which is a `ToolFailure`'s `reason` or the\n * failure's tag.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport class ToolResult extends Schema.TaggedClass<ToolResult>()(\"ToolResult\", {\n  callId: Schema.String,\n  tool: Schema.String,\n  outcome: ToolOutcome,\n  result: Schema.Json,\n  reason: Schema.optional(Schema.String)\n}) {}\n\n/**\n * Represents the start of a turn.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport class TurnStarted extends Schema.TaggedClass<TurnStarted>()(\"TurnStarted\", {\n  /** The assistant that runs it. */\n  assistant: Schema.String,\n  /**\n   * The id of the turn's trace, when a tracer records it (not Effect's own, which exports nothing).\n   */\n  traceId: Schema.optional(Schema.String)\n}) {}\n\n/**\n * Represents a turn that finished.\n *\n * `throughSeq` is the last entry the turn read. Inputs after it still need a turn.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport class TurnCompleted extends Schema.TaggedClass<TurnCompleted>()(\"TurnCompleted\", {\n  throughSeq: Schema.Int\n}) {}\n\n/**\n * Represents a turn that failed.\n *\n * `throughSeq` covers everything stored when the turn failed, so a failing input isn't retried\n * forever.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport class TurnFailed extends Schema.TaggedClass<TurnFailed>()(\"TurnFailed\", {\n  throughSeq: Schema.Int,\n  message: Schema.String\n}) {}\n\n/**\n * Represents a specialist run that started working, either spawned or continued by a follow-up\n * message.\n *\n * The model doesn't see it, since the call that started the run says so, and the run's report\n * arrives as a {@link SpecialistFinished}.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport class SpecialistStarted extends Schema.TaggedClass<SpecialistStarted>()(\"SpecialistStarted\", {\n  runId: RunId,\n  specialist: Schema.String,\n  /** The goal it's working on. */\n  goal: Schema.String\n}) {}\n\n/**\n * Represents the deletion of a chat.\n *\n * The chat stores nothing after it, the work running in the chat stopped, and its subscribers'\n * streams end here. Its log stays.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport class ChatDeleted extends Schema.TaggedClass<ChatDeleted>()(\"ChatDeleted\", {}) {}\n\n/**\n * Represents blocks that closed without an answer, like the ones `BlockKit.closeStale` closes\n * from a turn once the user moved on.\n *\n * The model doesn't see it.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport class BlocksClosed extends Schema.TaggedClass<BlocksClosed>()(\"BlocksClosed\", {\n  messageIds: Schema.Array(Schema.String)\n}) {}\n\n/**\n * Schema for every event the library defines.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const AssistantEvent = Schema.Union([\n  UserMessage,\n  BlockAnswer,\n  AssistantMessage,\n  ModelOutput,\n  ToolStarted,\n  ToolResult,\n  TurnStarted,\n  TurnCompleted,\n  TurnFailed,\n  SpecialistStarted,\n  SpecialistFinished,\n  BlocksClosed,\n  ChatDeleted\n])\n\n/**\n * Represents an event the library defines.\n *\n * @category models\n * @since 0.1.0\n */\nexport type AssistantEvent = typeof AssistantEvent.Type\n\nconst libraryTags: ReadonlySet<string> = new Set(\n  AssistantEvent.members.map((member) => member.fields._tag.schema.literal)\n)\n\n/**\n * Schema for the tag of one of the application's own events.\n *\n * It accepts any tag but the library's, and it is branded, so narrowing an entry's event to one\n * of the library's events (`Predicate.isTagged(event, \"UserMessage\")`) never leaves an app event\n * in.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const AppTag = Schema.String.pipe(Schema.brand(\"~effect-assistant/AppTag\"))\n\n/**\n * Schema for one of the application's own events as it is stored, with its `_tag` and its fields\n * in JSON.\n *\n * An assistant made with `events: [AppEvent.make(Summary)]` decodes it to a `Summary` in\n * `CurrentChat`'s `entries` and in its `subscribe`.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const StoredAppEvent = Schema.StructWithRest(Schema.Struct({ _tag: AppTag }), [\n  Schema.Record(Schema.String, Schema.Json)\n]).check(Schema.makeFilter((event) => !libraryTags.has(event._tag) || `${event._tag} is one of the library's events`))\n\n/**\n * Represents one of the application's own events, as it is stored.\n *\n * @category models\n * @since 0.1.0\n */\nexport type StoredAppEvent = typeof StoredAppEvent.Type\n\n/**\n * Returns whether an event is one of the library's, not one of the app's own.\n *\n * @category guards\n * @since 0.1.0\n */\nexport const isLibraryEvent = (event: { readonly _tag: string }): event is AssistantEvent => libraryTags.has(event._tag)\n\n/**\n * Represents a chat's entry with any event in it, either the library's or the application's own\n * (decoded or not).\n *\n * The folds over a chat take this type, so a client's typed entries fit too.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface AnyEntry {\n  readonly chatId: ChatId\n  readonly seq: number\n  readonly at: number\n  readonly event: { readonly _tag: string }\n}\n\n/**\n * Schema for a stored event with its position in the chat.\n *\n * `seq` starts at 1 and has no gaps. `at` is the time the event was stored, in epoch\n * milliseconds.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const Entry = Schema.Struct({\n  chatId: ChatId,\n  seq: Schema.Int,\n  at: Schema.Finite,\n  event: Schema.Union([AssistantEvent, StoredAppEvent])\n})\n\n/**\n * Represents a stored event with its position in the chat.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Entry = typeof Entry.Type\n\n/**\n * Returns whether an event is one of the library's inputs, which are a user message, a block\n * answer, or a finished specialist run.\n *\n * The application's events that wake a turn are inputs too, but only their assistant knows which\n * (see `AppEvent`).\n *\n * @category guards\n * @since 0.1.0\n */\nexport const isInput = (event: { readonly _tag: string }): event is Input =>\n  Predicate.isTagged(event, \"UserMessage\") ||\n  Predicate.isTagged(event, \"BlockAnswer\") ||\n  Predicate.isTagged(event, \"SpecialistFinished\")\n\n/**\n * Returns whether an input starts a turn, which every input does except a run the assistant\n * stopped itself.\n *\n * @category guards\n * @since 0.1.0\n */\nexport const isWaking = (input: Input): boolean =>\n  !(Predicate.isTagged(input, \"SpecialistFinished\") && input.status === \"stopped\")\n\n/**\n * Returns whether an input came from the chat's user, and so is owed a reply.\n *\n * @category guards\n * @since 0.1.0\n */\nexport const isUserInput = (input: Input): input is UserInput =>\n  Predicate.isTagged(input, \"UserMessage\") || Predicate.isTagged(input, \"BlockAnswer\")\n\n/**\n * Returns whether an event ends a turn, and so says how far the assistant has read.\n *\n * @category guards\n * @since 0.1.0\n */\nexport const isTurnEnd = (event: { readonly _tag: string }): event is TurnCompleted | TurnFailed =>\n  Predicate.isTagged(event, \"TurnCompleted\") || Predicate.isTagged(event, \"TurnFailed\")\n\n/**\n * Returns the text of every message the user was shown, in order.\n *\n * @category utils\n * @since 0.1.0\n */\nexport const assistantTexts = (entries: ReadonlyArray<AnyEntry>): ReadonlyArray<string> =>\n  entries.flatMap(({ event }) =>\n    isLibraryEvent(event) && Predicate.isTagged(event, \"AssistantMessage\") ? [event.text] : []\n  )\n"],"mappings":"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"}

package/dist/AssistantLoop.d.ts

@@ -0,0 +1,173 @@
+import { Instructions_d_exports, Resolved } from "./Instructions.js";
+import { ToolServices, toolkit_d_exports } from "./internal/toolkit.js";
+import { ChatHistory as ChatHistory$1, Event as Event$1, Step as Step$1, StepResult as StepResult$1, loop as loop$1, loop_d_exports, next as next$1, stop as stop$1, value as value$1 } from "./internal/loop.js";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import * as Prompt from "effect/ai/Prompt";
+import * as Tool from "effect/ai/Tool";
+import * as Toolkit from "effect/ai/Toolkit";
+import * as LanguageModel from "effect/ai/LanguageModel";
+import * as AiError from "effect/ai/AiError";
+declare namespace AssistantLoop_d_exports {
+  export { ChatHistory, Event, Options, Step, StepOptions, StepResult, ToolkitServices, loop, next, run, step, stop, value };
+}
+/**
+ * Represents what the loop emits.
+ *
+ * For each model call, the loop emits the call's output. Then, for each of its tool calls, it
+ * emits a `ToolStarted` before the call runs and the call's result.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Event = Event$1;
+/**
+ * Represents a chat's history as the model reads it.
+ *
+ * It holds the messages, and the last `seq` of the chat they cover.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type ChatHistory = ChatHistory$1;
+/**
+ * Represents how a step went, for deciding what comes next.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type StepResult = StepResult$1;
+/**
+ * Represents what a loop body emits, which is either a value or what to do next.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Step<A, S> = Step$1<A, S>;
+/**
+ * Emits a value from a loop body.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const value: typeof value$1;
+/**
+ * Ends a loop body's step and continues the loop with the given state.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const next: typeof next$1;
+/**
+ * Ends the loop.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const stop: typeof stop$1;
+/**
+ * Runs a loop body from an initial state.
+ *
+ * It emits the body's values, and runs the body again with the state it passes to `next`, until
+ * the body calls `stop`.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const loop: typeof loop$1;
+type NoTools = Record<never, never>;
+/**
+ * Extracts the services a toolkit's tools need when they run, which are their handlers and the
+ * services those handlers use.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type ToolkitServices<T extends Record<string, Tool.Any>> = Tool.HandlersFor<T> | ToolServices<T>;
+/**
+ * Represents the options for {@link step}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface StepOptions<T extends Record<string, Tool.Any> = NoTools> {
+  /** The full system prompt, like `turn.instructions(text)`, optionally with span attributes. */
+  readonly instructions: string | Resolved;
+  /**
+   * The tools the model can call, in addition to the assistant's own tools in a turn. Their
+   * handlers come from the layer.
+   */
+  readonly toolkit?: Toolkit.Toolkit<T> | undefined;
+  /**
+   * The current history, read at the start of the step. It is either messages, or a chat's
+   * history (`turn.history()`), whose `throughSeq` the step's `ModelOutput` records as how far
+   * the model had read.
+   */
+  readonly history: Effect.Effect<ReadonlyArray<Prompt.Message> | ChatHistory>;
+  /**
+   * Defaults to `"auto"`, where a step without a tool call ends the loop. Forcing a call
+   * (`"required"`, or a tool by name) is refused by newer models, and with extended thinking.
+   */
+  readonly toolChoice?: LanguageModel.ToolChoice<string> | undefined;
+}
+/**
+ * Represents the options for {@link run}.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Options<T extends Record<string, Tool.Any> = NoTools> extends StepOptions<T> {
+  /** The model calls allowed. Defaults to 16. */
+  readonly maxSteps?: number | undefined;
+}
+/**
+ * Runs one step of the agent loop, as a body for {@link loop}.
+ *
+ * **Details**
+ *
+ * The step calls the model with the current history and emits its `ModelOutput`. It then runs
+ * the output's tool calls and emits a `ToolStarted` and a `ToolResult` for each. `then` receives
+ * the step's result and decides what comes next, with `AssistantLoop.next(state)` or
+ * `AssistantLoop.stop()`.
+ *
+ * A tool with Effect's `needsApproval` set fails the loop before the model is called: the
+ * library doesn't run calls that wait for approval (see the guide on involving the user).
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const step: <T extends Record<string, Tool.Any> = NoTools, S = never, E2 = never, R2 = never>(options: StepOptions<T>, then: (result: StepResult) => Stream.Stream<Step<never, S>, E2, R2>) => Stream.Stream<Step<Event, S>, AiError.AiError | E2, LanguageModel.LanguageModel | ToolkitServices<T> | R2>;
+/**
+ * Runs the agent loop as a stream.
+ *
+ * **Details**
+ *
+ * It runs {@link step} after step until the model is done and nothing new arrived while it
+ * worked, or until it has made `maxSteps` model calls.
+ *
+ * **Example** (A turn's loop with a step limit)
+ *
+ * ```ts
+ * import { AssistantLoop } from "effect-assistant"
+ * import * as Layer from "effect/Layer"
+ * import * as Stream from "effect/Stream"
+ *
+ * const instructions = "You help a small marketing team."
+ *
+ * const MyAssistantLive = MyAssistant.toLayer((turn) =>
+ *   AssistantLoop.run({
+ *     instructions: turn.instructions(instructions),
+ *     toolkit: MyTools, // the assistant's own tools are added to them
+ *     history: turn.history(),
+ *     maxSteps: 12
+ *   }).pipe(Stream.concat(turn.replyIfOwed({ instructions })))
+ * ).pipe(Layer.provide(MyToolsLive))
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const run: <T extends Record<string, Tool.Any> = NoTools>(options: Options<T>) => Stream.Stream<Event, AiError.AiError, LanguageModel.LanguageModel | ToolkitServices<T>>;
+//#endregion
+export { AssistantLoop_d_exports };
+//# sourceMappingURL=AssistantLoop.d.ts.map