effect-assistant 0.5.0 → 0.7.0

package/src/internal/chat.ts

@@ -87,7 +87,7 @@ const deletedChat = (entries: ReadonlyArray<AssistantEvent.Entry>): Chat => ({
   submit: () => Effect.void,
   submitInBackground: () => Effect.void,
   resume: Effect.void,
-  stream: (after) => Stream.fromIterable(entries.filter((entry) => entry.seq > after)),
+  stream: (after) => Stream.fromIterable(entries.filter((entry) => entry.sequence > after)),
   delete: Effect.void
 })
 
@@ -314,15 +314,15 @@ export const make = Effect.fnUntraced(function* (options: {
           // Subscribes before it reads, so nothing appended in between is missed.
           const subscription = yield* PubSub.subscribe(channel)
           const all = yield* chat.entries
-          const stored = all.filter((entry) => entry.seq > after)
-          const last = stored.at(-1)?.seq ?? after
+          const stored = all.filter((entry) => entry.sequence > after)
+          const last = stored.at(-1)?.sequence ?? after
 
           // Deleted: what the reader hasn't seen, then the end. Otherwise the stream ends with the `ChatDeleted`.
           if (all.some(isChatDeleted)) return Stream.fromIterable(stored)
 
           return Stream.concat(
             Stream.fromIterable(stored),
-            Stream.fromSubscription(subscription).pipe(Stream.filter((entry) => entry.seq > last))
+            Stream.fromSubscription(subscription).pipe(Stream.filter((entry) => entry.sequence > last))
           ).pipe(Stream.takeUntil(isChatDeleted))
         })
       ),

package/src/internal/events.ts

@@ -95,6 +95,6 @@ export type DecodedEntries = ReturnType<typeof decodeEntries>
 
 const toEntry = (entry: AssistantEvent.AnyEntry) => ({
   chatId: entry.chatId,
-  seq: entry.seq,
+  sequence: entry.sequence,
   at: entry.at
 })

package/src/internal/history.ts

@@ -140,7 +140,7 @@ const awaitingMessage = (request: AssistantEvent.ApprovalRequested): Prompt.Tool
   })
 
 const isEntry = (item: AssistantEvent.AnyEntry | Prompt.Message): item is AssistantEvent.AnyEntry =>
-  Predicate.hasProperty(item, "seq")
+  Predicate.hasProperty(item, "sequence")
 
 // In the order the model saw the entries, not the order they were stored. A message a history view put in stands
 // where it is, right after the entry before it, and waits like an input for a call's result or for the model's next
@@ -166,15 +166,15 @@ export const fromEntries = (
     const next = entries.slice(from + 1).find(({ event }) => Predicate.isTagged(event, "ModelOutput"))?.event
 
     return next !== undefined && AssistantEvent.isLibraryEvent(next) && Predicate.isTagged(next, "ModelOutput")
-      ? next.seenThroughSeq
+      ? next.seenThroughSequence
       : undefined
   }
 
