effect-assistant 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "effect-assistant",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "A colleague assistant on Effect: an append-only event log per chat, an interruptible agent loop, specialists, skills, and UI blocks",
   "license": "MIT",
   "repository": {

package/src/Assistant.ts

@@ -48,12 +48,12 @@ const TypeId = "~effect-assistant/Assistant" as const
 export type TurnServices = CurrentChat | Specialist.Runner
 
 /**
- * Represents the options accepted by `turn.loop`.
+ * Represents the options accepted by `turn.run`.
  *
  * @category models
  * @since 0.1.0
  */
-export interface LoopOptions<T extends Record<string, Tool.Any> = Record<never, never>, Events = never> {
+export interface RunOptions<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
   /**
@@ -115,7 +115,7 @@ export interface LoopOptions<T extends Record<string, Tool.Any> = Record<never,
  *
  * // 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 })
+ *   turn.run({ instructions: "Be brief.", history: withOrders })
  * )
  * ```
  *
@@ -134,7 +134,7 @@ export type HistoryView<Events = never> = (
  */
 export interface Entry<Events = never> {
   readonly chatId: ChatId
-  readonly seq: number
+  readonly sequence: number
   readonly at: number
   readonly event: AssistantEvent.AssistantEvent | Events
 }
@@ -146,7 +146,7 @@ export interface Entry<Events = never> {
  * @since 0.1.0
  */
 export interface ReplyOptions {
-  /** The assistant's instructions, as passed to `turn.loop`. `Instructions.protocol` is added. */
+  /** The assistant's instructions, as passed to `turn.run`. `Instructions.protocol` is added. */
   readonly instructions: string | Instructions.Resolved
   /**
    * The message given to the model after the history. Defaults to a message saying that it
@@ -185,8 +185,8 @@ export interface Turn<Events = never> {
    * 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>>(
-    options: LoopOptions<T, Events>
+  readonly run: <T extends Record<string, Tool.Any> = Record<never, never>>(
+    options: RunOptions<T, Events>
   ) => Stream.Stream<
     AssistantLoop.Event,
     AiError.AiError,
@@ -197,7 +197,7 @@ export interface Turn<Events = never> {
    * message. In this pass the model can only reply.
    *
    * The stream is empty when no reply is owed, or when an input arrived that the next turn will
-   * read. `loop` runs this pass with its own prompt and tools, so the pass reuses the cached
+   * read. `run` runs this pass with its own prompt and tools, so the pass reuses the cached
    * prompt.
    */
   readonly replyIfOwed: (
@@ -309,7 +309,7 @@ export interface Service<Events = never> {
   /**
    * Streams the chat's stored entries, then live ones, with the assistant's own events decoded.
    * A reader that already has the earlier entries passes `after` and receives only the entries
-   * after that `seq`.
+   * after that `sequence`.
    *
    * 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
@@ -382,7 +382,7 @@ export interface Assistant<
    * export const MyAssistant = Assistant.make("my-assistant")
    *
    * const MyAssistantLive = MyAssistant.toLayer((turn) =>
-   *   turn.loop({ instructions: "You help a small team. Be brief." })
+   *   turn.run({ instructions: "You help a small team. Be brief." })
    * )
    *
    * const AppLive = MyAssistantLive.pipe(
@@ -458,7 +458,7 @@ function entrySchema(events: ReadonlyArray<AssistantEvent.AppEventSchema>): Sche
   return Schema.toCodecJson(
     Schema.Struct({
       chatId: ChatId,
-      seq: Schema.Int,
+      sequence: Schema.Int,
       at: Schema.Finite,
       event: Schema.Union([AssistantEvent.AssistantEvent, ...events])
     })

package/src/AssistantActivity.ts

@@ -43,8 +43,8 @@ export interface State {
    * to start.
    */
   readonly queued: boolean
-  /** The `seq` of the newest input. */
-  readonly lastInputSeq: number
+  /** The `sequence` of the newest input. */
+  readonly lastInputSequence: number
   /** Specialist runs that are working, by run id. */
   readonly specialists: ReadonlyMap<RunId, SpecialistRun>
 }
@@ -58,7 +58,7 @@ export interface State {
 export const empty: State = {
   turnSince: undefined,
   queued: false,
-  lastInputSeq: 0,
+  lastInputSequence: 0,
   specialists: new Map()
 }
 
@@ -89,14 +89,16 @@ export const apply = (activity: State, entry: AssistantEvent.AnyEntry): State =>
   const event = entry.event
 
   if (!AssistantEvent.isLibraryEvent(event)) {
-    return AssistantEvent.isAppInput(event) ? { ...activity, queued: true, lastInputSeq: entry.seq } : activity
+    return AssistantEvent.isAppInput(event)
+      ? { ...activity, queued: true, lastInputSequence: entry.sequence }
+      : activity
   }
 
   if (AssistantEvent.isInput(event)) {
     // A finished run's report is an input, and ends the run.
     const current = Predicate.isTagged(event, "SpecialistFinished") ? withoutRun(activity, event.runId) : activity
 
-    return AssistantEvent.isWaking(event) ? { ...current, queued: true, lastInputSeq: entry.seq } : current
+    return AssistantEvent.isWaking(event) ? { ...current, queued: true, lastInputSequence: entry.sequence } : current
   }
 
   return Match.value(event).pipe(
@@ -105,7 +107,7 @@ export const apply = (activity: State, entry: AssistantEvent.AnyEntry): State =>
     Match.tag("TurnCompleted", "TurnFailed", (ended): State => ({
       ...activity,
       turnSince: undefined,
-      queued: activity.lastInputSeq > ended.throughSeq
+      queued: activity.lastInputSequence > ended.throughSequence
     })),
     Match.tag("SpecialistStarted", (started): State => ({
       ...activity,
@@ -117,7 +119,7 @@ export const apply = (activity: State, entry: AssistantEvent.AnyEntry): State =>
       })
     })),
     // Deleting a chat stops everything in it, and nothing starts again.
-    Match.tag("ChatDeleted", (): State => ({ ...empty, lastInputSeq: activity.lastInputSeq })),
+    Match.tag("ChatDeleted", (): State => ({ ...empty, lastInputSequence: activity.lastInputSequence })),
     Match.orElse(() => activity)
   )
 }

package/src/AssistantEngine.ts

@@ -54,7 +54,7 @@ export class AssistantEngine extends Context.Service<
       chatId: ChatId,
       input: AssistantEvent.Input | AssistantEvent.StoredAppEvent
     ) => Effect.Effect<void>
-    /** Streams the chat's stored entries after the `after` seq, then live ones. */
+    /** Streams the chat's stored entries after the `after` sequence, then live ones. */
     readonly subscribe: (assistant: string, chatId: ChatId, after: number) => Stream.Stream<AssistantEvent.Entry>
     /**
      * Deletes one of the assistant's chats. The chat's log records the deletion, and everything
@@ -90,7 +90,7 @@ const notRegistered = (assistant: string) =>
  *
  * const MyAssistant = Assistant.make("my-assistant")
  *
- * const AppLive = MyAssistant.toLayer((turn) => turn.loop({ instructions: "Be brief." })).pipe(
+ * const AppLive = MyAssistant.toLayer((turn) => turn.run({ instructions: "Be brief." })).pipe(
  *   Layer.provide(ModelLive),
  *   Layer.provideMerge(AssistantEngine.layerMemory),
  *   Layer.provideMerge(ChatLog.layerMemory)
@@ -289,7 +289,7 @@ const makeClusterClient = Effect.gen(function* () {
  *
  * const MyAssistant = Assistant.make("my-assistant")
  *
- * const AppLive = MyAssistant.toLayer((turn) => turn.loop({ instructions: "Be brief." })).pipe(
+ * const AppLive = MyAssistant.toLayer((turn) => turn.run({ instructions: "Be brief." })).pipe(
  *   Layer.provide(ModelLive),
  *   Layer.provideMerge(AssistantEngine.layerCluster),
  *   Layer.provideMerge(

package/src/AssistantEvent.ts

@@ -280,7 +280,7 @@ export class ModelOutput extends Schema.TaggedClass<ModelOutput>()("ModelOutput"
    * arrived while the model was working. A turn has handled what its
    * outputs had read.
    */
-  seenThroughSeq: Schema.optional(Schema.Int),
+  seenThroughSequence: Schema.optional(Schema.Int),
   /** The model that wrote it, as the provider's id for it or the name the context gave it. */
   model: Schema.optional(Schema.String),
   /** The provider's id for the response, when it gives one. */
@@ -365,26 +365,26 @@ export class TurnStarted extends Schema.TaggedClass<TurnStarted>()("TurnStarted"
 /**
  * Represents a turn that finished.
  *
- * `throughSeq` is the last entry the turn read. Inputs after it still need a turn.
+ * `throughSequence` is the last entry the turn read. Inputs after it still need a turn.
  *
  * @category schemas
  * @since 0.1.0
  */
 export class TurnCompleted extends Schema.TaggedClass<TurnCompleted>()("TurnCompleted", {
-  throughSeq: Schema.Int
+  throughSequence: Schema.Int
 }) {}
 
 /**
  * Represents a turn that failed.
  *
- * `throughSeq` covers everything stored when the turn failed, so a failing input isn't retried
+ * `throughSequence` covers everything stored when the turn failed, so a failing input isn't retried
  * forever.
  *
  * @category schemas
  * @since 0.1.0
  */
 export class TurnFailed extends Schema.TaggedClass<TurnFailed>()("TurnFailed", {
-  throughSeq: Schema.Int,
+  throughSequence: Schema.Int,
   message: Schema.String
 }) {}
 
@@ -585,7 +585,7 @@ export const isAppInput = (event: { readonly _tag: string }): boolean =>
  */
 export interface AnyEntry {
   readonly chatId: ChatId
-  readonly seq: number
+  readonly sequence: number
   readonly at: number
   readonly event: { readonly _tag: string }
 }
@@ -593,7 +593,7 @@ export interface AnyEntry {
 /**
  * Schema for a stored event with its position in the chat.
  *
- * `seq` starts at 1 and has no gaps. `at` is the time the event was stored, in epoch
+ * `sequence` starts at 1 and has no gaps. `at` is the time the event was stored, in epoch
  * milliseconds.
  *
  * @category schemas
@@ -601,7 +601,7 @@ export interface AnyEntry {
  */
 export const Entry = Schema.Struct({
   chatId: ChatId,
-  seq: Schema.Int,
+  sequence: Schema.Int,
   at: Schema.Finite,
   event: Schema.Union([AssistantEvent, StoredAppEvent])
 })

package/src/AssistantLoop.ts

@@ -1,7 +1,7 @@
 /**
  * Runs the agent loop, which calls the model, runs its tool calls, and repeats.
  *
- * Most handlers use `turn.loop` or `run.loop`. This module is for a loop of your own: {@link run}
+ * Most handlers use `turn.run` or `run.loop`. This module is for a loop of your own: {@link run}
  * runs the loop until the model is done, and {@link step} is one step, as a body for
  * {@link loop}.
  *
@@ -37,7 +37,7 @@ export type Event = Loop.Event
 /**
  * Represents a chat's history as the model reads it.
  *
- * It holds the messages, and the last `seq` of the chat they cover.
+ * It holds the messages, and the last `sequence` of the chat they cover.
  *
  * @category models
  * @since 0.1.0
@@ -122,7 +122,7 @@ export interface StepOptions<T extends Record<string, Tool.Any> = NoTools> {
   readonly toolkit?: Toolkit.Toolkit<T> | undefined
   /**
    * The current history, read at the start of the step. It is either messages, or a chat's
-   * history (`turn.history()`), whose `throughSeq` the step's `ModelOutput` records as how far
+   * history (`turn.history()`), whose `throughSequence` the step's `ModelOutput` records as how far
    * the model had read.
    */
   readonly history: Effect.Effect<ReadonlyArray<Prompt.Message> | ChatHistory>

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]))
  * ```
  *

package/src/Specialist.ts

@@ -226,7 +226,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)
  * )
  * ```