effect-assistant 0.3.0 → 0.4.0

package/src/Timeline.ts

@@ -2,8 +2,9 @@
  * This module provides a chat's timeline: the chat as its user sees it. A chat client receives the
  * timeline and nothing else.
  *
- * A {@link Timeline} holds the chat's items: the messages with their blocks, and the app's own
- * events it shows (each typed with its event, see {@link EventItem}). It also holds the chat's
+ * A {@link Timeline} holds the chat's items: the messages with their blocks, the app's own events
+ * it shows (each typed with its event, see {@link EventItem}), and the tool calls waiting for the
+ * user's approval ({@link ApprovalItem}). It also holds the chat's
  * {@link Activity}, and whether the last turn failed or the chat was deleted. It never contains the
  * model's output, tool calls or results, what the model read, or why a turn failed. The server
  * streams {@link Change}s by piping the assistant's `subscribe` through {@link changes}, and the
@@ -20,6 +21,7 @@
 import { dual } from "effect/Function"
 import * as Match from "effect/Match"
 import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
 import * as Schema from "effect/Schema"
 import * as SchemaTransformation from "effect/SchemaTransformation"
 import * as Stream from "effect/Stream"
@@ -29,6 +31,7 @@ import * as AssistantEvent from "./AssistantEvent.ts"
 import * as BlockKit from "./BlockKit.ts"
 import { InputId } from "./InputId.ts"
 import * as AppEvents from "./internal/events.ts"
+import * as ToolApproval from "./ToolApproval.ts"
 import { toJson } from "./internal/schema.ts"
 
 /**
@@ -135,8 +138,43 @@ export type EventItem<E> = E extends { readonly _tag: infer Tag extends string }
   : never
 
 /**
- * Represents an item in the chat's timeline: a message the user or the assistant sent, or one of
- * the app's own events it shows (see {@link EventItem}).
+ * Schema for a tool call that waits, or waited, for the user's approval, as an item on the
+ * timeline.
+ *
+ * **Details**
+ *
+ * It is only the yes or no: the assistant's own message tells the user what it asks them to
+ * approve, so the item carries no params. `id` is the call's id, which the decision is for (see
+ * `ToolApproval.approve`), and `tool` the tool's name, for a label. `status` is where the call stands
+ * (`ToolApproval.Status`); `reason` is the user's, when they rejected it with one; `outcome` is how
+ * the approved call went, once it ran. `at` is when the call started waiting, in epoch
+ * milliseconds. A change updates the item in place as the call is decided and run.
+ *
+ * @category schemas
+ * @since 0.4.0
+ */
+export const ApprovalItem = Schema.TaggedStruct("ToolApproval", {
+  id: Schema.String,
+  tool: Schema.String,
+  status: Schema.Literals(["pending", "approved", "rejected", "expired"]),
+  reason: Schema.optional(Schema.String),
+  outcome: Schema.optional(AssistantEvent.ToolOutcome),
+  at: Schema.Finite
+})
+
+/**
+ * Represents a tool call that waits, or waited, for the user's approval, as an item on the
+ * timeline.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export type ApprovalItem = typeof ApprovalItem.Type
+
+/**
+ * Represents an item in the chat's timeline: a message the user or the assistant sent, one of the
+ * app's own events it shows (see {@link EventItem}), or a tool call waiting for the user's approval
+ * (see {@link ApprovalItem}).
  *
  * **Example** (Showing each item of a chat)
  *
@@ -158,7 +196,7 @@ export type EventItem<E> = E extends { readonly _tag: infer Tag extends string }
  * @category models
  * @since 0.3.0
  */
