effect-assistant 0.1.0 → 0.3.0

package/src/internal/loop.ts

@@ -14,20 +14,14 @@ import * as Predicate from "effect/Predicate"
 import * as Schema from "effect/Schema"
 import * as Stream from "effect/Stream"
 import * as AssistantEvent from "../AssistantEvent.ts"
-import * as DecisionId from "../DecisionId.ts"
 import type * as Instructions from "../Instructions.ts"
-import * as Decisions from "./decisions.ts"
 import * as History from "./history.ts"
 import * as Telemetry from "./telemetry.ts"
 import * as Toolkits from "./toolkit.ts"
 import { isTurnEnding } from "./tools.ts"
 
 /** @internal */
-export type Event =
-  | AssistantEvent.ModelOutput
-  | AssistantEvent.ToolStarted
-  | AssistantEvent.ToolResult
-  | AssistantEvent.DecisionRequested
+export type Event = AssistantEvent.ModelOutput | AssistantEvent.ToolStarted | AssistantEvent.ToolResult
 
 // 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.
@@ -79,10 +73,7 @@ export interface StepResult {
 
 // The loop runs the calls itself, after storing each as started, so the model call runs none.
 const requestToolkit = (definitions: ReadonlyArray<Tool.Any>): Toolkit.WithHandler<Record<string, Tool.Any>> => ({
-  // The loop decides which calls wait for the user's decision; the model call would ask for approvals of its own.
-  tools: Object.fromEntries(
-    definitions.map((tool) => [tool.name, tool.needsApproval === undefined ? tool : tool.setNeedsApproval(false)])
-  ),
+  tools: Object.fromEntries(definitions.map((tool) => [tool.name, tool])),
   handle: () => Effect.succeed(Stream.empty)
 })
 
@@ -120,73 +111,28 @@ const runCall = Effect.fnUntraced(function* <R>(tools: Toolkits.Tools<R>, call:
   return AssistantEvent.ToolResult.make({ callId: call.id, tool: call.name, ...result })
 })
 
-interface Pending {
-  readonly call: AssistantEvent.ToolCallPart
-  readonly approved: boolean
-}
-
-// Only a turn parks: a specialist's call fails instead.
-const park = Effect.fnUntraced(
-  function* (call: AssistantEvent.ToolCallPart) {
-    if (Option.isNone(yield* Decisions.TurnDecisions)) {
-      return AssistantEvent.ToolResult.make({
-        callId: call.id,
-        tool: call.name,
-        ...Toolkits.failed(
-          `${call.name} needs the user's decision, and only the assistant can ask them. Don't run it: say in your answer what needs deciding, with the details.`,
-          "NeedsDecision"
-        )
-      })
-    }
-
-    return AssistantEvent.DecisionRequested.make({
-      id: DecisionId.fromCallId(call.id),
-      origin: AssistantEvent.CallOrigin.make({ callId: call.id, tool: call.name, params: call.params })
-    })
-  },
-  (effect, call) => effect.pipe(Telemetry.toolSpan(call))
-)
-
-// Every `ToolStarted` is stored before any call runs. `then` is told whether the model has to read the results: one
-// failed, or waits for the user's decision.
+// 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.
 const runCalls = <R, S, E, R2>(
   tools: Toolkits.Tools<R>,
-  pending: ReadonlyArray<Pending>,
-  history: ReadonlyArray<Prompt.Message>,
-  then: (reread: boolean) => Stream.Stream<Step<never, S>, E, R2>
+  calls: ReadonlyArray<AssistantEvent.ToolCallPart>,
+  then: (failed: boolean) => Stream.Stream<Step<never, S>, E, R2>
 ): Stream.Stream<Step<Event, S>, E, R | R2> =>
-  Stream.unwrap(
-    Effect.gen(function* () {
-      const parks = yield* Effect.forEach(pending, ({ call, approved }) =>
-        approved ? Effect.succeed(false) : Toolkits.needsDecisionOf(tools, call, history)
-      )
-
-      const started = pending.flatMap(({ call }, i) =>
-        parks[i] ? [] : [value(AssistantEvent.ToolStarted.make({ callId: call.id, tool: call.name }))]
-      )
-
-      const results = Effect.forEach(pending, ({ call }, i) => (parks[i] ? park(call) : runCall(tools, call)), {
-        concurrency: "unbounded"
-      })
-
-      const reread = (done: ReadonlyArray<Event>) =>
-        done.some((event) => Predicate.isTagged(event, "DecisionRequested") || isFailure(event))
-
-      return Stream.fromIterable(started).pipe(
-        Stream.concat(
-          Stream.unwrap(
-            Effect.gen(function* () {
-              const done = yield* results
-
-              return Stream.fromIterable(done.map(value)).pipe(Stream.concat(then(reread(done))))
-            })
-          )
-        )
+  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))))
+        })
       )
