effect-assistant 0.4.0 → 0.6.0

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

@@ -197,12 +197,16 @@ export type UserInput = typeof UserInput.Type
  * Represents the UI shown with a message, as a block kind from the assistant's `BlockKit` and its
  * props.
  *
+ * A block that shows a tool's result (`Block.fromToolResult`) has the tool's name as its kind and
+ * the result's `resultId`.
+ *
  * @category schemas
  * @since 0.1.0
  */
 export class MessageBlock extends Schema.Class<MessageBlock>("effect-assistant/MessageBlock")({
   kind: Schema.String,
-  props: Schema.Unknown
+  props: Schema.Unknown,
+  resultId: Schema.optional(Schema.String)
 }) {}
 
 /**
@@ -276,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. */
@@ -325,6 +329,10 @@ export type ToolOutcome = typeof ToolOutcome.Type
  * failure includes its reason when it has one, which is a `ToolFailure`'s `reason` or the
  * failure's tag.
  *
+ * When the model reads less than the whole success (a `ToolResult.modelView`, or the `resultId`
+ * added for a tool the assistant's blocks show), `full` holds the whole success, encoded by the
+ * tool's success schema.
+ *
  * @category schemas
  * @since 0.1.0
  */
@@ -333,7 +341,10 @@ export class ToolResult extends Schema.TaggedClass<ToolResult>()("ToolResult", {
   tool: Schema.String,
   outcome: ToolOutcome,
   result: Schema.Json,
-  reason: Schema.optional(Schema.String)
+  reason: Schema.optional(Schema.String),
+  full: Schema.optional(Schema.Json),
+  /** The id the model passes in a `tool_result` block to show this result. */
+  resultId: Schema.optional(Schema.String)
 }) {}
 
 /**
@@ -354,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
 }) {}
 
@@ -574,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 }
 }
@@ -582,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
@@ -590,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/Block.ts

@@ -5,9 +5,14 @@
  * pick from, a yes or no, or a small input. The assistant fills in its `props`, and
  * using the block sends back a value typed by its `answer` schema.
  *
+ * A block made with {@link fromToolResult} shows a tool's result instead: the assistant picks the
+ * result, and the client draws it from what the tool returned.
+ *
  * @since 0.1.0
  */
-import type * as Schema from "effect/Schema"
+import type * as Tool from "effect/ai/Tool"
+import * as Predicate from "effect/Predicate"
+import * as Schema from "effect/Schema"
 
 /**
  * Schema that a block's props or answer can use.
@@ -82,3 +87,79 @@ export const make = <const Kind extends string, Props extends Codec, Answer exte
   props: options.props,
   answer: options.answer
 })
+
+/**
+ * Schema for the props of a block that shows a tool's result: none, since the result is the block.
+ *
+ * @category schemas
+ * @since 0.5.0
+ */
+export const NoProps = Schema.Struct({})
+
+/**
+ * Represents a block that shows a tool's results, made with {@link fromToolResult}. Its kind is the
+ * tool's name.
+ *
+ * @category models
+ * @since 0.5.0
+ */
+export interface ToolResultBlock<T extends Tool.Any = Tool.Any> extends Block<
+  Tool.Name<T>,
+  typeof NoProps,
+  Schema.Never
+> {
+  readonly tool: T
+  /** The tool's success schema, which the client decodes the result with. */
+  readonly result: Codec
+}
+
+/**
+ * Creates a block that shows a tool's results.
+ *
+ * **Details**
+ *
+ * Put it in the assistant's `BlockKit`. The tool's results then carry a `resultId` in what the model
+ * reads, and the model shows one with a `tool_result` block that names it: it never sees the
+ * block's kind or how the client draws it. Sending the block fails back to the model when no
+ * successful result of a shown tool has that id.
+ *
+ * On the client, `BlockKit.toClient` gives the block's renderer the result, decoded by the tool's
+ * success schema. The tool's definition is shared with the client for that, so it can't need
+ * server-only services: add those on the server with `Tool.addDependency`.
+ *
+ * **Example** (Showing search results as cards)
+ *
+ * ```ts
+ * import { Block, BlockKit } from "effect-assistant"
+ * import { SearchAssets } from "./tools.ts"
+ *
+ * export const Blocks = BlockKit.make([PickOne, Block.fromToolResult(SearchAssets)])
+ *
+ * // Client
+ * const renderBlock = BlockKit.toClient<typeof Blocks, ReactNode>(Blocks, {
+ *   pick_one: ({ props, respond }) => <Options options={props.options} onPick={respond} />,
+ *   search_assets: ({ result }) => <AssetCards assets={result.items} />
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 0.5.0
+ */
+export const fromToolResult = <T extends Tool.Any>(
+  tool: T & { readonly successSchema: Codec }
+): ToolResultBlock<T> => ({
+  kind: tool.name,
+  description: `Shows a ${tool.name} result.`,
+  props: NoProps,
+  answer: undefined,
+  tool,
+  result: tool.successSchema
+})
+
+/**
+ * Returns whether a block shows a tool's results.
+ *
+ * @category guards
+ * @since 0.5.0
+ */
+export const isToolResult = (block: Any): block is ToolResultBlock => Predicate.hasProperty(block, "tool")

package/src/BlockKit.ts

@@ -8,12 +8,13 @@
  *
  * @since 0.1.0
  */
+import type * as Tool from "effect/ai/Tool"
 import * as Effect from "effect/Effect"
 import * as Option from "effect/Option"
 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 * as Block from "./Block.ts"
 import type * as Timeline from "./Timeline.ts"
 import { CurrentChat } from "./CurrentChat.ts"
 import * as InputId from "./InputId.ts"
@@ -40,6 +41,15 @@ export const make = <const Blocks extends ReadonlyArray<Block.Any>>(blocks: Bloc
   byKind: new Map(blocks.map((block) => [block.kind, block]))
 })
 
