effect-assistant 0.3.0 → 0.4.0

package/src/AssistantEvent.ts

@@ -140,13 +140,30 @@ export class SpecialistFinished extends Schema.TaggedClass<SpecialistFinished>()
   error: Schema.optional(Schema.String)
 }) {}
 
+/**
+ * Represents the user's decision on a tool call that waits for their approval: `"approved"`, so
+ * the call runs, or `"rejected"`, with an optional short reason the model reads.
+ *
+ * Its id is fixed per call (see `ToolApproval.approve`), so a decision is stored once. A decision on
+ * a call that isn't waiting any more (decided, or expired) isn't stored.
+ *
+ * @category schemas
+ * @since 0.4.0
+ */
+export class ApprovalDecision extends Schema.TaggedClass<ApprovalDecision>()("ApprovalDecision", {
+  id: InputId,
+  callId: Schema.String,
+  decision: Schema.Literals(["approved", "rejected"]),
+  reason: Schema.optional(Schema.String.check(Schema.isMaxLength(500)))
+}) {}
+
 /**
  * Schema for every input `Assistant.submit` accepts.
  *
  * @category schemas
  * @since 0.1.0
  */
-export const Input = Schema.Union([UserMessage, BlockAnswer, SpecialistFinished])
+export const Input = Schema.Union([UserMessage, BlockAnswer, SpecialistFinished, ApprovalDecision])
 
 /**
  * Represents an input to an assistant.
@@ -157,7 +174,8 @@ export const Input = Schema.Union([UserMessage, BlockAnswer, SpecialistFinished]
 export type Input = typeof Input.Type
 
 /**
- * Schema for the inputs from the chat's user, which are messages and block answers.
+ * Schema for the inputs from the chat's user, which are messages, block answers, and decisions on
+ * tool calls that wait for their approval.
  *
  * A turn owes each one a reply. It is also what a chat client usually may submit, since the app's
  * events come from the server.
@@ -165,7 +183,7 @@ export type Input = typeof Input.Type
  * @category schemas
  * @since 0.1.0
  */
-export const UserInput = Schema.Union([UserMessage, BlockAnswer])
+export const UserInput = Schema.Union([UserMessage, BlockAnswer, ApprovalDecision])
 
 /**
  * Represents an input from the chat's user.
@@ -400,6 +418,36 @@ export class BlocksClosed extends Schema.TaggedClass<BlocksClosed>()("BlocksClos
   messageIds: Schema.Array(Schema.String)
 }) {}
 
+/**
+ * Represents a tool call that waits for the user's approval instead of running: its tool needs
+ * approval (Effect's `needsApproval`).
+ *
+ * **Details**
+ *
+ * It holds the call's id, the tool, and its params, in JSON, as the model wrote them. The model
+ * reads it as the call's result, saying it waits for the user; the user's
+ * {@link ApprovalDecision} decides it, and an approved call runs then, with the same id.
+ *
+ * @category schemas
+ * @since 0.4.0
+ */
+export class ApprovalRequested extends Schema.TaggedClass<ApprovalRequested>()("ApprovalRequested", {
+  callId: Schema.String,
+  tool: Schema.String,
+  params: Schema.Json
+}) {}
+
+/**
+ * Represents tool calls that waited for the user's approval and won't run: the user moved on, like
+ * the ones `ToolApproval.closeStale` expires. The model reads that they weren't approved.
+ *
+ * @category schemas
+ * @since 0.4.0
+ */
+export class ApprovalsExpired extends Schema.TaggedClass<ApprovalsExpired>()("ApprovalsExpired", {
+  callIds: Schema.Array(Schema.String)
+}) {}
+
 /**
  * Schema for every event the library defines.
  *
@@ -419,6 +467,9 @@ export const AssistantEvent = Schema.Union([
   SpecialistStarted,
   SpecialistFinished,
   BlocksClosed,
+  ApprovalRequested,
+  ApprovalDecision,
+  ApprovalsExpired,
   ChatDeleted
 ])
 
@@ -554,7 +605,7 @@ export type Entry = typeof Entry.Type
 
 /**
  * Returns whether an event is one of the library's inputs, which are a user message, a block
- * answer, or a finished specialist run.
+ * answer, a finished specialist run, or a decision on a tool call waiting for approval.
  *
  * The application's events that came in through the assistant's `submit` are inputs too (see
  * {@link isAppInput}).
@@ -565,7 +616,8 @@ export type Entry = typeof Entry.Type
 export const isInput = (event: { readonly _tag: string }): event is Input =>
   Predicate.isTagged(event, "UserMessage") ||
   Predicate.isTagged(event, "BlockAnswer") ||
-  Predicate.isTagged(event, "SpecialistFinished")
+  Predicate.isTagged(event, "SpecialistFinished") ||
+  Predicate.isTagged(event, "ApprovalDecision")
 
 /**
  * Returns whether an input starts a turn, which every input does except a run the assistant
@@ -584,7 +636,9 @@ export const isWaking = (input: Input): boolean =>
  * @since 0.1.0
  */
 export const isUserInput = (input: Input): input is UserInput =>