-    })
+    )
   )
 
-const isFailure = (event: Event) => Predicate.isTagged(event, "ToolResult") && event.outcome === "failure"
+const isFailure = (result: AssistantEvent.ToolResult) => result.outcome === "failure"
 
 /** @internal */
 export type Step<A, S> = Data.TaggedEnum<{
@@ -246,6 +192,9 @@ 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* () {
@@ -253,23 +202,9 @@ export const step = <R, S, E2 = never, R2 = never>(
       // 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)
 
-      // Calls the user approved: they run as the model made them, before the model goes on. Not in a loop without them.
-      const decisions = yield* Decisions.TurnDecisions
-
-      const approved = Option.isNone(decisions)
-        ? []
-        : (yield* decisions.value.approved).filter((call) =>
-            toolkit.definitions.some((tool) => tool.name === call.name)
-          )
-
-      if (cutOff.length > 0 || approved.length > 0) {
-        const pending = [
-          ...cutOff.map((call) => ({ call, approved: false })),
-          ...approved.map((call) => ({ call, approved: true }))
-        ]
-
-        return runCalls(toolkit, pending, history, () =>
-          after({ output: undefined, done: false, historyLength: history.length + pending.length })
+      if (cutOff.length > 0) {
+        return runCalls(toolkit, cutOff, () =>
+          after({ output: undefined, done: false, historyLength: history.length + cutOff.length })
         )
       }
 
@@ -295,20 +230,15 @@ 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. Nor
-      // does a parked one: the model asks the user for the decision it waits for.
+      // A failed call doesn't end the turn: a message that failed never reached the user, so the model reads why.
       return Stream.make(value(output)).pipe(
         Stream.concat(
-          runCalls(
-            toolkit,
-            calls.map((call) => ({ call, approved: false })),
-            history,
-            (reread) =>
-              after({
-                output,
-                done: calls.length === 0 || (!reread && calls.some(isTurnEnding)),
-                historyLength
-              })
+          runCalls(toolkit, calls, (failed) =>
+            after({
+              output,
+              done: calls.length === 0 || (!failed && calls.some(isTurnEnding)),
+              historyLength
+            })
           )
         )
       )

package/src/internal/skills.ts

@@ -8,6 +8,17 @@ import type { Skill } from "../Skill.ts"
 import * as ToolFailure from "../ToolFailure.ts"
 import * as Toolkits from "./toolkit.ts"
 
+// A skill whose tools the loop doesn't have would send the model after calls it can't make.
+/** @internal */
+export const available = <R>(
+  skills: ReadonlyArray<Skill<R>>,
+  definitions: ReadonlyArray<Tool.Any>
+): ReadonlyArray<Skill<R>> => {
+  const names = new Set(definitions.map((tool) => tool.name))
+
+  return skills.filter((skill) => (skill.tools ?? []).every((tool) => names.has(tool.name)))
+}
+
 /** @internal */
 export const toTools = <R>(skills: ReadonlyArray<Skill<R>>): Toolkits.Tools<R> => {
   if (skills.length === 0) return Toolkits.empty

package/src/internal/specialists.ts

@@ -26,7 +26,6 @@ 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 * as Decisions from "./decisions.ts"
 import { toolMessage, userText } from "./history.ts"
 import { mapText } from "./instructions.ts"
 import * as Telemetry from "./telemetry.ts"
@@ -85,21 +84,21 @@ export const runBrief = Effect.fnUntraced(
       brief: options.brief,
       history: current,
       loop: (loop) => {
-        const skills = loop.skills ?? []
+        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), Toolkits.fromToolkitOrEmpty(loop.toolkit)),
+          toolkit: Toolkits.merge(Skills.toTools(skills), own),
           history: current,
           maxSteps: loop.maxSteps ?? 8
         })
       }
     }
 
-    // A run lives in memory, so there's nothing to run again after a crash: `ToolStarted` isn't kept. A run parks no
-    // call (it has no user to ask), so there's no `DecisionRequested` either.
+    // 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") || Predicate.isTagged(event, "DecisionRequested")) return
+      if (Predicate.isTagged(event, "ToolStarted")) return
 
       if (Predicate.isTagged(event, "ToolResult")) return yield* add([toolMessage(event)])
 
@@ -272,9 +271,7 @@ export const makeRunner = Effect.fnUntraced(function* (options: {
       chatId: chat.chatId
     }).pipe(
       Effect.provideContext(Context.merge(options.model, services)),
-      // Spawned from a turn, a run would inherit the turn's decisions: it can't park a call or run an approved one.
-      Effect.provideService(Decisions.TurnDecisions, Option.none()),
-      // Nor its own tools: a run can't message the user.
+      // Spawned from a turn, a run would inherit the turn's own tools: a run can't message the user.
       Effect.provideService(Loop.TurnTools, Option.none()),
       Effect.matchCause({
         onSuccess: (answer): Outcome => ({ status: "answered", report: answer }),

package/src/internal/toolkit.ts

@@ -1,11 +1,9 @@
 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 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"
@@ -25,17 +23,13 @@ export interface CallResult {
 export interface Tools<out R = never> {
   readonly definitions: ReadonlyArray<Tool.Any>
   readonly run: (call: AssistantEvent.ToolCallPart) => Effect.Effect<CallResult, never, R>
-  // Unset: no call waits for the user's decision.
-  readonly needsDecision?:
-    | ((call: AssistantEvent.ToolCallPart, history: ReadonlyArray<Prompt.Message>) => Effect.Effect<boolean, never, R>)
-    | undefined
 }
 
 /** @internal */
-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 decide on a call.
-  | T[keyof T]["parametersSchema"]["DecodingServices"]
+export type ToolServices<T extends Record<string, Tool.Any>> = Exclude<
+  Tool.HandlerServices<T[keyof T]>,
+  AssistantToolCall
+>
 
 const encodeFailure = Schema.encodeSync(ToolFailure.ToolFailure)
 
@@ -66,36 +60,15 @@ const hasTool = <T extends Record<string, Tool.Any>>(
   name: PropertyKey
 ): name is keyof T => Object.hasOwn(toolkit.tools, name)
 
-// 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
-
-const decodeParams = (tool: Tool.Any, params: Schema.Json) => Schema.decodeUnknownEffect(tool.parametersSchema)(params)
-
-// Params that don't fit the tool don't park: the call runs, and fails with why.
+// 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 needsDecision = 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)
-
-  if (tool === undefined) return false
+export const needingApproval = (definitions: ReadonlyArray<Tool.Any>): ReadonlyArray<string> =>
+  definitions.flatMap((tool) => (tool.needsApproval === undefined || tool.needsApproval === false ? [] : [tool.name]))
 
-  const needs = tool.needsApproval
-
-  if (needs === undefined || Predicate.isBoolean(needs)) return needs === true
-
-  return yield* Effect.gen(function* () {
-    const decided = needs(yield* decodeParams(tool, call.params), {
-      toolCallId: call.id,
-      messages: history
-    })
-
-    return Effect.isEffect(decided) ? yield* decided : decided
-  }).pipe(Effect.orElseSucceed(() => false))
-})
+/** @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.`
 
 // 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.
@@ -144,8 +117,7 @@ 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),
-  needsDecision: (call, history) => needsDecision(toolkit, call, history)
+  run: (call) => runNative(toolkit, call)
 })
 
 /** @internal */
@@ -155,8 +127,7 @@ 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)
-  }),
-  needsDecision: (call, history) => needsDecision(toolkit, call, history)
+  })
 })
 
 // The handlers use services of the loop they run in, so they're made for each call, with its context.
