effect-assistant 0.1.0 → 0.3.0

package/src/AssistantEngine.ts

@@ -1,11 +1,12 @@
 /**
- * This module provides the `AssistantEngine` service, which runs assistants' chats, and its two
+ * This module provides the `AssistantEngine` service, which runs assistants' chats, and its
  * implementations.
  *
  * An assistant's `toLayer` registers the assistant with the engine, and the assistant's `submit`
  * and `subscribe` go through it. Pick one engine for the app, as with a workflow engine.
  * {@link layerMemory} runs chats in the process, for tests and single-process apps.
- * {@link layerCluster} runs each chat as a cluster entity, so a turn cut off by a crash resumes.
+ * {@link layerCluster} runs each chat as a cluster entity, so a turn cut off by a crash resumes, and
+ * {@link layerClusterClient} reaches those chats from a process that runs none.
  *
  * @since 0.1.0
  */
@@ -155,7 +156,7 @@ export const layerMemory: Layer.Layer<AssistantEngine, never, ChatLog> = Layer.e
 
     // A chat owes a turn when its last turn was cut off, or an input came after.
     const resumeAll = Effect.fnUntraced(function* (registration: Turns.Registration) {
-      const { name, app } = registration.definition
+      const { name } = registration.definition
 
       for (const chatId of yield* log.unfinished) {
         const entries = yield* log.read(chatId)
@@ -163,7 +164,7 @@ export const layerMemory: Layer.Layer<AssistantEngine, never, ChatLog> = Layer.e
         const lastTurn = entries.findLast(({ event }) => Predicate.isTagged(event, "TurnStarted"))?.event
         const ours = Predicate.isTagged(lastTurn, "TurnStarted") && lastTurn.assistant === name
 
-        if (ours && History.needsTurn(entries, app.wakes)) yield* withChat(name, chatId, (chat) => chat.resume)
+        if (ours && History.needsTurn(entries)) yield* withChat(name, chatId, (chat) => chat.resume)
       }
     })
 
@@ -212,6 +213,59 @@ const Delete = Rpc.make("Delete")
 
 const chatEntity = (assistant: string) => Entity.make(`Assistant/${assistant}`, [Submit, Subscribe, Delete])
 
