effect-assistant 0.3.0 → 0.5.0

package/src/internal/loop.ts

@@ -18,10 +18,21 @@ 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 = AssistantEvent.ModelOutput | AssistantEvent.ToolStarted | AssistantEvent.ToolResult
+export type Event =
+  | AssistantEvent.ModelOutput
+  | AssistantEvent.ToolStarted
+  | AssistantEvent.ToolResult
+  | AssistantEvent.ApprovalRequested
+
+// Only a turn's loop can wait for the user's approval, and runs the calls they approved. A turn's specialists inherit
+// its context, so their runs set it back to none.
+/** @internal */
+export const TurnApprovals = Context.Reference<
+  Option.Option<{ readonly approved: Effect.Effect<ReadonlyArray<AssistantEvent.ToolCallPart>> }>
+>("effect-assistant/TurnApprovals", { defaultValue: Option.none })
 
 // The assistant's own tools with the turn's services, so an app's own loop in a turn can message the user. A
 // specialist's run has none.
@@ -61,8 +72,9 @@ export interface StepResult {
   /** The model's output; unset when the step only ran calls a crash cut off. */
   readonly output: AssistantEvent.ModelOutput | undefined
   /**
-   * Whether the model is done: it made no tool calls, or ended its turn (`wait`, or a message
-   * with `wait: true`) and none of the step's calls failed.
+   * Whether the model is done: it made no tool calls, one of its calls waits for the user's
+   * approval, or it ended its turn (`wait`, or a message with `wait: true`) and none of the step's
+   * calls failed.
    */
   readonly done: boolean
   /**
@@ -71,9 +83,15 @@ export interface StepResult {
   readonly historyLength: number
 }
 
-// The loop runs the calls itself, after storing each as started, so the model call runs none.
+// The loop runs the calls itself, after storing each as started, so the model call runs none. It also decides which
+// calls wait for approval: the model call would ask for approvals of its own.
 const requestToolkit = (definitions: ReadonlyArray<Tool.Any>): Toolkit.WithHandler<Record<string, Tool.Any>> => ({
-  tools: Object.fromEntries(definitions.map((tool) => [tool.name, tool])),
+  tools: Object.fromEntries(
+    definitions.map((tool) => [
+      tool.name,
+      tool.needsApproval === undefined || tool.needsApproval === false ? tool : tool.setNeedsApproval(false)
+    ])
+  ),
   handle: () => Effect.succeed(Stream.empty)
 })
 
@@ -111,28 +129,96 @@ const runCall = Effect.fnUntraced(function* <R>(tools: Toolkits.Tools<R>, call:
   return AssistantEvent.ToolResult.make({ callId: call.id, tool: call.name, ...result })
 })
 
-// Every `ToolStarted` is stored before any call runs. `then` is told whether one of the calls failed, so the model
-// has to read the results.
+// A call that needs approval waits for the user in a turn. A specialist's run can't ask them, so its call fails.
+const awaitApproval = Effect.fnUntraced(function* (call: AssistantEvent.ToolCallPart) {
+  if (Option.isNone(yield* TurnApprovals)) {
+    return AssistantEvent.ToolResult.make({
+      callId: call.id,
+      tool: call.name,
+      ...Toolkits.failed(
+        `${call.name} needs the user's approval, and only the assistant can ask for it. Don't run it: say in your answer what needs approving, with the details.`,
+        "NeedsApproval"
+      )
+    })
+  }
+
+  return AssistantEvent.ApprovalRequested.make({ callId: call.id, tool: call.name, params: call.params })
+})
+
+interface Pending {
+  readonly call: AssistantEvent.ToolCallPart
+  /** The user approved it: it runs without asking again. */
+  readonly approved: boolean
+}
+
+interface Ran {
+  /** One of the calls failed, so the model has to read the results. */
+  readonly failed: boolean
+  /** One of the calls waits for the user's approval, so the turn ends. */
+  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>,
-  calls: ReadonlyArray<AssistantEvent.ToolCallPart>,
-  then: (failed: boolean) => Stream.Stream<Step<never, S>, E, R2>
+  pending: ReadonlyArray<Pending>,
+  history: ReadonlyArray<Prompt.Message>,
+  then: (ran: Ran) => Stream.Stream<Step<never, S>, E, R2>
 ): Stream.Stream<Step<Event, S>, E, R | R2> =>
