effect-assistant 0.4.0 → 0.6.0

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

package/src/Timeline.ts

@@ -64,7 +64,9 @@ export const Block = Schema.Struct({
   kind: Schema.String,
   props: Schema.Json,
   status: BlockStatus,
-  answer: Schema.optional(Schema.Json)
+  answer: Schema.optional(Schema.Json),
+  /** For a block that shows a tool's result (`Block.fromToolResult`): the result, as the tool's success schema encodes it. */
+  result: Schema.optional(Schema.Json)
 })
 
 /**
@@ -244,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. */
@@ -266,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
@@ -296,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(
@@ -359,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,
@@ -405,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))
@@ -463,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
@@ -620,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
@@ -628,6 +630,8 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
   // The items in order, and the assistant's messages as stored: their blocks change as the chat goes on.
   const items = new Map<string, AnyItem>()
   const sent = new Map<string, AssistantEvent.AssistantMessage>()
+  // The results a block can show, by id: a message shows one stored before it.
+  const results = new Map<string, Schema.Json>()
 
   const blockOf = (message: AssistantEvent.AssistantMessage): Block | undefined => {
     if (message.block === undefined) return undefined
@@ -635,8 +639,11 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
     const state = blocks.get(message.id)
     const status = state === undefined || state.open ? "open" : state.answer === undefined ? "closed" : "answered"
     const block: Block = { kind: message.block.kind, props: toJson(message.block.props), status }
+    const { resultId } = message.block
+    const result = resultId === undefined ? undefined : results.get(resultId)
+    const shown = result === undefined ? block : { ...block, result }
 
-    return state?.answer === undefined ? block : { ...block, answer: toJson(state.answer.value) }
+    return state?.answer === undefined ? shown : { ...shown, answer: toJson(state.answer.value) }
   }
 
   const itemOf = (message: AssistantEvent.AssistantMessage, at: number): AssistantMessage => {
@@ -693,7 +700,13 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
         },
         ModelOutput: () => [],
         ToolStarted: () => [],
-        ToolResult: () => [],
+        ToolResult: (result) => {
+          if (result.resultId !== undefined && result.outcome === "success") {
+            results.set(result.resultId, result.full ?? result.result)
+          }
+
+          return []
+        },
         TurnStarted: () => [],
         TurnCompleted: () => [],
         SpecialistStarted: () => [],
@@ -716,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
     }))
@@ -756,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)) {
@@ -764,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 }
         }
       })
     }
@@ -798,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 }
     }
   }
 }
@@ -819,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,
@@ -851,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
@@ -876,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)
@@ -894,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.
@@ -915,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)
  *   })

package/src/ToolResult.ts

@@ -0,0 +1,80 @@
+/**
+ * Shapes what the model reads of a tool's result.
+ *
+ * A tool's success goes into the chat's log in full. {@link modelView} gives the model a smaller
+ * view of it, so fields only the app's UI needs (an image URL, a file id) stay out of its context
+ * and out of what it might copy into its replies.
+ *
+ * A tool whose results the assistant's blocks show (`Block.fromToolResult`) also gets a `resultId`
+ * in what the model reads. The model passes it in a `tool_result` block to show that result, and
+ * the client draws it from the full result in the log.
+ *
+ * @since 0.5.0
+ */
+import type * as Tool from "effect/ai/Tool"
+import * as Context from "effect/Context"
+import { dual } from "effect/Function"
+import type * as Schema from "effect/Schema"
+
+// The tool's schemas, as `Tool.Tool` constrains them.
+type Schemas = {
+  readonly parameters: Schema.Top
+  readonly success: Schema.Top
+  readonly failure: Schema.Top
+  readonly failureMode: Tool.FailureMode
+}
+
+/**
+ * Annotation for what the model reads of a tool's success, set with {@link modelView}.
+ *
+ * @category annotations
+ * @since 0.5.0
+ */
+export class ModelView extends Context.Service<ModelView, (success: any) => Schema.Json>()(
+  "effect-assistant/ToolResult/ModelView"
+) {}
+
+/**
+ * Sets what the model reads of a tool's success. The chat's log keeps the whole success.
+ *
+ * **Details**
+ *
+ * The view gets the success as the tool's success schema decodes it, and returns the JSON the
+ * model reads instead. Failures reach the model as they are.
+ *
+ * **Example** (Keeping image URLs out of the model's context)
+ *
+ * ```ts
+ * import * as Tool from "effect/ai/Tool"
+ * import * as Schema from "effect/Schema"
+ * import { ToolResult } from "effect-assistant"
+ *
+ * const Asset = Schema.Struct({ id: Schema.String, name: Schema.String, imageUrl: Schema.String })
+ *
+ * export const SearchAssets = ToolResult.modelView(
+ *   Tool.make("search_assets", {
+ *     parameters: Schema.Struct({ query: Schema.String }),
+ *     success: Schema.Struct({ items: Schema.Array(Asset) })
+ *   }),
+ *   (result) => ({ items: result.items.map(({ id, name }) => ({ id, name })) })
+ * )
+ * ```
+ *
+ * @category annotations
+ * @since 0.5.0
+ */
+export const modelView: {
+  <Config extends Schemas>(
+    view: (success: Config["success"]["Type"]) => Schema.Json
+  ): <Name extends string, R>(tool: Tool.Tool<Name, Config, R>) => Tool.Tool<Name, Config, R>
+  <Name extends string, Config extends Schemas, R>(
+    tool: Tool.Tool<Name, Config, R>,
+    view: (success: Config["success"]["Type"]) => Schema.Json
+  ): Tool.Tool<Name, Config, R>
+} = dual(
+  2,
+  <Name extends string, Config extends Schemas, R>(
+    tool: Tool.Tool<Name, Config, R>,
+    view: (success: Config["success"]["Type"]) => Schema.Json
+  ): Tool.Tool<Name, Config, R> => tool.annotate(ModelView, view)
+)

package/src/index.ts

@@ -118,3 +118,8 @@ export * as ToolDiscovery from "./ToolDiscovery.ts"
  * @since 0.1.0
  */
 export * as ToolFailure from "./ToolFailure.ts"
+
+/**
+ * @since 0.5.0
+ */
+export * as ToolResult from "./ToolResult.ts"

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
 })