+type EngineClient = Omit<AssistantEngine["Service"], "register">
+
+// Entity clients are made on first use, so a process that registers no assistant can still reach its chats.
+const makeClusterClient = Effect.gen(function* () {
+  const context = yield* Effect.context<Sharding.Sharding>()
+  const clients = new Map<string, EntityClient>()
+
+  const clientOf = Effect.fnUntraced(function* (assistant: string) {
+    const known = clients.get(assistant)
+
+    if (known !== undefined) return known
+
+    const makeClient = yield* chatEntity(assistant).client.pipe(Effect.provide(context))
+
+    const client: EntityClient = {
+      submit: (chatId, input) => makeClient(chatId).Submit({ input }, { discard: true }).pipe(Effect.orDie),
+      subscribe: (chatId, after) => makeClient(chatId).Subscribe({ after }).pipe(Stream.orDie),
+      delete: (chatId) => makeClient(chatId).Delete().pipe(Effect.orDie)
+    }
+
+    clients.set(assistant, client)
+
+    return client
+  })
+
+  const engine: EngineClient = {
+    submit: Effect.fn("AssistantEngine.submit")(function* (
+      assistant: string,
+      chatId: ChatId,
+      input: AssistantEvent.Input | AssistantEvent.StoredAppEvent
+    ) {
+      const client = yield* clientOf(assistant)
+
+      yield* client.submit(chatId, input)
+    }),
+    subscribe: (assistant, chatId, after) =>
+      Stream.unwrap(
+        Effect.gen(function* () {
+          const client = yield* clientOf(assistant)
+
+          return client.subscribe(chatId, after)
+        })
+      ),
+    delete: Effect.fn("AssistantEngine.delete")(function* (assistant: string, chatId: ChatId) {
+      const client = yield* clientOf(assistant)
+
+      yield* client.delete(chatId)
+    })
+  }
+
+  return engine
+})
+
 /**
  * Layer that runs chats as cluster entities, one entity per chat, keyed by chat id.
  *
@@ -249,6 +303,7 @@ const chatEntity = (assistant: string) => Entity.make(`Assistant/${assistant}`,
  * ```
  *
  * @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
@@ -258,7 +313,6 @@ export const layerCluster: Layer.Layer<AssistantEngine, never, ChatLog | Shardin
   Effect.gen(function* () {
     const context = yield* Effect.context<ChatLog | Sharding.Sharding>()
     const sharding = yield* Sharding.Sharding
-    const clients = new Map<string, EntityClient>()
 
     const register = Effect.fnUntraced(function* (registration: Turns.Registration) {
       const ChatEntity = chatEntity(registration.definition.name)
@@ -295,49 +349,62 @@ export const layerCluster: Layer.Layer<AssistantEngine, never, ChatLog | Shardin
       })
     })
 
-    // Made on first use, so a process that registers no assistant can still reach its chats.
-    const clientOf = Effect.fnUntraced(function* (assistant: string) {
-      const known = clients.get(assistant)
-
-      if (known !== undefined) return known
-
-      const makeClient = yield* chatEntity(assistant).client.pipe(Effect.provide(context))
-
-      const client: EntityClient = {
-        submit: (chatId, input) => makeClient(chatId).Submit({ input }, { discard: true }).pipe(Effect.orDie),
-        subscribe: (chatId, after) => makeClient(chatId).Subscribe({ after }).pipe(Stream.orDie),
-        delete: (chatId) => makeClient(chatId).Delete().pipe(Effect.orDie)
-      }
-
-      clients.set(assistant, client)
-
-      return client
-    })
+    const client = yield* makeClusterClient
 
     return AssistantEngine.of({
       register: (registration) => register(registration).pipe(Effect.provide(context)),
-      submit: Effect.fn("AssistantEngine.submit")(function* (
-        assistant: string,
-        chatId: ChatId,
-        input: AssistantEvent.Input | AssistantEvent.StoredAppEvent
-      ) {
-        const client = yield* clientOf(assistant)
-
-        yield* client.submit(chatId, input)
-      }),
-      subscribe: (assistant, chatId, after) =>
-        Stream.unwrap(
-          Effect.gen(function* () {
-            const client = yield* clientOf(assistant)
+      ...client
+    })
+  })
+)
 
-            return client.subscribe(chatId, after)
-          })
-        ),
-      delete: Effect.fn("AssistantEngine.delete")(function* (assistant: string, chatId: ChatId) {
-        const client = yield* clientOf(assistant)
+/**
+ * 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 const layerClusterClient: Layer.Layer<AssistantEngine, never, Sharding.Sharding> = Layer.effect(
+  AssistantEngine,
+  Effect.gen(function* () {
+    const client = yield* makeClusterClient
 
-        yield* client.delete(chatId)
-      })
+    return AssistantEngine.of({
+      register: (registration) =>
+        Effect.die(
+          `The ${registration.definition.name} assistant can't register with AssistantEngine.layerClusterClient, which runs no chats: provide AssistantEngine.layerCluster where its toLayer runs.`
+        ),
+      ...client
     })
   })
 )

package/src/AssistantEvent.ts

@@ -2,7 +2,7 @@
  * Defines the events that can happen in a chat.
  *
  * A chat is an append-only log of these events, and the log is the source of truth. A chat client
- * receives the part of the log its user sees (`ChatView`), and the model's history is rebuilt
+ * receives the part of the log its user sees (its `Timeline`), and the model's history is rebuilt
  * from the log before every model call. Besides the library's events ({@link AssistantEvent}), a
  * log holds the application's own events ({@link StoredAppEvent}).
  *
@@ -11,9 +11,10 @@
 import * as Response from "effect/ai/Response"
 import * as Predicate from "effect/Predicate"
 import * as Schema from "effect/Schema"
+import type * as SchemaAST from "effect/SchemaAST"
 import { ChatId } from "./ChatId.ts"
-import { DecisionId } from "./DecisionId.ts"
 import { InputId, make as makeInputId } from "./InputId.ts"
+import { inputKey } from "./internal/input.ts"
 import { RunId } from "./RunId.ts"
 
 /**
@@ -139,69 +140,6 @@ export class SpecialistFinished extends Schema.TaggedClass<SpecialistFinished>()
   error: Schema.optional(Schema.String)
 }) {}
 
-/**
- * Schema for how the user decided, either `"approved"` or `"declined"`.
- *
- * @category schemas
- * @since 0.1.0
- */
-export const DecisionOutcome = Schema.Literals(["approved", "declined"])
-
-/**
- * Represents how the user decided.
- *
- * @category models
- * @since 0.1.0
- */
-export type DecisionOutcome = typeof DecisionOutcome.Type
-
-/**
- * Schema for the origin of a decision that a tool call waits for.
- *
- * It holds the call as the model wrote it. Approving the decision runs exactly this call.
- *
- * @category schemas
- * @since 0.1.0
- */
-export const CallOrigin = Schema.TaggedStruct("Call", {
-  callId: Schema.String,
-  tool: Schema.String,
-  params: Schema.Json
-})
-
-/**
- * Represents the origin of a decision that a tool call waits for.
- *
- * @category models
- * @since 0.1.0
- */
-export type CallOrigin = typeof CallOrigin.Type
-
-/**
- * Represents a request for the user to decide something, by approving or declining it.
- *
- * @category schemas
- * @since 0.1.0
- */
-export class DecisionRequested extends Schema.TaggedClass<DecisionRequested>()("DecisionRequested", {
-  id: DecisionId,
-  origin: CallOrigin
-}) {}
-
-/**
- * Represents a decision the user made by answering a decision block for it.
- *
- * `answer` is the id of that `BlockAnswer`. An approved call runs at the turn's next step.
- *
- * @category schemas
- * @since 0.1.0
- */
-export class DecisionResolved extends Schema.TaggedClass<DecisionResolved>()("DecisionResolved", {
-  id: DecisionId,
-  outcome: DecisionOutcome,
-  answer: InputId
-}) {}
-
 /**
  * Schema for every input `Assistant.submit` accepts.
  *
@@ -481,8 +419,6 @@ export const AssistantEvent = Schema.Union([
   SpecialistStarted,
   SpecialistFinished,
   BlocksClosed,
-  DecisionRequested,
-  DecisionResolved,
   ChatDeleted
 ])
 
@@ -510,19 +446,43 @@ const libraryTags: ReadonlySet<string> = new Set(
  */
 export const AppTag = Schema.String.pipe(Schema.brand("~effect-assistant/AppTag"))
 