-  Predicate.isTagged(input, "UserMessage") || Predicate.isTagged(input, "BlockAnswer")
+  Predicate.isTagged(input, "UserMessage") ||
+  Predicate.isTagged(input, "BlockAnswer") ||
+  Predicate.isTagged(input, "ApprovalDecision")
 
 /**
  * Returns whether an event ends a turn, and so says how far the assistant has read.

package/src/AssistantLoop.ts

@@ -161,8 +161,10 @@ const toolsOf = <T extends Record<string, Tool.Any>>(toolkit: Toolkit.Toolkit<T>
  * the step's result and decides what comes next, with `AssistantLoop.next(state)` or
  * `AssistantLoop.stop()`.
  *
- * A tool with Effect's `needsApproval` set fails the loop before the model is called: the
- * library doesn't run calls that wait for approval (see the guide on involving the user).
+ * In a turn's loop, a call to a tool with Effect's `needsApproval` doesn't run: the step emits an
+ * `ApprovalRequested` for it, and ends the turn, which waits for the user (see `ToolApproval`). A
+ * call the user approved runs at the start of the next step, before the model is called. A
+ * specialist's run can't wait for the user: such a call fails, and the run reads why.
  *
  * @category constructors
  * @since 0.1.0

package/src/Compaction.ts

@@ -18,6 +18,8 @@ import * as AssistantActivity from "./AssistantActivity.ts"
 import * as AssistantEvent from "./AssistantEvent.ts"
 import * as BlockKit from "./BlockKit.ts"
 import { userText } from "./internal/history.ts"
+import { toJsonText } from "./internal/schema.ts"
+import * as ToolApproval from "./ToolApproval.ts"
 
 /**
  * Represents the fields a summary event must have: its text and the last `seq` it covers.
@@ -54,7 +56,7 @@ export const inputTokens = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): nu
 
 /**
  * Returns the items that were open at `throughSeq` and are still open: blocks the user hasn't
- * answered, and specialists that are working. The result is text for
+ * answered, specialists that are working, and tool calls waiting for the user's approval. The result is text for
  * the model, or `None` when nothing is open.
  *
  * @category utils
@@ -100,9 +102,24 @@ export const openItems = (
       : []
   )
 
+  const approvals = [...ToolApproval.fromEntries(entries).values()].flatMap((approval) =>
+    approval.status === "pending" &&
+    opened(
+      seqOf(
+        (event) =>
+          AssistantEvent.isLibraryEvent(event) &&
+          Predicate.isTagged(event, "ApprovalRequested") &&
+          event.callId === approval.request.callId
+      )
+    )
+      ? [`- your call to ${approval.request.tool} (${approval.request.callId}): ${toJsonText(approval.request.params)}`]
+      : []
+  )
+
   const sections = [
     blocks.length > 0 ? `Blocks the user hasn't answered:\n${blocks.join("\n")}` : "",
-    specialists.length > 0 ? `Specialists still working:\n${specialists.join("\n")}` : ""
+    specialists.length > 0 ? `Specialists still working:\n${specialists.join("\n")}` : "",
+    approvals.length > 0 ? `Calls waiting for the user's approval:\n${approvals.join("\n")}` : ""
   ].filter((section) => section.length > 0)
 
   return sections.length === 0 ? Option.none() : Option.some(sections.join("\n\n"))

package/src/Skill.ts

@@ -1,14 +1,19 @@
 /**
  * Defines skills, which are playbooks with step-by-step instructions for a kind of task.
  *
- * A loop lists its skills as a catalog in the prompt, with each skill's name and description
- * ({@link withCatalog}). The model loads a skill's instructions with the `load_skill` tool when a
- * task matches.
+ * A list of skills becomes a toolkit with one tool, `load_skill` ({@link toolkit}). Its
+ * description is the catalog, each skill's name and when to use it, and the model calls it to read
+ * a skill's instructions when a task matches. Merge it into a loop's toolkit like any other.
  *
  * @since 0.1.0
  */