@@ -171,8 +142,7 @@ export const withContext = <T extends Record<string, Tool.Any>, R>(
     const resolved = yield* Effect.provideContext(toolkit, yield* toolkit.toHandlers(handlers(context)))
 
     return yield* runNative(resolved, call)
-  }),
-  needsDecision: (call, history) => needsDecision(toolkit, call, history)
+  })
 })
 
 /** @internal */
@@ -192,26 +162,15 @@ 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)),
-    needsDecision: (call, history) =>
-      inSelf(call) ? needsDecisionOf(self, call, history) : needsDecisionOf(that, call, history)
+    run: (call) => (inSelf(call) ? self.run(call) : that.run(call))
   }
 }
 
-/** @internal */
-export const needsDecisionOf = <R>(
-  tools: Tools<R>,
-  call: AssistantEvent.ToolCallPart,
-  history: ReadonlyArray<Prompt.Message>
-): Effect.Effect<boolean, never, R> =>
-  tools.needsDecision === undefined ? Effect.succeed(false) : tools.needsDecision(call, history)
-
 // 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),
-  needsDecision: (call, history) => Effect.provideContext(needsDecisionOf(tools, call, history), context)
+  run: (call) => Effect.provideContext(tools.run(call), context)
 })
 
 /** @internal */
@@ -225,7 +184,5 @@ 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"))),
-  needsDecision: (call, history) =>
-    names.includes(call.name) ? needsDecisionOf(tools, call, history) : Effect.succeed(false)
+  run: (call) => (names.includes(call.name) ? tools.run(call) : Effect.succeed(failed(message, "NotNow")))
 })

