effect-assistant 0.5.0 → 0.7.0

package/src/ChatLog.ts

@@ -33,7 +33,7 @@ export class ChatLog extends Context.Service<
       chatId: ChatId,
       events: ReadonlyArray<AssistantEvent.AssistantEvent | AssistantEvent.StoredAppEvent>
     ) => Effect.Effect<ReadonlyArray<AssistantEvent.Entry>>
-    /** Reads a chat's stored entries in order, either all of them or only those after a `seq`. */
+    /** Reads a chat's stored entries in order, either all of them or only those after a `sequence`. */
     readonly read: (chatId: ChatId, options?: ReadOptions) => Effect.Effect<ReadonlyArray<AssistantEvent.Entry>>
     /**
      * Returns the chats whose last entry ends neither a turn nor the chat. After a restart, these
@@ -50,14 +50,14 @@ export class ChatLog extends Context.Service<
  * @since 0.1.0
  */
 export interface ReadOptions {
-  /** Reads only the entries after this `seq`. */
+  /** Reads only the entries after this `sequence`. */
   readonly after?: number | undefined
 }
 
 /**
  * Represents the storage that a `ChatLog` is built on.
  *
- * A storage reads a chat's entries, finds a chat's last `seq`, writes new entries, and finds every
+ * A storage reads a chat's entries, finds a chat's last `sequence`, writes new entries, and finds every
  * chat's last entry. Entries are never removed, so a deleted chat keeps its log, which ends in
  * `ChatDeleted`.
  *
@@ -66,7 +66,7 @@ export interface ReadOptions {
  */
 export interface Storage {
   readonly read: (chatId: ChatId, options?: ReadOptions) => Effect.Effect<ReadonlyArray<AssistantEvent.Entry>>
-  readonly lastSeq: (chatId: ChatId) => Effect.Effect<number>
+  readonly lastSequence: (chatId: ChatId) => Effect.Effect<number>
   readonly write: (chatId: ChatId, entries: ReadonlyArray<AssistantEvent.Entry>) => Effect.Effect<void>
   /** Returns the last entry of every chat. */
   readonly lastEntries: Effect.Effect<ReadonlyArray<AssistantEvent.Entry>>
@@ -74,7 +74,7 @@ export interface Storage {
 
 /**
  * Creates a `ChatLog` from a {@link Storage}. `append` numbers new entries after the chat's last
- * `seq` and stamps them with the current time.
+ * `sequence` and stamps them with the current time.
  *
  * @category constructors
  * @since 0.1.0
@@ -88,9 +88,12 @@ export const make = (storage: Storage): ChatLog["Service"] =>
     ) {
       if (events.length === 0) return []
 
-      const seq = yield* storage.lastSeq(chatId)
+      const sequence = yield* storage.lastSequence(chatId)
       const at = yield* Clock.currentTimeMillis
-      const entries = events.map((event, n) => AssistantEvent.Entry.make({ chatId, seq: seq + n + 1, at, event }))
+
+      const entries = events.map((event, n) =>
+        AssistantEvent.Entry.make({ chatId, sequence: sequence + n + 1, at, event })
+      )
 
       yield* storage.write(chatId, entries)
 
@@ -121,12 +124,12 @@ export const layerMemory: Layer.Layer<ChatLog> = Layer.effect(
       read: Effect.fnUntraced(function* (chatId: ChatId, options?: ReadOptions) {
         const all = yield* Ref.get(chats)
 
-        return (all.get(chatId) ?? []).filter((entry) => entry.seq > (options?.after ?? 0))
+        return (all.get(chatId) ?? []).filter((entry) => entry.sequence > (options?.after ?? 0))
       }),
-      lastSeq: Effect.fnUntraced(function* (chatId: ChatId) {
+      lastSequence: Effect.fnUntraced(function* (chatId: ChatId) {
         const all = yield* Ref.get(chats)
 
-        return all.get(chatId)?.at(-1)?.seq ?? 0
+        return all.get(chatId)?.at(-1)?.sequence ?? 0
       }),
       write: (chatId, entries) =>
         Ref.update(chats, (all) => new Map(all).set(chatId, [...(all.get(chatId) ?? []), ...entries])),
@@ -144,17 +147,19 @@ const EventJson = Schema.fromJsonString(Schema.Union([AssistantEvent.AssistantEv
 // Postgres returns BIGINT and DOUBLE PRECISION columns as strings; other databases as numbers.
 const SqlNumber = Schema.Union([Schema.Finite, Schema.FiniteFromString])
 
-const Row = Schema.Struct({ chat_id: ChatId, seq: SqlNumber, at: SqlNumber, event: EventJson })
+const Row = Schema.Struct({ chat_id: ChatId, sequence: SqlNumber, at: SqlNumber, event: EventJson })
 
-const decodeLastSeq = Schema.decodeUnknownEffect(Schema.Array(Schema.Struct({ seq: Schema.NullOr(SqlNumber) })))
+const decodeLastSequence = Schema.decodeUnknownEffect(
+  Schema.Array(Schema.Struct({ sequence: Schema.NullOr(SqlNumber) }))
+)
 
 /**
  * Layer that stores chats in a SQL table named `chat_log`.
  *
  * **Details**
  *
- * The table must already exist. It has the columns `chat_id`, `seq`, `at`, and `event`, with the
- * primary key `(chat_id, seq)`. The layer requires a `SqlClient`.
+ * The table must already exist. It has the columns `chat_id`, `sequence`, `at`, and `event`, with the
+ * primary key `(chat_id, sequence)`. The layer requires a `SqlClient`.
  *
  * **Example** (Storing chats in Postgres)
  *
@@ -174,10 +179,10 @@ const decodeLastSeq = Schema.decodeUnknownEffect(Schema.Array(Schema.Struct({ se
  * ```sql
  * CREATE TABLE chat_log (
  *   chat_id TEXT NOT NULL,
- *   seq INTEGER NOT NULL,
+ *   sequence INTEGER NOT NULL,
  *   at DOUBLE PRECISION NOT NULL,
  *   event TEXT NOT NULL,
- *   PRIMARY KEY (chat_id, seq)
+ *   PRIMARY KEY (chat_id, sequence)
  * );
  * ```
  *
@@ -195,7 +200,7 @@ export const layerSql: Layer.Layer<ChatLog, never, SqlClient.SqlClient> = Layer.
       return decoded.map((row) =>
         AssistantEvent.Entry.make({
           chatId: row.chat_id,
-          seq: row.seq,
+          sequence: row.sequence,
           at: row.at,
           event: row.event
         })
@@ -207,19 +212,19 @@ export const layerSql: Layer.Layer<ChatLog, never, SqlClient.SqlClient> = Layer.
     return make({
       read: Effect.fnUntraced(function* (chatId: ChatId, options?: ReadOptions) {
         const rows = yield* sql`
-          SELECT chat_id, seq, at, event FROM chat_log WHERE chat_id = ${chatId} AND seq > ${options?.after ?? 0} ORDER BY seq
+          SELECT chat_id, sequence, at, event FROM chat_log WHERE chat_id = ${chatId} AND sequence > ${options?.after ?? 0} ORDER BY sequence
         `
 
         return yield* toEntries(rows)
       }, Effect.orDie),
-      lastSeq: Effect.fnUntraced(function* (chatId: ChatId) {
+      lastSequence: Effect.fnUntraced(function* (chatId: ChatId) {
         const result = yield* sql`
-          SELECT MAX(seq) AS seq FROM chat_log WHERE chat_id = ${chatId}
+          SELECT MAX(sequence) AS sequence FROM chat_log WHERE chat_id = ${chatId}
         `
 
-        const rows = yield* decodeLastSeq(result)
+        const rows = yield* decodeLastSequence(result)
 
-        return rows[0]?.seq ?? 0
+        return rows[0]?.sequence ?? 0
       }, Effect.orDie),
       write: Effect.fnUntraced(function* (chatId: ChatId, entries: ReadonlyArray<AssistantEvent.Entry>) {
         const rows = yield* Effect.forEach(
@@ -227,7 +232,7 @@ export const layerSql: Layer.Layer<ChatLog, never, SqlClient.SqlClient> = Layer.
           Effect.fnUntraced(function* (entry: AssistantEvent.Entry) {
             const event = yield* encodeEvent(entry.event)
 
-            return { chat_id: chatId, seq: entry.seq, at: entry.at, event }
+            return { chat_id: chatId, sequence: entry.sequence, at: entry.at, event }
           })
         )
 
@@ -235,9 +240,9 @@ export const layerSql: Layer.Layer<ChatLog, never, SqlClient.SqlClient> = Layer.
       }, Effect.orDie),
       lastEntries: Effect.gen(function* () {
         const rows = yield* sql`
-          SELECT e.chat_id, e.seq, e.at, e.event FROM chat_log e
-          JOIN (SELECT chat_id, MAX(seq) AS seq FROM chat_log GROUP BY chat_id) last
-            ON last.chat_id = e.chat_id AND last.seq = e.seq
+          SELECT e.chat_id, e.sequence, e.at, e.event FROM chat_log e
+          JOIN (SELECT chat_id, MAX(sequence) AS sequence FROM chat_log GROUP BY chat_id) last
+            ON last.chat_id = e.chat_id AND last.sequence = e.sequence
         `
 
         return yield* toEntries(rows)

package/src/Compaction.ts

@@ -22,9 +22,9 @@ import { toJsonText } from "./internal/schema.ts"
 import * as ToolApproval from "./ToolApproval.ts"
 
 /**
- * Represents the fields a summary event must have: its text and the last `seq` it covers.
+ * Represents the fields a summary event must have: its text and the last `sequence` it covers.
  *
- * Entries after `throughSeq` are kept as they are, so an input that arrived while the summary was
+ * Entries after `throughSequence` are kept as they are, so an input that arrived while the summary was
  * being written isn't lost.
  *
  * @category models
@@ -33,7 +33,7 @@ import * as ToolApproval from "./ToolApproval.ts"
 export interface Summary {
   readonly _tag: string
   readonly text: string
-  readonly throughSeq: number
+  readonly throughSequence: number
 }
 
 /**
@@ -55,7 +55,7 @@ export const inputTokens = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): nu
 }
 
 /**
- * Returns the items that were open at `throughSeq` and are still open: blocks the user hasn't
+ * Returns the items that were open at `throughSequence` and are still open: blocks the user hasn't
  * answered, specialists that are working, and tool calls waiting for the user's approval. The result is text for
  * the model, or `None` when nothing is open.
  *
@@ -64,12 +64,12 @@ export const inputTokens = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): nu
  */
 export const openItems = (
   entries: ReadonlyArray<AssistantEvent.AnyEntry>,
-  throughSeq: number
+  throughSequence: number
 ): Option.Option<string> => {
-  const seqOf = (found: (event: AssistantEvent.AnyEntry["event"]) => boolean) =>
-    entries.find(({ event }) => found(event))?.seq ?? Number.POSITIVE_INFINITY
+  const sequenceOf = (found: (event: AssistantEvent.AnyEntry["event"]) => boolean) =>
+    entries.find(({ event }) => found(event))?.sequence ?? Number.POSITIVE_INFINITY
 
-  const opened = (seq: number) => seq <= throughSeq
+  const opened = (sequence: number) => sequence <= throughSequence
 
   const blocks = [...BlockKit.fromEntries(entries)].flatMap(([messageId, state]) => {
     const shown = entries.find(
@@ -81,7 +81,7 @@ export const openItems = (
 
     return state.open &&
       shown !== undefined &&
-      opened(shown.seq) &&
+      opened(shown.sequence) &&
       message !== undefined &&
       AssistantEvent.isLibraryEvent(message) &&
       Predicate.isTagged(message, "AssistantMessage")
@@ -91,7 +91,7 @@ export const openItems = (
 
   const specialists = [...AssistantActivity.fromEntries(entries).specialists.values()].flatMap((run) =>
     opened(
-      seqOf(
+      sequenceOf(
         (event) =>
           AssistantEvent.isLibraryEvent(event) &&
           Predicate.isTagged(event, "SpecialistStarted") &&
@@ -105,7 +105,7 @@ export const openItems = (
   const approvals = [...ToolApproval.fromEntries(entries).values()].flatMap((approval) =>
     approval.status === "pending" &&
     opened(
-      seqOf(
+      sequenceOf(
         (event) =>
           AssistantEvent.isLibraryEvent(event) &&
           Predicate.isTagged(event, "ApprovalRequested") &&
@@ -126,7 +126,7 @@ export const openItems = (
 }
 
 /**
- * Returns the files the user attached up to `throughSeq`, as lines of text for the model, or
+ * Returns the files the user attached up to `throughSequence`, as lines of text for the model, or
  * `None` when there are none. A summary may leave out a file's id, which tools need.
  *
  * @category utils
@@ -134,10 +134,10 @@ export const openItems = (
  */
 export const attachedFiles = (
   entries: ReadonlyArray<AssistantEvent.AnyEntry>,
-  throughSeq: number
+  throughSequence: number
 ): Option.Option<string> => {
-  const lines = entries.flatMap(({ seq, event }) =>
-    seq <= throughSeq && AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, "UserMessage")
+  const lines = entries.flatMap(({ sequence, event }) =>
+    sequence <= throughSequence && AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, "UserMessage")
       ? (event.attachments ?? []).map(AssistantEvent.attachmentLine)
       : []
   )
@@ -170,7 +170,7 @@ export const attachedFiles = (
  *
  * class Summary extends Schema.TaggedClass<Summary>()("Summary", {
  *   text: Schema.String,
- *   throughSeq: Schema.Int
+ *   throughSequence: Schema.Int
  * }) {}
  *
  * declare const transcript: (entries: ReadonlyArray<AssistantEvent.AnyEntry>) => string
@@ -188,12 +188,12 @@ export const attachedFiles = (
  *       prompt: `Summarize this chat:\n\n${transcript(entries)}`
  *     })
  *
- *     yield* chat.append(Summary.make({ text, throughSeq: entries.at(-1)?.seq ?? 0 }))
+ *     yield* chat.append(Summary.make({ text, throughSequence: entries.at(-1)?.sequence ?? 0 }))
  *   })
  *
  *   // After the reply, so the user doesn't wait for the summary.
  *   return Stream.concat(
- *     turn.loop({ instructions: "Be brief.", history: Compaction.since(Schema.is(Summary)) }),
+ *     turn.run({ instructions: "Be brief.", history: Compaction.since(Schema.is(Summary)) }),
  *     Stream.drain(Stream.fromEffect(compact))
  *   )
  * })
@@ -211,18 +211,18 @@ export const since =
 
     if (last === undefined || !isSummary(last)) return entries
 
-    const open = Option.match(openItems(entries, last.throughSeq), {
+    const open = Option.match(openItems(entries, last.throughSequence), {
       onNone: () => "",
       onSome: (items) => `\n\n<still_open>\n${items}\n</still_open>`
     })
 
-    const files = Option.match(attachedFiles(entries, last.throughSeq), {
+    const files = Option.match(attachedFiles(entries, last.throughSequence), {
       onNone: () => "",
       onSome: (lines) => `\n\n<files_attached_earlier>\n${lines}\n</files_attached_earlier>`
     })
 
     return [
       userText(`<earlier_in_this_chat>\n${last.text}\n</earlier_in_this_chat>${files}${open}`),
-      ...entries.filter(({ seq, event }) => seq > last.throughSeq && !isSummary(event))
+      ...entries.filter(({ sequence, event }) => sequence > last.throughSequence && !isSummary(event))
     ]
   }

package/src/Memory.ts

@@ -218,7 +218,7 @@ const Recall = Tool.make("recall", {
  *     return (turn) =>
  *       Stream.unwrap(
  *         Effect.map(memory.facts(turn.chatId), (facts) =>
- *           turn.loop({
+ *           turn.run({
  *             instructions: `You help a small team.\n\n${Memory.render(facts)}`,
  *             toolkit: Memory.Tools
  *           })

package/src/Skill.ts

@@ -168,7 +168,7 @@ function toolkitOf(skills: ReadonlyArray<Skill<unknown>>): Toolkit<unknown> {
  * const AssistantSkills = Skill.toolkit([orderingCampaigns, sharingAssets])
  *
  * const MyAssistantLive = MyAssistant.toLayer((turn) =>
- *   turn.loop({ instructions, toolkit: Toolkit.merge(MyTools, AssistantSkills) })
+ *   turn.run({ instructions, toolkit: Toolkit.merge(MyTools, AssistantSkills) })
  * ).pipe(Layer.provide([MyToolsLive, AssistantSkills.layer]))
  * ```
  *
@@ -186,7 +186,7 @@ function toolkitOf(skills: ReadonlyArray<Skill<unknown>>): Toolkit<unknown> {
  *       const skills = Skill.toolkit(allSkills.filter((skill) => allowed(role, skill)))
  *
  *       return turn
- *         .loop({ instructions, toolkit: Toolkit.merge(MyTools, skills) })
+ *         .run({ instructions, toolkit: Toolkit.merge(MyTools, skills) })
  *         .pipe(Stream.provide(skills.layer))
  *     })
  *   )

package/src/Specialist.ts

@@ -40,12 +40,12 @@ export interface Specialist<Name extends string = string> {
   /** The key of the specialist's handler, as `toLayer` provides it. */
   readonly Handler: Context.Key<SpecialistHandler<Name>, Built>
   /**
-   * Provides the specialist's handler. The handler may use the {@link RunServices} and the
+   * Provides the specialist's handler. The handler may use the {@link TurnServices} and the
    * services its build Effect required (see {@link CheckServices}).
    */
   readonly toLayer: <R = never, RE = never, E = never, RX = never>(
     build: (Handler<R, RE> | Effect.Effect<Handler<R, RE>, E, RX>) &
-      CheckServices<Exclude<R | RE, RunServices | RX | Tool.Handler<string>>>
+      CheckServices<Exclude<R | RE, TurnServices | RX | Tool.Handler<string>>>
   ) => Layer.Layer<SpecialistHandler<Name>, never, Exclude<RX, Scope.Scope | CurrentChat> | ToolHandlers<R | RE>>
 }
 
@@ -108,21 +108,21 @@ export interface SpecialistHandler<Name extends string> {
 export type HandlerOf<S> = S extends Specialist<infer Name> ? SpecialistHandler<Name> : never
 
 /**
- * The services a run provides to its handler, which are its chat, the chat's runner, and the
+ * The services a turn provides to its handler, which are its chat, the chat's runner, and the
  * model.
  *
  * @category utility types
  * @since 0.1.0
  */
-export type RunServices = CurrentChat | Runner | LanguageModel.LanguageModel
+export type TurnServices = CurrentChat | Runner | LanguageModel.LanguageModel
 
 /**
- * Represents the options for `run.loop`.
+ * Represents the options for `turn.run`.
  *
  * @category models
  * @since 0.1.0
  */
-export interface LoopOptions<T extends Record<string, Tool.Any> = Record<never, never>> {
+export interface RunOptions<T extends Record<string, Tool.Any> = Record<never, never>> {
   readonly instructions: string | Instructions.Resolved
   /**
    * The loop's tools, as a native toolkit whose handlers come from the layer. Merge in a
@@ -134,12 +134,13 @@ export interface LoopOptions<T extends Record<string, Tool.Any> = Record<never,
 }
 
 /**
- * Represents one run of a specialist on a brief, as its handler sees it.
+ * Represents one turn of a specialist's run, as its handler sees it. The first turn works on the
+ * brief, and each later one on the messages sent to the run since (follow-ups and steering).
  *
  * @category models
  * @since 0.1.0
  */
-export interface Run {
+export interface Turn {
   readonly runId: RunId
   /** The chat the run belongs to, which is the chat of the turn that spawned it. */
   readonly chatId: ChatId
@@ -150,8 +151,8 @@ export interface Run {
    */
   readonly history: Effect.Effect<ReadonlyArray<Prompt.Message>>
   /** Runs the agent loop over the run's history, with the given instructions and tools. */
-  readonly loop: <T extends Record<string, Tool.Any> = Record<never, never>>(
-    options: LoopOptions<T>
+  readonly run: <T extends Record<string, Tool.Any> = Record<never, never>>(
+    options: RunOptions<T>
   ) => Stream.Stream<
     AssistantLoop.Event,
     AiError.AiError,
@@ -170,7 +171,7 @@ export interface Run {
  * @since 0.1.0
  */
 export type Handler<R = never, RE = R> = (
-  run: Run
+  turn: Turn
 ) =>
   | Stream.Stream<AssistantLoop.Event, unknown, R>
   | Effect.Effect<Stream.Stream<AssistantLoop.Event, unknown, R>, unknown, RE>
@@ -186,7 +187,7 @@ export type Handler<R = never, RE = R> = (
  */
 export interface Built {
   readonly open: Effect.Effect<
-    (run: Run) => Stream.Stream<AssistantLoop.Event, unknown, RunServices>,
+    (turn: Turn) => Stream.Stream<AssistantLoop.Event, unknown, TurnServices>,
     never,
     Scope.Scope | CurrentChat
   >
@@ -203,7 +204,7 @@ const toStream = <R, RE>(
  *
  * **Details**
  *
- * The specialist's `toLayer` provides its handler, which is usually `run.loop` with the
+ * The specialist's `toLayer` provides its handler, which is usually `turn.run` with the
  * specialist's own instructions and tools. List the specialist in `Assistant.make`'s
  * `specialists`, and provide its layer to the assistant's.
  *
@@ -217,8 +218,8 @@ const toStream = <R, RE>(
  *   description: "Researches past campaigns and orders. Give it the question and any context."
  * })
  *
- * const ResearchLive = Research.toLayer((run) =>
- *   run.loop({
+ * const ResearchLive = Research.toLayer((turn) =>
+ *   turn.run({
  *     instructions: "Answer with the findings and numbers the colleague needs, in a few lines.",
  *     toolkit: ResearchTools
  *   })
@@ -226,7 +227,7 @@ const toStream = <R, RE>(
  *
  * export const MyAssistant = Assistant.make("my-assistant", { specialists: [Research] })
  *
- * const MyAssistantLive = MyAssistant.toLayer((turn) => turn.loop({ instructions })).pipe(
+ * const MyAssistantLive = MyAssistant.toLayer((turn) => turn.run({ instructions })).pipe(
  *   Layer.provide(ResearchLive)
  * )
  * ```
@@ -248,7 +249,7 @@ export const make = <const Name extends string>(
   // services.
   function toLayer<R = never, RE = never, E = never, RX = never>(
     build: (Handler<R, RE> | Effect.Effect<Handler<R, RE>, E, RX>) &
-      CheckServices<Exclude<R | RE, RunServices | RX | Tool.Handler<string>>>
+      CheckServices<Exclude<R | RE, TurnServices | RX | Tool.Handler<string>>>
   ): Layer.Layer<SpecialistHandler<Name>, never, Exclude<RX, Scope.Scope | CurrentChat> | ToolHandlers<R | RE>>
   function toLayer(
     build: Handler<any, any> | Effect.Effect<Handler<any, any>, unknown, any>
@@ -264,7 +265,7 @@ export const make = <const Name extends string>(
           open: Effect.gen(function* () {
             const handler = Effect.isEffect(build) ? yield* build : build
 
-            return (run: Run) => Stream.provideContext(toStream(handler(run)), context)
+            return (turn: Turn) => Stream.provideContext(toStream(handler(turn)), context)
           }).pipe(Effect.provideContext(context), Effect.orDie)
         }
       })

package/src/Timeline.ts

@@ -246,13 +246,13 @@ export type Activity = typeof Activity.Type
 /**
  * Represents a chat's timeline: the chat as its user sees it, typed with the app's events it shows.
  * It holds the chat's items in order, what is working in it, whether the last turn failed, and
- * whether the chat was deleted. `seq` is the position in the chat's log that the timeline is up to.
+ * whether the chat was deleted. `sequence` is the position in the chat's log that the timeline is up to.
  *
  * @category models
  * @since 0.3.0
  */
 export interface Timeline<Events = never> {
-  readonly seq: number
+  readonly sequence: number
   readonly items: ReadonlyArray<Item<Events>>
   readonly activity: Activity
   /** Whether the last turn failed with no message after it. */
@@ -268,14 +268,14 @@ export interface Timeline<Events = never> {
  *
  * A change holds each item that is new or changed (for example, a message whose block was
  * answered or closed, or a call the user approved), in full. It also holds the current activity, whether the last turn failed,
- * and whether the chat was deleted. `seq` is the position in the chat's log that the change is up
+ * and whether the chat was deleted. `sequence` is the position in the chat's log that the change is up
  * to.
  *
  * @category models
  * @since 0.3.0
  */
 export interface Change<Events = never> {
-  readonly seq: number
+  readonly sequence: number
   readonly items: ReadonlyArray<Item<Events>>
   readonly activity: Activity
   readonly failed: boolean
@@ -298,7 +298,7 @@ function makeChange(events: ReadonlyArray<AssistantEvent.AppEventSchema> = []):
   const encodeItem = Schema.encodeUnknownSync(AnyItem)
 
   return Schema.Struct({
-    seq: Schema.Int,
+    sequence: Schema.Int,
     // An item for an event this schema doesn't name, or that doesn't decode (from a newer server, say), is left out
     // rather than failing the whole change.
     items: Schema.Array(Schema.Json).pipe(
@@ -361,7 +361,7 @@ export const Change: <const Events extends ReadonlyArray<AssistantEvent.AppEvent
  * @since 0.1.0
  */
 export const empty: Timeline = {
-  seq: 0,
+  sequence: 0,
   items: [],
   activity: { working: false, specialists: [] },
   failed: false,
@@ -407,7 +407,7 @@ export const apply = <Events>(timeline: Timeline<Events>, change: Change<Events>
   const known = new Set(timeline.items.map((item) => item.id))
 
   return {
-    seq: Math.max(timeline.seq, change.seq),
+    sequence: Math.max(timeline.sequence, change.sequence),
     items: [
       ...timeline.items.map((item) => changed.get(item.id) ?? item),
       ...change.items.filter((item) => !known.has(item.id))
@@ -465,7 +465,7 @@ type AnyItem = UserMessage | AssistantMessage | AnyEventItem | ApprovalItem
 
 // What the fold below builds: the overloads that use it type its items with the events shown.
 interface AnyChange {
-  readonly seq: number
+  readonly sequence: number
   readonly items: ReadonlyArray<AnyItem>
   readonly activity: Activity
   readonly failed: boolean
@@ -622,7 +622,7 @@ const sameActivity = (a: Activity, b: Activity) =>
 const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding => {
   const shown = new Map(show.map((schema) => [AppEvents.tagOf(schema), schema]))
   let approvals: ReadonlyMap<string, ToolApproval.State> = new Map()
-  let seq = 0
+  let sequence = 0
   let failed = false
   let deleted = false
   let activity = AssistantActivity.empty
@@ -729,7 +729,7 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
 
     return Option.map(event, (decoded) => ({
       _tag: decoded._tag,
-      id: `app-event:${entry.seq}`,
+      id: `app-event:${entry.sequence}`,
       at: entry.at,
       event: decoded
     }))
@@ -769,7 +769,7 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
     const previous = { activity: activityOf(activity), failed, deleted }
     const { event } = entry
 
-    seq = entry.seq
+    sequence = entry.sequence
     activity = AssistantActivity.apply(activity, entry)
 
     if (!AssistantEvent.isLibraryEvent(event)) {
@@ -777,11 +777,11 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
 
       return Option.match(eventItemOf(entry), {
         onNone: () =>
-          sameActivity(previous.activity, now) ? undefined : { seq, items: [], activity: now, failed, deleted },
+          sameActivity(previous.activity, now) ? undefined : { sequence, items: [], activity: now, failed, deleted },
         onSome: (item) => {
           items.set(item.id, item)
 
-          return { seq, items: [item], activity: now, failed, deleted }
+          return { sequence, items: [item], activity: now, failed, deleted }
         }
       })
     }
@@ -811,13 +811,13 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
       deleted === previous.deleted &&
       sameActivity(previous.activity, now)
       ? undefined
-      : { seq, items: all, activity: now, failed, deleted }
+      : { sequence, items: all, activity: now, failed, deleted }
   }
 
   return {
     step,
     get snapshot() {
-      return { seq, items: [...items.values()], activity: activityOf(activity), failed, deleted }
+      return { sequence, items: [...items.values()], activity: activityOf(activity), failed, deleted }
     }
   }
 }
@@ -832,7 +832,7 @@ const merge = (changes: ReadonlyArray<AnyChange>): AnyChange | undefined => {
   for (const change of changes) for (const item of change.items) items.set(item.id, item)
 
   return {
-    seq: last.seq,
+    sequence: last.sequence,
     items: [...items.values()],
     activity: last.activity,
     failed: last.failed,
@@ -864,7 +864,7 @@ export interface ChangesOptions<
   Show extends ReadonlyArray<AssistantEvent.AppEventSchema> = readonly []
 > extends ShowOptions<Show> {
   /**
-   * The `seq` up to which the client already has the timeline. The result contains only the
+   * The `sequence` up to which the client already has the timeline. The result contains only the
    * changes after it. Defaults to `0`, every change.
    */
   readonly after?: number | undefined
@@ -889,7 +889,7 @@ function changesWith<E, R>(
         const changed = chunk.flatMap((entry) => {
           const change = timeline.step(entry)
 
-          return change === undefined || entry.seq <= after ? [] : [change]
+          return change === undefined || entry.sequence <= after ? [] : [change]
         })
 
         const merged = merge(changed)
@@ -907,9 +907,9 @@ function changesWith<E, R>(
  *
  * The entries must stream from the start of the chat's log, as `assistant.subscribe(chatId)` does
  * without `after`. The fold reads every entry, because a message depends on earlier entries: its
- * block is answered or closed later. `after` only skips emitting the changes up to that `seq`, so a
- * client that has the timeline up to a `seq` receives only what changed since. Pass `after` here,
- * not to `subscribe`: a subscription that starts after a `seq` gives the fold an incomplete log,
+ * block is answered or closed later. `after` only skips emitting the changes up to that `sequence`, so a
+ * client that has the timeline up to a `sequence` receives only what changed since. Pass `after` here,
+ * not to `subscribe`: a subscription that starts after a `sequence` gives the fold an incomplete log,
  * and the changes it produces are wrong.
  *
  * Each chunk of entries becomes one change; the stored entries, for example, arrive as one chunk.
@@ -928,7 +928,7 @@ function changesWith<E, R>(
  * import * as Schema from "effect/Schema"
  * import * as Stream from "effect/Stream"
  *
- * class Summary extends Schema.TaggedClass<Summary>()("Summary", { text: Schema.String, throughSeq: Schema.Int }) {}
+ * class Summary extends Schema.TaggedClass<Summary>()("Summary", { text: Schema.String, throughSequence: Schema.Int }) {}
  * class DailyBudgetReached extends Schema.TaggedClass<DailyBudgetReached>()("DailyBudgetReached", {}) {}
  *
  * const MyAssistant = Assistant.make("my-assistant", { events: [Summary, DailyBudgetReached] })

package/src/ToolApproval.ts

@@ -231,7 +231,7 @@ export const staleApprovals = (
  *     yield* BlockKit.closeStale({ messages: 10 })
  *     yield* ToolApproval.closeStale({ messages: 10 })
  *
- *     return turn.loop({ instructions, toolkit: MyTools })
+ *     return turn.run({ instructions, toolkit: MyTools })
  *   })
  * )
  * ```

package/src/ToolDiscovery.ts

@@ -110,7 +110,7 @@ const requiring =
  * const OfficeDiscoveryLive = ToolDiscovery.layer(OfficeTools).pipe(Layer.provide(OfficeToolsLive))
  *
  * const MyAssistantLive = MyAssistant.toLayer((turn) =>
- *   turn.loop({
+ *   turn.run({
  *     instructions,
  *     toolkit: Toolkit.merge(CommonTools, OfficeDiscovery)
  *   })