-import type * as Tool from "effect/ai/Tool"
-import type * as Instructions from "./Instructions.ts"
+import * as Tool from "effect/ai/Tool"
+import * as AiToolkit from "effect/ai/Toolkit"
+import * as Effect from "effect/Effect"
+import type * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+import * as Instructions from "./Instructions.ts"
+import * as ToolFailure from "./ToolFailure.ts"
 
 /**
  * Represents a skill.
@@ -24,11 +29,6 @@ export interface Skill<R = never> {
   readonly description: string
   /** Text, or an Effect resolved each time the skill is loaded. */
   readonly instructions: Instructions.Instructions<R>
-  /**
-   * The tools its instructions use. A loop offers the skill only when its toolkit has every one of
-   * them, matched by name. Unset, a loop always offers it.
-   */
-  readonly tools?: ReadonlyArray<Tool.Any> | undefined
 }
 
 /**
@@ -38,12 +38,7 @@ export interface Skill<R = never> {
  *
  * Write the description as a trigger ("Use when…"), since it's all the model sees until it loads
  * the skill. The instructions are text, or an Effect that is resolved each time the skill is
- * loaded.
- *
- * `tools` lists the tools the instructions use. A loop whose toolkit lacks any of them, matched by
- * name, leaves the skill out of its catalog and of `load_skill`, so a loop that gets its tools per
- * user (by role, say) never offers a playbook it can't follow. A tool that only `ToolDiscovery`
- * finds isn't in the toolkit, so it doesn't count. Without `tools`, every loop offers the skill.
+ * loaded. Offer skills to a loop with {@link toolkit}.
  *
  * **Example** (Defining a playbook for ordering campaigns)
  *
@@ -56,30 +51,6 @@ export interface Skill<R = never> {
  * 2. You need who it should reach and a budget. Ask for what's missing, one question at a time.
  * 3. When you have both, call start_campaign.`
  * })
- *
- * const MyAssistantLive = MyAssistant.toLayer((turn) =>
- *   turn.loop({ instructions, skills: [orderingCampaigns] })
- * )
- * ```
- *
- * **Example** (Offering a skill only with the tools it uses)
- *
- * ```ts
- * import { Skill } from "effect-assistant"
- * import * as Tool from "effect/ai/Tool"
- * import * as Schema from "effect/Schema"
- *
- * const StartCampaign = Tool.make("start_campaign", {
- *   parameters: Schema.Struct({ campaignId: Schema.String, budget: Schema.Finite }),
- *   success: Schema.String
- * })
- *
- * // Left out of a loop whose toolkit has no start_campaign, like a viewer's.
- * const orderingCampaigns = Skill.make("Ordering a campaign", {
- *   description: "Use when the user wants to order or start a campaign.",
- *   instructions: "When you know who it should reach and the budget, call start_campaign.",
- *   tools: [StartCampaign]
- * })
  * ```
  *
  * @category constructors
@@ -92,10 +63,8 @@ export const make = <R = never>(
     readonly description: string
     /** Text, or an Effect resolved each time the skill is loaded. */
     readonly instructions: Instructions.Instructions<R>
-    /** The tools its instructions use: a loop whose toolkit lacks one leaves the skill out. */
-    readonly tools?: ReadonlyArray<Tool.Any> | undefined
   }