-  // `index` is the last entry at or before the item, and `seq` where the item stands.
-  const input = (index: number, seq: number, item: Prompt.Message) => {
+  // `index` is the last entry at or before the item, and `sequence` where the item stands.
+  const input = (index: number, sequence: number, item: Prompt.Message) => {
     const seen = nextSeen(index)
 
-    if (open.size > 0 || (seen !== undefined && seen < seq)) held.push(item)
+    if (open.size > 0 || (seen !== undefined && seen < sequence)) held.push(item)
     else history.push(item)
   }
 
@@ -182,14 +182,14 @@ export const fromEntries = (
 
   for (const item of items) {
     if (!isEntry(item)) {
-      input(index, (entries[index]?.seq ?? 0) + 0.5, item)
+      input(index, (entries[index]?.sequence ?? 0) + 0.5, item)
 
       continue
     }
 
     index += 1
 
-    const { event, seq } = item
+    const { event, sequence } = item
     const at = index
 
     if (!AssistantEvent.isLibraryEvent(event)) continue
@@ -197,8 +197,8 @@ export const fromEntries = (
     Match.value(event).pipe(
       Match.tagsExhaustive({
         UserMessage: (message) =>
-          input(at, seq, userText(AssistantEvent.textWithAttachments(message.text, message.attachments))),
-        BlockAnswer: (answer) => input(at, seq, userText(answerText(answer))),
+          input(at, sequence, userText(AssistantEvent.textWithAttachments(message.text, message.attachments))),
+        BlockAnswer: (answer) => input(at, sequence, userText(answerText(answer))),
         ModelOutput: (output) => {
           history.push(...Prompt.fromResponseParts(output.parts).content)
 
@@ -212,11 +212,11 @@ export const fromEntries = (
           flushIfClosed()
         },
         ToolResult: (result) => {
-          if (requests.has(result.callId)) return input(at, seq, userText(approvedText(result)))
+          if (requests.has(result.callId)) return input(at, sequence, userText(approvedText(result)))
 
           // A view that starts after the call (since a summary, say) keeps its result as text: a tool result needs its
           // call right before it.
-          if (!called.has(result.callId)) return input(at, seq, userText(resultText(result)))
+          if (!called.has(result.callId)) return input(at, sequence, userText(resultText(result)))
 
           history.push(toolMessage(result))
           open.delete(result.callId)
@@ -227,7 +227,7 @@ export const fromEntries = (
         TurnStarted: () => undefined,
         TurnCompleted: () => undefined,
         TurnFailed: () => undefined,
-        SpecialistFinished: (finished) => input(at, seq, userText(finishedText(entries, at, finished))),
+        SpecialistFinished: (finished) => input(at, sequence, userText(finishedText(entries, at, finished))),
         // Every run starts in a call of the model's own (a spawn or a follow-up), whose result says so.
         SpecialistStarted: () => undefined,
         BlocksClosed: () => undefined,
@@ -235,7 +235,7 @@ export const fromEntries = (
         ApprovalRequested: (request) => {
           requests.set(request.callId, request)
 
-          if (!called.has(request.callId)) return input(at, seq, userText(awaitingText(request)))
+          if (!called.has(request.callId)) return input(at, sequence, userText(awaitingText(request)))
 
           history.push(awaitingMessage(request))
           open.delete(request.callId)
@@ -244,10 +244,10 @@ export const fromEntries = (
         // An approved call's result says so.
         ApprovalDecision: (decision) =>
           decision.decision === "rejected"
-            ? input(at, seq, userText(rejectedText(decision, toolOf(decision.callId))))
+            ? input(at, sequence, userText(rejectedText(decision, toolOf(decision.callId))))
             : undefined,
         ApprovalsExpired: (expired) =>
-          expired.callIds.forEach((callId) => input(at, seq, userText(expiredText(callId, toolOf(callId))))),
+          expired.callIds.forEach((callId) => input(at, sequence, userText(expiredText(callId, toolOf(callId))))),
         ChatDeleted: () => undefined
       })
     )
@@ -264,7 +264,7 @@ export const isInput = (event: { readonly _tag: string }): boolean =>
 export const handledThrough = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): number => {
   const last = entries.findLast(({ event }) => AssistantEvent.isTurnEnd(event))?.event
 
-  return last !== undefined && AssistantEvent.isTurnEnd(last) ? last.throughSeq : 0
+  return last !== undefined && AssistantEvent.isTurnEnd(last) ? last.throughSequence : 0
 }
 
 // A run the assistant stopped isn't an input here: it wakes nothing.
@@ -274,8 +274,10 @@ export const unhandledInputs = (
 ): ReadonlyArray<{ readonly _tag: string }> => {
   const seen = handledThrough(entries)
 
-  return entries.flatMap(({ event, seq }) =>
-    seq > seen && isInput(event) && !(AssistantEvent.isInput(event) && !AssistantEvent.isWaking(event)) ? [event] : []
+  return entries.flatMap(({ event, sequence }) =>
+    sequence > seen && isInput(event) && !(AssistantEvent.isInput(event) && !AssistantEvent.isWaking(event))
+      ? [event]
+      : []
   )
 }
 
@@ -285,16 +287,17 @@ export const needsTurn = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): bool
 
 // A failure the user was shown counts as a reply, and so does a call they're asked to approve.
 /** @internal */
-export const owesReply = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, throughSeq: number): boolean => {
+export const owesReply = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, throughSequence: number): boolean => {
   const latest = entries.findLast(
-    ({ event, seq }) => seq <= throughSeq && AssistantEvent.isInput(event) && AssistantEvent.isUserInput(event)
+    ({ event, sequence }) =>
+      sequence <= throughSequence && AssistantEvent.isInput(event) && AssistantEvent.isUserInput(event)
   )
 
   return (
     latest !== undefined &&
     !entries.some(
-      ({ event, seq }) =>
-        seq > latest.seq &&
+      ({ event, sequence }) =>
+        sequence > latest.sequence &&
         (Predicate.isTagged(event, "AssistantMessage") ||
           Predicate.isTagged(event, "TurnFailed") ||
           Predicate.isTagged(event, "ApprovalRequested"))
@@ -321,15 +324,16 @@ const progressMessages = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): Read
 // The model said it was on it and stopped without the result: only progress messages since the user's latest input.
 // A specialist still working doesn't count, since its report is what comes next.
 /** @internal */
-export const owesDelivery = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, throughSeq: number): boolean => {
+export const owesDelivery = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, throughSequence: number): boolean => {
   const latest = entries.findLast(
-    ({ event, seq }) => seq <= throughSeq && AssistantEvent.isInput(event) && AssistantEvent.isUserInput(event)
+    ({ event, sequence }) =>
+      sequence <= throughSequence && AssistantEvent.isInput(event) && AssistantEvent.isUserInput(event)
   )
 
   if (latest === undefined) return false
 
-  const after = entries.flatMap(({ seq, event }) =>
-    seq > latest.seq && AssistantEvent.isLibraryEvent(event) ? [event] : []
+  const after = entries.flatMap(({ sequence, event }) =>
+    sequence > latest.sequence && AssistantEvent.isLibraryEvent(event) ? [event] : []
   )
 
   const messages = after.flatMap((event) => (Predicate.isTagged(event, "AssistantMessage") ? [event] : []))
@@ -352,5 +356,5 @@ export const owesDelivery = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, th
 }
 
 /** @internal */
-export const unreadAfter = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, throughSeq: number): boolean =>
-  entries.some(({ event, seq }) => seq > throughSeq && isInput(event))
+export const unreadAfter = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, throughSequence: number): boolean =>
+  entries.some(({ event, sequence }) => sequence > throughSequence && isInput(event))

package/src/internal/loop.ts

@@ -44,13 +44,13 @@ export const TurnTools = Context.Reference<Option.Option<Toolkits.Tools>>("effec
 /** @internal */
 export interface ChatHistory {
   readonly messages: ReadonlyArray<Prompt.Message>
-  readonly throughSeq: number
+  readonly throughSequence: number
 }
 
 const readHistory = (read: ReadonlyArray<Prompt.Message> | ChatHistory) =>
   "messages" in read
-    ? { messages: read.messages, throughSeq: read.throughSeq }
-    : { messages: read, throughSeq: undefined }
+    ? { messages: read.messages, throughSequence: read.throughSequence }
+    : { messages: read, throughSequence: undefined }
 
 // `AssistantLoop` takes native toolkits; turns and specialist runs come here with their tools already merged.
 /** @internal */
@@ -281,7 +281,7 @@ export const step = <R, S, E2 = never, R2 = never>(
 
   return Stream.unwrap(
     Effect.gen(function* () {
-      const { messages: history, throughSeq } = readHistory(yield* options.history)
+      const { messages: history, throughSequence } = readHistory(yield* options.history)
       // Calls a crash cut off, with no result: they run again, with the same ids, before the model goes on.
       const cutOff = History.unansweredCalls(history)
       const approvals = yield* TurnApprovals
@@ -318,7 +318,7 @@ export const step = <R, S, E2 = never, R2 = never>(
 
       const output = AssistantEvent.ModelOutput.make({
         parts: modelParts(response.content),
-        seenThroughSeq: throughSeq,
+        seenThroughSequence: throughSequence,
         model: metadata?.modelId ?? Option.getOrUndefined(name),
         responseId: metadata?.id,
         usage: response.usage,

package/src/internal/specialists.ts

@@ -30,7 +30,7 @@ import * as Toolkits from "./toolkit.ts"
 import type { Writer } from "./writer.ts"
 
 /** @internal */
-export type RunHandler = (run: Specialist.Run) => Stream.Stream<AssistantLoop.Event, unknown, Specialist.RunServices>
+export type RunHandler = (turn: Specialist.Turn) => Stream.Stream<AssistantLoop.Event, unknown, Specialist.TurnServices>
 
 /** @internal */
 export const briefText = (brief: Specialist.Brief): string =>
@@ -75,18 +75,18 @@ export const runBrief = Effect.fnUntraced(
       return yield* Ref.get(history)
     })
 
-    const run: Specialist.Run = {
+    const turn: Specialist.Turn = {
       runId: options.runId,
       chatId: options.chatId,
       brief: options.brief,
       history: current,
       // A run can't wait for the user's approval: a call that needs it fails, and the run reads why.
-      loop: (loop) =>
+      run: (run) =>
         Loop.run({
-          instructions: loop.instructions,
-          toolkit: Toolkits.fromToolkitOrEmpty(loop.toolkit),
+          instructions: run.instructions,
+          toolkit: Toolkits.fromToolkitOrEmpty(run.toolkit),
           history: current,
-          maxSteps: loop.maxSteps ?? 8
+          maxSteps: run.maxSteps ?? 8
         }).pipe(Stream.provideService(Loop.TurnApprovals, Option.none()))
     }
 
@@ -102,7 +102,7 @@ export const runBrief = Effect.fnUntraced(
       if (text.length > 0) yield* Ref.set(answer, text)
     })
 
-    yield* Stream.runForEach(handler(run), record)
+    yield* Stream.runForEach(handler(turn), record)
 
     const text = yield* Ref.get(answer)
 

package/src/internal/turns.ts

@@ -140,12 +140,13 @@ const approvedCalls = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): Readonl
       : []
   )
 
-const lastSeq = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, otherwise: number) => entries.at(-1)?.seq ?? otherwise
+const lastSequence = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, otherwise: number) =>
+  entries.at(-1)?.sequence ?? otherwise
 
 // The handler's stream can end between a step's output and its tools, or while they run. An interrupted turn (a
 // shutdown) leaves its calls open instead: the next turn runs them again.
-const closeOpenCalls = Effect.fnUntraced(function* (chat: Writer, startSeq: number) {
-  const entries = (yield* chat.entries).filter(({ seq }) => seq > startSeq)
+const closeOpenCalls = Effect.fnUntraced(function* (chat: Writer, startSequence: number) {
+  const entries = (yield* chat.entries).filter(({ sequence }) => sequence > startSequence)
 
   const started = new Set(
     entries.flatMap(({ event }) => (Predicate.isTagged(event, "ToolStarted") ? [event.callId] : []))
@@ -169,18 +170,18 @@ const closeOpenCalls = Effect.fnUntraced(function* (chat: Writer, startSeq: numb
   )
 })
 
-// The inputs before the turn's `TurnStarted` (at `startSeq`) woke it; past that, what its model outputs record
+// The inputs before the turn's `TurnStarted` (at `startSequence`) woke it; past that, what its model outputs record
 // reading.
-const handledThrough = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, startSeq: number) =>
+const handledThrough = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, startSequence: number) =>
   entries.reduce(
-    (through, { seq, event }) =>
-      seq > startSeq &&
+    (through, { sequence, event }) =>
+      sequence > startSequence &&
       AssistantEvent.isLibraryEvent(event) &&
       Predicate.isTagged(event, "ModelOutput") &&
-      event.seenThroughSeq !== undefined
-        ? Math.max(through, event.seenThroughSeq)
+      event.seenThroughSequence !== undefined
+        ? Math.max(through, event.seenThroughSequence)
         : through,
-    startSeq
+    startSequence
   )
 
 // A turn that ran the loop fails visibly when the user's latest input got no reply; an input that arrived after what
@@ -190,8 +191,8 @@ const finishTurn = Effect.fnUntraced(function* (chat: Writer, read: number, ranL
 
   const end =
     ranLoop && History.owesReply(entries, read) && !History.unreadAfter(entries, read)
-      ? AssistantEvent.TurnFailed.make({ throughSeq: read, message: silentTurnMessage })
-      : AssistantEvent.TurnCompleted.make({ throughSeq: read })
+      ? AssistantEvent.TurnFailed.make({ throughSequence: read, message: silentTurnMessage })
+      : AssistantEvent.TurnCompleted.make({ throughSequence: read })
 
   yield* chat.append([end])
 })
@@ -200,15 +201,15 @@ const finishTurn = Effect.fnUntraced(function* (chat: Writer, read: number, ranL
 const failTurn = Effect.fnUntraced(function* (chat: Writer, cause: Cause.Cause<unknown>) {
   yield* Effect.logError("assistant turn failed", cause)
 
-  const last = lastSeq(yield* chat.entries, 0)
+  const last = lastSequence(yield* chat.entries, 0)
 
-  yield* chat.append([AssistantEvent.TurnFailed.make({ throughSeq: last, message: failureMessage(cause) })])
+  yield* chat.append([AssistantEvent.TurnFailed.make({ throughSequence: last, message: failureMessage(cause) })])
 })
 
 const makeTurnApi = (
   registration: Registration,
   chat: Writer,
-  startSeq: number,
+  startSequence: number,
   checkOpen: Effect.Effect<void>,
   ranLoop: Ref.Ref<boolean>
 ): Assistant.Turn<any> => {
@@ -228,7 +229,7 @@ const makeTurnApi = (
 
     const read: AssistantLoop.ChatHistory = {
       messages: History.fromEntries(view(AppEvents.decodeEntries(app, all))),
-      throughSeq: lastSeq(all, startSeq)
+      throughSequence: lastSequence(all, startSequence)
     }
 
     return read
@@ -247,7 +248,7 @@ const makeTurnApi = (
     Stream.unwrap(
       Effect.gen(function* () {
         const all = yield* chat.entries
-        const through = handledThrough(all, startSeq)
+        const through = handledThrough(all, startSequence)
 
         // Something arrived after what the loop's model read: the next turn reads it with the full loop, and replies.
         if (History.unreadAfter(all, through)) return Stream.empty
@@ -277,7 +278,7 @@ const makeTurnApi = (
                 ...History.fromEntries(options.view(AppEvents.decodeEntries(app, entries))),
                 History.userText(nudge)
               ],
-              throughSeq: lastSeq(entries, startSeq)
+              throughSequence: lastSequence(entries, startSequence)
             }
           }),
           // A second step, for a reply after a call it was refused.
@@ -300,7 +301,7 @@ const makeTurnApi = (
       })
     )
 
-  const prepare = <T extends Record<string, Tool.Any>>(options: Assistant.LoopOptions<T, any>) => {
+  const prepare = <T extends Record<string, Tool.Any>>(options: Assistant.RunOptions<T, any>) => {
     const own = Toolkits.showing(Toolkits.fromToolkitOrEmpty(options.toolkit), shownTools)
 
     return {
@@ -315,7 +316,7 @@ const makeTurnApi = (
     history,
     instructions,
     replyIfOwed,
-    loop: (options) => {
+    run: (options) => {
       const { system, toolkit, view } = prepare(options)
       const twice = Toolkits.duplicateNames(toolkit)
 
@@ -362,15 +363,15 @@ export const run = Effect.fnUntraced(
       )
     ])
 
-    const startSeq = lastSeq(started, 0)
+    const startSequence = lastSequence(started, 0)
     const ranLoop = yield* Ref.make(false)
-    const turn = makeTurnApi(options.registration, chat, startSeq, options.checkOpen, ranLoop)
+    const turn = makeTurnApi(options.registration, chat, startSequence, options.checkOpen, ranLoop)
 
     const record = (event: AssistantLoop.Event) => chat.append([event])
 
     yield* options.handler(turn).pipe(
       Stream.runForEach(record),
-      Effect.onExit((exit) => (Exit.hasInterrupts(exit) ? Effect.void : closeOpenCalls(chat, startSeq))),
+      Effect.onExit((exit) => (Exit.hasInterrupts(exit) ? Effect.void : closeOpenCalls(chat, startSequence))),
       // A loop the app writes gets the assistant's own tools too, with this turn's services.
       Effect.provideService(
         Loop.TurnTools,
@@ -383,15 +384,16 @@ export const run = Effect.fnUntraced(
         onSuccess: Effect.fnUntraced(function* () {
           const all = yield* chat.entries
 
-          yield* finishTurn(chat, handledThrough(all, startSeq), yield* Ref.get(ranLoop))
+          yield* finishTurn(chat, handledThrough(all, startSequence), yield* Ref.get(ranLoop))
         }),
         onFailure: (cause) => failTurn(chat, cause)
       })
     )
 
     // The trace's output is what the user saw this turn, and a failure if any.
-    const shown = (yield* chat.entries).flatMap(({ event, seq }) =>
-      seq > startSeq && (Predicate.isTagged(event, "AssistantMessage") || Predicate.isTagged(event, "TurnFailed"))
+    const shown = (yield* chat.entries).flatMap(({ event, sequence }) =>
+      sequence > startSequence &&
+      (Predicate.isTagged(event, "AssistantMessage") || Predicate.isTagged(event, "TurnFailed"))
         ? [event]
         : []
     )