effect-assistant 0.2.0 → 0.4.0

package/dist/Assistant.d.ts

@@ -1,12 +1,10 @@
-import { Any as Any$1, AppEvent_d_exports, Type } from "./AppEvent.js";
 import { ChatId } from "./ChatId.js";
-import { AssistantEvent, AssistantEvent_d_exports, Input } from "./AssistantEvent.js";
+import { AppEventSchema, AssistantEvent, AssistantEvent_d_exports, Input } from "./AssistantEvent.js";
 import { Instructions_d_exports, Resolved } from "./Instructions.js";
 import { AssistantLoop_d_exports, ChatHistory, Event, ToolkitServices } from "./AssistantLoop.js";
 import { CurrentChat } from "./CurrentChat.js";
 import { BlockKit, BlockKit_d_exports } from "./BlockKit.js";
-import { Skill } from "./Skill.js";
-import { Any as Any$2, CheckServices, HandlerOf, Runner, Specialist_d_exports, ToolHandlers } from "./Specialist.js";
+import { Any as Any$1, CheckServices, HandlerOf, Runner, Specialist_d_exports, ToolHandlers } from "./Specialist.js";
 import { AssistantEngine } from "./AssistantEngine.js";
 import { Chats_d_exports, GetChatError } from "./Chats.js";
 import * as Context from "effect/Context";
@@ -38,27 +36,24 @@ export type TurnServices = CurrentChat | Runner;
  * @category models
  * @since 0.1.0
  */