+/**
+ * Returns the names of the tools whose results the kit's blocks show (`Block.fromToolResult`).
+ *
+ * @category utils
+ * @since 0.5.0
+ */
+export const toolNames = (kit: BlockKit | undefined): ReadonlySet<string> =>
+  new Set((kit?.blocks ?? []).flatMap((block) => (Block.isToolResult(block) ? [block.tool.name] : [])))
+
 type KindOf<B> = B extends { readonly kind: infer K extends string } ? K : never
 
 type BlockOf<Kit extends BlockKit, K> = Extract<Kit["blocks"][number], { readonly kind: K }>
@@ -48,6 +58,13 @@ type PropsOf<B> = B extends { readonly props: Schema.Top } ? B["props"]["Type"]
 
 type AnswerOf<B> = B extends { readonly answer: infer A } ? (A extends Schema.Top ? A["Type"] : never) : never
 
+type ResultArgs<B> = B extends { readonly tool: infer T }
+  ? {
+      /** The tool's result the block shows, decoded by its success schema. */
+      readonly result: Tool.Success<T>
+    }
+  : unknown
+
 /**
  * Represents the state of a message's block.
  *
@@ -164,12 +181,21 @@ export const closeStale = Effect.fn(function* (options: { readonly messages: num
 })
 
 /**
- * Represents what a renderer receives for one block.
+ * Represents what a renderer receives for one block. A block that shows a tool's result also gets
+ * the `result`.
  *
  * @category models
  * @since 0.1.0
  */
-export interface RenderArgs<B> {
+export type RenderArgs<B> = BlockArgs<B> & ResultArgs<B>
+
+/**
+ * Represents what every block's renderer receives.
+ *
+ * @category models
+ * @since 0.5.0
+ */
+export interface BlockArgs<B> {
   /**
    * The id of the message the block is on. A block whose button calls your API can key the work
    * on it, with the chat's id, so the work runs once per block.
@@ -256,7 +282,7 @@ export function toClient<Kit extends BlockKit, Out>(
 // arguments.
 export function toClient<Out>(
   kit: BlockKit,
-  renderers: Readonly<Record<string, (args: RenderArgs<Block.Any>) => Out>>
+  renderers: Readonly<Record<string, (args: BlockArgs<Block.Any> & { readonly result?: unknown }) => Out>>
 ): (message: Timeline.AssistantMessage, options: RenderOptions) => Out | undefined {
   return (message, options) => {
     if (message.block === undefined) return undefined
@@ -271,6 +297,12 @@ export function toClient<Out>(
 
     if (Option.isNone(props)) return undefined
 
+    const result = Block.isToolResult(block)
+      ? Schema.decodeUnknownOption(Schema.toCodecJson(block.result))(message.block.result)
+      : Option.some(undefined)
+
+    if (Option.isNone(result)) return undefined
+
     const given = message.block.answer
     const answerCodec = block.answer === undefined ? undefined : Schema.toCodecJson(block.answer)
 
@@ -281,6 +313,7 @@ export function toClient<Out>(
       messageId: message.id,
       text: message.text,
       props: props.value,
+      result: result.value,
       open: message.block.status === "open",
       answer: Option.getOrUndefined(answer),
       respond: (value) =>

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)