-  Stream.fromIterable(
-    calls.map((call) => value(AssistantEvent.ToolStarted.make({ callId: call.id, tool: call.name })))
-  ).pipe(
-    Stream.concat(
-      Stream.unwrap(
-        Effect.gen(function* () {
-          const done = yield* Effect.forEach(calls, (call) => runCall(tools, call), { concurrency: "unbounded" })
-
-          return Stream.fromIterable(done.map(value)).pipe(Stream.concat(then(done.some(isFailure))))
-        })
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const waits = yield* Effect.forEach(pending, ({ call, approved }) =>
+        approved ? Effect.succeed(false) : tools.needsApproval(call, history)
       )
-    )
+
+      const started = pending.flatMap(({ call }, i) =>
+        waits[i] === true ? [] : [value(AssistantEvent.ToolStarted.make({ callId: call.id, tool: call.name }))]
+      )
+
+      return Stream.fromIterable(started).pipe(
+        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
+                    ? runCall(tools, call)
+                    : explained
+                      ? awaitApproval(call)
+                      : Effect.succeed(unexplained(call)),
+                { concurrency: "unbounded" }
+              )
+
+              return Stream.fromIterable(done.map(value)).pipe(
+                Stream.concat(
+                  then({
+                    failed: done.some(isFailure),
+                    waiting: done.some((event) => Predicate.isTagged(event, "ApprovalRequested"))
+                  })
+                )
+              )
+            })
+          )
+        )
+      )
+    })
   )
 
