effect-assistant 0.2.0 → 0.4.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/index.ts

@@ -4,11 +4,6 @@
  * @since 0.1.0
  */
 
-/**
- * @since 0.1.0
- */
-export * as AppEvent from "./AppEvent.ts"
-
 /**
  * @since 0.1.0
  */
@@ -64,11 +59,6 @@ export * as ChatLog from "./ChatLog.ts"
  */
 export * as Chats from "./Chats.ts"
 
-/**
- * @since 0.1.0
- */
-export * as ChatView from "./ChatView.ts"
-
 /**
  * @since 0.1.0
  */
@@ -109,6 +99,16 @@ export * as Skill from "./Skill.ts"
  */
 export * as Specialist from "./Specialist.ts"
 
+/**
+ * @since 0.3.0
+ */
+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"
@@ -101,7 +102,6 @@ export const make = Effect.fnUntraced(function* (options: {
 }) {
   const { registration, chatId } = options
   const { app } = registration.definition
-  const { wakes } = app
   const storage = yield* ChatLog
   const chats = yield* Chats.Chats
   const initial = yield* storage.read(chatId)
@@ -198,10 +198,20 @@ 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
 
-        yield* write([input])
+        // 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)])
       })
     )
   })
@@ -232,7 +242,7 @@ export const make = Effect.fnUntraced(function* (options: {
 
   const drain: Effect.Effect<void> = Semaphore.withPermit(turnsLock)(
     Effect.gen(function* () {
-      while (!(yield* isDeleted) && History.needsTurn(yield* chat.entries, wakes)) {
+      while (!(yield* isDeleted) && History.needsTurn(yield* chat.entries)) {
         yield* Turns.run({ registration, handler, chat, services, checkOpen: Effect.asVoid(checkAvailable) })
       }
     })
@@ -296,7 +306,7 @@ export const make = Effect.fnUntraced(function* (options: {
       yield* inBackground(drain)
     }),
     resume: Effect.gen(function* () {
-      if (History.needsTurn(yield* chat.entries, wakes)) yield* inBackground(drain)
+      if (History.needsTurn(yield* chat.entries)) yield* inBackground(drain)
     }),
     stream: (after) =>
       Stream.unwrap(

package/src/internal/events.ts

@@ -1,27 +1,30 @@
 import * as Effect from "effect/Effect"
 import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as Record from "effect/Record"
 import * as Schema from "effect/Schema"
-import type * as AppEvent from "../AppEvent.ts"
+import * as SchemaAST from "effect/SchemaAST"
 import type * as Assistant from "../Assistant.ts"
 import * as AssistantEvent from "../AssistantEvent.ts"
-import { toJsonText } from "./schema.ts"
+import { inputKey } from "./input.ts"
 
 /** @internal */
 export interface AppEvents {
-  readonly byTag: ReadonlyMap<string, Registered>
-  readonly wakes: ReadonlySet<string>
+  readonly byTag: ReadonlyMap<string, AssistantEvent.AppEventSchema>
 }
 
-interface Registered {
-  readonly schema: AppEvent.EventSchema
-  readonly render: AppEvent.Render<{ readonly _tag: string }> | undefined
+/** @internal */
+export const tagOf = (schema: AssistantEvent.AppEventSchema): string => {
+  const ast = schema.fields._tag.ast
+
+  if (SchemaAST.isLiteral(ast) && Predicate.isString(ast.literal)) return ast.literal
+
+  throw new Error("An app event is a tagged struct or class.")
 }
 
 /** @internal */
-export const make = (events: ReadonlyArray<AppEvent.Any>): AppEvents => {
-  const byTag = new Map(
-    events.map((event): [string, Registered] => [event.tag, { schema: event.schema, render: event.render }])
-  )
+export const make = (events: ReadonlyArray<AssistantEvent.AppEventSchema>): AppEvents => {
+  const byTag = new Map(events.map((schema): [string, AssistantEvent.AppEventSchema] => [tagOf(schema), schema]))
 
   for (const tag of byTag.keys()) {
     if (AssistantEvent.isLibraryEvent({ _tag: tag })) throw new Error(`${tag} is one of the library's events.`)
@@ -29,17 +32,17 @@ export const make = (events: ReadonlyArray<AppEvent.Any>): AppEvents => {
 
   if (byTag.size !== events.length) throw new Error("An assistant's events have different tags.")
 
-  return { byTag, wakes: new Set(events.flatMap((event) => (event.wakes ? [event.tag] : []))) }
+  return { byTag }
 }
 
 /** @internal */
 export const encode = Effect.fnUntraced(function* (app: AppEvents, event: { readonly _tag: string }) {
-  const registered = app.byTag.get(event._tag)
+  const schema = app.byTag.get(event._tag)
 
   // The types only let registered events through, so one with no schema here is a defect.
-  if (registered === undefined) return yield* Effect.die(`${event._tag} isn't one of this assistant's events.`)
+  if (schema === undefined) return yield* Effect.die(`${event._tag} isn't one of this assistant's events.`)
 
-  const json = yield* Schema.encodeUnknownEffect(Schema.toCodecJson(registered.schema))(event)
+  const json = yield* Schema.encodeUnknownEffect(Schema.toCodecJson(schema))(event)
 
   return yield* Schema.decodeUnknownEffect(AssistantEvent.StoredAppEvent)(json)
 }, Effect.orDie)
@@ -47,6 +50,30 @@ export const encode = Effect.fnUntraced(function* (app: AppEvents, event: { read
 /** @internal */
 export const isRegistered = (app: AppEvents, event: { readonly _tag: string }): boolean => app.byTag.has(event._tag)
 
+// The app's schema decodes the event as the app wrote it.
+const unmarked = (event: { readonly _tag: string }) =>
+  Predicate.hasProperty(event, inputKey) ? Record.remove(event, inputKey) : event
+
+// An event as the log stores it, decoded with its schema.
+/** @internal */
+export const decodeWith = (
+  schema: AssistantEvent.AppEventSchema,
+  event: { readonly _tag: string }
+): Option.Option<{ readonly _tag: string }> => Schema.decodeUnknownOption(Schema.toCodecJson(schema))(unmarked(event))
+
+const decodeEvent = (app: AppEvents, event: { readonly _tag: string }): Option.Option<{ readonly _tag: string }> => {
+  const schema = app.byTag.get(event._tag)
+
+  return schema === undefined ? Option.none() : decodeWith(schema, event)
+}
+
+// What came in through `submit`, from outside a turn, is an input: it wakes a turn.
+/** @internal */
+export const markInput = (event: AssistantEvent.StoredAppEvent): AssistantEvent.StoredAppEvent => ({
+  ...event,
+  [inputKey]: true
+})
+
 // An app event that doesn't decode (say, one from an older version of its schema) is left out.
 /** @internal */
 export const decodeEntry = (app: AppEvents, entry: AssistantEvent.AnyEntry): Option.Option<Assistant.Entry<any>> => {
@@ -54,14 +81,7 @@ export const decodeEntry = (app: AppEvents, entry: AssistantEvent.AnyEntry): Opt
 
   if (AssistantEvent.isLibraryEvent(event)) return Option.some({ ...toEntry(entry), event })
 
-  const registered = app.byTag.get(event._tag)
-
-  if (registered === undefined) return Option.none()
-
-  return Option.map(Schema.decodeUnknownOption(Schema.toCodecJson(registered.schema))(event), (decoded) => ({
-    ...toEntry(entry),
-    event: decoded
-  }))
+  return Option.map(decodeEvent(app, event), (decoded) => ({ ...toEntry(entry), event: decoded }))
 }
 
 /** @internal */
@@ -73,28 +93,8 @@ export const decodeEntries = (
 /** @internal */
 export type DecodedEntries = ReturnType<typeof decodeEntries>
 
-const decodeStored = Schema.decodeUnknownOption(AssistantEvent.StoredAppEvent)
-
 const toEntry = (entry: AssistantEvent.AnyEntry) => ({
   chatId: entry.chatId,
   seq: entry.seq,
   at: entry.at
 })
-
-/** @internal */
-export const read = (app: AppEvents, event: { readonly _tag: string }): string | undefined => {
-  const registered = app.byTag.get(event._tag)
-
-  if (registered?.render === undefined) return undefined
-
-  if (registered.render !== "json") return registered.render(event)
-
-  const stored = Schema.encodeUnknownOption(Schema.toCodecJson(registered.schema))(event).pipe(
-    Option.flatMap(decodeStored)
-  )
-
-  return Option.match(stored, {
-    onNone: () => undefined,
-    onSome: ({ _tag, ...fields }) => `<${_tag}>\n${toJsonText(fields)}\n</${_tag}>`
-  })
-}