package/src/internal/tools.ts

@@ -6,9 +6,8 @@ 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 BlockKit from "../BlockKit.ts"
+import type * as BlockKit from "../BlockKit.ts"
 import { CurrentChat } from "../CurrentChat.ts"
-import * as Decision from "../Decision.ts"
 import * as ToolFailure from "../ToolFailure.ts"
 import * as Toolkits from "./toolkit.ts"
 import * as Uuid from "./uuid.ts"
@@ -77,45 +76,6 @@ const plainTools = Effect.gen(function* () {
   return yield* Effect.provideContext(PlainTools, yield* plainHandlers)
 })
 
-const decodeDecisionProps = Schema.decodeUnknownOption(Decision.Props)
-
-const checkDecisions = Effect.fnUntraced(function* (ids: ReadonlyArray<string>) {
-  const states = Decision.fromEntries(yield* CurrentChat.use((chat) => chat.entries))
-  const notWaiting = ids.filter((id) => states.get(id)?.outcome !== undefined || !states.has(id))
-
-  if (notWaiting.length > 0) {
-    return yield* ToolFailure.fail(
-      `Not waiting for the user's decision: ${notWaiting.join(", ")}. Use the ids of decisions that wait for one.`,
-      { reason: "NotWaitingForDecision" }
-    )
-  }
-})
-
-// A decision block closes when the user decides on it, not because the model says so: the order it asks about would
-// otherwise never be approved.
-const checkCloses = Effect.fnUntraced(function* (ids: ReadonlyArray<string>) {
-  const entries = yield* CurrentChat.use((chat) => chat.entries)
-  const states = BlockKit.fromEntries(entries)
-
-  const waiting = ids.filter((id) =>
-    entries.some(
-      ({ event }) =>
-        AssistantEvent.isLibraryEvent(event) &&
-        Predicate.isTagged(event, "AssistantMessage") &&
-        event.id === id &&
-        event.block?.kind === Decision.kind &&
-        states.get(id)?.open === true
-    )
-  )
-
-  if (waiting.length > 0) {
-    return yield* ToolFailure.fail(
-      `${waiting.join(", ")} asks for a decision that still waits for the user: only their answer in the block closes it. Send the message again without ${waiting.length === 1 ? "that id" : "those ids"} in closes.`,
-      { reason: "DecisionWaiting" }
-    )
-  }
-})
-
 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)
@@ -137,7 +97,7 @@ ${catalog}`,
       ),
       closes: Schema.optional(Schema.Array(Schema.String)).annotate({
         description:
-          "Ids of your earlier messages whose block the user just answered by typing instead of using it. Those blocks close. Leave it out otherwise: a block stays open when the user talks about something else. A decision block never closes this way: only the user's answer in it decides."
+          "Ids of your earlier messages whose block the user just answered by typing instead of using it. Those blocks close. Leave it out otherwise: a block stays open when the user talks about something else."
       })
     }),
     success: Schema.String,
@@ -160,8 +120,6 @@ ${catalog}`,
       const id = yield* messageId
       const closed = closes === undefined || closes.length === 0 ? {} : { closes }
 
-      if (closes !== undefined && closes.length > 0) yield* checkCloses(closes)
-
       if (block === undefined) {
         yield* append(AssistantEvent.AssistantMessage.make({ id, text, ...closed }))
 
@@ -174,15 +132,6 @@ ${catalog}`,
         return yield* ToolFailure.fail(`Those props don't fit a ${block.kind} block.`)
       }
 
-      if (block.kind === Decision.kind) {
-        yield* checkDecisions(
-          Option.match(decodeDecisionProps(block.props), {
-            onNone: () => [],
-            onSome: (decoded) => decoded.decisionIds
-          })
-        )
-      }
-
       yield* append(
         AssistantEvent.AssistantMessage.make({
           id,