-const isFailure = (result: AssistantEvent.ToolResult) => result.outcome === "failure"
+const isFailure = (event: Event) => Predicate.isTagged(event, "ToolResult") && event.outcome === "failure"
 
 /** @internal */
 export type Step<A, S> = Data.TaggedEnum<{
@@ -192,19 +278,31 @@ export const step = <R, S, E2 = never, R2 = never>(
   const instructions = Predicate.isString(options.instructions) ? { text: options.instructions } : options.instructions
 
   const after = (result: StepResult) => Stream.suspend(() => then(result))
-  const needingApproval = Toolkits.needingApproval(toolkit.definitions)
-
-  if (needingApproval.length > 0) return Stream.die(Toolkits.needsApprovalMessage(needingApproval))
 
   return Stream.unwrap(
     Effect.gen(function* () {
       const { messages: history, throughSeq } = 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
+
+      // Calls the user approved: they run as the model made them, with the same ids, before the model goes on. Not in
+      // a loop without their tools.
+      const approved = Option.isNone(approvals)
+        ? []
+        : (yield* approvals.value.approved).filter(
+            (call) =>
+              toolkit.definitions.some((tool) => tool.name === call.name) && !cutOff.some((cut) => cut.id === call.id)
+          )
+
+      if (cutOff.length > 0 || approved.length > 0) {
+        const pending = [
+          ...cutOff.map((call) => ({ call, approved: false })),
+          ...approved.map((call) => ({ call, approved: true }))
+        ]
 
-      if (cutOff.length > 0) {
-        return runCalls(toolkit, cutOff, () =>
-          after({ output: undefined, done: false, historyLength: history.length + cutOff.length })
+        return runCalls(toolkit, pending, history, ({ waiting }) =>
+          after({ output: undefined, done: waiting, historyLength: history.length + pending.length })
         )
       }
 
@@ -230,15 +328,20 @@ export const step = <R, S, E2 = never, R2 = never>(
       const calls = toolCalls(output.parts)
       const historyLength = history.length + Prompt.fromResponseParts(output.parts).content.length + calls.length
 
-      // A failed call doesn't end the turn: a message that failed never reached the user, so the model reads why.
+      // A failed call doesn't end the turn: a message that failed never reached the user, so the model reads why. A call
+      // that waits for approval does: the turn waits for the user.
       return Stream.make(value(output)).pipe(
         Stream.concat(
-          runCalls(toolkit, calls, (failed) =>
-            after({
-              output,
-              done: calls.length === 0 || (!failed && calls.some(isTurnEnding)),
-              historyLength
-            })
+          runCalls(
+            toolkit,
+            calls.map((call) => ({ call, approved: false })),
+            history,
+            ({ failed, waiting }) =>
+              after({
+                output,
+                done: calls.length === 0 || waiting || (!failed && calls.some(isTurnEnding)),
+                historyLength
+              })
           )
         )
       )

package/src/internal/specialists.ts

@@ -22,12 +22,9 @@ import * as Loop from "./loop.ts"
 import { CurrentChat } from "../CurrentChat.ts"
 import * as InputId from "../InputId.ts"
 import * as RunId from "../RunId.ts"
-import * as Skill from "../Skill.ts"
-import * as Skills from "./skills.ts"
 import * as Specialist from "../Specialist.ts"
 import * as ToolFailure from "../ToolFailure.ts"
 import { toolMessage, userText } from "./history.ts"
-import { mapText } from "./instructions.ts"
 import * as Telemetry from "./telemetry.ts"
 import * as Toolkits from "./toolkit.ts"
 import type { Writer } from "./writer.ts"
@@ -83,22 +80,19 @@ export const runBrief = Effect.fnUntraced(
       chatId: options.chatId,
       brief: options.brief,
       history: current,
-      loop: (loop) => {
-        const own = Toolkits.fromToolkitOrEmpty(loop.toolkit)
-        const skills = Skills.available(loop.skills ?? [], own.definitions)
-
-        return Loop.run({
-          instructions: mapText(loop.instructions, (text) => Skill.withCatalog(text, skills)),
-          toolkit: Toolkits.merge(Skills.toTools(skills), own),
+      // A run can't wait for the user's approval: a call that needs it fails, and the run reads why.
+      loop: (loop) =>
+        Loop.run({
+          instructions: loop.instructions,
+          toolkit: Toolkits.fromToolkitOrEmpty(loop.toolkit),
           history: current,
           maxSteps: loop.maxSteps ?? 8
-        })
-      }
+        }).pipe(Stream.provideService(Loop.TurnApprovals, Option.none()))
     }
 
     // A run lives in memory, so there's nothing to run again after a crash: `ToolStarted` isn't kept.
     const record = Effect.fnUntraced(function* (event: AssistantLoop.Event) {
-      if (Predicate.isTagged(event, "ToolStarted")) return
+      if (Predicate.isTagged(event, "ToolStarted") || Predicate.isTagged(event, "ApprovalRequested")) return
 
       if (Predicate.isTagged(event, "ToolResult")) return yield* add([toolMessage(event)])
 

package/src/internal/toolkit.ts

@@ -1,21 +1,27 @@
 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"
 import * as Schema from "effect/Schema"
 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.
@@ -23,13 +29,18 @@ export interface CallResult {
 export interface Tools<out R = never> {
   readonly definitions: ReadonlyArray<Tool.Any>
   readonly run: (call: AssistantEvent.ToolCallPart) => Effect.Effect<CallResult, never, R>
+  // Whether the call waits for the user's approval instead of running: its tool's `needsApproval`.
+  readonly needsApproval: (
+    call: AssistantEvent.ToolCallPart,
+    history: ReadonlyArray<Prompt.Message>
+  ) => Effect.Effect<boolean, never, R>
 }
 
 /** @internal */
-export type ToolServices<T extends Record<string, Tool.Any>> = Exclude<
-  Tool.HandlerServices<T[keyof T]>,
-  AssistantToolCall
->
+export type ToolServices<T extends Record<string, Tool.Any>> =
+  | Exclude<Tool.HandlerServices<T[keyof T]>, AssistantToolCall>
+  // Already in the handlers' services; stated for the loop, which decodes params to ask `needsApproval`.
+  | T[keyof T]["parametersSchema"]["DecodingServices"]
 
 const encodeFailure = Schema.encodeSync(ToolFailure.ToolFailure)
 
@@ -60,15 +71,32 @@ const hasTool = <T extends Record<string, Tool.Any>>(
   name: PropertyKey
 ): name is keyof T => Object.hasOwn(toolkit.tools, name)
 
-// Approval would park a call until the user decides, which this library doesn't do: the model calls a tool with
-// final values, and a user's own commitment goes through the app's API from a block.
 /** @internal */
 export const needingApproval = (definitions: ReadonlyArray<Tool.Any>): ReadonlyArray<string> =>
   definitions.flatMap((tool) => (tool.needsApproval === undefined || tool.needsApproval === false ? [] : [tool.name]))
 
-/** @internal */
-export const needsApprovalMessage = (names: ReadonlyArray<string>): string =>
-  `${names.join(", ")} ${names.length === 1 ? "sets" : "set"} needsApproval, and effect-assistant doesn't run tools that wait for approval. Remove needsApproval: let the model call the tool with final values, or show a block whose button calls your app's API, which does the work and submits an app event that wakes the chat.`
+// With noUncheckedIndexedAccess, an index doesn't narrow on `hasTool`.
+const toolNamed = (toolkit: { readonly tools: Record<string, Tool.Any> }, name: string): Tool.Any | undefined =>
+  Object.hasOwn(toolkit.tools, name) ? toolkit.tools[name] : undefined
+
+// Params that don't fit the tool don't wait: the call runs, and fails with why.
+const needsApprovalNative = Effect.fnUntraced(function* <T extends Record<string, Tool.Any>>(
+  toolkit: { readonly tools: T },
+  call: AssistantEvent.ToolCallPart,
+  history: ReadonlyArray<Prompt.Message>
+): Effect.fn.Return<boolean, never, ToolServices<T>> {
+  const tool = toolNamed(toolkit, call.name)
+  const needs = tool?.needsApproval
+
+  if (tool === undefined || needs === undefined || Predicate.isBoolean(needs)) return needs === true
+
+  return yield* Effect.gen(function* () {
+    const params = yield* Schema.decodeUnknownEffect(tool.parametersSchema)(call.params)
+    const decided = needs(params, { toolCallId: call.id, messages: history })
+
+    return Effect.isEffect(decided) ? yield* decided : decided
+  }).pipe(Effect.orElseSucceed(() => false))
+})
 
 // The toolkit decodes the params with the tool's schema before its handler sees them, and a call whose params don't
 // fit fails with a validation error the model reads: the model's JSON is what `handle` takes.
@@ -95,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) =>
@@ -117,7 +155,8 @@ export const fromWithHandler = <T extends Record<string, Tool.Any>>(
   toolkit: Toolkit.WithHandler<T>
 ): Tools<ToolServices<T>> => ({
   definitions: Object.values(toolkit.tools),
-  run: (call) => runNative(toolkit, call)
+  run: (call) => runNative(toolkit, call),
+  needsApproval: (call, history) => needsApprovalNative(toolkit, call, history)
 })
 
 /** @internal */
@@ -127,22 +166,8 @@ export const fromToolkit = <T extends Record<string, Tool.Any>>(
   definitions: Object.values(toolkit.tools),
   run: Effect.fnUntraced(function* (call) {
     return yield* runNative(yield* toolkit, call)
-  })
-})
-
-// The handlers use services of the loop they run in, so they're made for each call, with its context.
-/** @internal */
-export const withContext = <T extends Record<string, Tool.Any>, R>(
-  toolkit: Toolkit.Toolkit<T>,
-  handlers: (context: Context.Context<R>) => Toolkit.HandlersFrom<T>
-): Tools<R | ToolServices<T>> => ({
-  definitions: Object.values(toolkit.tools),
-  run: Effect.fnUntraced(function* (call) {
-    const context = yield* Effect.context<R>()
-    const resolved = yield* Effect.provideContext(toolkit, yield* toolkit.toHandlers(handlers(context)))
-
-    return yield* runNative(resolved, call)
-  })
+  }),
+  needsApproval: (call, history) => needsApprovalNative(toolkit, call, history)
 })
 
 /** @internal */
@@ -153,7 +178,8 @@ export const fromToolkitOrEmpty = <T extends Record<string, Tool.Any>>(
 /** @internal */
 export const empty: Tools = {
   definitions: [],
-  run: (call) => Effect.succeed(failed(`No tool named ${call.name}.`, "ToolNotFoundError"))
+  run: (call) => Effect.succeed(failed(`No tool named ${call.name}.`, "ToolNotFoundError")),
+  needsApproval: () => Effect.succeed(false)
 }
 
 /** @internal */
@@ -162,15 +188,54 @@ export const merge = <A, B>(self: Tools<A>, that: Tools<B>): Tools<A | B> => {
 
   return {
     definitions: [...self.definitions, ...that.definitions],
-    run: (call) => (inSelf(call) ? self.run(call) : that.run(call))
+    run: (call) => (inSelf(call) ? self.run(call) : that.run(call)),
+    needsApproval: (call, history) =>
+      inSelf(call) ? self.needsApproval(call, history) : that.needsApproval(call, history)
+  }
+}
+
+// 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 => ({
   definitions: tools.definitions,
-  run: (call) => Effect.provideContext(tools.run(call), context)
+  run: (call) => Effect.provideContext(tools.run(call), context),
+  needsApproval: (call, history) => Effect.provideContext(tools.needsApproval(call, history), context)
 })
 
 /** @internal */
@@ -184,5 +249,7 @@ export const duplicateNames = (tools: Tools<unknown>): ReadonlyArray<string> =>
 /** @internal */
 export const runOnly = <R>(tools: Tools<R>, names: ReadonlyArray<string>, message: string): Tools<R> => ({
   definitions: tools.definitions,
-  run: (call) => (names.includes(call.name) ? tools.run(call) : Effect.succeed(failed(message, "NotNow")))
+  run: (call) => (names.includes(call.name) ? tools.run(call) : Effect.succeed(failed(message, "NotNow"))),
+  // Refused like any other call it doesn't run.
+  needsApproval: () => Effect.succeed(false)
 })

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