effect-assistant 0.2.0 → 0.3.0

package/src/Assistant.ts

@@ -24,7 +24,6 @@ import * as Predicate from "effect/Predicate"
 import * as Schema from "effect/Schema"
 import type * as Scope from "effect/Scope"
 import * as Stream from "effect/Stream"
-import type * as AppEvent from "./AppEvent.ts"
 import { AssistantEngine } from "./AssistantEngine.ts"
 import * as AssistantEvent from "./AssistantEvent.ts"
 import type * as AssistantLoop from "./AssistantLoop.ts"
@@ -66,7 +65,8 @@ export interface LoopOptions<T extends Record<string, Tool.Any> = Record<never,
   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.
+   * with `load_skill` when a task matches it. A skill made with `tools` is left out when the turn's
+   * tools lack one of them.
    */
   readonly skills?: ReadonlyArray<Skill<RS>> | undefined
   /** The maximum number of model calls per turn. Defaults to 16. */
@@ -75,7 +75,8 @@ export interface LoopOptions<T extends Record<string, Tool.Any> = Record<never,
   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
 }
@@ -86,9 +87,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
@@ -249,8 +284,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.AssistantEvent | Events>): Effect.Effect<void>
 }
@@ -266,8 +301,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.
@@ -279,9 +317,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,
@@ -323,8 +362,8 @@ export interface Assistant<
   readonly blocks: BlockKit.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<AppEvent.Any>
+  /** The schemas of the app's own events the assistant stores. */
+  readonly events: ReadonlyArray<AssistantEvent.AppEventSchema>
   /**
    * Creates a layer that registers the assistant's handler with the engine and provides the
    * assistant's service.
@@ -387,9 +426,9 @@ export interface Assistant<
    *
    * 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)
    * )
    * ```
    */
@@ -419,28 +458,35 @@ export type Any = Assistant<any, any, any>
  */
 export const isAssistant = (u: unknown): u is Any => Predicate.hasProperty(u, TypeId)
 
-function entrySchema<E>(events: ReadonlyArray<AppEvent.Any>): Schema.Codec<Entry<E>, Schema.Json>
+function entrySchema<E>(events: ReadonlyArray<AssistantEvent.AppEventSchema>): Schema.Codec<Entry<E>, Schema.Json>
 // The overload states the decoded type: the library's events, or one of these schemas' types.
-function entrySchema(events: ReadonlyArray<AppEvent.Any>): Schema.Top {
+function entrySchema(events: ReadonlyArray<AssistantEvent.AppEventSchema>): Schema.Top {
   return Schema.toCodecJson(
     Schema.Struct({
       chatId: ChatId,
       seq: Schema.Int,
       at: Schema.Finite,
-      event: Schema.Union([AssistantEvent.AssistantEvent, ...events.map((event) => event.schema)])
+      event: Schema.Union([AssistantEvent.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
@@ -466,7 +512,7 @@ function entrySchema(events: ReadonlyArray<AppEvent.Any>): Schema.Top {
 export const make = <
   const Name extends string,
   const Specs extends ReadonlyArray<Specialist.Any> = readonly [],
-  const Events extends ReadonlyArray<AppEvent.Any> = readonly []
+  const Events extends ReadonlyArray<AssistantEvent.AppEventSchema> = readonly []
 >(
   name: Name,
   options?: {
@@ -478,14 +524,14 @@ export const make = <
      */
     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], AppEvent.Type<Events[number]>> => {
+): Assistant<Name, Specs[number], Events[number]["Type"]> => {
   const events = options?.events ?? []
 
   const definition: Turns.Definition = {
@@ -495,7 +541,7 @@ export const make = <
     app: AppEvents.make(events)
   }
 
-  type OwnEvents = AppEvent.Type<Events[number]>
+  type OwnEvents = Events[number]["Type"]
 
   const Key = Context.Service<Identifier<Name>, Service<OwnEvents>>(`effect-assistant/Assistant/${name}`)
 

package/src/AssistantActivity.ts

@@ -71,32 +71,25 @@ const withoutRun = (activity: State, runId: RunId): State => {
   return { ...activity, specialists }
 }
 
-/**
- * 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 const apply = (activity: State, entry: AssistantEvent.AnyEntry, options?: Options): State => {
+export const apply = (activity: State, entry: AssistantEvent.AnyEntry): State => {
   const event = entry.event
 
   if (!AssistantEvent.isLibraryEvent(event)) {
-    return options?.wakes?.has(event._tag) === true ? { ...activity, queued: true, lastInputSeq: entry.seq } : activity
+    return AssistantEvent.isAppInput(event) ? { ...activity, queued: true, lastInputSeq: entry.seq } : activity
   }
 
   if (AssistantEvent.isInput(event)) {
@@ -136,8 +129,8 @@ export const apply = (activity: State, entry: AssistantEvent.AnyEntry, options?:
  * @category constructors
  * @since 0.1.0
  */
-export const fromEntries = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, options?: Options): State =>
-  entries.reduce((activity, entry) => apply(activity, entry, options), empty)
+export const fromEntries = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): State =>
+  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

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,8 +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 { InputId, make as makeInputId } from "./InputId.ts"
+import { inputKey } from "./internal/input.ts"
 import { RunId } from "./RunId.ts"
 
 /**
@@ -444,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.
@@ -474,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).
@@ -518,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/BlockKit.ts

@@ -14,7 +14,7 @@ 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 InputId from "./InputId.ts"
 
@@ -210,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**
  *
@@ -241,7 +241,7 @@ export interface RenderOptions {
  *   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) })
  * ```
  *
@@ -251,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
 

package/src/Compaction.ts

@@ -138,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"
@@ -154,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>
   }