-export type Item<Events = never> = UserMessage | AssistantMessage | EventItem<Events>
+export type Item<Events = never> = UserMessage | AssistantMessage | EventItem<Events> | ApprovalItem
 
 /**
  * Schema for a specialist that is working for the assistant. It holds the specialist's name and
@@ -227,7 +265,7 @@ export interface Timeline<Events = never> {
  * **Details**
  *
  * A change holds each item that is new or changed (for example, a message whose block was
- * answered or closed), in full. It also holds the current activity, whether the last turn failed,
+ * 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
  * to.
  *
@@ -250,7 +288,10 @@ function makeChange<const Events extends ReadonlyArray<AssistantEvent.AppEventSc
 ): Schema.Codec<Change<Events[number]["Type"]>, Schema.Json>
 // The overload states the decoded type: an item per given schema, each typed with its own event.
 function makeChange(events: ReadonlyArray<AssistantEvent.AppEventSchema> = []): Schema.Top {
-  const AnyItem = Schema.toCodecJson(Schema.Union([UserMessage, AssistantMessage, ...events.map(eventItem)]))
+  const AnyItem = Schema.toCodecJson(
+    Schema.Union([UserMessage, AssistantMessage, ApprovalItem, ...events.map(eventItem)])
+  )
+
   const decodeItem = Schema.decodeUnknownOption(AnyItem)
   const encodeItem = Schema.encodeUnknownSync(AnyItem)
 
@@ -280,7 +321,8 @@ function makeChange(events: ReadonlyArray<AssistantEvent.AppEventSchema> = []):
  * **Details**
  *
  * It is the success schema of the RPC that streams a chat's timeline: name the events the chat's
- * users see, the same ones the handler passes to {@link changes} as `show`. Each item decodes its
+ * users see, the same ones the handler passes to {@link changes} as `show`. Tool calls waiting for
+ * approval are always in it, as {@link ApprovalItem}s. Each item decodes its
  * event with that event's schema, so the client gets `Change<Events>` typed with them and folds it
  * with {@link fold}, no definition needed. `Change()` carries no app events.
  *
@@ -417,10 +459,12 @@ interface AnyEventItem {
   readonly event: { readonly _tag: string }
 }
 
+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 items: ReadonlyArray<UserMessage | AssistantMessage | AnyEventItem>
+  readonly items: ReadonlyArray<AnyItem>
   readonly activity: Activity
   readonly failed: boolean
   readonly deleted: boolean
@@ -575,13 +619,14 @@ 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 failed = false
   let deleted = false
   let activity = AssistantActivity.empty
   let blocks: ReadonlyMap<string, BlockKit.State> = new Map()
   // The items in order, and the assistant's messages as stored: their blocks change as the chat goes on.
-  const items = new Map<string, UserMessage | AssistantMessage | AnyEventItem>()
+  const items = new Map<string, AnyItem>()
   const sent = new Map<string, AssistantEvent.AssistantMessage>()
 
   const blockOf = (message: AssistantEvent.AssistantMessage): Block | undefined => {
@@ -634,6 +679,13 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
           return [answer.messageId]
         },
         BlocksClosed: (closed) => closed.messageIds,
+        ApprovalRequested: () => [],
+        ApprovalDecision: () => {
+          failed = false
+
+          return []
+        },
+        ApprovalsExpired: () => [],
         TurnFailed: () => {
           failed = true
 
@@ -670,8 +722,38 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
     }))
   }
 
+  const callsOf = (event: AssistantEvent.AssistantEvent): ReadonlyArray<string> =>
+    Predicate.isTagged(event, "ApprovalsExpired")
+      ? event.callIds
+      : Predicate.isTagged(event, "ApprovalRequested") ||
+          Predicate.isTagged(event, "ApprovalDecision") ||
+          Predicate.isTagged(event, "ToolResult")
+        ? [event.callId]
+        : []
+
+  // The items of the calls this entry changed.
+  const approvalItems = (event: AssistantEvent.AssistantEvent, before: ReadonlyMap<string, ToolApproval.State>) =>
+    callsOf(event).flatMap((callId) => {
+      const state = approvals.get(callId)
+
+      if (state === undefined || state === before.get(callId)) return []
+
+      const item = ApprovalItem.make({
+        id: callId,
+        tool: state.request.tool,
+        status: state.status,
+        reason: state.reason,
+        outcome: state.outcome,
+        at: state.at
+      })
+
+      items.set(callId, item)
+
+      return [item]
+    })
+
   const step = (entry: AssistantEvent.AnyEntry): AnyChange | undefined => {
-    const before = { activity: activityOf(activity), failed, deleted }
+    const previous = { activity: activityOf(activity), failed, deleted }
     const { event } = entry
 
     seq = entry.seq
@@ -682,7 +764,7 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
 
       return Option.match(eventItemOf(entry), {
         onNone: () =>
-          sameActivity(before.activity, now) ? undefined : { seq, items: [], activity: now, failed, deleted },
+          sameActivity(previous.activity, now) ? undefined : { seq, items: [], activity: now, failed, deleted },
         onSome: (item) => {
           items.set(item.id, item)
 
@@ -693,6 +775,9 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
 
     blocks = BlockKit.apply(blocks, event)
 
+    const decidedBefore = approvals
+    approvals = ToolApproval.apply(approvals, entry)
+
     const changed = [...new Set(touched(event, entry.at))].flatMap((id) => {
       const message = sent.get(id)
       const current = items.get(id)
@@ -705,14 +790,15 @@ const folding = (show: ReadonlyArray<AssistantEvent.AppEventSchema>): Folding =>
       return [next]
     })
 
+    const all = [...changed, ...approvalItems(event, decidedBefore)]
     const now = activityOf(activity)
 
-    return changed.length === 0 &&
-      failed === before.failed &&
-      deleted === before.deleted &&
-      sameActivity(before.activity, now)
+    return all.length === 0 &&
+      failed === previous.failed &&
+      deleted === previous.deleted &&
+      sameActivity(previous.activity, now)
       ? undefined
-      : { seq, items: changed, activity: now, failed, deleted }
+      : { seq, items: all, activity: now, failed, deleted }
   }
 
   return {
@@ -728,7 +814,7 @@ const merge = (changes: ReadonlyArray<AnyChange>): AnyChange | undefined => {
 
   if (last === undefined) return undefined
 
-  const items = new Map<string, UserMessage | AssistantMessage | AnyEventItem>()
+  const items = new Map<string, AnyItem>()
 
   for (const change of changes) for (const item of change.items) items.set(item.id, item)
 

package/src/ToolApproval.ts

@@ -0,0 +1,249 @@
+/**
+ * Tool calls that wait for the user's approval.
+ *
+ * A tool made with Effect's `needsApproval` doesn't run when the model calls it in a turn: the
+ * call waits ({@link AssistantEvent.ApprovalRequested}), the turn ends, and the chat's timeline
+ * shows it to the user. Their decision, built with {@link approve} or {@link reject} and submitted
+ * like a message, wakes a turn: an approved call runs then, with its params and id, and a rejected
+ * one doesn't. A call the user moved on from expires ({@link closeStale}, like `BlockKit.closeStale`). On the timeline, every
+ * call is an item with its tool's name and where it stands: only the yes or no, since the
+ * assistant's message says what it asks.
+ *
+ * @since 0.4.0
+ */
+import * as Effect from "effect/Effect"
+import * as Predicate from "effect/Predicate"
+import * as AssistantEvent from "./AssistantEvent.ts"
+import { CurrentChat } from "./CurrentChat.ts"
+import * as InputId from "./InputId.ts"
+
+/**
+ * Represents where a call that waits for approval stands: `"pending"` until the user decides,
+ * then `"approved"` or `"rejected"`, or `"expired"` when the user moved on.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export type Status = "pending" | "approved" | "rejected" | "expired"
+
+/**
+ * Represents a tool call that waited, or waits, for the user's approval.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface State {
+  readonly request: AssistantEvent.ApprovalRequested
+  /** When the call started waiting, in epoch milliseconds. */
+  readonly at: number
+  readonly status: Status
+  /** The user's reason, when they rejected it with one. */
+  readonly reason: string | undefined
+  /** How the approved call went, once it ran. */
+  readonly outcome: AssistantEvent.ToolOutcome | undefined
+}
+
+const decided = (state: State, decision: AssistantEvent.ApprovalDecision): State =>
+  decision.reason === undefined
+    ? { ...state, status: decision.decision }
+    : { ...state, status: decision.decision, reason: decision.reason }
+
+/**
+ * Returns the approvals after one more entry. Fold a chat's entries in order, or use
+ * {@link fromEntries}.
+ *
+ * **Details**
+ *
+ * The first of a call's decision and its expiry counts: anything after it changes nothing.
+ *
+ * @category combinators
+ * @since 0.4.0
+ */
+export const apply = (
+  states: ReadonlyMap<string, State>,
+  entry: AssistantEvent.AnyEntry
+): ReadonlyMap<string, State> => {
+  const { event } = entry
+
+  if (!AssistantEvent.isLibraryEvent(event)) return states
+
+  if (Predicate.isTagged(event, "ApprovalRequested")) {
+    return states.has(event.callId)
+      ? states
+      : new Map(states).set(event.callId, {
+          request: event,
+          at: entry.at,
+          status: "pending",
+          reason: undefined,
+          outcome: undefined
+        })
+  }
+
+  if (Predicate.isTagged(event, "ApprovalDecision")) {
+    const state = states.get(event.callId)
+
+    return state === undefined || state.status !== "pending"
+      ? states
+      : new Map(states).set(event.callId, decided(state, event))
+  }
+
+  if (Predicate.isTagged(event, "ApprovalsExpired")) {
+    const expired = event.callIds.flatMap((callId) => {
+      const state = states.get(callId)
+
+      return state === undefined || state.status !== "pending" ? [] : [{ ...state, status: "expired" as const }]
+    })
+
+    if (expired.length === 0) return states
+
+    const next = new Map(states)
+
+    for (const state of expired) next.set(state.request.callId, state)
+
+    return next
+  }
+
+  if (Predicate.isTagged(event, "ToolResult")) {
+    const state = states.get(event.callId)
+
+    return state === undefined || state.status !== "approved"
+      ? states
+      : new Map(states).set(event.callId, { ...state, outcome: event.outcome })
+  }
+
+  return states
+}
+
+/**
+ * Returns every call that waited for approval in a chat, by call id, with where it stands.
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export const fromEntries = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): ReadonlyMap<string, State> =>
+  entries.reduce(apply, new Map<string, State>())
+
+/**
+ * The id of a decision on a call: the same for every decision on it, so the chat stores one.
+ *
+ * @category utils
+ * @since 0.4.0
+ */
+export const decisionId = (callId: string): InputId.InputId => InputId.fromKey(`approval:${callId}`)
+
+/**
+ * Returns the input that approves a call waiting for the user's approval, to submit like a
+ * message. `approval` is the call's item on the chat's timeline, or anything with the call's id.
+ *
+ * **Example** (Approve and reject buttons on the client)
+ *
+ * ```tsx
+ * import { ToolApproval } from "effect-assistant"
+ *
+ * const buttons = (approval: { readonly id: string; readonly status: ToolApproval.Status }) =>
+ *   approval.status === "pending" ? (
+ *     <>
+ *       <button onClick={() => submit(ToolApproval.approve(approval))}>Approve</button>
+ *       <button onClick={() => submit(ToolApproval.reject(approval, { reason: "Not this week" }))}>Reject</button>
+ *     </>
+ *   ) : null
+ * ```
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export const approve = (approval: { readonly id: string }): AssistantEvent.ApprovalDecision =>
+  AssistantEvent.ApprovalDecision.make({ id: decisionId(approval.id), callId: approval.id, decision: "approved" })
+
+/**
+ * Returns the input that rejects a call waiting for the user's approval, with an optional short
+ * reason the model reads.
+ *
+ * @see {@link approve} for an example
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export const reject = (
+  approval: { readonly id: string },
+  options?: { readonly reason?: string | undefined }
+): AssistantEvent.ApprovalDecision =>
+  options?.reason === undefined
+    ? AssistantEvent.ApprovalDecision.make({ id: decisionId(approval.id), callId: approval.id, decision: "rejected" })
+    : AssistantEvent.ApprovalDecision.make({
+        id: decisionId(approval.id),
+        callId: approval.id,
+        decision: "rejected",
+        reason: options.reason
+      })
+
+/**
+ * Returns the ids of the calls still waiting for approval after the user typed the given number
+ * of messages without deciding them.
+ *
+ * **Details**
+ *
+ * These are the calls {@link closeStale} closes.
+ *
+ * @category utils
+ * @since 0.4.0
+ */
+export const staleApprovals = (
+  entries: ReadonlyArray<AssistantEvent.AnyEntry>,
+  options: { readonly messages: number }
+): ReadonlyArray<string> => {
+  const states = fromEntries(entries)
+
+  return [...states.values()].flatMap((state) => {
+    if (state.status !== "pending") return []
+
+    const requested = entries.findIndex(
+      ({ event }) =>
+        AssistantEvent.isLibraryEvent(event) &&
+        Predicate.isTagged(event, "ApprovalRequested") &&
+        event.callId === state.request.callId
+    )
+
+    const typed = entries.slice(requested + 1).filter(({ event }) => Predicate.isTagged(event, "UserMessage")).length
+
+    return typed >= options.messages ? [state.request.callId] : []
+  })
+}
+
+/**
+ * Closes the calls the user moved on from, which still wait for approval after the given number
+ * of typed messages: they expire, and won't run.
+ *
+ * **Details**
+ *
+ * Run it from a turn, before or after its loop, like `BlockKit.closeStale`. It records an
+ * `ApprovalsExpired` event: the timeline shows the calls as expired, the model reads that they
+ * weren't approved, and a decision that arrives later isn't stored.
+ *
+ * **Example** (Closing calls the user moved on from, and stale blocks, every turn)
+ *
+ * ```ts
+ * import { BlockKit, ToolApproval } from "effect-assistant"
+ * import * as Effect from "effect/Effect"
+ *
+ * const MyAssistantLive = MyAssistant.toLayer(
+ *   Effect.fn(function* (turn) {
+ *     yield* BlockKit.closeStale({ messages: 10 })
+ *     yield* ToolApproval.closeStale({ messages: 10 })
+ *
+ *     return turn.loop({ instructions, toolkit: MyTools })
+ *   })
+ * )
+ * ```
+ *
+ * @see {@link staleApprovals} for the calls it closes
+ *
+ * @category utils
+ * @since 0.4.0
+ */
+export const closeStale = Effect.fn(function* (options: { readonly messages: number }) {
+  const chat = yield* CurrentChat
+  const stale = staleApprovals(yield* chat.entries, options)
+
+  if (stale.length > 0) yield* chat.append(AssistantEvent.ApprovalsExpired.make({ callIds: stale }))
+})

