effect-assistant 0.4.0 → 0.6.0

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

@@ -18,7 +18,7 @@ import type * as Instructions from "../Instructions.ts"
 import * as History from "./history.ts"
 import * as Telemetry from "./telemetry.ts"
 import * as Toolkits from "./toolkit.ts"
-import { isTurnEnding } from "./tools.ts"
+import { isTurnEnding, isUserMessage } from "./tools.ts"
 
 /** @internal */
 export type Event =
@@ -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 */
@@ -158,6 +158,17 @@ interface Ran {
   readonly waiting: boolean
 }
 
+// The approval shows the call, not what it does: the user learns that from the assistant's message beside it.
+const unexplained = (call: AssistantEvent.ToolCallPart) =>
+  AssistantEvent.ToolResult.make({
+    callId: call.id,
+    tool: call.name,
+    ...Toolkits.failed(
+      `Not sent for approval: the user would see buttons without knowing what they approve. In one step, send them a message with send_user_message saying what ${call.name} will do (what, to whom, how many), and call ${call.name} again.`,
+      "ApprovalNeedsMessage"
+    )
+  })
+
 // Every `ToolStarted` is stored before any call runs; a call that waits for approval doesn't start.
 const runCalls = <R, S, E, R2>(
   tools: Toolkits.Tools<R>,
@@ -179,10 +190,16 @@ const runCalls = <R, S, E, R2>(
         Stream.concat(
           Stream.unwrap(
             Effect.gen(function* () {
+              const explained = pending.some(({ call }) => isUserMessage(call))
+
               const done = yield* Effect.forEach(
                 pending,
                 ({ call }, i): Effect.Effect<Event, never, R> =>
-                  waits[i] === true ? awaitApproval(call) : runCall(tools, call),
+                  waits[i] !== true
+                    ? runCall(tools, call)
+                    : explained
+                      ? awaitApproval(call)
+                      : Effect.succeed(unexplained(call)),
                 { concurrency: "unbounded" }
               )
 
@@ -264,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
@@ -301,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/toolkit.ts

@@ -2,7 +2,7 @@ import * as AiError from "effect/ai/AiError"
 import type * as Prompt from "effect/ai/Prompt"
 import type * as Tool from "effect/ai/Tool"
 import type * as Toolkit from "effect/ai/Toolkit"
-import type * as Context from "effect/Context"
+import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
 import * as Option from "effect/Option"
 import * as Predicate from "effect/Predicate"
@@ -11,13 +11,17 @@ import * as Stream from "effect/Stream"
 import type * as AssistantEvent from "../AssistantEvent.ts"
 import { AssistantToolCall } from "../AssistantToolCall.ts"
 import * as ToolFailure from "../ToolFailure.ts"
+import { ModelView } from "../ToolResult.ts"
 import { toJson } from "./schema.ts"
+import * as Uuid from "./uuid.ts"
 
 /** @internal */
 export interface CallResult {
   readonly outcome: AssistantEvent.ToolOutcome
   readonly result: Schema.Json
   readonly reason?: string | undefined
+  readonly full?: Schema.Json | undefined
+  readonly resultId?: string | undefined
 }
 
 // Apps give the loop native toolkits; these are what the loop makes of them, merged with its own.
@@ -119,12 +123,22 @@ export const runNative = Effect.fnUntraced(function* <T extends Record<string, T
     const results = yield* toolkit.handle<keyof T>(name, params, call.id)
     const last = yield* Stream.runLast(Stream.filter(results, (result) => !result.preliminary))
 
+    const view = Option.flatMap(Option.fromUndefinedOr(toolNamed(toolkit, call.name)), (tool) =>
+      Context.getOption(tool.annotations, ModelView)
+    )
+
     return Option.match(last, {
       onNone: () => failed(`${call.name} returned no result.`, "NoResult"),
-      onSome: (result): CallResult =>
-        result.isFailure
-          ? failure(toJson(result.encodedResult))
-          : { outcome: "success", result: toJson(result.encodedResult) }
+      onSome: (result): CallResult => {
+        if (result.isFailure) return failure(toJson(result.encodedResult))
+
+        const full = toJson(result.encodedResult)
+
+        return Option.match(view, {
+          onNone: () => ({ outcome: "success", result: full }),
+          onSome: (read) => ({ outcome: "success", result: toJson(read(result.result)), full })
+        })
+      }
     })
   }).pipe(
     Effect.catch((error) =>
@@ -180,6 +194,42 @@ export const merge = <A, B>(self: Tools<A>, that: Tools<B>): Tools<A | B> => {
   }
 }
 
+// Short, for the model to copy, and from the call: a call run again after a crash keeps its id.
+/** @internal */
+export const resultIdOf = (callId: string): string => `r-${Uuid.fromKey(`result:${callId}`).slice(0, 8)}`
+
+const decodeJsonObject = Schema.decodeUnknownOption(Schema.Record(Schema.String, Schema.Json))
+
+const withResultId = (result: CallResult, resultId: string): CallResult => {
+  if (result.outcome === "failure") return result
+
+  const read = result.result
+  const fields = Array.isArray(read) ? Option.none() : decodeJsonObject(read)
+
+  return {
+    ...result,
+    result: Option.match(fields, {
+      onNone: () => ({ resultId, result: read }),
+      onSome: (object) => ({ resultId, ...object })
+    }),
+    full: result.full ?? read,
+    resultId
+  }
+}
+
+// The results of tools the assistant's blocks show get an id the model passes to show one.
+/** @internal */
+export const showing = <R>(tools: Tools<R>, names: ReadonlySet<string>): Tools<R> =>
+  names.size === 0
+    ? tools
+    : {
+        ...tools,
+        run: (call) =>
+          names.has(call.name)
+            ? Effect.map(tools.run(call), (result) => withResultId(result, resultIdOf(call.id)))
+            : tools.run(call)
+      }
+
 // A turn's own services, for a loop the app writes.
 /** @internal */
 export const provide = <R>(tools: Tools<R>, context: Context.Context<R>): Tools => ({

package/src/internal/tools.ts

@@ -6,6 +6,7 @@ import * as Predicate from "effect/Predicate"
 import * as Schema from "effect/Schema"
 import * as AssistantEvent from "../AssistantEvent.ts"
 import { AssistantToolCall } from "../AssistantToolCall.ts"
+import * as Block from "../Block.ts"
 import type * as BlockKit from "../BlockKit.ts"
 import { CurrentChat } from "../CurrentChat.ts"
 import * as ToolFailure from "../ToolFailure.ts"
@@ -34,6 +35,13 @@ const WaitFlag = Schema.Boolean.annotate({
 
 const endsWithMessage = Schema.decodeUnknownOption(Schema.Struct({ wait: Schema.Literal(true) }))
 
+const messageText = Schema.decodeUnknownOption(Schema.Struct({ text: Schema.String }))
+
+// A message the user reads: the call's text isn't empty.
+/** @internal */
+export const isUserMessage = (call: AssistantEvent.ToolCallPart): boolean =>
+  call.name === sendUserMessageName && Option.exists(messageText(call.params), ({ text }) => text.trim() !== "")
+
 /** @internal */
 export const isTurnEnding = (call: AssistantEvent.ToolCallPart): boolean =>
   call.name === waitToolName || (call.name === sendUserMessageName && Option.isSome(endsWithMessage(call.params)))
@@ -76,9 +84,56 @@ const plainTools = Effect.gen(function* () {
   return yield* Effect.provideContext(PlainTools, yield* plainHandlers)
 })
 
+/** @internal */
+export const toolResultKind = "tool_result"
+
+const ToolResultRef = Schema.Struct({
+  resultId: Schema.String.annotate({ description: "The resultId of the tool result to show." })
+})
+
+const decodeRef = Schema.decodeUnknownOption(ToolResultRef)
+
+// The latest successful result with that id, of a tool the kit shows.
+const shownResult = Effect.fnUntraced(function* (resultId: string, shown: ReadonlySet<string>) {
+  const entries = yield* (yield* CurrentChat).entries
+
+  const result = entries
+    .flatMap(({ event }) =>
+      AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, "ToolResult") && event.resultId === resultId
+        ? [event]
+        : []
+    )
+    .at(-1)
+
+  if (result === undefined || result.outcome === "failure") {
+    return yield* ToolFailure.fail(
+      `No tool result ${resultId} to show: pass the resultId of a result you got in this chat.`,
+      { reason: "ResultNotFound" }
+    )
+  }
+
+  if (!shown.has(result.tool)) {
+    return yield* ToolFailure.fail(`${result.tool} results can't be shown.`, { reason: "ResultNotShown" })
+  }
+
+  return result
+})
+
 const blockTools = Effect.fnUntraced(function* (kit: BlockKit.BlockKit) {
-  const catalog = kit.blocks.map((block) => `- ${block.kind}: ${block.description}`).join("\n")
-  const kinds = kit.blocks.map((block) => block.kind)
+  const asked = kit.blocks.filter((block) => !Block.isToolResult(block))
+  const shown = new Set(kit.blocks.flatMap((block) => (Block.isToolResult(block) ? [block.tool.name] : [])))
+
+  const catalog = [
+    ...asked.map((block) => `- ${block.kind}: ${block.description}`),
+    ...(shown.size === 0
+      ? []
+      : [
+          `- ${toolResultKind}: a tool's result, shown the way the app draws it (found items as cards, a download as a button). Results you can show have a resultId: pass it as the props. From: ${[...shown].join(", ")}.`
+        ])
+  ].join("\n")
+
+  const kinds = [...asked.map((block) => block.kind), ...(shown.size === 0 ? [] : [toolResultKind])]
+  const props = [...asked.map((block) => block.props), ...(shown.size === 0 ? [] : [ToolResultRef])]
 
   const BlockMessage = Tool.make(sendUserMessageName, {
     description: `${description}
@@ -92,7 +147,7 @@ ${catalog}`,
       block: Schema.optional(
         Schema.Struct({
           kind: Schema.Literals(kinds),
-          props: Schema.Union(kit.blocks.map((block) => block.props))
+          props: Schema.Union(props)
         })
       ),
       closes: Schema.optional(Schema.Array(Schema.String)).annotate({
@@ -126,9 +181,30 @@ ${catalog}`,
         return "sent"
       }
 
-      const props = kit.byKind.get(block.kind)?.props
+      if (block.kind === toolResultKind) {
+        const ref = decodeRef(block.props)
+
+        if (Option.isNone(ref)) {
+          return yield* ToolFailure.fail(`A ${toolResultKind} block's props are { resultId }.`)
+        }
+
+        const result = yield* shownResult(ref.value.resultId, shown)
+
+        yield* append(
+          AssistantEvent.AssistantMessage.make({
+            id,
+            text,
+            block: AssistantEvent.MessageBlock.make({ kind: result.tool, props: {}, resultId: ref.value.resultId }),
+            ...closed
+          })
+        )
+
+        return `sent as message ${id}`
+      }
+
+      const schema = kit.byKind.get(block.kind)?.props
 
-      if (props === undefined || Option.isNone(Schema.decodeUnknownOption(props)(block.props))) {
+      if (schema === undefined || Option.isNone(Schema.decodeUnknownOption(schema)(block.props))) {
         return yield* ToolFailure.fail(`Those props don't fit a ${block.kind} block.`)
       }
 

package/src/internal/turns.ts

@@ -17,7 +17,7 @@ import type { ChatId } from "../ChatId.ts"
 import * as AssistantEvent from "../AssistantEvent.ts"
 import type * as AssistantLoop from "../AssistantLoop.ts"
 import * as Loop from "./loop.ts"
-import type * as BlockKit from "../BlockKit.ts"
+import * as BlockKit from "../BlockKit.ts"
 import type { CurrentChat } from "../CurrentChat.ts"
 import * as Instructions from "../Instructions.ts"
 import * as ToolApproval from "../ToolApproval.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,20 +201,21 @@ 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> => {
   const { definition, builtins } = registration
   const { app } = definition
+  const shownTools = BlockKit.toolNames(definition.blocks)
 
   const running = <A, E, R>(stream: Stream.Stream<A, E, R>) =>
     Stream.unwrap(Ref.set(ranLoop, true).pipe(Effect.as(stream)))
@@ -227,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
@@ -246,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
@@ -276,11 +278,14 @@ 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.
-          maxSteps: 2
+          maxSteps: 2,
+          // The pass runs because the model wrote text of its own instead of replying, which reaches nobody: it has to
+          // call a tool now. Changing the choice costs a read of the history at full price, on these rare turns only.
+          toolChoice: "required"
           // The loop ran the approved calls; a pass that can only reply runs none.
         }).pipe(Stream.provideService(Loop.TurnApprovals, Option.none()))
       })
@@ -296,8 +301,8 @@ const makeTurnApi = (
       })
     )
 
-  const prepare = <T extends Record<string, Tool.Any>>(options: Assistant.LoopOptions<T, any>) => {
-    const own = Toolkits.fromToolkitOrEmpty(options.toolkit)
+  const prepare = <T extends Record<string, Tool.Any>>(options: Assistant.RunOptions<T, any>) => {
+    const own = Toolkits.showing(Toolkits.fromToolkitOrEmpty(options.toolkit), shownTools)
 
     return {
       system: instructions(options.instructions),
@@ -311,7 +316,7 @@ const makeTurnApi = (
     history,
     instructions,
     replyIfOwed,
-    loop: (options) => {
+    run: (options) => {
       const { system, toolkit, view } = prepare(options)
       const twice = Toolkits.duplicateNames(toolkit)
 
@@ -358,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,
@@ -379,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]
         : []
     )