effect-assistant 0.4.0 → 0.5.0

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)
 }) {}
 
 /**
@@ -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)
 }) {}
 
 /**

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/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)
 })
 
 /**
@@ -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: () => [],

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/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 =
@@ -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" }
               )
 

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"
@@ -214,6 +214,7 @@ const makeTurnApi = (
 ): 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)))
@@ -280,7 +281,10 @@ const makeTurnApi = (
             }
           }),
           // 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()))
       })
@@ -297,7 +301,7 @@ const makeTurnApi = (
     )
 
   const prepare = <T extends Record<string, Tool.Any>>(options: Assistant.LoopOptions<T, any>) => {
-    const own = Toolkits.fromToolkitOrEmpty(options.toolkit)
+    const own = Toolkits.showing(Toolkits.fromToolkitOrEmpty(options.toolkit), shownTools)
 
     return {
       system: instructions(options.instructions),