package/src/ToolDiscovery.ts

@@ -94,8 +94,9 @@ const requiring =
  * the tools' handlers. A catalog tool's services are `execute_tool`'s, so the turn provides them
  * as it does for any tool.
  *
- * A catalog tool with Effect's `needsApproval` set fails the layer when it is built, as it would
- * fail a loop: the library doesn't run calls that wait for approval.
+ * A catalog tool with Effect's `needsApproval` set fails the layer when it is built: a call
+ * through `execute_tool` can't wait for the user's approval. Give such a tool to the loop's toolkit
+ * directly (see `ToolApproval`).
  *
  * **Example** (Finding rarely used tools when needed)
  *
@@ -148,7 +149,11 @@ export const layer = <T extends Record<string, Tool.Any>>(catalog: Toolkit.Toolk
       const definitions = Object.values(resolved.tools)
       const needingApproval = Toolkits.needingApproval(definitions)
 
-      if (needingApproval.length > 0) return yield* Effect.die(Toolkits.needsApprovalMessage(needingApproval))
+      if (needingApproval.length > 0) {
+        return yield* Effect.die(
+          `${needingApproval.join(", ")} ${needingApproval.length === 1 ? "sets" : "set"} needsApproval, and a call through execute_tool can't wait for the user's approval. Give it to the loop's toolkit instead of ToolDiscovery's catalog.`
+        )
+      }
 
       return {
         search_tools: ({ query }) =>

package/src/index.ts

@@ -104,6 +104,11 @@ export * as Specialist from "./Specialist.ts"
  */
 export * as Timeline from "./Timeline.ts"
 
+/**
+ * @since 0.4.0
+ */
+export * as ToolApproval from "./ToolApproval.ts"
+
 /**
  * @since 0.1.0
  */

package/src/internal/chat.ts

@@ -18,6 +18,7 @@ import { ChatLog } from "../ChatLog.ts"
 import { CurrentChat } from "../CurrentChat.ts"
 import * as Chats from "../Chats.ts"
 import * as SpecialistService from "../Specialist.ts"
+import * as ToolApproval from "../ToolApproval.ts"
 import * as AppEvents from "./events.ts"
 import * as History from "./history.ts"
 import * as Specialists from "./specialists.ts"
@@ -197,8 +198,17 @@ export const make = Effect.fnUntraced(function* (options: {
         if (yield* isDeleted) return yield* refused(input, "is deleted")
 
         const id = idOf(input)
+        const all = yield* Ref.get(entries)
 
-        if (id !== undefined && (yield* Ref.get(entries)).some(({ event }) => idOf(event) === id)) return
+        if (id !== undefined && all.some(({ event }) => idOf(event) === id)) return
+
+        // A decision counts only for a call that still waits: not one decided, or expired, or unknown.
+        if (
+          Predicate.isTagged(input, "ApprovalDecision") &&
+          ToolApproval.fromEntries(all).get(input.callId)?.status !== "pending"
+        ) {
+          return yield* refused(input, "has no call waiting for that decision")
+        }
 
         // Stored as an input: it came in from outside a turn, so it wakes one, also after a restart.
         yield* write([AssistantEvent.isLibraryEvent(input) ? input : AppEvents.markInput(input)])

package/src/internal/history.ts

@@ -110,6 +110,35 @@ const answerText = (answer: AssistantEvent.BlockAnswer) =>
 const resultText = (result: AssistantEvent.ToolResult) =>
   `<result tool="${result.tool}" call="${result.callId}" outcome="${result.outcome}">\nThe result of a call from earlier in this chat.\n${toJsonText(result.result)}\n</result>`
 
+/** @internal */
+export const awaitingApprovalOutput =
+  "Waiting for the user's approval: they see this call and approve or reject it. Its outcome arrives later in this chat; don't call it again meanwhile."
+
+const awaitingText = (request: AssistantEvent.ApprovalRequested) =>
+  `<approval tool="${request.tool}" call="${request.callId}" status="pending">\nYour call to ${request.tool} from earlier in this chat waits for the user's approval.\n${toJsonText(request.params)}\n</approval>`
+
+const approvedText = (result: AssistantEvent.ToolResult) =>
+  `<result tool="${result.tool}" call="${result.callId}" outcome="${result.outcome}">\nThe user approved your call to ${result.tool} from earlier in this chat, and it ran.\n${toJsonText(result.result)}\n</result>`
+
+const rejectedText = (decision: AssistantEvent.ApprovalDecision, tool: string) =>
+  `<approval tool="${tool}" call="${decision.callId}" decision="rejected">\nThe user rejected your call to ${tool}; it didn't run.${decision.reason === undefined ? "" : `\nTheir reason: ${decision.reason}`}\n</approval>`
+
+const expiredText = (callId: string, tool: string) =>
+  `<approval tool="${tool}" call="${callId}" status="expired">\nThe user moved on without approving your call to ${tool}; it didn't run.\n</approval>`
+
+const awaitingMessage = (request: AssistantEvent.ApprovalRequested): Prompt.ToolMessage =>
+  Prompt.toolMessage({
+    content: [
+      Prompt.toolResultPart({
+        id: request.callId,
+        name: request.tool,
+        isFailure: false,
+        result: awaitingApprovalOutput,
+        providerExecuted: false
+      })
+    ]
+  })
+
 const isEntry = (item: AssistantEvent.AnyEntry | Prompt.Message): item is AssistantEvent.AnyEntry =>
   Predicate.hasProperty(item, "seq")
 
@@ -125,6 +154,9 @@ export const fromEntries = (
   const held: Array<Prompt.Message> = []
   const open = new Set<string>()
   const called = new Set<string>()
+  // Calls that waited for approval: the placeholder answered them, so what came of them later is an input.
+  const requests = new Map<string, AssistantEvent.ApprovalRequested>()
+  const toolOf = (callId: string) => requests.get(callId)?.tool ?? "a tool"
 
   const flushIfClosed = () => {
     if (open.size === 0) history.push(...held.splice(0))
@@ -180,6 +212,8 @@ export const fromEntries = (
           flushIfClosed()
         },
         ToolResult: (result) => {
+          if (requests.has(result.callId)) return input(at, seq, 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)))
@@ -197,6 +231,23 @@ export const fromEntries = (
         // 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,
+        // The call's result, for the provider's pairing; what the user decides comes later.
+        ApprovalRequested: (request) => {
+          requests.set(request.callId, request)
+
+          if (!called.has(request.callId)) return input(at, seq, userText(awaitingText(request)))
+
+          history.push(awaitingMessage(request))
+          open.delete(request.callId)
+          flushIfClosed()
+        },
+        // An approved call's result says so.
+        ApprovalDecision: (decision) =>
+          decision.decision === "rejected"
+            ? input(at, seq, userText(rejectedText(decision, toolOf(decision.callId))))
+            : undefined,
+        ApprovalsExpired: (expired) =>
+          expired.callIds.forEach((callId) => input(at, seq, userText(expiredText(callId, toolOf(callId))))),
         ChatDeleted: () => undefined
       })
     )
@@ -232,7 +283,7 @@ export const unhandledInputs = (
 export const needsTurn = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): boolean =>
   unhandledInputs(entries).length > 0
 
-// A failure the user was shown counts as a reply.
+// 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 => {
   const latest = entries.findLast(
@@ -243,7 +294,10 @@ export const owesReply = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, throu
     latest !== undefined &&
     !entries.some(
       ({ event, seq }) =>
-        seq > latest.seq && (Predicate.isTagged(event, "AssistantMessage") || Predicate.isTagged(event, "TurnFailed"))
+        seq > latest.seq &&
+        (Predicate.isTagged(event, "AssistantMessage") ||
+          Predicate.isTagged(event, "TurnFailed") ||
+          Predicate.isTagged(event, "ApprovalRequested"))
     )
   )
 }
@@ -288,10 +342,11 @@ export const owesDelivery = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, th
     )
   )
 
+  // A call waiting for the user's approval is what comes next, like a specialist's report.
   return (
     messages.length > 0 &&
     messages.every((message) => message.block === undefined && progress.has(message.id)) &&
-    !after.some((event) => Predicate.isTagged(event, "TurnFailed")) &&
+    !after.some((event) => Predicate.isTagged(event, "TurnFailed") || Predicate.isTagged(event, "ApprovalRequested")) &&
     started.every((runId) => finished.has(runId))
   )
 }