+/**
+ * Represents the schema of one of the application's own events, as `Assistant.make`'s `events`
+ * takes it.
+ *
+ * **Details**
+ *
+ * It is a tagged struct or class (`Schema.TaggedStruct`, `Schema.TaggedClass`) whose `_tag` is a
+ * string literal other than the library's, and that needs no services. The log stores the event in
+ * the schema's JSON form.
+ *
+ * @category models
+ * @since 0.3.0
+ */
+export type AppEventSchema = Schema.Codec<{ readonly _tag: string }, { readonly _tag: string }> & {
+  readonly fields: { readonly _tag: { readonly ast: SchemaAST.AST } }
+}
+
 /**
  * Schema for one of the application's own events as it is stored, with its `_tag` and its fields
  * in JSON.
  *
- * An assistant made with `events: [AppEvent.make(Summary)]` decodes it to a `Summary` in
- * `CurrentChat`'s `entries` and in its `subscribe`.
+ * **Details**
+ *
+ * An assistant made with `events: [Summary]` decodes it to a `Summary` in `CurrentChat`'s
+ * `entries` and in its `subscribe`.
+ *
+ * An event that came in through the assistant's `submit`, from outside a turn, is an input, and the
+ * log marks it with a `"~effect-assistant/input": true` key (see {@link isAppInput}); one a turn
+ * appended has none. Decoding drops the key, so the app's schemas never see it.
  *
  * @category schemas
  * @since 0.1.0
  */
-export const StoredAppEvent = Schema.StructWithRest(Schema.Struct({ _tag: AppTag }), [
-  Schema.Record(Schema.String, Schema.Json)
-]).check(Schema.makeFilter((event) => !libraryTags.has(event._tag) || `${event._tag} is one of the library's events`))
+export const StoredAppEvent = Schema.StructWithRest(
+  Schema.Struct({ _tag: AppTag, [inputKey]: Schema.optionalKey(Schema.Literal(true)) }),
+  [Schema.Record(Schema.String, Schema.Json)]
+).check(Schema.makeFilter((event) => !libraryTags.has(event._tag) || `${event._tag} is one of the library's events`))
 
 /**
  * Represents one of the application's own events, as it is stored.
@@ -540,6 +500,18 @@ export type StoredAppEvent = typeof StoredAppEvent.Type
  */
 export const isLibraryEvent = (event: { readonly _tag: string }): event is AssistantEvent => libraryTags.has(event._tag)
 
