effect-assistant 0.0.0-stage → 0.2.0

package/src/internal/toolkit.ts

@@ -0,0 +1,188 @@
+import * as AiError from "effect/ai/AiError"
+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 Schema from "effect/Schema"
+import * as Stream from "effect/Stream"
+import type * as AssistantEvent from "../AssistantEvent.ts"
+import { AssistantToolCall } from "../AssistantToolCall.ts"
+import * as ToolFailure from "../ToolFailure.ts"
+import { toJson } from "./schema.ts"
+
+/** @internal */
+export interface CallResult {
+  readonly outcome: AssistantEvent.ToolOutcome
+  readonly result: Schema.Json
+  readonly reason?: string | undefined
+}
+
+// Apps give the loop native toolkits; these are what the loop makes of them, merged with its own.
+/** @internal */
+export interface Tools<out R = never> {
+  readonly definitions: ReadonlyArray<Tool.Any>
+  readonly run: (call: AssistantEvent.ToolCallPart) => Effect.Effect<CallResult, never, R>
+}
+
+/** @internal */
+export type ToolServices<T extends Record<string, Tool.Any>> = Exclude<
+  Tool.HandlerServices<T[keyof T]>,
+  AssistantToolCall
+>
+
+const encodeFailure = Schema.encodeSync(ToolFailure.ToolFailure)
+
+/** @internal */
+export const failed = (message: string, reason: string): CallResult => ({
+  outcome: "failure",
+  result: toJson(encodeFailure(new ToolFailure.ToolFailure({ message, reason }))),
+  reason
+})
+
+const decodeReason = Schema.decodeUnknownOption(Schema.Struct({ reason: Schema.String }))
+
+const decodeTag = Schema.decodeUnknownOption(Schema.Struct({ _tag: Schema.String }))
+
+const failure = (result: Schema.Json): CallResult => ({
+  outcome: "failure",
+  result,
+  reason: Option.getOrUndefined(
+    Option.orElse(
+      Option.map(decodeReason(result), ({ reason }) => reason),
+      () => Option.map(decodeTag(result), ({ _tag }) => _tag)
+    )
+  )
+})
+
+const hasTool = <T extends Record<string, Tool.Any>>(
+  toolkit: { readonly tools: T },
+  name: PropertyKey
+): name is keyof T => Object.hasOwn(toolkit.tools, name)
+
+// 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 needingApproval = (definitions: ReadonlyArray<Tool.Any>): ReadonlyArray<string> =>
+  definitions.flatMap((tool) => (tool.needsApproval === undefined || tool.needsApproval === false ? [] : [tool.name]))
+
+/** @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.
+const isParams = <T>(params: unknown): params is Tool.ParametersEncoded<T> => params !== undefined
+
+// Every failure is the call's result, for the model to read. With `failureMode: "return"` the toolkit encodes the
+// tool's own failure with its schema first.
+/** @internal */
+export const runNative = Effect.fnUntraced(function* <T extends Record<string, Tool.Any>>(
+  toolkit: Toolkit.WithHandler<T>,
+  call: AssistantEvent.ToolCallPart
+): Effect.fn.Return<CallResult, never, ToolServices<T>> {
+  const name: PropertyKey = call.name
+
+  if (!hasTool(toolkit, name)) return failed(`No tool named ${call.name}.`, "ToolNotFoundError")
+
+  const params: unknown = call.params
+
+  if (!isParams<T[keyof T]>(params)) {
+    return failed(`Invalid parameters for ${call.name}.`, "ToolParameterValidationError")
+  }
+
+  return yield* Effect.gen(function* () {
+    const results = yield* toolkit.handle<keyof T>(name, params, call.id)
+    const last = yield* Stream.runLast(Stream.filter(results, (result) => !result.preliminary))
+
+    return Option.match(last, {
+      onNone: () => failed(`${call.name} returned no result.`, "NoResult"),
+      onSome: (result): CallResult =>
+        result.isFailure
+          ? failure(toJson(result.encodedResult))
+          : { outcome: "success", result: toJson(result.encodedResult) }
+    })
+  }).pipe(
+    Effect.catch((error) =>
+      Effect.succeed(
+        AiError.isAiError(error) ? failed(error.reason.message, error.reason._tag) : failure(toJson(error))
+      )
+    ),
+    Effect.provideService(AssistantToolCall, { callId: call.id, tool: call.name })
+  )
+})
+
+/** @internal */
+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)
+})
+
+/** @internal */
+export const fromToolkit = <T extends Record<string, Tool.Any>>(
+  toolkit: Toolkit.Toolkit<T>
+): Tools<ToolServices<T> | Tool.HandlersFor<T>> => ({
+  definitions: Object.values(toolkit.tools),
+  run: Effect.fnUntraced(function* (call) {
+    return yield* runNative(yield* toolkit, call)
+  })
+})
+
+// The handlers use services of the loop they run in, so they're made for each call, with its context.
+/** @internal */
+export const withContext = <T extends Record<string, Tool.Any>, R>(
+  toolkit: Toolkit.Toolkit<T>,
+  handlers: (context: Context.Context<R>) => Toolkit.HandlersFrom<T>
+): Tools<R | ToolServices<T>> => ({
+  definitions: Object.values(toolkit.tools),
+  run: Effect.fnUntraced(function* (call) {
+    const context = yield* Effect.context<R>()
+    const resolved = yield* Effect.provideContext(toolkit, yield* toolkit.toHandlers(handlers(context)))
+
+    return yield* runNative(resolved, call)
+  })
+})
+
+/** @internal */
+export const fromToolkitOrEmpty = <T extends Record<string, Tool.Any>>(
+  toolkit: Toolkit.Toolkit<T> | undefined
+): Tools<ToolServices<T> | Tool.HandlersFor<T>> => (toolkit === undefined ? empty : fromToolkit(toolkit))
+
+/** @internal */
+export const empty: Tools = {
+  definitions: [],
+  run: (call) => Effect.succeed(failed(`No tool named ${call.name}.`, "ToolNotFoundError"))
+}
+
+/** @internal */
+export const merge = <A, B>(self: Tools<A>, that: Tools<B>): Tools<A | B> => {
+  const inSelf = (call: AssistantEvent.ToolCallPart) => self.definitions.some((tool) => tool.name === call.name)
+
+  return {
+    definitions: [...self.definitions, ...that.definitions],
+    run: (call) => (inSelf(call) ? self.run(call) : that.run(call))
+  }
+}
+
+// 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)
+})
+
+/** @internal */
+export const duplicateNames = (tools: Tools<unknown>): ReadonlyArray<string> => {
+  const names = tools.definitions.map((tool) => tool.name)
+
+  return names.filter((name, i) => names.indexOf(name) !== i)
+}
+
+// The same tools are offered, so the prompt doesn't change.
+/** @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")))
+})

package/src/internal/tools.ts

@@ -0,0 +1,159 @@
+import * as Tool from "effect/ai/Tool"
+import * as Toolkit from "effect/ai/Toolkit"
+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 AssistantEvent from "../AssistantEvent.ts"
+import { AssistantToolCall } from "../AssistantToolCall.ts"
+import type * as BlockKit from "../BlockKit.ts"
+import { CurrentChat } from "../CurrentChat.ts"
+import * as ToolFailure from "../ToolFailure.ts"
+import * as Toolkits from "./toolkit.ts"
+import * as Uuid from "./uuid.ts"
+
+/** @internal */
+export const waitToolName = "wait"
+
+/** @internal */
+export const sendUserMessageName = "send_user_message"
+
+const Wait = Tool.make(waitToolName, {
+  description:
+    "End your turn and wait for the next message or update, when you have nothing more to do right now and no message to send (otherwise set wait on send_user_message).",
+  success: Schema.String
+})
+
+const description =
+  "Send the user a chat message. It's the only way they see anything you write: text outside it is private to you."
+
+const WaitFlag = Schema.Boolean.annotate({
+  description:
+    "true when this is your last message for now: your turn ends with it, as with the wait tool. false when you keep working after it."
+})
+
+const endsWithMessage = Schema.decodeUnknownOption(Schema.Struct({ wait: Schema.Literal(true) }))
+
+/** @internal */
+export const isTurnEnding = (call: AssistantEvent.ToolCallPart): boolean =>
+  call.name === waitToolName || (call.name === sendUserMessageName && Option.isSome(endsWithMessage(call.params)))
+
+// From the call: a call cut off by a crash runs again with the same id, and finds its message already sent.
+const messageId = AssistantToolCall.useSync((call) => Uuid.fromKey(`message:${call.callId}`))
+
+const append = Effect.fnUntraced(function* (message: AssistantEvent.AssistantMessage) {
+  const chat = yield* CurrentChat
+  const entries = yield* chat.entries
+
+  const sent = entries.some(
+    ({ event }) =>
+      AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, "AssistantMessage") && event.id === message.id
+  )
+
+  if (!sent) yield* chat.append(message)
+})
+
+const PlainMessage = Tool.make(sendUserMessageName, {
+  description,
+  parameters: Schema.Struct({ text: Schema.String, wait: WaitFlag }),
+  success: Schema.String,
+  failure: ToolFailure.ToolFailure,
+  dependencies: [CurrentChat, AssistantToolCall]
+})
+
+const PlainTools = Toolkit.make(PlainMessage, Wait)
+
+const plainHandlers = PlainTools.toHandlers({
+  wait: () => Effect.succeed("waiting"),
+  send_user_message: Effect.fnUntraced(function* ({ text }) {
+    yield* append(AssistantEvent.AssistantMessage.make({ id: yield* messageId, text }))
+
+    return "sent"
+  })
+})
+
+const plainTools = Effect.gen(function* () {
+  return yield* Effect.provideContext(PlainTools, yield* plainHandlers)
+})
+
+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)
+
+  const BlockMessage = Tool.make(sendUserMessageName, {
+    description: `${description}
+You can add a block to show UI with the message, e.g. a few options to pick from or a yes/no, when that makes answering easier than typing. Plain text is fine too. Using it sends you an <answer>; the user may also just type their answer instead, and then you pass that message's id in closes.
+Blocks:
+${catalog}`,
+    // Props are checked against their kind's schema by the handler; the model sees every kind's in the parameters.
+    parameters: Schema.Struct({
+      text: Schema.String,
+      wait: WaitFlag,
+      block: Schema.optional(
+        Schema.Struct({
+          kind: Schema.Literals(kinds),
+          props: Schema.Union(kit.blocks.map((block) => block.props))
+        })
+      ),
+      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."
+      })
+    }),
+    success: Schema.String,
+    failure: ToolFailure.ToolFailure,
+    dependencies: [CurrentChat, AssistantToolCall]
+  })
+
+  const BlockTools = Toolkit.make(BlockMessage, Wait)
+
+  const handlers = yield* BlockTools.toHandlers({
+    wait: () => Effect.succeed("waiting"),
+    send_user_message: Effect.fnUntraced(function* ({ text, block, closes }) {
+      if (text.trim() === "") {
+        return yield* ToolFailure.fail(
+          "The message has no text: the user sees only what you send here, and a block alone is an empty bubble. Send it again with the words they should read (a short lead-in for the block).",
+          { reason: "EmptyMessage" }
+        )
+      }
+
+      const id = yield* messageId
+      const closed = closes === undefined || closes.length === 0 ? {} : { closes }
+
+      if (block === undefined) {
+        yield* append(AssistantEvent.AssistantMessage.make({ id, text, ...closed }))
+
+        return "sent"
+      }
+
+      const props = kit.byKind.get(block.kind)?.props
+
+      if (props === undefined || Option.isNone(Schema.decodeUnknownOption(props)(block.props))) {
+        return yield* ToolFailure.fail(`Those props don't fit a ${block.kind} block.`)
+      }
+
+      yield* append(
+        AssistantEvent.AssistantMessage.make({
+          id,
+          text,
+          block: AssistantEvent.MessageBlock.make(block),
+          ...closed
+        })
+      )
+
+      return `sent as message ${id}`
+    })
+  })
+
+  return yield* Effect.provideContext(BlockTools, handlers)
+})
+
+/** @internal */
+export const makeMessaging: (kit: BlockKit.BlockKit | undefined) => Effect.Effect<Toolkits.Tools<CurrentChat>> =
+  Effect.fnUntraced(function* (kit) {
+    if (kit === undefined || kit.blocks.length === 0) {
+      return Toolkits.fromWithHandler(yield* plainTools)
+    }
+
+    return Toolkits.fromWithHandler(yield* blockTools(kit))
+  })