effect-assistant 0.3.0 → 0.5.0

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/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

@@ -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
  */
@@ -113,3 +118,8 @@ export * as ToolDiscovery from "./ToolDiscovery.ts"
  * @since 0.1.0
  */
 export * as ToolFailure from "./ToolFailure.ts"
+
+/**
+ * @since 0.5.0
+ */
+export * as ToolResult from "./ToolResult.ts"

package/src/internal/chat.ts

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