+/**
+ * Returns whether one of the application's events, as the log stores it, is an input: it came in
+ * through the assistant's `submit`, from outside a turn, so storing it woke a turn. An event a turn
+ * appended (`CurrentChat`'s `append`) isn't, and neither is a decoded one, which no longer has the
+ * mark.
+ *
+ * @category guards
+ * @since 0.3.0
+ */
+export const isAppInput = (event: { readonly _tag: string }): boolean =>
+  !isLibraryEvent(event) && Predicate.hasProperty(event, inputKey) && event[inputKey] === true
+
 /**
  * Represents a chat's entry with any event in it, either the library's or the application's own
  * (decoded or not).
@@ -584,8 +556,8 @@ export type Entry = typeof Entry.Type
  * Returns whether an event is one of the library's inputs, which are a user message, a block
  * answer, or a finished specialist run.
  *
- * The application's events that wake a turn are inputs too, but only their assistant knows which
- * (see `AppEvent`).
+ * The application's events that came in through the assistant's `submit` are inputs too (see
+ * {@link isAppInput}).
  *
  * @category guards
  * @since 0.1.0

package/src/AssistantLoop.ts

@@ -27,8 +27,7 @@ import * as Toolkits from "./internal/toolkit.ts"
  * Represents what the loop emits.
  *
  * For each model call, the loop emits the call's output. Then, for each of its tool calls, it
- * emits a `ToolStarted` before the call runs and the call's result, or a `DecisionRequested` for
- * a call that waits for the user's decision.
+ * emits a `ToolStarted` before the call runs and the call's result.
  *
  * @category models
  * @since 0.1.0
@@ -158,9 +157,12 @@ const toolsOf = <T extends Record<string, Tool.Any>>(toolkit: Toolkit.Toolkit<T>
  * **Details**
  *
  * The step calls the model with the current history and emits its `ModelOutput`. It then runs
- * the output's tool calls and emits a `ToolStarted` and a `ToolResult` for each, or a
- * `DecisionRequested` for a call that waits for the user's decision. `then` receives the step's
- * result and decides what comes next, with `AssistantLoop.next(state)` or `AssistantLoop.stop()`.
+ * the output's tool calls and emits a `ToolStarted` and a `ToolResult` for each. `then` receives
+ * the step's result and decides what comes next, with `AssistantLoop.next(state)` or
+ * `AssistantLoop.stop()`.
+ *
+ * A tool with Effect's `needsApproval` set fails the loop before the model is called: the
+ * library doesn't run calls that wait for approval (see the guide on involving the user).
  *
  * @category constructors
  * @since 0.1.0

package/src/Block.ts

@@ -2,7 +2,7 @@
  * Defines UI blocks that an assistant can put in a message.
  *
  * A block is a bit of UI for when a structured answer is easier than typing, such as options to
- * pick from, approve and deny buttons, or a small input. The assistant fills in its `props`, and
+ * pick from, a yes or no, or a small input. The assistant fills in its `props`, and
  * using the block sends back a value typed by its `answer` schema.
  *
  * @since 0.1.0

package/src/BlockKit.ts

@@ -14,9 +14,8 @@ import * as Predicate from "effect/Predicate"
 import * as Schema from "effect/Schema"
 import * as AssistantEvent from "./AssistantEvent.ts"
 import type * as Block from "./Block.ts"
-import type * as ChatView from "./ChatView.ts"
+import type * as Timeline from "./Timeline.ts"
 import { CurrentChat } from "./CurrentChat.ts"
-import * as Decision from "./Decision.ts"
 import * as InputId from "./InputId.ts"
 
 /**
@@ -118,8 +117,7 @@ export const fromEntries = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): Re
  *
  * **Details**
  *
- * These are the blocks {@link closeStale} closes. Decision blocks never go stale, since work waits
- * on them and closing one would leave it waiting.
+ * These are the blocks {@link closeStale} closes.
  *
  * @category utils
  * @since 0.1.0
@@ -136,15 +134,7 @@ export const staleBlocks = (
         AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, "AssistantMessage") && event.id === id
     )
 
-    const message = entries[shown]?.event
-
-    if (
-      message === undefined ||
-      (AssistantEvent.isLibraryEvent(message) &&
-        Predicate.isTagged(message, "AssistantMessage") &&
-        message.block?.kind === Decision.kind)
-    )
-      return false
+    if (shown === -1) return false
 
     const typed = entries.slice(shown + 1).filter(({ event }) => Predicate.isTagged(event, "UserMessage")).length
 
@@ -180,6 +170,11 @@ export const closeStale = Effect.fn(function* (options: { readonly messages: num
  * @since 0.1.0
  */
 export interface RenderArgs<B> {
+  /**
+   * The id of the message the block is on. A block whose button calls your API can key the work
+   * on it, with the chat's id, so the work runs once per block.
+   */
+  readonly messageId: string
   readonly text: string
   readonly props: PropsOf<B>
   /**
@@ -189,11 +184,6 @@ export interface RenderArgs<B> {
   readonly open: boolean
   /** The user's answer, if they used the block. */
   readonly answer: AnswerOf<B> | undefined
-  /**
-   * For the decision block, the call each decision is for (its tool and params) and how it was
-   * decided. Empty for other blocks.
-   */
-  readonly decisions: ReadonlyArray<ChatView.PendingDecision>
   /** Sends an answer. Only call it while `open`. */
   readonly respond: (answer: AnswerOf<B>) => void
 }
