effect-assistant 0.2.0 → 0.4.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"
@@ -35,7 +34,6 @@ import type { CurrentChat } from "./CurrentChat.ts"
 import type * as Instructions from "./Instructions.ts"
 import * as AppEvents from "./internal/events.ts"
 import * as Turns from "./internal/turns.ts"
-import type { Skill } from "./Skill.ts"
 import type * as Specialist from "./Specialist.ts"
 
 const TypeId = "~effect-assistant/Assistant" as const
@@ -55,27 +53,24 @@ export type TurnServices = CurrentChat | Specialist.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 | Instructions.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
 }
@@ -86,9 +81,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
@@ -153,15 +182,15 @@ export interface Turn<Events = never> {
   readonly instructions: (instructions: string | Instructions.Resolved) => Instructions.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>
+  readonly loop: <T extends Record<string, Tool.Any> = Record<never, never>>(
+    options: LoopOptions<T, Events>
   ) => Stream.Stream<
     AssistantLoop.Event,
     AiError.AiError,
-    LanguageModel.LanguageModel | TurnServices | AssistantLoop.ToolkitServices<T> | RS
+    LanguageModel.LanguageModel | TurnServices | AssistantLoop.ToolkitServices<T>
   >
   /**
    * Runs one more pass when the turn would otherwise end without a reply to the user's latest
@@ -249,8 +278,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 +295,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 +311,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 +356,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 +420,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 +452,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 +506,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 +518,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 +535,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
     })
   })
 )