-): Skill<R> => ({ name, description: options.description, instructions: options.instructions, tools: options.tools })
+): Skill<R> => ({ name, description: options.description, instructions: options.instructions })
 
 /**
  * Extracts the services that skills need when they're loaded.
@@ -105,20 +74,128 @@ export const make = <R = never>(
  */
 export type Services<S> = S extends Skill<infer R> ? R : never
 
+const loadSkill = (description: string) =>
+  Tool.make("load_skill", {
+    description,
+    parameters: Schema.Struct({ name: Schema.String }),
+    success: Schema.String,
+    failure: ToolFailure.ToolFailure
+  })
+
 /**
- * Returns the prompt with the skills' catalog appended, or the prompt unchanged when there are no
- * skills.
+ * Represents the `load_skill` tool, which reads a skill's instructions by name.
  *
- * @category utils
- * @since 0.1.0
+ * @category models
+ * @since 0.4.0
+ */
+export type LoadSkill = ReturnType<typeof loadSkill>
+
+/**
+ * Represents a list of skills as a toolkit: the `load_skill` tool, and the layer with its handler.
+ *
+ * `R` is the services the skills' instructions need, which the layer requires.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface Toolkit<R = never> extends AiToolkit.Toolkit<{ readonly load_skill: LoadSkill }> {
+  /** The handler of `load_skill`, which resolves the instructions of these skills. */
+  readonly layer: Layer.Layer<Tool.Handler<"load_skill">, never, R>
+}
+
+const catalog = (skills: ReadonlyArray<Skill<unknown>>): string =>
+  [
+    "Load a skill, a playbook for a kind of task, by name, and follow it for the rest of the task. When one matches what you're doing, load it in the same step as your first lookups, not in a step of its own.",
+    "",
+    "Skills:",
+    ...skills.map((skill) => `- ${skill.name}: ${skill.description}`)
+  ].join("\n")
+
+function toolkitOf<const Skills extends ReadonlyArray<Skill<unknown>>>(
+  skills: Skills
+): Toolkit<Services<Skills[number]>>
+// The overload states what the layer requires: the services of these skills' instructions.
+function toolkitOf(skills: ReadonlyArray<Skill<unknown>>): Toolkit<unknown> {
+  const byName = new Map(skills.map((skill) => [skill.name, skill]))
+  const tools = AiToolkit.make(loadSkill(catalog(skills)))
+
+  const layer = tools.toLayer(
+    Effect.gen(function* () {
+      const context = yield* Effect.context<unknown>()
+
+      return {
+        load_skill: Effect.fnUntraced(function* ({ name }) {
+          const skill = byName.get(name)
+
+          if (skill === undefined) {
+            return yield* ToolFailure.fail(
+              `No skill named ${name}. The skills are: ${skills.map((known) => known.name).join(", ")}.`
+            )
+          }
+
+          const resolved = yield* Instructions.resolve(skill.instructions).pipe(Effect.provideContext(context))
+
+          return resolved.text
+        })
+      }
+    })
+  )
+
+  return Object.assign(tools, { layer })
+}
+
+/**
+ * Creates a toolkit from a list of skills: the `load_skill` tool, whose description lists each
+ * skill's name and when to use it, and its handler's `layer`.
+ *
+ * **Details**
+ *
+ * Merge the toolkit into a loop's own with `Toolkit.merge`, and provide its `layer`, which requires
+ * the services the skills' instructions need. The model loads a skill by name; a name that isn't
+ * in the list is a failure the model reads, with the names there are.
+ *
+ * The handler resolves only the skills of its own list. To offer each user the skills they may
+ * use, build the toolkit in the turn from that user's list, and provide its layer to the loop's
+ * stream (`Stream.provide(skills.layer)`): building one does no work.
+ *
+ * **Example** (Giving an assistant its playbooks)
+ *
+ * ```ts
+ * import { Skill } from "effect-assistant"
+ * import * as Layer from "effect/Layer"
+ * import * as Toolkit from "effect/ai/Toolkit"
+ *
+ * const AssistantSkills = Skill.toolkit([orderingCampaigns, sharingAssets])
+ *
+ * const MyAssistantLive = MyAssistant.toLayer((turn) =>
+ *   turn.loop({ instructions, toolkit: Toolkit.merge(MyTools, AssistantSkills) })
+ * ).pipe(Layer.provide([MyToolsLive, AssistantSkills.layer]))
+ * ```
+ *
+ * **Example** (Offering each user the skills their role allows)
+ *
+ * ```ts
+ * import { Skill } from "effect-assistant"
+ * import * as Effect from "effect/Effect"
+ * import * as Stream from "effect/Stream"
+ * import * as Toolkit from "effect/ai/Toolkit"
+ *
+ * const MyAssistantLive = MyAssistant.toLayer((turn) =>
+ *   Stream.unwrap(
+ *     Effect.map(roleOf(turn.chatId), (role) => {
+ *       const skills = Skill.toolkit(allSkills.filter((skill) => allowed(role, skill)))
+ *
+ *       return turn
+ *         .loop({ instructions, toolkit: Toolkit.merge(MyTools, skills) })
+ *         .pipe(Stream.provide(skills.layer))
+ *     })
+ *   )
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.4.0
  */
