effect-assistant 0.0.0-stage → 0.2.0

package/src/internal/history.ts

@@ -0,0 +1,294 @@
+import * as Prompt from "effect/ai/Prompt"
+import * as Response from "effect/ai/Response"
+import * as Match from "effect/Match"
+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 { toJson, toJsonText } from "./schema.ts"
+import * as Uuid from "./uuid.ts"
+
+/** @internal */
+export const userText = (text: string): Prompt.UserMessage =>
+  Prompt.userMessage({ content: [Prompt.textPart({ text })] })
+
+/** @internal */
+export const toolMessage = (result: AssistantEvent.ToolResult): Prompt.ToolMessage =>
+  Prompt.toolMessage({
+    content: [
+      Prompt.toolResultPart({
+        id: result.callId,
+        name: result.tool,
+        isFailure: result.outcome === "failure",
+        result: result.result,
+        providerExecuted: false
+      })
+    ]
+  })
+
+// A call with no result is one a crash cut off.
+/** @internal */
+export const unansweredCalls = (history: ReadonlyArray<Prompt.Message>): ReadonlyArray<AssistantEvent.ToolCallPart> => {
+  const answered = new Set(
+    history.flatMap((message) =>
+      message.role === "tool" ? message.content.flatMap((part) => (part.type === "tool-result" ? [part.id] : [])) : []
+    )
+  )
+
+  return history.flatMap((message) =>
+    message.role === "assistant"
+      ? message.content.flatMap((part) =>
+          part.type === "tool-call" && !part.providerExecuted && !answered.has(part.id)
+            ? [
+                Response.makePart("tool-call", {
+                  id: part.id,
+                  name: part.name,
+                  params: toJson(part.params),
+                  providerExecuted: false,
+                  metadata: part.options
+                })
+              ]
+            : []
+        )
+      : []
+  )
+}
+
+/** @internal */
+export const notRunOutput = "Not run: the turn ended before this call ran."
+
+/** @internal */
+export const mayHaveRunOutput =
+  "Stopped: the turn ended while this call ran. It may have done its work; check before doing it again."
+
+const ago = (millis: number) => {
+  const seconds = Math.max(0, Math.round(millis / 1000))
+
+  return seconds < 90 ? `${seconds} seconds` : `${Math.round(seconds / 60)} minutes`
+}
+
+const finishedText = (
+  entries: ReadonlyArray<AssistantEvent.AnyEntry>,
+  index: number,
+  finished: AssistantEvent.SpecialistFinished
+) => {
+  const at = entries[index]!
+
+  const isStart = ({ event }: AssistantEvent.AnyEntry) =>
+    AssistantEvent.isLibraryEvent(event) &&
+    Predicate.isTagged(event, "SpecialistStarted") &&
+    event.runId === finished.runId
+
+  const from = entries.slice(0, index).findLastIndex(isStart)
+  const started = from === -1 ? undefined : entries[from]
+  const since = started === undefined ? [] : entries.slice(from + 1, index)
+  const wrote = since.some(({ event }) => Predicate.isTagged(event, "UserMessage"))
+
+  const lines = [
+    "A report from a specialist you started. The user hasn't seen it.",
+    started === undefined
+      ? `You started it for: ${finished.goal}`
+      : `You started it ${ago(at.at - started.at)} ago for: ${finished.goal}`,
+    wrote ? "The user has written since you started it." : "The user hasn't written since you started it.",
+    Match.value(finished.status).pipe(
+      Match.when("answered", () => `Report:\n${finished.report ?? ""}`),
+      Match.when("failed", () => `It failed: ${finished.error ?? ""}`),
+      Match.when("cut_off", () => "A restart cut it off before it finished. Spawn it again if it's still needed."),
+      Match.when("stopped", () => "You stopped it."),
+      Match.exhaustive
+    )
+  ]
+
+  return `<specialist name="${finished.specialist}" run="${finished.runId}" status="${finished.status}">\n${lines.join(
+    "\n"
+  )}\n</specialist>`
+}
+
+const answerText = (answer: AssistantEvent.BlockAnswer) =>
+  `<answer message="${answer.messageId}" kind="${answer.kind}">\nThe user answered with the block on your message ${answer.messageId}.\n${toJsonText(answer.value)}\n</answer>`
+
+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>`
+
+// In the order the model saw the entries, not the order they were stored.
+/** @internal */
+export const fromEntries = (
+  entries: ReadonlyArray<AssistantEvent.AnyEntry>,
+  readApp: (event: { readonly _tag: string }) => string | undefined
+): ReadonlyArray<Prompt.Message> => {
+  const history: Array<Prompt.Message> = []
+  const held: Array<Prompt.Message> = []
+  const open = new Set<string>()
+  const called = new Set<string>()
+
+  const flushIfClosed = () => {
+    if (open.size === 0) history.push(...held.splice(0))
+  }
+
+  const nextSeen = (from: number) => {
+    const next = entries.slice(from + 1).find(({ event }) => Predicate.isTagged(event, "ModelOutput"))?.event
+
+    return next !== undefined && AssistantEvent.isLibraryEvent(next) && Predicate.isTagged(next, "ModelOutput")
+      ? next.seenThroughSeq
+      : undefined
+  }
+
+  const input = (index: number, item: Prompt.Message) => {
+    const seen = nextSeen(index)
+
+    if (open.size > 0 || (seen !== undefined && seen < entries[index]!.seq)) held.push(item)
+    else history.push(item)
+  }
+
+  entries.forEach(({ event }, index) => {
+    if (!AssistantEvent.isLibraryEvent(event)) {
+      const text = readApp(event)
+
+      if (text !== undefined) input(index, userText(text))
+
+      return
+    }
+
+    Match.value(event).pipe(
+      Match.tagsExhaustive({
+        UserMessage: (message) =>
+          input(index, userText(AssistantEvent.textWithAttachments(message.text, message.attachments))),
+        BlockAnswer: (answer) => input(index, userText(answerText(answer))),
+        ModelOutput: (output) => {
+          history.push(...Prompt.fromResponseParts(output.parts).content)
+
+          for (const part of output.parts) {
+            if (part.type === "tool-call") {
+              open.add(part.id)
+              called.add(part.id)
+            }
+          }
+
+          flushIfClosed()
+        },
+        ToolResult: (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(index, userText(resultText(result)))
+
+          history.push(toolMessage(result))
+          open.delete(result.callId)
+          flushIfClosed()
+        },
+        AssistantMessage: () => undefined,
+        ToolStarted: () => undefined,
+        TurnStarted: () => undefined,
+        TurnCompleted: () => undefined,
+        TurnFailed: () => undefined,
+        SpecialistFinished: (finished) => input(index, userText(finishedText(entries, index, finished))),
+        // 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,
+        ChatDeleted: () => undefined
+      })
+    )
+  })
+
+  return [...history, ...held]
+}
+
+/** @internal */
+export const isInput = (event: { readonly _tag: string }, wakes: ReadonlySet<string>): boolean =>
+  AssistantEvent.isInput(event) || (!AssistantEvent.isLibraryEvent(event) && wakes.has(event._tag))
+
+/** @internal */
+export const handledThrough = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): number => {
+  const last = entries.findLast(({ event }) => AssistantEvent.isTurnEnd(event))?.event
+
+  return last !== undefined && AssistantEvent.isTurnEnd(last) ? last.throughSeq : 0
+}
+
+// A run the assistant stopped isn't an input here: it wakes nothing.
+/** @internal */
+export const unhandledInputs = (
+  entries: ReadonlyArray<AssistantEvent.AnyEntry>,
+  wakes: ReadonlySet<string>
+): ReadonlyArray<{ readonly _tag: string }> => {
+  const seen = handledThrough(entries)
+
+  return entries.flatMap(({ event, seq }) =>
+    seq > seen && isInput(event, wakes) && !(AssistantEvent.isInput(event) && !AssistantEvent.isWaking(event))
+      ? [event]
+      : []
+  )
+}
+
+/** @internal */
+export const needsTurn = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, wakes: ReadonlySet<string>): boolean =>
+  unhandledInputs(entries, wakes).length > 0
+
+// A failure the user was shown counts as a reply.
+/** @internal */
+export const owesReply = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, throughSeq: number): boolean => {
+  const latest = entries.findLast(
+    ({ event, seq }) => seq <= throughSeq && AssistantEvent.isInput(event) && AssistantEvent.isUserInput(event)
+  )
+
+  return (
+    latest !== undefined &&
+    !entries.some(
+      ({ event, seq }) =>
+        seq > latest.seq && (Predicate.isTagged(event, "AssistantMessage") || Predicate.isTagged(event, "TurnFailed"))
+    )
+  )
+}
+
+const sentToWaitOn = Schema.decodeUnknownOption(Schema.Struct({ wait: Schema.Literal(false) }))
+
+// Messages sent with `wait: false` are progress while the model kept working, like "On it".
+const progressMessages = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): ReadonlySet<string> =>
+  new Set(
+    entries.flatMap(({ event }) =>
+      AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, "ModelOutput")
+        ? event.parts.flatMap((part) =>
+            part.type === "tool-call" && part.name === "send_user_message" && Option.isSome(sentToWaitOn(part.params))
+              ? [Uuid.fromKey(`message:${part.id}`)]
+              : []
+          )
+        : []
+    )
+  )
+
+// The model said it was on it and stopped without the result: only progress messages since the user's latest input.
+// A specialist still working doesn't count, since its report is what comes next.
+/** @internal */
+export const owesDelivery = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, throughSeq: number): boolean => {
+  const latest = entries.findLast(
+    ({ event, seq }) => seq <= throughSeq && AssistantEvent.isInput(event) && AssistantEvent.isUserInput(event)
+  )
+
+  if (latest === undefined) return false
+
+  const after = entries.flatMap(({ seq, event }) =>
+    seq > latest.seq && AssistantEvent.isLibraryEvent(event) ? [event] : []
+  )
+
+  const messages = after.flatMap((event) => (Predicate.isTagged(event, "AssistantMessage") ? [event] : []))
+  const progress = progressMessages(entries)
+  const started = after.flatMap((event) => (Predicate.isTagged(event, "SpecialistStarted") ? [event.runId] : []))
+
+  const finished = new Set(
+    entries.flatMap(({ event }) =>
+      AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, "SpecialistFinished") ? [event.runId] : []
+    )
+  )
+
+  return (
+    messages.length > 0 &&
+    messages.every((message) => message.block === undefined && progress.has(message.id)) &&
+    !after.some((event) => Predicate.isTagged(event, "TurnFailed")) &&
+    started.every((runId) => finished.has(runId))
+  )
+}
+
+/** @internal */
+export const unreadAfter = (
+  entries: ReadonlyArray<AssistantEvent.AnyEntry>,
+  throughSeq: number,
+  wakes: ReadonlySet<string>
+): boolean => entries.some(({ event, seq }) => seq > throughSeq && isInput(event, wakes))

package/src/internal/instructions.ts

@@ -0,0 +1,9 @@
+import * as Predicate from "effect/Predicate"
+import type * as Instructions from "../Instructions.ts"
+
+/** @internal */
+export const mapText = (
+  instructions: string | Instructions.Resolved,
+  f: (text: string) => string
+): Instructions.Resolved =>
+  Predicate.isString(instructions) ? { text: f(instructions) } : { ...instructions, text: f(instructions.text) }

package/src/internal/loop.ts

@@ -0,0 +1,274 @@
+import type * as AiError from "effect/ai/AiError"
+import * as LanguageModel from "effect/ai/LanguageModel"
+import * as Model from "effect/ai/Model"
+import * as Prompt from "effect/ai/Prompt"
+import type * as Response from "effect/ai/Response"
+import type * as Tool from "effect/ai/Tool"
+import type * as Toolkit from "effect/ai/Toolkit"
+import * as Clock from "effect/Clock"
+import * as Context from "effect/Context"
+import * as Data from "effect/Data"
+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 * as AssistantEvent from "../AssistantEvent.ts"
+import type * as Instructions from "../Instructions.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
+
+// 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.
+/** @internal */
+export const TurnTools = Context.Reference<Option.Option<Toolkits.Tools>>("effect-assistant/TurnTools", {
+  defaultValue: Option.none
+})
+
+/** @internal */
+export interface ChatHistory {
+  readonly messages: ReadonlyArray<Prompt.Message>
+  readonly throughSeq: number
+}
+
+const readHistory = (read: ReadonlyArray<Prompt.Message> | ChatHistory) =>
+  "messages" in read
+    ? { messages: read.messages, throughSeq: read.throughSeq }
+    : { messages: read, throughSeq: undefined }
+
+// `AssistantLoop` takes native toolkits; turns and specialist runs come here with their tools already merged.
+/** @internal */
+export interface StepOptions<R = never> {
+  readonly instructions: string | Instructions.Resolved
+  readonly toolkit?: Toolkits.Tools<R> | undefined
+  readonly history: Effect.Effect<ReadonlyArray<Prompt.Message> | ChatHistory>
+  readonly toolChoice?: LanguageModel.ToolChoice<string> | undefined
+}
+
+/** @internal */
+export interface Options<R = never> extends StepOptions<R> {
+  readonly maxSteps?: number | undefined
+}
+
+// Its member docs show through `AssistantLoop.StepResult`.
+/** @internal */
+export interface StepResult {
+  /** The model's output; unset when the step only ran calls a crash cut off. */
+  readonly output: AssistantEvent.ModelOutput | undefined
+  /**
+   * Whether the model is done: it made no tool calls, or ended its turn (`wait`, or a message
+   * with `wait: true`) and none of the step's calls failed.
+   */
+  readonly done: boolean
+  /**
+   * The history's length with this step's output and results: a longer one got something new meanwhile.
+   */
+  readonly historyLength: number
+}
+
+// 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>> => ({
+  tools: Object.fromEntries(definitions.map((tool) => [tool.name, tool])),
+  handle: () => Effect.succeed(Stream.empty)
+})
+
+// Tool call resolution stays on with a toolkit that runs nothing: with it off, a call whose params don't fit its
+// tool's schema fails the whole model call, and here the model reads why instead.
+const generate = (
+  prompt: Prompt.Prompt,
+  definitions: ReadonlyArray<Tool.Any>,
+  toolChoice: LanguageModel.ToolChoice<string> | undefined
+): Effect.Effect<
+  LanguageModel.GenerateTextResponse<Record<string, Tool.Any>, "opaque">,
+  AiError.AiError,
+  LanguageModel.LanguageModel
+> => LanguageModel.generateText({ prompt, toolkit: requestToolkit(definitions), toolChoice })
+
+const decodePart = Schema.decodeUnknownOption(AssistantEvent.ModelPart)
+
+const modelParts = (content: ReadonlyArray<Response.AllParts<Record<string, Tool.Any>>>) =>
+  content.flatMap((part) =>
+    Option.toArray(decodePart(part)).filter((decoded) => !(decoded.type === "tool-call" && decoded.providerExecuted))
+  )
+
+const toolCalls = (parts: ReadonlyArray<AssistantEvent.ModelPart>): ReadonlyArray<AssistantEvent.ToolCallPart> =>
+  parts.flatMap((part) => (part.type === "tool-call" ? [part] : []))
+
+const runCall = Effect.fnUntraced(function* <R>(tools: Toolkits.Tools<R>, call: AssistantEvent.ToolCallPart) {
+  const result = yield* Effect.gen(function* () {
+    const result = yield* tools.run(call)
+
+    yield* Telemetry.toolOutput(result.result)
+
+    return result
+  }).pipe(Telemetry.toolSpan(call))
+
+  return AssistantEvent.ToolResult.make({ callId: call.id, tool: call.name, ...result })
+})
+
+// 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>,
+  calls: ReadonlyArray<AssistantEvent.ToolCallPart>,
+  then: (failed: boolean) => Stream.Stream<Step<never, S>, E, R2>
+): Stream.Stream<Step<Event, S>, E, R | R2> =>
+  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 = (result: AssistantEvent.ToolResult) => result.outcome === "failure"
+
+/** @internal */
+export type Step<A, S> = Data.TaggedEnum<{
+  Value: { readonly value: A }
+  Next: { readonly state: S }
+  Stop: Record<never, never>
+}>
+
+interface StepDefinition extends Data.TaggedEnum.WithGenerics<2> {
+  readonly taggedEnum: Step<this["A"], this["B"]>
+}
+
+const Steps = Data.taggedEnum<StepDefinition>()
+
+/** @internal */
+export const value = <A>(value: A): Step<A, never> => Steps.Value({ value })
+
+/** @internal */
+export const next = <S>(state: S): Stream.Stream<Step<never, S>> => Stream.succeed(Steps.Next({ state }))
+
+/** @internal */
+// oxlint-disable-next-line no-unnecessary-type-parameters -- `stop<number>()` types a loop's state where inference can't.
+export const stop = <S = never>(): Stream.Stream<Step<never, S>> => Stream.succeed(Steps.Stop())
+
+const isValue = <A, S>(step: Step<A, S>): step is Data.TaggedEnum.Value<Step<A, S>, "Value"> =>
+  Predicate.isTagged(step, "Value")
+
+// A body that ends without `next` or `stop` stops too.
+/** @internal */
+export const loop = <S, A, E, R>(
+  initial: S,
+  body: (state: S) => Stream.Stream<Step<A, S>, E, R>
+): Stream.Stream<A, E, R> => {
+  const go = (state: S): Stream.Stream<A, E, R> =>
+    Stream.suspend(() => {
+      let after: Option.Option<S> = Option.none()
+
+      return body(state).pipe(
+        Stream.tap((step) =>
+          Effect.sync(() => (after = Predicate.isTagged(step, "Next") ? Option.some(step.state) : after))
+        ),
+        Stream.filter(isValue),
+        Stream.map((step) => step.value),
+        Stream.concat(Stream.suspend(() => Option.match(after, { onNone: () => Stream.empty, onSome: go })))
+      )
+    })
+
+  return go(initial)
+}
+
+/** @internal */
+export const step = <R, S, E2 = never, R2 = never>(
+  options: StepOptions<R>,
+  then: (result: StepResult) => Stream.Stream<Step<never, S>, E2, R2>
+): Stream.Stream<Step<Event, S>, AiError.AiError | E2, LanguageModel.LanguageModel | R | R2> => {
+  const toolkit = options.toolkit ?? Toolkits.empty
+  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* () {
+      const { messages: history, throughSeq } = readHistory(yield* options.history)
+      // 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)
+
+      if (cutOff.length > 0) {
+        return runCalls(toolkit, cutOff, () =>
+          after({ output: undefined, done: false, historyLength: history.length + cutOff.length })
+        )
+      }
+
+      const prompt = Prompt.fromMessages([Prompt.systemMessage({ content: instructions.text }), ...history])
+      const name = yield* Effect.serviceOption(Model.ModelName)
+      const started = yield* Clock.currentTimeMillis
+
+      const response = yield* generate(prompt, toolkit.definitions, options.toolChoice).pipe(
+        Telemetry.chatSpan(prompt, instructions.attributes)
+      )
+
+      const metadata = response.content.find((part) => part.type === "response-metadata")
+
+      const output = AssistantEvent.ModelOutput.make({
+        parts: modelParts(response.content),
+        seenThroughSeq: throughSeq,
+        model: metadata?.modelId ?? Option.getOrUndefined(name),
+        responseId: metadata?.id,
+        usage: response.usage,
+        durationMillis: (yield* Clock.currentTimeMillis) - started
+      })
+
+      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.
+      return Stream.make(value(output)).pipe(
+        Stream.concat(
+          runCalls(toolkit, calls, (failed) =>
+            after({
+              output,
+              done: calls.length === 0 || (!failed && calls.some(isTurnEnding)),
+              historyLength
+            })
+          )
+        )
+      )
+    })
+  )
+}
+
+/** @internal */
+export const run = <R = never>(
+  options: Options<R>
+): Stream.Stream<Event, AiError.AiError, LanguageModel.LanguageModel | R> => {
+  const maxSteps = options.maxSteps ?? 16
+
+  // Done: stop, unless something arrived while the model was working; then it reads that first.
+  const afterDone = (steps: number, historyLength: number) =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const read = yield* options.history
+
+        return readHistory(read).messages.length > historyLength ? next(steps) : stop<number>()
+      })
+    )
+
+  return loop(0, (steps: number) =>
+    step(options, (result) => {
+      const taken = result.output === undefined ? steps : steps + 1
+
+      if (taken >= maxSteps) return stop<number>()
+
+      return result.done ? afterDone(taken, result.historyLength) : next(taken)
+    })
+  )
+}

package/src/internal/schema.ts

@@ -0,0 +1,25 @@
+import { flow } from "effect/Function"
+import * as Option from "effect/Option"
+import * as Schema from "effect/Schema"
+
+const JsonText = Schema.fromJsonString(Schema.Unknown)
+
+// A value with no JSON form (`undefined`, a cycle) is empty text rather than a defect.
+/** @internal */
+export const toJsonText = flow(
+  Schema.encodeUnknownOption(JsonText),
+  Option.getOrElse(() => "")
+)
+
+/** @internal */
+export const isJsonText = (text: string): boolean => Option.isSome(Schema.decodeOption(JsonText)(text))
+
+const decodeJsonText = Schema.decodeOption(Schema.fromJsonString(Schema.Json))
+
+// As `JSON.stringify` writes it (a `Date` as its ISO string, a class as its fields), or `null` when it has none.
+/** @internal */
+export const toJson = flow(
+  Schema.encodeUnknownOption(JsonText),
+  Option.flatMap(decodeJsonText),
+  Option.getOrElse((): Schema.Json => null)
+)

package/src/internal/skills.ts

@@ -0,0 +1,37 @@
+import * as Tool from "effect/ai/Tool"
+import * as Toolkit from "effect/ai/Toolkit"
+import type * as Context from "effect/Context"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+import * as Instructions from "../Instructions.ts"
+import type { Skill } from "../Skill.ts"
+import * as ToolFailure from "../ToolFailure.ts"
+import * as Toolkits from "./toolkit.ts"
+
+/** @internal */
+export const toTools = <R>(skills: ReadonlyArray<Skill<R>>): Toolkits.Tools<R> => {
+  if (skills.length === 0) return Toolkits.empty
+
+  const byName = new Map(skills.map((skill) => [skill.name, skill]))
+
+  const LoadSkill = Tool.make("load_skill", {
+    description:
+      "Load a skill's instructions by name, in the same step as your first lookups (not in a step of its own). Follow them for the rest of the task.",
+    parameters: Schema.Struct({ name: Schema.Literals(skills.map((skill) => skill.name)) }),
+    success: Schema.String,
+    failure: ToolFailure.ToolFailure
+  })
+
+  // A skill's instructions resolve with the services of the loop that loads it.
+  return Toolkits.withContext(Toolkit.make(LoadSkill), (context: Context.Context<R>) => ({
+    load_skill: Effect.fnUntraced(function* ({ name }) {
+      const skill = byName.get(name)
+
+      if (skill === undefined) return yield* ToolFailure.fail(`No skill named ${name}.`)
+
+      const resolved = yield* Instructions.resolve(skill.instructions).pipe(Effect.provideContext(context))
+
+      return resolved.text
+    })
+  }))
+}