-export interface LoopOptions<T extends Record<string, Tool.Any> = Record<never, never>, RS = never, Events = never> {
+export interface LoopOptions<T extends Record<string, Tool.Any> = Record<never, never>, Events = never> {
   /** The assistant's role and rules. The loop places `Instructions.protocol` before them. */
   readonly instructions: string | Resolved;
   /**
    * Tools the model can use in addition to the assistant's own. This is an `effect/ai` toolkit,
    * and its handlers come from the layer. Combine several toolkits with `Toolkit.merge`, for
-   * example `Memory.Tools` or a `ToolDiscovery.make(...)` toolkit together with your own.
+   * example `Memory.Tools`, a `Skill.toolkit(...)`, or a `ToolDiscovery.make(...)` toolkit together
+   * with your own.
    */
   readonly toolkit?: Toolkit.Toolkit<T> | undefined;
-  /**
-   * Playbooks the model can follow. The prompt lists them as a catalog, and the model loads one
-   * with `load_skill` when a task matches it.
-   */
-  readonly skills?: ReadonlyArray<Skill<RS>> | undefined;
   /** The maximum number of model calls per turn. Defaults to 16. */
   readonly maxSteps?: number | undefined;
   /** The message the reply pass gives the model when the turn would end without a reply. */
   readonly replyNudge?: string | undefined;
   /**
    * Selects which of the chat's entries the model reads, for example only those since the last
-   * summary. Defaults to all entries.
+   * summary, and maps the app's own events it should read into prompt messages. Defaults to all
+   * entries, without the app's events.
    */
   readonly history?: HistoryView<Events> | undefined;
 }
@@ -68,9 +63,43 @@ export interface LoopOptions<T extends Record<string, Tool.Any> = Record<never,
  *
  * **Details**
  *
- * The function receives the chat's entries and returns, in order, a mix of entries and
- * `Prompt.Message`s. The model reads the returned entries the same way it reads the full history,
- * and reads each prompt message unchanged.
+ * The function receives the chat's entries, the app's own events among them, and returns, in
+ * order, a mix of entries and `Prompt.Message`s. The model reads the returned entries the same way
+ * it reads the full history, and reads each prompt message unchanged, where the view put it. The
+ * model reads none of the app's events by itself: map those it should read to a message, and an
+ * app event's entry left in the result is dropped.
+ *
+ * A message stands right after the entry before it: one that came after the model's last read, or
+ * between a tool call and its result, moves after them, as an input does.
+ *
+ * **Example** (Telling the model about an order the user placed)
+ *
+ * ```ts
+ * import { Assistant, InputId } from "effect-assistant"
+ * import * as Prompt from "effect/ai/Prompt"
+ * import * as Schema from "effect/Schema"
+ *
+ * class OrderPlaced extends Schema.TaggedClass<OrderPlaced>()("OrderPlaced", {
+ *   id: InputId.InputId,
+ *   reference: Schema.String
+ * }) {}
+ *
+ * const MyAssistant = Assistant.make("my-assistant", { events: [OrderPlaced] })
+ *
+ * const withOrders: Assistant.HistoryView<OrderPlaced> = (entries) =>
+ *   entries.map((entry) =>
+ *     entry.event instanceof OrderPlaced
+ *       ? Prompt.userMessage({
+ *           content: [Prompt.textPart({ text: `The user placed order ${entry.event.reference}.` })]
+ *         })
+ *       : entry
+ *   )
+ *
+ * // An `OrderPlaced` that the API submits wakes a turn, which reads it as this note.
+ * const MyAssistantLive = MyAssistant.toLayer((turn) =>
+ *   turn.loop({ instructions: "Be brief.", history: withOrders })
+ * )
+ * ```
  *
  * @category models
  * @since 0.1.0
@@ -130,10 +159,10 @@ export interface Turn<Events = never> {
   readonly instructions: (instructions: string | Resolved) => Resolved;
   /**
    * Runs the agent loop over the chat. The loop uses `Instructions.protocol`, the assistant's own
-   * tools, and the instructions, tools, and skills in `options`. Every step is a tool call, and
+   * tools, and the instructions and tools in `options`. Every step is a tool call, and
    * the loop ends with `replyIfOwed`.
    */
-  readonly loop: <T extends Record<string, Tool.Any> = Record<never, never>, RS = never>(options: LoopOptions<T, RS, Events>) => Stream.Stream<Event, AiError.AiError, LanguageModel.LanguageModel | TurnServices | ToolkitServices<T> | RS>;
+  readonly loop: <T extends Record<string, Tool.Any> = Record<never, never>>(options: LoopOptions<T, Events>) => Stream.Stream<Event, AiError.AiError, LanguageModel.LanguageModel | TurnServices | ToolkitServices<T>>;
   /**
    * Runs one more pass when the turn would otherwise end without a reply to the user's latest
    * message. In this pass the model can only reply.
@@ -203,8 +232,8 @@ export interface Chat<Events = never> {
   readonly entries: Effect.Effect<ReadonlyArray<Entry<Events>>>;
   /**
    * Appends events after the chat's last entry and sends them to the chat's subscribers. The
-   * events can be the library's or the assistant's own, such as a summary. An event that wakes a
-   * turn is handled by the next turn.
+   * events can be the library's or the assistant's own, such as a summary. None of them wakes a
+   * turn: only what comes in through the assistant's `submit` does.
    */
   append(...events: ReadonlyArray<AssistantEvent | Events>): Effect.Effect<void>;
 }
@@ -219,8 +248,11 @@ export interface Chat<Events = never> {
 export interface Service<Events = never> {
   /**
    * Stores an input or one of the assistant's own events, then returns. Examples are a user's
-   * message or block answer, a workflow's progress, or the draft the user opened. The assistant
-   * works on events that wake a turn in the background.
+   * message or block answer, a workflow's progress, or the order the user placed. Each one is an
+   * input: storing it wakes a turn, which the assistant runs in the background. The handler decides
+   * what the turn does with it, and an app event the model should read needs a history view that
+   * maps it (see {@link HistoryView}). To store an app event without waking a turn, append it from
+   * within the chat instead (`yield* MyAssistant.Chat`).
    *
    * Fails with `GetChatError` when the app's `Chats` service reports that the chat can't be used,
    * because the app doesn't know the chat or has deleted it.
@@ -231,9 +263,10 @@ export interface Service<Events = never> {
    * A reader that already has the earlier entries passes `after` and receives only the entries
    * after that `seq`.
    *
-   * For a chat client, pipe the whole log into `ChatView.updates(MyAssistant, { after })`, which
-   * streams the chat as its user sees it. Its `after` goes there, not here: the view of a message
-   * depends on earlier entries.
+   * For a chat client, pipe the whole log into `Timeline.changes(MyAssistant, { after })`, which
+   * streams the chat's timeline, as its user sees it. Its `after` goes there, not here: a message
+   * on the timeline depends on earlier entries. The timeline shows only the app events named in its
+   * `show`, none by default (see `Timeline.changes`).
    */
   readonly subscribe: (chatId: ChatId, options?: {
     readonly after?: number | undefined;
@@ -263,14 +296,14 @@ export interface Service<Events = never> {
  * @category models
  * @since 0.1.0
  */
-export interface Assistant<Name extends string = string, Specs extends Any$2 = never, Events = never> extends Context.Service<Identifier<Name>, Service<Events>> {
+export interface Assistant<Name extends string = string, Specs extends Any$1 = never, Events = never> extends Context.Service<Identifier<Name>, Service<Events>> {
   readonly [TypeId]: typeof TypeId;
   readonly name: Name;
   readonly blocks: BlockKit | undefined;
   /** The specialists the assistant can hand work to. */
   readonly specialists: ReadonlyArray<Specs>;
-  /** The app's own events the assistant registered. */
-  readonly events: ReadonlyArray<Any$1>;
+  /** The schemas of the app's own events the assistant stores. */
+  readonly events: ReadonlyArray<AppEventSchema>;
   /**
    * Creates a layer that registers the assistant's handler with the engine and provides the
    * assistant's service.
@@ -322,9 +355,9 @@ export interface Assistant<Name extends string = string, Specs extends Any$2 = n
    *
    * export const MyAssistant = Assistant.make("my-assistant")
    *
-   * // Requires `ChatLog` and `Sharding`. The cluster's runners run the chats.
+   * // Requires `Sharding`. The cluster's runners run the chats, with `AssistantEngine.layerCluster`.
    * const MyAssistantClient = MyAssistant.layerClient.pipe(
-   *   Layer.provide(AssistantEngine.layerCluster)
+   *   Layer.provide(AssistantEngine.layerClusterClient)
    * )
    * ```
    */
@@ -352,14 +385,21 @@ export type Any = Assistant<any, any, any>;
  */
 export declare const isAssistant: (u: unknown) => u is Any;
 /**
- * Creates an assistant definition from its name, its UI blocks, its specialists, and the app's own
- * events it stores (see `AppEvent`).
+ * Creates an assistant definition from its name, its UI blocks, its specialists, and the schemas of
+ * the app's own events it stores.
  *
  * **Details**
  *
  * The definition holds no code that runs turns. Provide a handler with its `toLayer`, then yield
  * the definition to get the assistant's {@link Service}.
  *
+ * The definition only says which of the app's events a chat stores. What happens with one is up
+ * to the places that use it. One that comes in through the service's `submit`, from outside a
+ * turn, is an input and wakes a turn, like a user's message; one a turn appends to its chat never
+ * does. The handler decides what a turn does, a history view says how the model reads an event
+ * ({@link HistoryView}), and the chat's timeline says which its user sees
+ * (`Timeline.changes`).
+ *
  * **Example** (Defining an assistant and submitting a message)
  *
  * ```ts
@@ -382,7 +422,7 @@ export declare const isAssistant: (u: unknown) => u is Any;
  * @category constructors
  * @since 0.1.0
  */
-export declare const make: <const Name extends string, const Specs extends ReadonlyArray<Any$2> = readonly [], const Events extends ReadonlyArray<Any$1> = readonly []>(name: Name, options?: {
+export declare const make: <const Name extends string, const Specs extends ReadonlyArray<Any$1> = readonly [], const Events extends ReadonlyArray<AppEventSchema> = readonly []>(name: Name, options?: {
   /** UI blocks the assistant can add to its messages. */
   readonly blocks?: BlockKit | undefined;
   /**
@@ -391,13 +431,13 @@ export declare const make: <const Name extends string, const Specs extends Reado
    */
   readonly specialists?: Specs | undefined;
   /**
-   * The app's own events, each created with `AppEvent.make(schema, { wakes, render })`.
-   * `submit` and the chat's `append` store them, and the chat's `entries` read them back,
-   * decoded. Events that wake a turn are inputs, and the model reads each event that has a
-   * `render`.
+   * The schemas of the app's own events, each a tagged struct or class. `submit` and the chat's
+   * `append` store them, in their JSON form, and the chat's `entries` and `subscribe` read them
+   * back, decoded. Each needs a tag of its own that isn't one of the library's: `make` throws
+   * otherwise.
    */
   readonly events?: Events | undefined;
-}) => Assistant<Name, Specs[number], Type<Events[number]>>;
+}) => Assistant<Name, Specs[number], Events[number]["Type"]>;
 //#endregion
 export { Assistant_d_exports };
 //# sourceMappingURL=Assistant.d.ts.map

package/dist/Assistant.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Assistant.d.ts","names":[],"sources":["../src/Assistant.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;cAwCM;;;;;;;;YASM,eAAe,cAAc;;;;;;;iBAQxB,YAAY,UAAU,eAAe,KAAK,OAAO,sBAAsB,YAAY;;WAEzF,uBAAuB;;;;;;WAMvB,UAAU,QAAQ,QAAQ;;;;;WAK1B,SAAS,cAAc,MAAM;;WAE7B;;WAEA;;;;;WAKA,UAAU,YAAY;;;;;;;;;;;;;;;YAgBrB,YAAY,mBACtB,SAAS,cAAc,MAAM,aAC1B,cAAc,MAAM,UAAU,OAAO;;;;;;;iBAQzB,MAAM;WACZ,QAAQ;WACR;WACA;WACA,OAAO,iBAAgC;;;;;;;;iBASjC;;WAEN,uBAAuB;;;;;WAKvB;;;;;;;;;;;iBAYM,KAAK;WACX,QAAQ;;;;;;;;;WASR,UAAU,OAAO,YAAY,YAAY,OAAO,OAAO;;;;;WAKvD,eAAe,uBAAuB,aAA0B;;;;;;WAMhE,OAAO,UAAU,eAAe,KAAK,OAAO,sBAAsB,YACzE,SAAS,YAAY,GAAG,IAAI,YACzB,OAAO,OACV,OACA,QAAQ,SACR,cAAc,gBAAgB,eAAe,gBAA8B,KAAK;;;;;;;;;WAUzE,cACP,SAAS,iBACN,OAAO,OAAO,OAAqB,QAAQ,SAAS,cAAc,gBAAgB;;;;;;;;;;;;YAa7E,QAAQ,WAAW,KAAK,GAAG,mBACrC,MAAM,KAAK,YAET,OAAO,OAAO,gBAA8B,KAC5C,OAAO,OAAO,OAAO,OAAO,gBAA8B,aAAa;;;;;;;;;YAU/D,gBAAgB,KAAK,QAAQ,GAAG,eAAe,cAAc,gBAAgB,KAAK;;;;;;;;iBAe7E,WAAW;WACjB,+BAA+B;;;;;;;;iBASzB,eAAe;WACrB,oCAAoC;;;;;;;;;;;;;iBAc9B,KAAK;WACX,QAAQ;;;;;WAKR,SAAS,OAAO,OAAO,cAAc,MAAM;;;;;;EAMpD,UAAU,QAAQ,cAAc,iBAAgC,UAAU,OAAO;;;;;;;;;;iBAWlE,QAAQ;;;;;;;;;EAUvB,OAAO,QAAQ,QAAQ,OAAO,QAAuB,SAAS,OAAO,aAAa;;;;;;;;;;WAUzE,YACP,QAAQ,QACR;aAAqB;QAClB,OAAO,OAAO,MAAM;;;;;;;;;;;;;;WAchB,SAAS,QAAQ,WAAW,OAAO;;;;;;;;;;;;iBAa7B,UACf,8BACA,cAAc,eACd,wBACQ,QAAQ,QAAQ,WAAW,OAAO,QAAQ;YACxC,gBAAgB;WACjB,MAAM;WACN,QAAQ;;WAER,aAAa,cAAc;;WAE3B,QAAQ,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAmCtB,UAAU,WAAW,YAAY,WAAW,YACnD,QAAQ,QAAQ,GAAG,IAAI,UAAU,OAAO,OAAO,QAAQ,GAAG,IAAI,SAAS,GAAG,OACxE,cAAyB,QAAQ,gBAAgB,IAAI,KAAK,KAAK,eAAe,YAC7E,MAAM,MACT,WAAW,cAET,kBACA,cAAc,gBACd,UAAqB,SACrB,QAAQ,IAAI,MAAM,QAAQ,cAAc,eAAe,SACvD,aAAwB,IAAI;;;;;;;;;;;;;;;;;;;;;;;WAwBvB,aAAa,MAAM,MAAM,WAAW,cAAc;;;;;WAKlD,MAAM,QAAQ,QAAQ,eAAe,OAAO,KAAK;;WAEjD,OAAO,OAAO,MAAM,MAAM,SAAS,OAAO;;;;;;;;YASzC,MAAM;;;;;;;qBAQL,cAAW,eAAiB,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA8CjC,aACL,2BACA,cAAc,cAAc,4BAC5B,eAAe,cAAc,sBAA2B,MAExD,MAAI;;WAGC,SAAS;;;;;WAKT,cAAc;;;;;;;WAOd,SAAS;MAEnB,UAAU,MAAM,eAAe,KAAc"}
+{"version":3,"file":"Assistant.d.ts","names":[],"sources":["../src/Assistant.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;cAsCM;;;;;;;;YASM,eAAe,cAAc;;;;;;;iBAQxB,YAAY,UAAU,eAAe,KAAK,OAAO,sBAAsB;;WAE7E,uBAAuB;;;;;;;WAOvB,UAAU,QAAQ,QAAQ;;WAE1B;;WAEA;;;;;;WAMA,UAAU,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAkDrB,YAAY,mBACtB,SAAS,cAAc,MAAM,aAC1B,cAAc,MAAM,UAAU,OAAO;;;;;;;iBAQzB,MAAM;WACZ,QAAQ;WACR;WACA;WACA,OAAO,iBAAgC;;;;;;;;iBASjC;;WAEN,uBAAuB;;;;;WAKvB;;;;;;;;;;;iBAYM,KAAK;WACX,QAAQ;;;;;;;;;WASR,UAAU,OAAO,YAAY,YAAY,OAAO,OAAO;;;;;WAKvD,eAAe,uBAAuB,aAA0B;;;;;;WAMhE,OAAO,UAAU,eAAe,KAAK,OAAO,sBACnD,SAAS,YAAY,GAAG,YACrB,OAAO,OACV,OACA,QAAQ,SACR,cAAc,gBAAgB,eAAe,gBAA8B;;;;;;;;;WAUpE,cACP,SAAS,iBACN,OAAO,OAAO,OAAqB,QAAQ,SAAS,cAAc,gBAAgB;;;;;;;;;;;;YAa7E,QAAQ,WAAW,KAAK,GAAG,mBACrC,MAAM,KAAK,YAET,OAAO,OAAO,gBAA8B,KAC5C,OAAO,OAAO,OAAO,OAAO,gBAA8B,aAAa;;;;;;;;;YAU/D,gBAAgB,KAAK,QAAQ,GAAG,eAAe,cAAc,gBAAgB,KAAK;;;;;;;;iBAe7E,WAAW;WACjB,+BAA+B;;;;;;;;iBASzB,eAAe;WACrB,oCAAoC;;;;;;;;;;;;;iBAc9B,KAAK;WACX,QAAQ;;;;;WAKR,SAAS,OAAO,OAAO,cAAc,MAAM;;;;;;EAMpD,UAAU,QAAQ,cAAc,iBAAgC,UAAU,OAAO;;;;;;;;;;iBAWlE,QAAQ;;;;;;;;;;;;EAavB,OAAO,QAAQ,QAAQ,OAAO,QAAuB,SAAS,OAAO,aAAa;;;;;;;;;;;WAWzE,YACP,QAAQ,QACR;aAAqB;QAClB,OAAO,OAAO,MAAM;;;;;;;;;;;;;;WAchB,SAAS,QAAQ,WAAW,OAAO;;;;;;;;;;;;iBAa7B,UACf,8BACA,cAAc,eACd,wBACQ,QAAQ,QAAQ,WAAW,OAAO,QAAQ;YACxC,gBAAgB;WACjB,MAAM;WACN,QAAQ;;WAER,aAAa,cAAc;;WAE3B,QAAQ,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAmCtB,UAAU,WAAW,YAAY,WAAW,YACnD,QAAQ,QAAQ,GAAG,IAAI,UAAU,OAAO,OAAO,QAAQ,GAAG,IAAI,SAAS,GAAG,OACxE,cAAyB,QAAQ,gBAAgB,IAAI,KAAK,KAAK,eAAe,YAC7E,MAAM,MACT,WAAW,cAET,kBACA,cAAc,gBACd,UAAqB,SACrB,QAAQ,IAAI,MAAM,QAAQ,cAAc,eAAe,SACvD,aAAwB,IAAI;;;;;;;;;;;;;;;;;;;;;;;WAwBvB,aAAa,MAAM,MAAM,WAAW,cAAc;;;;;WAKlD,MAAM,QAAQ,QAAQ,eAAe,OAAO,KAAK;;WAEjD,OAAO,OAAO,MAAM,MAAM,SAAS,OAAO;;;;;;;;YASzC,MAAM;;;;;;;qBAQL,cAAW,eAAiB,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAqDjC,aACL,2BACA,cAAc,cAAc,4BAC5B,eAAe,cAAc,+BAA4C,MAEzE,MAAI;;WAGC,SAAS;;;;;WAKT,cAAc;;;;;;;WAOd,SAAS;MAEnB,UAAU,MAAM,eAAe"}

package/dist/Assistant.js

@@ -5,11 +5,11 @@ import { Chats } from "./Chats.js";
 import { decodeEntry, encode, make as make$1 } from "./internal/events.js";
 import { register } from "./internal/turns.js";
 import { AssistantEngine } from "./AssistantEngine.js";
-import * as Predicate from "effect/Predicate";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Filter from "effect/Filter";
 import * as Layer from "effect/Layer";
+import * as Predicate from "effect/Predicate";
 import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
 //#region src/Assistant.ts
@@ -31,18 +31,25 @@ function entrySchema(events) {
 		chatId: ChatId,
 		seq: Schema.Int,
 		at: Schema.Finite,
-		event: Schema.Union([AssistantEvent, ...events.map((event) => event.schema)])
+		event: Schema.Union([AssistantEvent, ...events])
 	}));
 }
 /**
-* Creates an assistant definition from its name, its UI blocks, its specialists, and the app's own
-* events it stores (see `AppEvent`).
+* Creates an assistant definition from its name, its UI blocks, its specialists, and the schemas of
+* the app's own events it stores.
 *
 * **Details**
 *
 * The definition holds no code that runs turns. Provide a handler with its `toLayer`, then yield
 * the definition to get the assistant's {@link Service}.
 *
+* The definition only says which of the app's events a chat stores. What happens with one is up
+* to the places that use it. One that comes in through the service's `submit`, from outside a
+* turn, is an input and wakes a turn, like a user's message; one a turn appends to its chat never
+* does. The handler decides what a turn does, a history view says how the model reads an event
+* ({@link HistoryView}), and the chat's timeline says which its user sees
+* (`Timeline.changes`).
+*
 * **Example** (Defining an assistant and submitting a message)
 *
 * ```ts

package/dist/Assistant.js.map

@@ -1 +1 @@
-{"version":3,"file":"Assistant.js","names":["AssistantEvent.AssistantEvent","AppEvents.make","AssistantEvent.isInput","AppEvents.encode","Chats.Chats","AppEvents.decodeEntry","Turns.register"],"sources":["../src/Assistant.ts"],"sourcesContent":["/**\n * This module provides `Assistant.make`, which defines an assistant that works in a chat the way a\n * colleague does: the user messages it, it works in the background with the app's tools, and it\n * messages the user back.\n *\n * A definition is what the rest of an app imports. Yielding it (`yield* MyAssistant`) returns the\n * assistant's {@link Service}, which submits inputs to chats and streams them back. Its `toLayer`\n * registers the handler that runs each {@link Turn} with the `AssistantEngine`, and its\n * `layerClient` provides the service without a handler. Code that runs inside a chat reads and\n * extends that chat through the definition's {@link Chat} key.\n *\n * @since 0.1.0\n */\nimport type * as AiError from \"effect/ai/AiError\"\nimport type * as LanguageModel from \"effect/ai/LanguageModel\"\nimport type * as Prompt from \"effect/ai/Prompt\"\nimport type * as Tool from \"effect/ai/Tool\"\nimport type * as Toolkit from \"effect/ai/Toolkit\"\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Filter from \"effect/Filter\"\nimport * as Layer from \"effect/Layer\"\nimport * as Predicate from \"effect/Predicate\"\nimport * as Schema from \"effect/Schema\"\nimport type * as Scope from \"effect/Scope\"\nimport * as Stream from \"effect/Stream\"\nimport type * as AppEvent from \"./AppEvent.ts\"\nimport { AssistantEngine } from \"./AssistantEngine.ts\"\nimport * as AssistantEvent from \"./AssistantEvent.ts\"\nimport type * as AssistantLoop from \"./AssistantLoop.ts\"\nimport type * as BlockKit from \"./BlockKit.ts\"\nimport { ChatId } from \"./ChatId.ts\"\nimport * as Chats from \"./Chats.ts\"\nimport type { CurrentChat } from \"./CurrentChat.ts\"\nimport type * as Instructions from \"./Instructions.ts\"\nimport * as AppEvents from \"./internal/events.ts\"\nimport * as Turns from \"./internal/turns.ts\"\nimport type { Skill } from \"./Skill.ts\"\nimport type * as Specialist from \"./Specialist.ts\"\n\nconst TypeId = \"~effect-assistant/Assistant\" as const\n\n/**\n * Represents the services that a turn provides to its tools, its loop, and its specialists. These\n * are the turn's chat (`CurrentChat`) and the chat's specialist runner (`Specialist.Runner`).\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type TurnServices = CurrentChat | Specialist.Runner\n\n/**\n * Represents the options accepted by `turn.loop`.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface LoopOptions<T extends Record<string, Tool.Any> = Record<never, never>, RS = never, Events = never> {\n  /** The assistant's role and rules. The loop places `Instructions.protocol` before them. */\n  readonly instructions: string | Instructions.Resolved\n  /**\n   * Tools the model can use in addition to the assistant's own. This is an `effect/ai` toolkit,\n   * and its handlers come from the layer. Combine several toolkits with `Toolkit.merge`, for\n   * example `Memory.Tools` or a `ToolDiscovery.make(...)` toolkit together with your own.\n   */\n  readonly toolkit?: Toolkit.Toolkit<T> | undefined\n  /**\n   * Playbooks the model can follow. The prompt lists them as a catalog, and the model loads one\n   * with `load_skill` when a task matches it.\n   */\n  readonly skills?: ReadonlyArray<Skill<RS>> | undefined\n  /** The maximum number of model calls per turn. Defaults to 16. */\n  readonly maxSteps?: number | undefined\n  /** The message the reply pass gives the model when the turn would end without a reply. */\n  readonly replyNudge?: string | undefined\n  /**\n   * Selects which of the chat's entries the model reads, for example only those since the last\n   * summary. Defaults to all entries.\n   */\n  readonly history?: HistoryView<Events> | undefined\n}\n\n/**\n * Represents a function that selects which of a chat's entries the model reads, and what else it\n * reads with them.\n *\n * **Details**\n *\n * The function receives the chat's entries and returns, in order, a mix of entries and\n * `Prompt.Message`s. The model reads the returned entries the same way it reads the full history,\n * and reads each prompt message unchanged.\n *\n * @category models\n * @since 0.1.0\n */\nexport type HistoryView<Events = never> = (\n  entries: ReadonlyArray<Entry<Events>>\n) => ReadonlyArray<Entry<Events> | Prompt.Message>\n\n/**\n * Represents an entry in a chat's log, with the assistant's own events decoded to their types.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Entry<Events = never> {\n  readonly chatId: ChatId\n  readonly seq: number\n  readonly at: number\n  readonly event: AssistantEvent.AssistantEvent | Events\n}\n\n/**\n * Represents the options accepted by `turn.replyIfOwed`.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface ReplyOptions {\n  /** The assistant's instructions, as passed to `turn.loop`. `Instructions.protocol` is added. */\n  readonly instructions: string | Instructions.Resolved\n  /**\n   * The message given to the model after the history. Defaults to a message saying that it\n   * hasn't replied yet and should reply now.\n   */\n  readonly nudge?: string | undefined\n}\n\n/**\n * Represents one turn, as the assistant's handler receives it.\n *\n * `Events` is the type of the app's own events that the assistant registered with its `events`\n * option.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Turn<Events = never> {\n  readonly chatId: ChatId\n  /**\n   * Returns the model's history, built from the chat's entries (all of them, or those a view\n   * keeps), together with how far into the chat it reaches.\n   *\n   * Read it before every model call, as the loop does. Each step records how far its model call\n   * read, and the turn ends once it has handled what the model saw. An input that arrived after\n   * that is handled by the next turn.\n   */\n  readonly history: (view?: HistoryView<Events>) => Effect.Effect<AssistantLoop.ChatHistory>\n  /**\n   * Returns the full system prompt for the given instructions. It contains\n   * `Instructions.protocol`, the instructions, and the specialist runs that are working now.\n   */\n  readonly instructions: (instructions: string | Instructions.Resolved) => Instructions.Resolved\n  /**\n   * Runs the agent loop over the chat. The loop uses `Instructions.protocol`, the assistant's own\n   * tools, and the instructions, tools, and skills in `options`. Every step is a tool call, and\n   * the loop ends with `replyIfOwed`.\n   */\n  readonly loop: <T extends Record<string, Tool.Any> = Record<never, never>, RS = never>(\n    options: LoopOptions<T, RS, Events>\n  ) => Stream.Stream<\n    AssistantLoop.Event,\n    AiError.AiError,\n    LanguageModel.LanguageModel | TurnServices | AssistantLoop.ToolkitServices<T> | RS\n  >\n  /**\n   * Runs one more pass when the turn would otherwise end without a reply to the user's latest\n   * message. In this pass the model can only reply.\n   *\n   * The stream is empty when no reply is owed, or when an input arrived that the next turn will\n   * read. `loop` runs this pass with its own prompt and tools, so the pass reuses the cached\n   * prompt.\n   */\n  readonly replyIfOwed: (\n    options: ReplyOptions\n  ) => Stream.Stream<AssistantLoop.Event, AiError.AiError, LanguageModel.LanguageModel | TurnServices>\n}\n\n/**\n * Represents an assistant's handler, which runs a turn and returns it as a stream of the loop's\n * events.\n *\n * The handler may return the stream directly or from an Effect. `R` is the services the stream\n * requires, and `RE` is the services the Effect requires.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Handler<R = never, RE = R, Events = never> = (\n  turn: Turn<Events>\n) =>\n  | Stream.Stream<AssistantLoop.Event, unknown, R>\n  | Effect.Effect<Stream.Stream<AssistantLoop.Event, unknown, R>, unknown, RE>\n\n/**\n * Computes the services an assistant's handler needs beyond those its turns provide (the turn\n * services and `LanguageModel`) and its tools' handlers (which its layer requires). These are the\n * services that its build Effect must require.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type HandlerServices<R> = Exclude<R, TurnServices | LanguageModel.LanguageModel | Tool.Handler<string>>\n\nconst toStream = <R, RE>(\n  result:\n    | Stream.Stream<AssistantLoop.Event, unknown, R>\n    | Effect.Effect<Stream.Stream<AssistantLoop.Event, unknown, R>, unknown, RE>\n): Stream.Stream<AssistantLoop.Event, unknown, R | RE> => (Effect.isEffect(result) ? Stream.unwrap(result) : result)\n\n/**\n * Identifies an assistant's service in a context. Each assistant has its own identifier, keyed by\n * its name.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Identifier<Name extends string> {\n  readonly \"~effect-assistant/Assistant\": Name\n}\n\n/**\n * Identifies, in a context, the chat that an assistant's turns run in.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface ChatIdentifier<Name extends string> {\n  readonly \"~effect-assistant/Assistant/Chat\": Name\n}\n\n/**\n * Represents the chat that a turn of this assistant runs in, typed with the assistant's events.\n *\n * Use `yield* MyAssistant.Chat` in the handler, in the handler's build, or in a tool that its\n * turns run. Code that doesn't know the assistant uses `CurrentChat` instead.\n *\n * @see {@link CurrentChat} for the same chat without the assistant's event types\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Chat<Events = never> {\n  readonly chatId: ChatId\n  /**\n   * The chat's entries so far, in order. They include the library's events and the assistant's\n   * own events, typed.\n   */\n  readonly entries: Effect.Effect<ReadonlyArray<Entry<Events>>>\n  /**\n   * Appends events after the chat's last entry and sends them to the chat's subscribers. The\n   * events can be the library's or the assistant's own, such as a summary. An event that wakes a\n   * turn is handled by the next turn.\n   */\n  append(...events: ReadonlyArray<AssistantEvent.AssistantEvent | Events>): Effect.Effect<void>\n}\n\n/**\n * Represents the service that `yield* MyAssistant` returns. It gives code outside a chat, such as\n * a server or a workflow, access to the assistant's chats. Code that runs inside a chat uses\n * `CurrentChat` instead.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Service<Events = never> {\n  /**\n   * Stores an input or one of the assistant's own events, then returns. Examples are a user's\n   * message or block answer, a workflow's progress, or the draft the user opened. The assistant\n   * works on events that wake a turn in the background.\n   *\n   * Fails with `GetChatError` when the app's `Chats` service reports that the chat can't be used,\n   * because the app doesn't know the chat or has deleted it.\n   */\n  // Method syntax: a service for these events is one for any (`Service<any>`), for helpers over assistants.\n  submit(chatId: ChatId, input: AssistantEvent.Input | Events): Effect.Effect<void, Chats.GetChatError>\n  /**\n   * Streams the chat's stored entries, then live ones, with the assistant's own events decoded.\n   * A reader that already has the earlier entries passes `after` and receives only the entries\n   * after that `seq`.\n   *\n   * For a chat client, pipe the whole log into `ChatView.updates(MyAssistant, { after })`, which\n   * streams the chat as its user sees it. Its `after` goes there, not here: the view of a message\n   * depends on earlier entries.\n   */\n  readonly subscribe: (\n    chatId: ChatId,\n    options?: { readonly after?: number | undefined }\n  ) => Stream.Stream<Entry<Events>>\n  /**\n   * Deletes a chat by storing a `ChatDeleted` event and stopping everything that works in it.\n   *\n   * **Details**\n   *\n   * A turn or specialist run working in the chat stops, and subscribers' streams end with the\n   * `ChatDeleted` event. After that the chat stores nothing more: a later input, a run's report,\n   * or a workflow's event for it is dropped without an error. The log is kept, and removing it is\n   * up to the app. Deleting a chat a second time does nothing.\n   *\n   * When the app's `Chats` service reports a chat as deleted, the assistant deletes it in the same\n   * way the next time it checks. It checks before an input is stored and before each model call.\n   */\n  readonly delete: (chatId: ChatId) => Effect.Effect<void>\n}\n\n/**\n * Represents an assistant's definition.\n *\n * The definition holds what callers and the UI need to know about the assistant, builds its\n * handler's layer, and is the key of its service (`yield* MyAssistant`). `Events` is the type of\n * the app's own events that the assistant registered.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Assistant<\n  Name extends string = string,\n  Specs extends Specialist.Any = never,\n  Events = never\n> extends Context.Service<Identifier<Name>, Service<Events>> {\n  readonly [TypeId]: typeof TypeId\n  readonly name: Name\n  readonly blocks: BlockKit.BlockKit | undefined\n  /** The specialists the assistant can hand work to. */\n  readonly specialists: ReadonlyArray<Specs>\n  /** The app's own events the assistant registered. */\n  readonly events: ReadonlyArray<AppEvent.Any>\n  /**\n   * Creates a layer that registers the assistant's handler with the engine and provides the\n   * assistant's service.\n   *\n   * **Details**\n   *\n   * `build` is the handler, or an Effect that returns it. The handler may use the turn services,\n   * `LanguageModel`, its tools' handlers (which the layer then requires), and services that its\n   * build Effect required (see `Specialist.CheckServices`). The layer requires the\n   * `AssistantEngine`, the `LanguageModel`, and each specialist's handler\n   * (`Research.toLayer(...)`).\n   *\n   * **Example** (Providing an assistant's handler)\n   *\n   * ```ts\n   * import { Assistant, AssistantEngine, ChatLog } from \"effect-assistant\"\n   * import type * as LanguageModel from \"effect/ai/LanguageModel\"\n   * import * as Layer from \"effect/Layer\"\n   *\n   * declare const ModelLive: Layer.Layer<LanguageModel.LanguageModel>\n   *\n   * export const MyAssistant = Assistant.make(\"my-assistant\")\n   *\n   * const MyAssistantLive = MyAssistant.toLayer((turn) =>\n   *   turn.loop({ instructions: \"You help a small team. Be brief.\" })\n   * )\n   *\n   * const AppLive = MyAssistantLive.pipe(\n   *   Layer.provide(ModelLive),\n   *   Layer.provideMerge(AssistantEngine.layerMemory),\n   *   Layer.provideMerge(ChatLog.layerMemory)\n   * )\n   * ```\n   */\n  readonly toLayer: <R = never, RE = never, E = never, RX = never>(\n    build: (Handler<R, RE, Events> | Effect.Effect<Handler<R, RE, Events>, E, RX>) &\n      Specialist.CheckServices<Exclude<HandlerServices<R | RE>, RX | ChatIdentifier<Name>>>\n  ) => Layer.Layer<\n    Identifier<Name>,\n    never,\n    | AssistantEngine\n    | LanguageModel.LanguageModel\n    | Specialist.HandlerOf<Specs>\n    | Exclude<RX, Scope.Scope | CurrentChat | ChatIdentifier<Name>>\n    | Specialist.ToolHandlers<R | RE>\n  >\n  /**\n   * A layer that provides the assistant's service without its handler.\n   *\n   * **When to use**\n   *\n   * Use it in a process that submits to chats that another process runs, such as a web server in\n   * front of a cluster.\n   *\n   * **Example** (Serving clients in front of a cluster)\n   *\n   * ```ts\n   * import { Assistant, AssistantEngine } from \"effect-assistant\"\n   * import * as Layer from \"effect/Layer\"\n   *\n   * export const MyAssistant = Assistant.make(\"my-assistant\")\n   *\n   * // Requires `ChatLog` and `Sharding`. The cluster's runners run the chats.\n   * const MyAssistantClient = MyAssistant.layerClient.pipe(\n   *   Layer.provide(AssistantEngine.layerCluster)\n   * )\n   * ```\n   */\n  readonly layerClient: Layer.Layer<Identifier<Name>, never, AssistantEngine>\n  /**\n   * The key of the chat that the assistant's turns run in, typed with its events. See\n   * {@link Chat}.\n   */\n  readonly Chat: Context.Service<ChatIdentifier<Name>, Chat<Events>>\n  /** A schema that encodes the chat's entries to JSON, including the assistant's own events. */\n  readonly Entry: Schema.Codec<Entry<Events>, Schema.Json>\n}\n\n/**\n * Represents any assistant, for use in generic constraints.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type Any = Assistant<any, any, any>\n\n/**\n * Returns `true` when the value is an assistant's definition, created with {@link make}.\n *\n * @category guards\n * @since 0.1.0\n */\nexport const isAssistant = (u: unknown): u is Any => Predicate.hasProperty(u, TypeId)\n\nfunction entrySchema<E>(events: ReadonlyArray<AppEvent.Any>): Schema.Codec<Entry<E>, Schema.Json>\n// The overload states the decoded type: the library's events, or one of these schemas' types.\nfunction entrySchema(events: ReadonlyArray<AppEvent.Any>): Schema.Top {\n  return Schema.toCodecJson(\n    Schema.Struct({\n      chatId: ChatId,\n      seq: Schema.Int,\n      at: Schema.Finite,\n      event: Schema.Union([AssistantEvent.AssistantEvent, ...events.map((event) => event.schema)])\n    })\n  )\n}\n\n/**\n * Creates an assistant definition from its name, its UI blocks, its specialists, and the app's own\n * events it stores (see `AppEvent`).\n *\n * **Details**\n *\n * The definition holds no code that runs turns. Provide a handler with its `toLayer`, then yield\n * the definition to get the assistant's {@link Service}.\n *\n * **Example** (Defining an assistant and submitting a message)\n *\n * ```ts\n * import { Assistant, AssistantEvent, ChatId } from \"effect-assistant\"\n * import * as Effect from \"effect/Effect\"\n *\n * export const MyAssistant = Assistant.make(\"my-assistant\")\n *\n * const program = Effect.gen(function* () {\n *   const assistant = yield* MyAssistant\n *   const chatId = yield* ChatId.make()\n *\n *   yield* assistant.submit(chatId, AssistantEvent.UserMessage.make({ text: \"Weather in Oslo?\" }))\n * })\n * ```\n *\n * @see {@link Assistant} for the definition's members\n * @see {@link Service} for what `yield* MyAssistant` returns\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = <\n  const Name extends string,\n  const Specs extends ReadonlyArray<Specialist.Any> = readonly [],\n  const Events extends ReadonlyArray<AppEvent.Any> = readonly []\n>(\n  name: Name,\n  options?: {\n    /** UI blocks the assistant can add to its messages. */\n    readonly blocks?: BlockKit.BlockKit | undefined\n    /**\n     * The specialists the assistant can hand work to. Each specialist's `toLayer` must be\n     * provided to the assistant's layer.\n     */\n    readonly specialists?: Specs | undefined\n    /**\n     * The app's own events, each created with `AppEvent.make(schema, { wakes, render })`.\n     * `submit` and the chat's `append` store them, and the chat's `entries` read them back,\n     * decoded. Events that wake a turn are inputs, and the model reads each event that has a\n     * `render`.\n     */\n    readonly events?: Events | undefined\n  }\n): Assistant<Name, Specs[number], AppEvent.Type<Events[number]>> => {\n  const events = options?.events ?? []\n\n  const definition: Turns.Definition = {\n    name,\n    blocks: options?.blocks,\n    specialists: options?.specialists ?? [],\n    app: AppEvents.make(events)\n  }\n\n  type OwnEvents = AppEvent.Type<Events[number]>\n\n  const Key = Context.Service<Identifier<Name>, Service<OwnEvents>>(`effect-assistant/Assistant/${name}`)\n\n  // The app's own events go to the engine encoded, as they're stored; the library's go unchanged.\n  const stored = (\n    input: AssistantEvent.Input | OwnEvents\n  ): Effect.Effect<AssistantEvent.Input | AssistantEvent.StoredAppEvent> =>\n    AssistantEvent.isInput(input) ? Effect.succeed(input) : AppEvents.encode(definition.app, input)\n\n  const ChatKey = Context.Service<ChatIdentifier<Name>, Chat<OwnEvents>>(`effect-assistant/Assistant/${name}/Chat`)\n\n  // On the engine and the app's `Chats` the layer was given, so every caller sees the same ones.\n  const makeService = Effect.gen(function* () {\n    const engine = yield* AssistantEngine\n    const chats = yield* Chats.Chats\n\n    return Key.of({\n      submit: Effect.fn(\"Assistant.submit\")(function* (chatId: ChatId, input: AssistantEvent.Input | OwnEvents) {\n        // Checked here, where the caller can handle it: the chat checks again when it stores the input.\n        yield* chats.get(chatId)\n        yield* engine.submit(name, chatId, yield* stored(input))\n      }),\n      subscribe: (chatId, options) =>\n        engine\n          .subscribe(name, chatId, options?.after ?? 0)\n          .pipe(\n            Stream.filterMap(\n              Filter.fromPredicateOption((entry: AssistantEvent.Entry) => AppEvents.decodeEntry(definition.app, entry))\n            )\n          ),\n      delete: (chatId) => engine.delete(name, chatId)\n    })\n  })\n\n  // The signature checks what the handler uses (`CheckServices`); the layer's services, which the build\n  // required, are provided to it and to every turn's stream, so what's left is the turn services.\n  function toLayer<R = never, RE = never, E = never, RX = never>(\n    build: (Handler<R, RE, OwnEvents> | Effect.Effect<Handler<R, RE, OwnEvents>, E, RX>) &\n      Specialist.CheckServices<Exclude<HandlerServices<R | RE>, RX | ChatIdentifier<Name>>>\n  ): Layer.Layer<\n    Identifier<Name>,\n    never,\n    | AssistantEngine\n    | LanguageModel.LanguageModel\n    | Specialist.HandlerOf<Specs[number]>\n    | Exclude<RX, Scope.Scope | CurrentChat | ChatIdentifier<Name>>\n    | Specialist.ToolHandlers<R | RE>\n  >\n  function toLayer(\n    build: Handler<any, any, any> | Effect.Effect<Handler<any, any, any>, unknown, any>\n  ): Layer.Layer<Identifier<Name>, never, any> {\n    return Layer.effect(\n      Key,\n      Effect.gen(function* () {\n        const context = yield* Effect.context()\n\n        const registration = yield* Turns.register(definition, {\n          // The build runs per chat activation, in the chat; here it only keeps the layer's services for it.\n          open: (typed) =>\n            Effect.gen(function* () {\n              // The chat's entries are already decoded with this assistant's events.\n              const chat = ChatKey.of({ chatId: typed.chatId, entries: typed.entries, append: typed.append })\n              const handler = Effect.isEffect(build) ? yield* Effect.provideService(build, ChatKey, chat) : build\n\n              return (turn: Turn<any>) =>\n                Stream.provideContext(toStream(handler(turn)), context).pipe(Stream.provideService(ChatKey, chat))\n            }).pipe(Effect.provideContext(context), Effect.orDie)\n        })\n\n        yield* (yield* AssistantEngine).register(registration)\n\n        return yield* makeService\n      })\n    )\n  }\n\n  // The key is a function, whose own `name` is read-only: the assistant's name replaces it.\n  const named = Object.defineProperty(Key, \"name\", { value: name, writable: true })\n\n  return Object.assign(named, {\n    [TypeId]: TypeId,\n    name,\n    blocks: options?.blocks,\n    specialists: options?.specialists ?? [],\n    events,\n    toLayer,\n    layerClient: Layer.effect(Key, makeService),\n    Chat: ChatKey,\n    Entry: entrySchema<OwnEvents>(events)\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAwCA,MAAM,SAAS;AAoKf,MAAM,YACJ,WAGyD,OAAO,SAAS,MAAM,IAAI,OAAO,OAAO,MAAM,IAAI;;;;;;;AAmN7G,MAAa,eAAe,MAAyB,UAAU,YAAY,GAAG,MAAM;AAIpF,SAAS,YAAY,QAAiD;CACpE,OAAO,OAAO,YACZ,OAAO,OAAO;EACZ,QAAQ;EACR,KAAK,OAAO;EACZ,IAAI,OAAO;EACX,OAAO,OAAO,MAAM,CAACA,gBAA+B,GAAG,OAAO,KAAK,UAAU,MAAM,MAAM,CAAC,CAAC;CAC7F,CAAC,CACH;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiCA,MAAa,QAKX,MACA,YAgBkE;CAClE,MAAM,SAAS,SAAS,UAAU,CAAC;CAEnC,MAAM,aAA+B;EACnC;EACA,QAAQ,SAAS;EACjB,aAAa,SAAS,eAAe,CAAC;EACtC,KAAKC,OAAe,MAAM;CAC5B;CAIA,MAAM,MAAM,QAAQ,QAA8C,8BAA8B,MAAM;CAGtG,MAAM,UACJ,UAEAC,QAAuB,KAAK,IAAI,OAAO,QAAQ,KAAK,IAAIC,OAAiB,WAAW,KAAK,KAAK;CAEhG,MAAM,UAAU,QAAQ,QAA+C,8BAA8B,KAAK,MAAM;CAGhH,MAAM,cAAc,OAAO,IAAI,aAAa;EAC1C,MAAM,SAAS,OAAO;EACtB,MAAM,QAAQ,OAAOC;EAErB,OAAO,IAAI,GAAG;GACZ,QAAQ,OAAO,GAAG,kBAAkB,CAAC,CAAC,WAAW,QAAgB,OAAyC;IAExG,OAAO,MAAM,IAAI,MAAM;IACvB,OAAO,OAAO,OAAO,MAAM,QAAQ,OAAO,OAAO,KAAK,CAAC;GACzD,CAAC;GACD,YAAY,QAAQ,YAClB,OACG,UAAU,MAAM,QAAQ,SAAS,SAAS,CAAC,CAAC,CAC5C,KACC,OAAO,UACL,OAAO,qBAAqB,UAAgCC,YAAsB,WAAW,KAAK,KAAK,CAAC,CAC1G,CACF;GACJ,SAAS,WAAW,OAAO,OAAO,MAAM,MAAM;EAChD,CAAC;CACH,CAAC;CAgBD,SAAS,QACP,OAC2C;EAC3C,OAAO,MAAM,OACX,KACA,OAAO,IAAI,aAAa;GACtB,MAAM,UAAU,OAAO,OAAO,QAAQ;GAEtC,MAAM,eAAe,OAAOC,SAAe,YAAY,EAErD,OAAO,UACL,OAAO,IAAI,aAAa;IAEtB,MAAM,OAAO,QAAQ,GAAG;KAAE,QAAQ,MAAM;KAAQ,SAAS,MAAM;KAAS,QAAQ,MAAM;IAAO,CAAC;IAC9F,MAAM,UAAU,OAAO,SAAS,KAAK,IAAI,OAAO,OAAO,eAAe,OAAO,SAAS,IAAI,IAAI;IAE9F,QAAQ,SACN,OAAO,eAAe,SAAS,QAAQ,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,KAAK,OAAO,eAAe,SAAS,IAAI,CAAC;GACrG,CAAC,CAAC,CAAC,KAAK,OAAO,eAAe,OAAO,GAAG,OAAO,KAAK,EACxD,CAAC;GAED,QAAQ,OAAO,gBAAA,CAAiB,SAAS,YAAY;GAErD,OAAO,OAAO;EAChB,CAAC,CACH;CACF;CAGA,MAAM,QAAQ,OAAO,eAAe,KAAK,QAAQ;EAAE,OAAO;EAAM,UAAU;CAAK,CAAC;CAEhF,OAAO,OAAO,OAAO,OAAO;GACzB,SAAS;EACV;EACA,QAAQ,SAAS;EACjB,aAAa,SAAS,eAAe,CAAC;EACtC;EACA;EACA,aAAa,MAAM,OAAO,KAAK,WAAW;EAC1C,MAAM;EACN,OAAO,YAAuB,MAAM;CACtC,CAAC;AACH"}
+{"version":3,"file":"Assistant.js","names":["AssistantEvent.AssistantEvent","AppEvents.make","AssistantEvent.isInput","AppEvents.encode","Chats.Chats","AppEvents.decodeEntry","Turns.register"],"sources":["../src/Assistant.ts"],"sourcesContent":["/**\n * This module provides `Assistant.make`, which defines an assistant that works in a chat the way a\n * colleague does: the user messages it, it works in the background with the app's tools, and it\n * messages the user back.\n *\n * A definition is what the rest of an app imports. Yielding it (`yield* MyAssistant`) returns the\n * assistant's {@link Service}, which submits inputs to chats and streams them back. Its `toLayer`\n * registers the handler that runs each {@link Turn} with the `AssistantEngine`, and its\n * `layerClient` provides the service without a handler. Code that runs inside a chat reads and\n * extends that chat through the definition's {@link Chat} key.\n *\n * @since 0.1.0\n */\nimport type * as AiError from \"effect/ai/AiError\"\nimport type * as LanguageModel from \"effect/ai/LanguageModel\"\nimport type * as Prompt from \"effect/ai/Prompt\"\nimport type * as Tool from \"effect/ai/Tool\"\nimport type * as Toolkit from \"effect/ai/Toolkit\"\nimport * as Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Filter from \"effect/Filter\"\nimport * as Layer from \"effect/Layer\"\nimport * as Predicate from \"effect/Predicate\"\nimport * as Schema from \"effect/Schema\"\nimport type * as Scope from \"effect/Scope\"\nimport * as Stream from \"effect/Stream\"\nimport { AssistantEngine } from \"./AssistantEngine.ts\"\nimport * as AssistantEvent from \"./AssistantEvent.ts\"\nimport type * as AssistantLoop from \"./AssistantLoop.ts\"\nimport type * as BlockKit from \"./BlockKit.ts\"\nimport { ChatId } from \"./ChatId.ts\"\nimport * as Chats from \"./Chats.ts\"\nimport type { CurrentChat } from \"./CurrentChat.ts\"\nimport type * as Instructions from \"./Instructions.ts\"\nimport * as AppEvents from \"./internal/events.ts\"\nimport * as Turns from \"./internal/turns.ts\"\nimport type * as Specialist from \"./Specialist.ts\"\n\nconst TypeId = \"~effect-assistant/Assistant\" as const\n\n/**\n * Represents the services that a turn provides to its tools, its loop, and its specialists. These\n * are the turn's chat (`CurrentChat`) and the chat's specialist runner (`Specialist.Runner`).\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type TurnServices = CurrentChat | Specialist.Runner\n\n/**\n * Represents the options accepted by `turn.loop`.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface LoopOptions<T extends Record<string, Tool.Any> = Record<never, never>, Events = never> {\n  /** The assistant's role and rules. The loop places `Instructions.protocol` before them. */\n  readonly instructions: string | Instructions.Resolved\n  /**\n   * Tools the model can use in addition to the assistant's own. This is an `effect/ai` toolkit,\n   * and its handlers come from the layer. Combine several toolkits with `Toolkit.merge`, for\n   * example `Memory.Tools`, a `Skill.toolkit(...)`, or a `ToolDiscovery.make(...)` toolkit together\n   * with your own.\n   */\n  readonly toolkit?: Toolkit.Toolkit<T> | undefined\n  /** The maximum number of model calls per turn. Defaults to 16. */\n  readonly maxSteps?: number | undefined\n  /** The message the reply pass gives the model when the turn would end without a reply. */\n  readonly replyNudge?: string | undefined\n  /**\n   * Selects which of the chat's entries the model reads, for example only those since the last\n   * summary, and maps the app's own events it should read into prompt messages. Defaults to all\n   * entries, without the app's events.\n   */\n  readonly history?: HistoryView<Events> | undefined\n}\n\n/**\n * Represents a function that selects which of a chat's entries the model reads, and what else it\n * reads with them.\n *\n * **Details**\n *\n * The function receives the chat's entries, the app's own events among them, and returns, in\n * order, a mix of entries and `Prompt.Message`s. The model reads the returned entries the same way\n * it reads the full history, and reads each prompt message unchanged, where the view put it. The\n * model reads none of the app's events by itself: map those it should read to a message, and an\n * app event's entry left in the result is dropped.\n *\n * A message stands right after the entry before it: one that came after the model's last read, or\n * between a tool call and its result, moves after them, as an input does.\n *\n * **Example** (Telling the model about an order the user placed)\n *\n * ```ts\n * import { Assistant, InputId } from \"effect-assistant\"\n * import * as Prompt from \"effect/ai/Prompt\"\n * import * as Schema from \"effect/Schema\"\n *\n * class OrderPlaced extends Schema.TaggedClass<OrderPlaced>()(\"OrderPlaced\", {\n *   id: InputId.InputId,\n *   reference: Schema.String\n * }) {}\n *\n * const MyAssistant = Assistant.make(\"my-assistant\", { events: [OrderPlaced] })\n *\n * const withOrders: Assistant.HistoryView<OrderPlaced> = (entries) =>\n *   entries.map((entry) =>\n *     entry.event instanceof OrderPlaced\n *       ? Prompt.userMessage({\n *           content: [Prompt.textPart({ text: `The user placed order ${entry.event.reference}.` })]\n *         })\n *       : entry\n *   )\n *\n * // An `OrderPlaced` that the API submits wakes a turn, which reads it as this note.\n * const MyAssistantLive = MyAssistant.toLayer((turn) =>\n *   turn.loop({ instructions: \"Be brief.\", history: withOrders })\n * )\n * ```\n *\n * @category models\n * @since 0.1.0\n */\nexport type HistoryView<Events = never> = (\n  entries: ReadonlyArray<Entry<Events>>\n) => ReadonlyArray<Entry<Events> | Prompt.Message>\n\n/**\n * Represents an entry in a chat's log, with the assistant's own events decoded to their types.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Entry<Events = never> {\n  readonly chatId: ChatId\n  readonly seq: number\n  readonly at: number\n  readonly event: AssistantEvent.AssistantEvent | Events\n}\n\n/**\n * Represents the options accepted by `turn.replyIfOwed`.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface ReplyOptions {\n  /** The assistant's instructions, as passed to `turn.loop`. `Instructions.protocol` is added. */\n  readonly instructions: string | Instructions.Resolved\n  /**\n   * The message given to the model after the history. Defaults to a message saying that it\n   * hasn't replied yet and should reply now.\n   */\n  readonly nudge?: string | undefined\n}\n\n/**\n * Represents one turn, as the assistant's handler receives it.\n *\n * `Events` is the type of the app's own events that the assistant registered with its `events`\n * option.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Turn<Events = never> {\n  readonly chatId: ChatId\n  /**\n   * Returns the model's history, built from the chat's entries (all of them, or those a view\n   * keeps), together with how far into the chat it reaches.\n   *\n   * Read it before every model call, as the loop does. Each step records how far its model call\n   * read, and the turn ends once it has handled what the model saw. An input that arrived after\n   * that is handled by the next turn.\n   */\n  readonly history: (view?: HistoryView<Events>) => Effect.Effect<AssistantLoop.ChatHistory>\n  /**\n   * Returns the full system prompt for the given instructions. It contains\n   * `Instructions.protocol`, the instructions, and the specialist runs that are working now.\n   */\n  readonly instructions: (instructions: string | Instructions.Resolved) => Instructions.Resolved\n  /**\n   * Runs the agent loop over the chat. The loop uses `Instructions.protocol`, the assistant's own\n   * tools, and the instructions and tools in `options`. Every step is a tool call, and\n   * the loop ends with `replyIfOwed`.\n   */\n  readonly loop: <T extends Record<string, Tool.Any> = Record<never, never>>(\n    options: LoopOptions<T, Events>\n  ) => Stream.Stream<\n    AssistantLoop.Event,\n    AiError.AiError,\n    LanguageModel.LanguageModel | TurnServices | AssistantLoop.ToolkitServices<T>\n  >\n  /**\n   * Runs one more pass when the turn would otherwise end without a reply to the user's latest\n   * message. In this pass the model can only reply.\n   *\n   * The stream is empty when no reply is owed, or when an input arrived that the next turn will\n   * read. `loop` runs this pass with its own prompt and tools, so the pass reuses the cached\n   * prompt.\n   */\n  readonly replyIfOwed: (\n    options: ReplyOptions\n  ) => Stream.Stream<AssistantLoop.Event, AiError.AiError, LanguageModel.LanguageModel | TurnServices>\n}\n\n/**\n * Represents an assistant's handler, which runs a turn and returns it as a stream of the loop's\n * events.\n *\n * The handler may return the stream directly or from an Effect. `R` is the services the stream\n * requires, and `RE` is the services the Effect requires.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Handler<R = never, RE = R, Events = never> = (\n  turn: Turn<Events>\n) =>\n  | Stream.Stream<AssistantLoop.Event, unknown, R>\n  | Effect.Effect<Stream.Stream<AssistantLoop.Event, unknown, R>, unknown, RE>\n\n/**\n * Computes the services an assistant's handler needs beyond those its turns provide (the turn\n * services and `LanguageModel`) and its tools' handlers (which its layer requires). These are the\n * services that its build Effect must require.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type HandlerServices<R> = Exclude<R, TurnServices | LanguageModel.LanguageModel | Tool.Handler<string>>\n\nconst toStream = <R, RE>(\n  result:\n    | Stream.Stream<AssistantLoop.Event, unknown, R>\n    | Effect.Effect<Stream.Stream<AssistantLoop.Event, unknown, R>, unknown, RE>\n): Stream.Stream<AssistantLoop.Event, unknown, R | RE> => (Effect.isEffect(result) ? Stream.unwrap(result) : result)\n\n/**\n * Identifies an assistant's service in a context. Each assistant has its own identifier, keyed by\n * its name.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Identifier<Name extends string> {\n  readonly \"~effect-assistant/Assistant\": Name\n}\n\n/**\n * Identifies, in a context, the chat that an assistant's turns run in.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface ChatIdentifier<Name extends string> {\n  readonly \"~effect-assistant/Assistant/Chat\": Name\n}\n\n/**\n * Represents the chat that a turn of this assistant runs in, typed with the assistant's events.\n *\n * Use `yield* MyAssistant.Chat` in the handler, in the handler's build, or in a tool that its\n * turns run. Code that doesn't know the assistant uses `CurrentChat` instead.\n *\n * @see {@link CurrentChat} for the same chat without the assistant's event types\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Chat<Events = never> {\n  readonly chatId: ChatId\n  /**\n   * The chat's entries so far, in order. They include the library's events and the assistant's\n   * own events, typed.\n   */\n  readonly entries: Effect.Effect<ReadonlyArray<Entry<Events>>>\n  /**\n   * Appends events after the chat's last entry and sends them to the chat's subscribers. The\n   * events can be the library's or the assistant's own, such as a summary. None of them wakes a\n   * turn: only what comes in through the assistant's `submit` does.\n   */\n  append(...events: ReadonlyArray<AssistantEvent.AssistantEvent | Events>): Effect.Effect<void>\n}\n\n/**\n * Represents the service that `yield* MyAssistant` returns. It gives code outside a chat, such as\n * a server or a workflow, access to the assistant's chats. Code that runs inside a chat uses\n * `CurrentChat` instead.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Service<Events = never> {\n  /**\n   * Stores an input or one of the assistant's own events, then returns. Examples are a user's\n   * message or block answer, a workflow's progress, or the order the user placed. Each one is an\n   * input: storing it wakes a turn, which the assistant runs in the background. The handler decides\n   * what the turn does with it, and an app event the model should read needs a history view that\n   * maps it (see {@link HistoryView}). To store an app event without waking a turn, append it from\n   * within the chat instead (`yield* MyAssistant.Chat`).\n   *\n   * Fails with `GetChatError` when the app's `Chats` service reports that the chat can't be used,\n   * because the app doesn't know the chat or has deleted it.\n   */\n  // Method syntax: a service for these events is one for any (`Service<any>`), for helpers over assistants.\n  submit(chatId: ChatId, input: AssistantEvent.Input | Events): Effect.Effect<void, Chats.GetChatError>\n  /**\n   * Streams the chat's stored entries, then live ones, with the assistant's own events decoded.\n   * A reader that already has the earlier entries passes `after` and receives only the entries\n   * after that `seq`.\n   *\n   * For a chat client, pipe the whole log into `Timeline.changes(MyAssistant, { after })`, which\n   * streams the chat's timeline, as its user sees it. Its `after` goes there, not here: a message\n   * on the timeline depends on earlier entries. The timeline shows only the app events named in its\n   * `show`, none by default (see `Timeline.changes`).\n   */\n  readonly subscribe: (\n    chatId: ChatId,\n    options?: { readonly after?: number | undefined }\n  ) => Stream.Stream<Entry<Events>>\n  /**\n   * Deletes a chat by storing a `ChatDeleted` event and stopping everything that works in it.\n   *\n   * **Details**\n   *\n   * A turn or specialist run working in the chat stops, and subscribers' streams end with the\n   * `ChatDeleted` event. After that the chat stores nothing more: a later input, a run's report,\n   * or a workflow's event for it is dropped without an error. The log is kept, and removing it is\n   * up to the app. Deleting a chat a second time does nothing.\n   *\n   * When the app's `Chats` service reports a chat as deleted, the assistant deletes it in the same\n   * way the next time it checks. It checks before an input is stored and before each model call.\n   */\n  readonly delete: (chatId: ChatId) => Effect.Effect<void>\n}\n\n/**\n * Represents an assistant's definition.\n *\n * The definition holds what callers and the UI need to know about the assistant, builds its\n * handler's layer, and is the key of its service (`yield* MyAssistant`). `Events` is the type of\n * the app's own events that the assistant registered.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Assistant<\n  Name extends string = string,\n  Specs extends Specialist.Any = never,\n  Events = never\n> extends Context.Service<Identifier<Name>, Service<Events>> {\n  readonly [TypeId]: typeof TypeId\n  readonly name: Name\n  readonly blocks: BlockKit.BlockKit | undefined\n  /** The specialists the assistant can hand work to. */\n  readonly specialists: ReadonlyArray<Specs>\n  /** The schemas of the app's own events the assistant stores. */\n  readonly events: ReadonlyArray<AssistantEvent.AppEventSchema>\n  /**\n   * Creates a layer that registers the assistant's handler with the engine and provides the\n   * assistant's service.\n   *\n   * **Details**\n   *\n   * `build` is the handler, or an Effect that returns it. The handler may use the turn services,\n   * `LanguageModel`, its tools' handlers (which the layer then requires), and services that its\n   * build Effect required (see `Specialist.CheckServices`). The layer requires the\n   * `AssistantEngine`, the `LanguageModel`, and each specialist's handler\n   * (`Research.toLayer(...)`).\n   *\n   * **Example** (Providing an assistant's handler)\n   *\n   * ```ts\n   * import { Assistant, AssistantEngine, ChatLog } from \"effect-assistant\"\n   * import type * as LanguageModel from \"effect/ai/LanguageModel\"\n   * import * as Layer from \"effect/Layer\"\n   *\n   * declare const ModelLive: Layer.Layer<LanguageModel.LanguageModel>\n   *\n   * export const MyAssistant = Assistant.make(\"my-assistant\")\n   *\n   * const MyAssistantLive = MyAssistant.toLayer((turn) =>\n   *   turn.loop({ instructions: \"You help a small team. Be brief.\" })\n   * )\n   *\n   * const AppLive = MyAssistantLive.pipe(\n   *   Layer.provide(ModelLive),\n   *   Layer.provideMerge(AssistantEngine.layerMemory),\n   *   Layer.provideMerge(ChatLog.layerMemory)\n   * )\n   * ```\n   */\n  readonly toLayer: <R = never, RE = never, E = never, RX = never>(\n    build: (Handler<R, RE, Events> | Effect.Effect<Handler<R, RE, Events>, E, RX>) &\n      Specialist.CheckServices<Exclude<HandlerServices<R | RE>, RX | ChatIdentifier<Name>>>\n  ) => Layer.Layer<\n    Identifier<Name>,\n    never,\n    | AssistantEngine\n    | LanguageModel.LanguageModel\n    | Specialist.HandlerOf<Specs>\n    | Exclude<RX, Scope.Scope | CurrentChat | ChatIdentifier<Name>>\n    | Specialist.ToolHandlers<R | RE>\n  >\n  /**\n   * A layer that provides the assistant's service without its handler.\n   *\n   * **When to use**\n   *\n   * Use it in a process that submits to chats that another process runs, such as a web server in\n   * front of a cluster.\n   *\n   * **Example** (Serving clients in front of a cluster)\n   *\n   * ```ts\n   * import { Assistant, AssistantEngine } from \"effect-assistant\"\n   * import * as Layer from \"effect/Layer\"\n   *\n   * export const MyAssistant = Assistant.make(\"my-assistant\")\n   *\n   * // Requires `Sharding`. The cluster's runners run the chats, with `AssistantEngine.layerCluster`.\n   * const MyAssistantClient = MyAssistant.layerClient.pipe(\n   *   Layer.provide(AssistantEngine.layerClusterClient)\n   * )\n   * ```\n   */\n  readonly layerClient: Layer.Layer<Identifier<Name>, never, AssistantEngine>\n  /**\n   * The key of the chat that the assistant's turns run in, typed with its events. See\n   * {@link Chat}.\n   */\n  readonly Chat: Context.Service<ChatIdentifier<Name>, Chat<Events>>\n  /** A schema that encodes the chat's entries to JSON, including the assistant's own events. */\n  readonly Entry: Schema.Codec<Entry<Events>, Schema.Json>\n}\n\n/**\n * Represents any assistant, for use in generic constraints.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type Any = Assistant<any, any, any>\n\n/**\n * Returns `true` when the value is an assistant's definition, created with {@link make}.\n *\n * @category guards\n * @since 0.1.0\n */\nexport const isAssistant = (u: unknown): u is Any => Predicate.hasProperty(u, TypeId)\n\nfunction entrySchema<E>(events: ReadonlyArray<AssistantEvent.AppEventSchema>): Schema.Codec<Entry<E>, Schema.Json>\n// The overload states the decoded type: the library's events, or one of these schemas' types.\nfunction entrySchema(events: ReadonlyArray<AssistantEvent.AppEventSchema>): Schema.Top {\n  return Schema.toCodecJson(\n    Schema.Struct({\n      chatId: ChatId,\n      seq: Schema.Int,\n      at: Schema.Finite,\n      event: Schema.Union([AssistantEvent.AssistantEvent, ...events])\n    })\n  )\n}\n\n/**\n * Creates an assistant definition from its name, its UI blocks, its specialists, and the schemas of\n * the app's own events it stores.\n *\n * **Details**\n *\n * The definition holds no code that runs turns. Provide a handler with its `toLayer`, then yield\n * the definition to get the assistant's {@link Service}.\n *\n * The definition only says which of the app's events a chat stores. What happens with one is up\n * to the places that use it. One that comes in through the service's `submit`, from outside a\n * turn, is an input and wakes a turn, like a user's message; one a turn appends to its chat never\n * does. The handler decides what a turn does, a history view says how the model reads an event\n * ({@link HistoryView}), and the chat's timeline says which its user sees\n * (`Timeline.changes`).\n *\n * **Example** (Defining an assistant and submitting a message)\n *\n * ```ts\n * import { Assistant, AssistantEvent, ChatId } from \"effect-assistant\"\n * import * as Effect from \"effect/Effect\"\n *\n * export const MyAssistant = Assistant.make(\"my-assistant\")\n *\n * const program = Effect.gen(function* () {\n *   const assistant = yield* MyAssistant\n *   const chatId = yield* ChatId.make()\n *\n *   yield* assistant.submit(chatId, AssistantEvent.UserMessage.make({ text: \"Weather in Oslo?\" }))\n * })\n * ```\n *\n * @see {@link Assistant} for the definition's members\n * @see {@link Service} for what `yield* MyAssistant` returns\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = <\n  const Name extends string,\n  const Specs extends ReadonlyArray<Specialist.Any> = readonly [],\n  const Events extends ReadonlyArray<AssistantEvent.AppEventSchema> = readonly []\n>(\n  name: Name,\n  options?: {\n    /** UI blocks the assistant can add to its messages. */\n    readonly blocks?: BlockKit.BlockKit | undefined\n    /**\n     * The specialists the assistant can hand work to. Each specialist's `toLayer` must be\n     * provided to the assistant's layer.\n     */\n    readonly specialists?: Specs | undefined\n    /**\n     * The schemas of the app's own events, each a tagged struct or class. `submit` and the chat's\n     * `append` store them, in their JSON form, and the chat's `entries` and `subscribe` read them\n     * back, decoded. Each needs a tag of its own that isn't one of the library's: `make` throws\n     * otherwise.\n     */\n    readonly events?: Events | undefined\n  }\n): Assistant<Name, Specs[number], Events[number][\"Type\"]> => {\n  const events = options?.events ?? []\n\n  const definition: Turns.Definition = {\n    name,\n    blocks: options?.blocks,\n    specialists: options?.specialists ?? [],\n    app: AppEvents.make(events)\n  }\n\n  type OwnEvents = Events[number][\"Type\"]\n\n  const Key = Context.Service<Identifier<Name>, Service<OwnEvents>>(`effect-assistant/Assistant/${name}`)\n\n  // The app's own events go to the engine encoded, as they're stored; the library's go unchanged.\n  const stored = (\n    input: AssistantEvent.Input | OwnEvents\n  ): Effect.Effect<AssistantEvent.Input | AssistantEvent.StoredAppEvent> =>\n    AssistantEvent.isInput(input) ? Effect.succeed(input) : AppEvents.encode(definition.app, input)\n\n  const ChatKey = Context.Service<ChatIdentifier<Name>, Chat<OwnEvents>>(`effect-assistant/Assistant/${name}/Chat`)\n\n  // On the engine and the app's `Chats` the layer was given, so every caller sees the same ones.\n  const makeService = Effect.gen(function* () {\n    const engine = yield* AssistantEngine\n    const chats = yield* Chats.Chats\n\n    return Key.of({\n      submit: Effect.fn(\"Assistant.submit\")(function* (chatId: ChatId, input: AssistantEvent.Input | OwnEvents) {\n        // Checked here, where the caller can handle it: the chat checks again when it stores the input.\n        yield* chats.get(chatId)\n        yield* engine.submit(name, chatId, yield* stored(input))\n      }),\n      subscribe: (chatId, options) =>\n        engine\n          .subscribe(name, chatId, options?.after ?? 0)\n          .pipe(\n            Stream.filterMap(\n              Filter.fromPredicateOption((entry: AssistantEvent.Entry) => AppEvents.decodeEntry(definition.app, entry))\n            )\n          ),\n      delete: (chatId) => engine.delete(name, chatId)\n    })\n  })\n\n  // The signature checks what the handler uses (`CheckServices`); the layer's services, which the build\n  // required, are provided to it and to every turn's stream, so what's left is the turn services.\n  function toLayer<R = never, RE = never, E = never, RX = never>(\n    build: (Handler<R, RE, OwnEvents> | Effect.Effect<Handler<R, RE, OwnEvents>, E, RX>) &\n      Specialist.CheckServices<Exclude<HandlerServices<R | RE>, RX | ChatIdentifier<Name>>>\n  ): Layer.Layer<\n    Identifier<Name>,\n    never,\n    | AssistantEngine\n    | LanguageModel.LanguageModel\n    | Specialist.HandlerOf<Specs[number]>\n    | Exclude<RX, Scope.Scope | CurrentChat | ChatIdentifier<Name>>\n    | Specialist.ToolHandlers<R | RE>\n  >\n  function toLayer(\n    build: Handler<any, any, any> | Effect.Effect<Handler<any, any, any>, unknown, any>\n  ): Layer.Layer<Identifier<Name>, never, any> {\n    return Layer.effect(\n      Key,\n      Effect.gen(function* () {\n        const context = yield* Effect.context()\n\n        const registration = yield* Turns.register(definition, {\n          // The build runs per chat activation, in the chat; here it only keeps the layer's services for it.\n          open: (typed) =>\n            Effect.gen(function* () {\n              // The chat's entries are already decoded with this assistant's events.\n              const chat = ChatKey.of({ chatId: typed.chatId, entries: typed.entries, append: typed.append })\n              const handler = Effect.isEffect(build) ? yield* Effect.provideService(build, ChatKey, chat) : build\n\n              return (turn: Turn<any>) =>\n                Stream.provideContext(toStream(handler(turn)), context).pipe(Stream.provideService(ChatKey, chat))\n            }).pipe(Effect.provideContext(context), Effect.orDie)\n        })\n\n        yield* (yield* AssistantEngine).register(registration)\n\n        return yield* makeService\n      })\n    )\n  }\n\n  // The key is a function, whose own `name` is read-only: the assistant's name replaces it.\n  const named = Object.defineProperty(Key, \"name\", { value: name, writable: true })\n\n  return Object.assign(named, {\n    [TypeId]: TypeId,\n    name,\n    blocks: options?.blocks,\n    specialists: options?.specialists ?? [],\n    events,\n    toLayer,\n    layerClient: Layer.effect(Key, makeService),\n    Chat: ChatKey,\n    Entry: entrySchema<OwnEvents>(events)\n  })\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAsCA,MAAM,SAAS;AAmMf,MAAM,YACJ,WAGyD,OAAO,SAAS,MAAM,IAAI,OAAO,OAAO,MAAM,IAAI;;;;;;;AAuN7G,MAAa,eAAe,MAAyB,UAAU,YAAY,GAAG,MAAM;AAIpF,SAAS,YAAY,QAAkE;CACrF,OAAO,OAAO,YACZ,OAAO,OAAO;EACZ,QAAQ;EACR,KAAK,OAAO;EACZ,IAAI,OAAO;EACX,OAAO,OAAO,MAAM,CAACA,gBAA+B,GAAG,MAAM,CAAC;CAChE,CAAC,CACH;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,MAAa,QAKX,MACA,YAgB2D;CAC3D,MAAM,SAAS,SAAS,UAAU,CAAC;CAEnC,MAAM,aAA+B;EACnC;EACA,QAAQ,SAAS;EACjB,aAAa,SAAS,eAAe,CAAC;EACtC,KAAKC,OAAe,MAAM;CAC5B;CAIA,MAAM,MAAM,QAAQ,QAA8C,8BAA8B,MAAM;CAGtG,MAAM,UACJ,UAEAC,QAAuB,KAAK,IAAI,OAAO,QAAQ,KAAK,IAAIC,OAAiB,WAAW,KAAK,KAAK;CAEhG,MAAM,UAAU,QAAQ,QAA+C,8BAA8B,KAAK,MAAM;CAGhH,MAAM,cAAc,OAAO,IAAI,aAAa;EAC1C,MAAM,SAAS,OAAO;EACtB,MAAM,QAAQ,OAAOC;EAErB,OAAO,IAAI,GAAG;GACZ,QAAQ,OAAO,GAAG,kBAAkB,CAAC,CAAC,WAAW,QAAgB,OAAyC;IAExG,OAAO,MAAM,IAAI,MAAM;IACvB,OAAO,OAAO,OAAO,MAAM,QAAQ,OAAO,OAAO,KAAK,CAAC;GACzD,CAAC;GACD,YAAY,QAAQ,YAClB,OACG,UAAU,MAAM,QAAQ,SAAS,SAAS,CAAC,CAAC,CAC5C,KACC,OAAO,UACL,OAAO,qBAAqB,UAAgCC,YAAsB,WAAW,KAAK,KAAK,CAAC,CAC1G,CACF;GACJ,SAAS,WAAW,OAAO,OAAO,MAAM,MAAM;EAChD,CAAC;CACH,CAAC;CAgBD,SAAS,QACP,OAC2C;EAC3C,OAAO,MAAM,OACX,KACA,OAAO,IAAI,aAAa;GACtB,MAAM,UAAU,OAAO,OAAO,QAAQ;GAEtC,MAAM,eAAe,OAAOC,SAAe,YAAY,EAErD,OAAO,UACL,OAAO,IAAI,aAAa;IAEtB,MAAM,OAAO,QAAQ,GAAG;KAAE,QAAQ,MAAM;KAAQ,SAAS,MAAM;KAAS,QAAQ,MAAM;IAAO,CAAC;IAC9F,MAAM,UAAU,OAAO,SAAS,KAAK,IAAI,OAAO,OAAO,eAAe,OAAO,SAAS,IAAI,IAAI;IAE9F,QAAQ,SACN,OAAO,eAAe,SAAS,QAAQ,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,KAAK,OAAO,eAAe,SAAS,IAAI,CAAC;GACrG,CAAC,CAAC,CAAC,KAAK,OAAO,eAAe,OAAO,GAAG,OAAO,KAAK,EACxD,CAAC;GAED,QAAQ,OAAO,gBAAA,CAAiB,SAAS,YAAY;GAErD,OAAO,OAAO;EAChB,CAAC,CACH;CACF;CAGA,MAAM,QAAQ,OAAO,eAAe,KAAK,QAAQ;EAAE,OAAO;EAAM,UAAU;CAAK,CAAC;CAEhF,OAAO,OAAO,OAAO,OAAO;GACzB,SAAS;EACV;EACA,QAAQ,SAAS;EACjB,aAAa,SAAS,eAAe,CAAC;EACtC;EACA;EACA,aAAa,MAAM,OAAO,KAAK,WAAW;EAC1C,MAAM;EACN,OAAO,YAAuB,MAAM;CACtC,CAAC;AACH"}

package/dist/AssistantActivity.d.ts

@@ -1,7 +1,7 @@
 import { AnyEntry, AssistantEvent_d_exports } from "./AssistantEvent.js";
 import { RunId } from "./RunId.js";
 declare namespace AssistantActivity_d_exports {
-  export { Options, SpecialistRun, State, apply, empty, fromEntries, isWorking };
+  export { SpecialistRun, State, apply, empty, fromEntries, isWorking };
 }
 /**
  * Represents a specialist run that is working.
@@ -43,27 +43,21 @@ export interface State {
  * @since 0.1.0
  */
 export declare const empty: State;
-/**
- * Represents the options for folding a chat's entries into its activity.
- *
- * @category models
- * @since 0.1.0
- */
-export interface Options {
-  /**
-   * The tags of the app's events that wake a turn (see `AppEvent`). These events count as inputs
-   * too. Defaults to none.
-   */
-  readonly wakes?: ReadonlySet<string> | undefined;
-}
 /**
  * Returns the activity after one more entry. Fold a chat's entries in order, or use
  * {@link fromEntries}.
  *
+ * **Details**
+ *
+ * One of the app's events counts as an input, and a turn as about to start, when it came in
+ * through the assistant's `submit`. The log marks it so (`AssistantEvent.isAppInput`), as
+ * `ChatLog.read` returns it; `subscribe` streams it decoded, without the mark, so there the turn
+ * shows from its `TurnStarted`.
+ *
  * @category combinators
  * @since 0.1.0
  */
-export declare const apply: (activity: State, entry: AnyEntry, options?: Options) => State;
+export declare const apply: (activity: State, entry: AnyEntry) => State;
 /**
  * Returns what is working in a chat after the given entries, folded in order from
  * {@link empty}.
@@ -71,7 +65,7 @@ export declare const apply: (activity: State, entry: AnyEntry, options?: Options
  * @category constructors
  * @since 0.1.0
  */
-export declare const fromEntries: (entries: ReadonlyArray<AnyEntry>, options?: Options) => State;
+export declare const fromEntries: (entries: ReadonlyArray<AnyEntry>) => State;
 /**
  * Returns whether anything is working: a turn that is running or about to start, or a specialist
  * run.

package/dist/AssistantActivity.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AssistantActivity.d.ts","names":[],"sources":["../src/AssistantActivity.ts"],"mappings":";;;;;;;;;;;iBAsBiB;WACN,OAAO;WACP;;WAEA;;WAEA;;;;;;;;iBASM;;WAEN;;;;;WAKA;;WAEA;;WAEA,aAAa,YAAY,OAAO;;;;;;;;qBAS9B,OAAO;;;;;;;iBAsBH;;;;;WAKN,QAAQ;;;;;;;;;qBAUN,QAAK,UAAc,OAAK,OAAS,UAAuB,UAAY,YAAU;;;;;;;;qBA4C9E,cAAW,SAAa,cAAc,WAAwB,UAAY,YAAU;;;;;;;;qBAUpF,YAAS,UAAc"}
+{"version":3,"file":"AssistantActivity.d.ts","names":[],"sources":["../src/AssistantActivity.ts"],"mappings":";;;;;;;;;;;iBAsBiB;WACN,OAAO;WACP;;WAEA;;WAEA;;;;;;;;iBASM;;WAEN;;;;;WAKA;;WAEA;;WAEA,aAAa,YAAY,OAAO;;;;;;;;qBAS9B,OAAO;;;;;;;;;;;;;;;qBA8BP,QAAK,UAAc,OAAK,OAAS,aAA0B;;;;;;;;qBA4C3D,cAAW,SAAa,cAAc,cAA2B;;;;;;;;qBAUjE,YAAS,UAAc"}

package/dist/AssistantActivity.js

@@ -1,5 +1,5 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
-import { isInput, isLibraryEvent, isWaking } from "./AssistantEvent.js";
+import { isAppInput, isInput, isLibraryEvent, isWaking } from "./AssistantEvent.js";
 import * as Predicate from "effect/Predicate";
 import * as Match from "effect/Match";
 //#region src/AssistantActivity.ts
@@ -45,12 +45,19 @@ const withoutRun = (activity, runId) => {
 * Returns the activity after one more entry. Fold a chat's entries in order, or use
 * {@link fromEntries}.
 *
+* **Details**
+*
+* One of the app's events counts as an input, and a turn as about to start, when it came in
+* through the assistant's `submit`. The log marks it so (`AssistantEvent.isAppInput`), as
+* `ChatLog.read` returns it; `subscribe` streams it decoded, without the mark, so there the turn
+* shows from its `TurnStarted`.
+*
 * @category combinators
 * @since 0.1.0
 */
-const apply = (activity, entry, options) => {
+const apply = (activity, entry) => {
 	const event = entry.event;
-	if (!isLibraryEvent(event)) return options?.wakes?.has(event._tag) === true ? {
+	if (!isLibraryEvent(event)) return isAppInput(event) ? {
 		...activity,
 		queued: true,
 		lastInputSeq: entry.seq
@@ -90,7 +97,7 @@ const apply = (activity, entry, options) => {
 * @category constructors
 * @since 0.1.0
 */
-const fromEntries = (entries, options) => entries.reduce((activity, entry) => apply(activity, entry, options), empty);
+const fromEntries = (entries) => entries.reduce((activity, entry) => apply(activity, entry), empty);
 /**
 * Returns whether anything is working: a turn that is running or about to start, or a specialist
 * run.

package/dist/AssistantActivity.js.map

@@ -1 +1 @@
-{"version":3,"file":"AssistantActivity.js","names":["AssistantEvent.isLibraryEvent","AssistantEvent.isInput","AssistantEvent.isWaking"],"sources":["../src/AssistantActivity.ts"],"sourcesContent":["/**\n * This module provides functions that determine what is working in a chat right now, read from\n * the chat's log.\n *\n * A {@link State} records whether the assistant is running a turn or is about to start one,\n * and which specialist runs are working. Fold a chat's entries into it with {@link apply}, or\n * build it from a list of entries with {@link fromEntries}, then check it with\n * {@link isWorking}.\n *\n * @since 0.1.0\n */\nimport * as Match from \"effect/Match\"\nimport * as Predicate from \"effect/Predicate\"\nimport * as AssistantEvent from \"./AssistantEvent.ts\"\nimport type { RunId } from \"./RunId.ts\"\n\n/**\n * Represents a specialist run that is working.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface SpecialistRun {\n  readonly runId: RunId\n  readonly specialist: string\n  /** The goal the run is working on. */\n  readonly goal: string\n  /** When the run started, in epoch milliseconds. */\n  readonly since: number\n}\n\n/**\n * Represents what is working in a chat.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface State {\n  /** When the running turn started, in epoch milliseconds, or `undefined` when no turn runs. */\n  readonly turnSince: number | undefined\n  /**\n   * Whether an input arrived that no finished turn has read. When this is true, a turn is about\n   * to start.\n   */\n  readonly queued: boolean\n  /** The `seq` of the newest input. */\n  readonly lastInputSeq: number\n  /** Specialist runs that are working, by run id. */\n  readonly specialists: ReadonlyMap<RunId, SpecialistRun>\n}\n\n/**\n * The activity of a chat with an empty log, where nothing is working.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const empty: State = {\n  turnSince: undefined,\n  queued: false,\n  lastInputSeq: 0,\n  specialists: new Map()\n}\n\nconst withoutRun = (activity: State, runId: RunId): State => {\n  if (!activity.specialists.has(runId)) return activity\n\n  const specialists = new Map(activity.specialists)\n  specialists.delete(runId)\n\n  return { ...activity, specialists }\n}\n\n/**\n * Represents the options for folding a chat's entries into its activity.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Options {\n  /**\n   * The tags of the app's events that wake a turn (see `AppEvent`). These events count as inputs\n   * too. Defaults to none.\n   */\n  readonly wakes?: ReadonlySet<string> | undefined\n}\n\n/**\n * Returns the activity after one more entry. Fold a chat's entries in order, or use\n * {@link fromEntries}.\n *\n * @category combinators\n * @since 0.1.0\n */\nexport const apply = (activity: State, entry: AssistantEvent.AnyEntry, options?: Options): State => {\n  const event = entry.event\n\n  if (!AssistantEvent.isLibraryEvent(event)) {\n    return options?.wakes?.has(event._tag) === true ? { ...activity, queued: true, lastInputSeq: entry.seq } : activity\n  }\n\n  if (AssistantEvent.isInput(event)) {\n    // A finished run's report is an input, and ends the run.\n    const current = Predicate.isTagged(event, \"SpecialistFinished\") ? withoutRun(activity, event.runId) : activity\n\n    return AssistantEvent.isWaking(event) ? { ...current, queued: true, lastInputSeq: entry.seq } : current\n  }\n\n  return Match.value(event).pipe(\n    Match.tag(\"TurnStarted\", (): State => ({ ...activity, turnSince: entry.at })),\n    // Turns run one at a time, so an end closes whichever turn is open, also one a restart cut off.\n    Match.tag(\"TurnCompleted\", \"TurnFailed\", (ended): State => ({\n      ...activity,\n      turnSince: undefined,\n      queued: activity.lastInputSeq > ended.throughSeq\n    })),\n    Match.tag(\"SpecialistStarted\", (started): State => ({\n      ...activity,\n      specialists: new Map(activity.specialists).set(started.runId, {\n        runId: started.runId,\n        specialist: started.specialist,\n        goal: started.goal,\n        since: entry.at\n      })\n    })),\n    // Deleting a chat stops everything in it, and nothing starts again.\n    Match.tag(\"ChatDeleted\", (): State => ({ ...empty, lastInputSeq: activity.lastInputSeq })),\n    Match.orElse(() => activity)\n  )\n}\n\n/**\n * Returns what is working in a chat after the given entries, folded in order from\n * {@link empty}.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const fromEntries = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, options?: Options): State =>\n  entries.reduce((activity, entry) => apply(activity, entry, options), empty)\n\n/**\n * Returns whether anything is working: a turn that is running or about to start, or a specialist\n * run.\n *\n * @category guards\n * @since 0.1.0\n */\nexport const isWorking = (activity: State): boolean =>\n  activity.turnSince !== undefined || activity.queued || activity.specialists.size > 0\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,MAAa,QAAe;CAC1B,WAAW,KAAA;CACX,QAAQ;CACR,cAAc;CACd,6BAAa,IAAI,IAAI;AACvB;AAEA,MAAM,cAAc,UAAiB,UAAwB;CAC3D,IAAI,CAAC,SAAS,YAAY,IAAI,KAAK,GAAG,OAAO;CAE7C,MAAM,cAAc,IAAI,IAAI,SAAS,WAAW;CAChD,YAAY,OAAO,KAAK;CAExB,OAAO;EAAE,GAAG;EAAU;CAAY;AACpC;;;;;;;;AAuBA,MAAa,SAAS,UAAiB,OAAgC,YAA6B;CAClG,MAAM,QAAQ,MAAM;CAEpB,IAAI,CAACA,eAA8B,KAAK,GACtC,OAAO,SAAS,OAAO,IAAI,MAAM,IAAI,MAAM,OAAO;EAAE,GAAG;EAAU,QAAQ;EAAM,cAAc,MAAM;CAAI,IAAI;CAG7G,IAAIC,QAAuB,KAAK,GAAG;EAEjC,MAAM,UAAU,UAAU,SAAS,OAAO,oBAAoB,IAAI,WAAW,UAAU,MAAM,KAAK,IAAI;EAEtG,OAAOC,SAAwB,KAAK,IAAI;GAAE,GAAG;GAAS,QAAQ;GAAM,cAAc,MAAM;EAAI,IAAI;CAClG;CAEA,OAAO,MAAM,MAAM,KAAK,CAAC,CAAC,KACxB,MAAM,IAAI,sBAA6B;EAAE,GAAG;EAAU,WAAW,MAAM;CAAG,EAAE,GAE5E,MAAM,IAAI,iBAAiB,eAAe,WAAkB;EAC1D,GAAG;EACH,WAAW,KAAA;EACX,QAAQ,SAAS,eAAe,MAAM;CACxC,EAAE,GACF,MAAM,IAAI,sBAAsB,aAAoB;EAClD,GAAG;EACH,aAAa,IAAI,IAAI,SAAS,WAAW,CAAC,CAAC,IAAI,QAAQ,OAAO;GAC5D,OAAO,QAAQ;GACf,YAAY,QAAQ;GACpB,MAAM,QAAQ;GACd,OAAO,MAAM;EACf,CAAC;CACH,EAAE,GAEF,MAAM,IAAI,sBAA6B;EAAE,GAAG;EAAO,cAAc,SAAS;CAAa,EAAE,GACzF,MAAM,aAAa,QAAQ,CAC7B;AACF;;;;;;;;AASA,MAAa,eAAe,SAAiD,YAC3E,QAAQ,QAAQ,UAAU,UAAU,MAAM,UAAU,OAAO,OAAO,GAAG,KAAK;;;;;;;;AAS5E,MAAa,aAAa,aACxB,SAAS,cAAc,KAAA,KAAa,SAAS,UAAU,SAAS,YAAY,OAAO"}
+{"version":3,"file":"AssistantActivity.js","names":["AssistantEvent.isLibraryEvent","AssistantEvent.isAppInput","AssistantEvent.isInput","AssistantEvent.isWaking"],"sources":["../src/AssistantActivity.ts"],"sourcesContent":["/**\n * This module provides functions that determine what is working in a chat right now, read from\n * the chat's log.\n *\n * A {@link State} records whether the assistant is running a turn or is about to start one,\n * and which specialist runs are working. Fold a chat's entries into it with {@link apply}, or\n * build it from a list of entries with {@link fromEntries}, then check it with\n * {@link isWorking}.\n *\n * @since 0.1.0\n */\nimport * as Match from \"effect/Match\"\nimport * as Predicate from \"effect/Predicate\"\nimport * as AssistantEvent from \"./AssistantEvent.ts\"\nimport type { RunId } from \"./RunId.ts\"\n\n/**\n * Represents a specialist run that is working.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface SpecialistRun {\n  readonly runId: RunId\n  readonly specialist: string\n  /** The goal the run is working on. */\n  readonly goal: string\n  /** When the run started, in epoch milliseconds. */\n  readonly since: number\n}\n\n/**\n * Represents what is working in a chat.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface State {\n  /** When the running turn started, in epoch milliseconds, or `undefined` when no turn runs. */\n  readonly turnSince: number | undefined\n  /**\n   * Whether an input arrived that no finished turn has read. When this is true, a turn is about\n   * to start.\n   */\n  readonly queued: boolean\n  /** The `seq` of the newest input. */\n  readonly lastInputSeq: number\n  /** Specialist runs that are working, by run id. */\n  readonly specialists: ReadonlyMap<RunId, SpecialistRun>\n}\n\n/**\n * The activity of a chat with an empty log, where nothing is working.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const empty: State = {\n  turnSince: undefined,\n  queued: false,\n  lastInputSeq: 0,\n  specialists: new Map()\n}\n\nconst withoutRun = (activity: State, runId: RunId): State => {\n  if (!activity.specialists.has(runId)) return activity\n\n  const specialists = new Map(activity.specialists)\n  specialists.delete(runId)\n\n  return { ...activity, specialists }\n}\n\n/**\n * Returns the activity after one more entry. Fold a chat's entries in order, or use\n * {@link fromEntries}.\n *\n * **Details**\n *\n * One of the app's events counts as an input, and a turn as about to start, when it came in\n * through the assistant's `submit`. The log marks it so (`AssistantEvent.isAppInput`), as\n * `ChatLog.read` returns it; `subscribe` streams it decoded, without the mark, so there the turn\n * shows from its `TurnStarted`.\n *\n * @category combinators\n * @since 0.1.0\n */\nexport const apply = (activity: State, entry: AssistantEvent.AnyEntry): State => {\n  const event = entry.event\n\n  if (!AssistantEvent.isLibraryEvent(event)) {\n    return AssistantEvent.isAppInput(event) ? { ...activity, queued: true, lastInputSeq: entry.seq } : activity\n  }\n\n  if (AssistantEvent.isInput(event)) {\n    // A finished run's report is an input, and ends the run.\n    const current = Predicate.isTagged(event, \"SpecialistFinished\") ? withoutRun(activity, event.runId) : activity\n\n    return AssistantEvent.isWaking(event) ? { ...current, queued: true, lastInputSeq: entry.seq } : current\n  }\n\n  return Match.value(event).pipe(\n    Match.tag(\"TurnStarted\", (): State => ({ ...activity, turnSince: entry.at })),\n    // Turns run one at a time, so an end closes whichever turn is open, also one a restart cut off.\n    Match.tag(\"TurnCompleted\", \"TurnFailed\", (ended): State => ({\n      ...activity,\n      turnSince: undefined,\n      queued: activity.lastInputSeq > ended.throughSeq\n    })),\n    Match.tag(\"SpecialistStarted\", (started): State => ({\n      ...activity,\n      specialists: new Map(activity.specialists).set(started.runId, {\n        runId: started.runId,\n        specialist: started.specialist,\n        goal: started.goal,\n        since: entry.at\n      })\n    })),\n    // Deleting a chat stops everything in it, and nothing starts again.\n    Match.tag(\"ChatDeleted\", (): State => ({ ...empty, lastInputSeq: activity.lastInputSeq })),\n    Match.orElse(() => activity)\n  )\n}\n\n/**\n * Returns what is working in a chat after the given entries, folded in order from\n * {@link empty}.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const fromEntries = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): State =>\n  entries.reduce((activity, entry) => apply(activity, entry), empty)\n\n/**\n * Returns whether anything is working: a turn that is running or about to start, or a specialist\n * run.\n *\n * @category guards\n * @since 0.1.0\n */\nexport const isWorking = (activity: State): boolean =>\n  activity.turnSince !== undefined || activity.queued || activity.specialists.size > 0\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,MAAa,QAAe;CAC1B,WAAW,KAAA;CACX,QAAQ;CACR,cAAc;CACd,6BAAa,IAAI,IAAI;AACvB;AAEA,MAAM,cAAc,UAAiB,UAAwB;CAC3D,IAAI,CAAC,SAAS,YAAY,IAAI,KAAK,GAAG,OAAO;CAE7C,MAAM,cAAc,IAAI,IAAI,SAAS,WAAW;CAChD,YAAY,OAAO,KAAK;CAExB,OAAO;EAAE,GAAG;EAAU;CAAY;AACpC;;;;;;;;;;;;;;;AAgBA,MAAa,SAAS,UAAiB,UAA0C;CAC/E,MAAM,QAAQ,MAAM;CAEpB,IAAI,CAACA,eAA8B,KAAK,GACtC,OAAOC,WAA0B,KAAK,IAAI;EAAE,GAAG;EAAU,QAAQ;EAAM,cAAc,MAAM;CAAI,IAAI;CAGrG,IAAIC,QAAuB,KAAK,GAAG;EAEjC,MAAM,UAAU,UAAU,SAAS,OAAO,oBAAoB,IAAI,WAAW,UAAU,MAAM,KAAK,IAAI;EAEtG,OAAOC,SAAwB,KAAK,IAAI;GAAE,GAAG;GAAS,QAAQ;GAAM,cAAc,MAAM;EAAI,IAAI;CAClG;CAEA,OAAO,MAAM,MAAM,KAAK,CAAC,CAAC,KACxB,MAAM,IAAI,sBAA6B;EAAE,GAAG;EAAU,WAAW,MAAM;CAAG,EAAE,GAE5E,MAAM,IAAI,iBAAiB,eAAe,WAAkB;EAC1D,GAAG;EACH,WAAW,KAAA;EACX,QAAQ,SAAS,eAAe,MAAM;CACxC,EAAE,GACF,MAAM,IAAI,sBAAsB,aAAoB;EAClD,GAAG;EACH,aAAa,IAAI,IAAI,SAAS,WAAW,CAAC,CAAC,IAAI,QAAQ,OAAO;GAC5D,OAAO,QAAQ;GACf,YAAY,QAAQ;GACpB,MAAM,QAAQ;GACd,OAAO,MAAM;EACf,CAAC;CACH,EAAE,GAEF,MAAM,IAAI,sBAA6B;EAAE,GAAG;EAAO,cAAc,SAAS;CAAa,EAAE,GACzF,MAAM,aAAa,QAAQ,CAC7B;AACF;;;;;;;;AASA,MAAa,eAAe,YAC1B,QAAQ,QAAQ,UAAU,UAAU,MAAM,UAAU,KAAK,GAAG,KAAK;;;;;;;;AASnE,MAAa,aAAa,aACxB,SAAS,cAAc,KAAA,KAAa,SAAS,UAAU,SAAS,YAAY,OAAO"}

package/dist/AssistantEngine.d.ts

@@ -9,7 +9,7 @@ import * as Stream from "effect/Stream";
 import * as Sharding from "effect/cluster/Sharding";
 import * as Scope from "effect/Scope";
 declare namespace AssistantEngine_d_exports {
-  export { AssistantEngine, layerCluster, layerMemory };
+  export { AssistantEngine, layerCluster, layerClusterClient, layerMemory };
 }
 declare const AssistantEngine_base: Context.ServiceClass<AssistantEngine, "effect-assistant/AssistantEngine", {
   /** Registers an assistant for as long as the scope is open. */
@@ -106,11 +106,49 @@ export declare const layerMemory: Layer.Layer<AssistantEngine, never, ChatLog>;
  * ```
  *
  * @see {@link layerMemory} for running chats in one process
+ * @see {@link layerClusterClient} for a process that only reaches chats the cluster runs
  *
  * @category layers
  * @since 0.1.0
  */
 export declare const layerCluster: Layer.Layer<AssistantEngine, never, ChatLog | Sharding.Sharding>;
+/**
+ * Layer that reaches chats running as cluster entities elsewhere, and runs none itself.
+ *
+ * **When to use**
+ *
+ * Use it in a process that only submits to, subscribes to, and deletes chats that the cluster's
+ * runners run with {@link layerCluster}, such as a web server that provides an assistant's
+ * `layerClient`. It needs no `ChatLog`, since the runners store the chats.
+ *
+ * **Details**
+ *
+ * The layer requires `Sharding`. An assistant's `toLayer` can't register with it: it dies, since
+ * no chats run in this process.
+ *
+ * **Example** (A web server in front of the cluster)
+ *
+ * ```ts
+ * import { Assistant, AssistantEngine } from "effect-assistant"
+ * import type * as Sharding from "effect/cluster/Sharding"
+ * import * as Layer from "effect/Layer"
+ *
+ * declare const ShardingLive: Layer.Layer<Sharding.Sharding>
+ *
+ * export const MyAssistant = Assistant.make("my-assistant")
+ *
+ * const MyAssistantClient = MyAssistant.layerClient.pipe(
+ *   Layer.provide(AssistantEngine.layerClusterClient),
+ *   Layer.provide(ShardingLive)
+ * )
+ * ```
+ *
+ * @see {@link layerCluster} for the runners that run the chats
+ *
+ * @category layers
+ * @since 0.3.0
+ */
+export declare const layerClusterClient: Layer.Layer<AssistantEngine, never, Sharding.Sharding>;
 //#endregion
 export { AssistantEngine_d_exports };
 //# sourceMappingURL=AssistantEngine.d.ts.map

package/dist/AssistantEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AssistantEngine.d.ts","names":[],"sources":["../src/AssistantEngine.ts"],"mappings":";;;;;;;;;;;;;;;WA6CuB,WAAC,cAAc,iBAAuB,OAAO,oBAAoB,MAAM;;;;;WAKzE,SACf,mBACA,QAAQ,QACR,OAAO,QAAuB,mBAC3B,OAAO;;WAEQ,YAAC,mBAAmB,QAAQ,QAAQ,kBAAkB,OAAO,OAAO;;;;;WAKvE,SAAC,mBAAmB,QAAQ,WAAW,OAAO;;;;;;;;;qBApBtD,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA8DxB,aAAa,MAAM,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAwJjD,cAAc,MAAM,MAAM,wBAAwB,UAAU,SAAS"}
+{"version":3,"file":"AssistantEngine.d.ts","names":[],"sources":["../src/AssistantEngine.ts"],"mappings":";;;;;;;;;;;;;;;WA8CuB,WAAC,cAAc,iBAAuB,OAAO,oBAAoB,MAAM;;;;;WAKzE,SACf,mBACA,QAAQ,QACR,OAAO,QAAuB,mBAC3B,OAAO;;WAEQ,YAAC,mBAAmB,QAAQ,QAAQ,kBAAkB,OAAO,OAAO;;;;;WAKvE,SAAC,mBAAmB,QAAQ,WAAW,OAAO;;;;;;;;;qBApBtD,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA8DxB,aAAa,MAAM,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA8MjD,cAAc,MAAM,MAAM,wBAAwB,UAAU,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAsFrE,oBAAoB,MAAM,MAAM,wBAAwB,SAAS"}