-export const withCatalog = <R>(prompt: string, skills: ReadonlyArray<Skill<R>>): string =>
-  skills.length === 0
-    ? prompt
-    : [
-        prompt,
-        "",
-        "## Skills",
-        "Playbooks for common tasks. When one matches what you're doing, load it with load_skill in the same step as your first lookups, and follow it.",
-        ...skills.map((skill) => `- ${skill.name}: ${skill.description}`)
-      ].join("\n")
+export const toolkit: <const Skills extends ReadonlyArray<Skill<unknown>>>(
+  skills: Skills
+) => Toolkit<Services<Skills[number]>> = toolkitOf

package/src/Specialist.ts

@@ -23,7 +23,6 @@ import type { ChatId } from "./ChatId.ts"
 import type { CurrentChat } from "./CurrentChat.ts"
 import type * as Instructions from "./Instructions.ts"
 import type { RunId } from "./RunId.ts"
-import type { Skill } from "./Skill.ts"
 
 const TypeId = "~effect-assistant/Specialist"
 
@@ -123,15 +122,13 @@ export type RunServices = CurrentChat | Runner | LanguageModel.LanguageModel
  * @category models
  * @since 0.1.0
  */
-export interface LoopOptions<T extends Record<string, Tool.Any> = Record<never, never>, RS = never> {
+export interface LoopOptions<T extends Record<string, Tool.Any> = Record<never, never>> {
   readonly instructions: string | Instructions.Resolved
-  /** The loop's tools, as a native toolkit whose handlers come from the layer. */
-  readonly toolkit?: Toolkit.Toolkit<T> | undefined
   /**
-   * Playbooks, listed as a catalog in the prompt and loaded with `load_skill` when one matches. A
-   * skill made with `tools` is left out when the toolkit lacks one of them.
+   * The loop's tools, as a native toolkit whose handlers come from the layer. Merge in a
+   * `Skill.toolkit(...)` for playbooks.
    */
-  readonly skills?: ReadonlyArray<Skill<RS>> | undefined
+  readonly toolkit?: Toolkit.Toolkit<T> | undefined
   /** The model calls allowed per brief. Defaults to 8. */
   readonly maxSteps?: number | undefined
 }
@@ -152,13 +149,13 @@ export interface Run {
    * (follow-ups and steering). Read it before every model call, as the loop does.
    */
   readonly history: Effect.Effect<ReadonlyArray<Prompt.Message>>
-  /** Runs the agent loop over the run's history, with the given instructions, tools, and skills. */
-  readonly loop: <T extends Record<string, Tool.Any> = Record<never, never>, RS = never>(
-    options: LoopOptions<T, RS>
+  /** Runs the agent loop over the run's history, with the given instructions and tools. */
+  readonly loop: <T extends Record<string, Tool.Any> = Record<never, never>>(
+    options: LoopOptions<T>
   ) => Stream.Stream<
     AssistantLoop.Event,
     AiError.AiError,
-    LanguageModel.LanguageModel | AssistantLoop.ToolkitServices<T> | RS
+    LanguageModel.LanguageModel | AssistantLoop.ToolkitServices<T>
   >
 }