@@ -220,8 +210,8 @@ export interface RenderOptions {
 }
 
 /**
- * Creates a client-side renderer for the blocks on a chat view's messages
- * (`ChatView.AssistantMessage`).
+ * Creates a client-side renderer for the blocks on the assistant's messages in a chat's timeline
+ * (`Timeline.AssistantMessage`).
  *
  * **Details**
  *
@@ -235,10 +225,10 @@ export interface RenderOptions {
  * **Example** (Rendering blocks with React)
  *
  * ```tsx
- * import { BlockKit, Decision } from "effect-assistant"
+ * import { BlockKit } from "effect-assistant"
  * import type { ReactNode } from "react"
  *
- * const Blocks = BlockKit.make([PickOne, Decision.block])
+ * const Blocks = BlockKit.make([PickOne, OrderDraft])
  *
  * const renderBlock = BlockKit.toClient<typeof Blocks, ReactNode>(Blocks, {
  *   pick_one: ({ props, open, respond }) =>
@@ -247,14 +237,11 @@ export interface RenderOptions {
  *         {option}
  *       </button>
  *     )),
- *   decision: ({ props, open, respond }) => (
- *     <button disabled={!open} onClick={() => respond(Decision.answerAll(props, "approved"))}>
- *       {props.approveLabel ?? "Approve"}
- *     </button>
- *   )
+ *   // No answer schema: the button calls the app's own API with the props the user sees.
+ *   order_draft: ({ props }) => <button onClick={() => placeOrder(props)}>Place order</button>
  * })
  *
- * // For each AssistantMessage in the chat's view:
+ * // For each AssistantMessage in the chat's timeline:
  * renderBlock(message, { respond: (answer) => submit(answer) })
  * ```
  *
@@ -264,13 +251,13 @@ export interface RenderOptions {
 export function toClient<Kit extends BlockKit, Out>(
   kit: Kit,
   renderers: Renderers<Kit, Out>
-): (message: ChatView.AssistantMessage, options: RenderOptions) => Out | undefined
+): (message: Timeline.AssistantMessage, options: RenderOptions) => Out | undefined
 // The overload above checks that every kind has a renderer; here each one takes any block's
 // arguments.
 export function toClient<Out>(
   kit: BlockKit,
   renderers: Readonly<Record<string, (args: RenderArgs<Block.Any>) => Out>>
-): (message: ChatView.AssistantMessage, options: RenderOptions) => Out | undefined {
+): (message: Timeline.AssistantMessage, options: RenderOptions) => Out | undefined {
   return (message, options) => {
     if (message.block === undefined) return undefined
 
@@ -291,11 +278,11 @@ export function toClient<Out>(
       given === undefined || answerCodec === undefined ? Option.none() : Schema.decodeUnknownOption(answerCodec)(given)
 
     return render({
+      messageId: message.id,
       text: message.text,
       props: props.value,
       open: message.block.status === "open",
       answer: Option.getOrUndefined(answer),
-      decisions: message.block.decisions ?? [],
       respond: (value) =>
         options.respond(
           AssistantEvent.BlockAnswer.make({

package/src/Compaction.ts

@@ -17,9 +17,7 @@ import type * as Assistant from "./Assistant.ts"
 import * as AssistantActivity from "./AssistantActivity.ts"
 import * as AssistantEvent from "./AssistantEvent.ts"
 import * as BlockKit from "./BlockKit.ts"
-import * as Decision from "./Decision.ts"
 import { userText } from "./internal/history.ts"
-import { toJsonText } from "./internal/schema.ts"
 
 /**
  * Represents the fields a summary event must have: its text and the last `seq` it covers.
@@ -55,8 +53,8 @@ export const inputTokens = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): nu
 }
 
 /**
- * Returns the items that were open at `throughSeq` and are still open: decisions waiting for the
- * user, blocks the user hasn't answered, and specialists that are working. The result is text for
+ * Returns the items that were open at `throughSeq` and are still open: blocks the user hasn't
+ * answered, and specialists that are working. The result is text for
  * the model, or `None` when nothing is open.
  *
  * @category utils
@@ -71,20 +69,6 @@ export const openItems = (
 
   const opened = (seq: number) => seq <= throughSeq
 
-  const decisions = [...Decision.fromEntries(entries).values()].flatMap((state) =>
-    state.outcome === undefined &&
-    opened(
-      seqOf(
-        (event) =>
-          AssistantEvent.isLibraryEvent(event) &&
-          Predicate.isTagged(event, "DecisionRequested") &&
-          event.id === state.request.id
-      )
-    )
-      ? [`- decision ${state.request.id}, for ${state.request.origin.tool}: ${toJsonText(state.request.origin.params)}`]
-      : []
-  )
-
   const blocks = [...BlockKit.fromEntries(entries)].flatMap(([messageId, state]) => {
     const shown = entries.find(
       ({ event }) =>
@@ -117,7 +101,6 @@ export const openItems = (
   )
 
   const sections = [
-    decisions.length > 0 ? `Decisions waiting for the user:\n${decisions.join("\n")}` : "",
     blocks.length > 0 ? `Blocks the user hasn't answered:\n${blocks.join("\n")}` : "",
     specialists.length > 0 ? `Specialists still working:\n${specialists.join("\n")}` : ""
   ].filter((section) => section.length > 0)
@@ -155,10 +138,14 @@ export const attachedFiles = (
  * ({@link openItems}), followed by the entries after the summary. When the chat has no summary,
  * the view returns every entry.
  *
+ * The app's other events after the summary stay entries, which the model doesn't read: map those
+ * it should read to messages after this view, as with any history view (see
+ * `Assistant.HistoryView`). A summary the handler appends wakes no turn.
+ *
  * **Example** (Compacting a long chat after each turn)
  *
  * ```ts
- * import { AppEvent, Assistant, type AssistantEvent, Compaction } from "effect-assistant"
+ * import { Assistant, type AssistantEvent, Compaction } from "effect-assistant"
  * import * as LanguageModel from "effect/ai/LanguageModel"
  * import * as Effect from "effect/Effect"
  * import * as Schema from "effect/Schema"
@@ -171,7 +158,7 @@ export const attachedFiles = (
  *
  * declare const transcript: (entries: ReadonlyArray<AssistantEvent.AnyEntry>) => string
  *
- * export const MyAssistant = Assistant.make("my-assistant", { events: [AppEvent.make(Summary)] })
+ * export const MyAssistant = Assistant.make("my-assistant", { events: [Summary] })
  *
  * const MyAssistantLive = MyAssistant.toLayer((turn) => {
  *   const compact = Effect.gen(function* () {

package/src/CurrentChat.ts

@@ -40,7 +40,8 @@ export class CurrentChat extends Context.Service<
     /**
      * 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 (registered with its `events` option),
-     * such as a summary. An event that wakes a turn is handled by the next turn.
+     * such as a summary. An app event appended here wakes no turn: only one that comes in through
+     * the assistant's `submit` does.
      */
     readonly append: (...events: ReadonlyArray<{ readonly _tag: string }>) => Effect.Effect<void>
   }