effect-assistant 0.3.0 → 0.4.0

package/dist/AssistantLoop.js

@@ -61,8 +61,10 @@ const toolsOf = (toolkit) => Effect.map(TurnTools, (turn) => {
 * 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/dist/AssistantLoop.js.map

@@ -1 +1 @@
-{"version":3,"file":"AssistantLoop.js","names":["Loop.value","Loop.next","Loop.stop","Loop.loop","Loop.TurnTools","Toolkits.empty","Toolkits.fromToolkit","Toolkits.merge","Loop.step","Loop.run"],"sources":["../src/AssistantLoop.ts"],"sourcesContent":["/**\n * Runs the agent loop, which calls the model, runs its tool calls, and repeats.\n *\n * Most handlers use `turn.loop` or `run.loop`. This module is for a loop of your own: {@link run}\n * runs the loop until the model is done, and {@link step} is one step, as a body for\n * {@link loop}.\n *\n * Tools are a native toolkit (`effect/ai/Toolkit`) whose handlers come from the handler's layer.\n * In a turn, the assistant's own tools (`send_user_message`, `wait`, and the specialist tools)\n * are added to them.\n *\n * @since 0.1.0\n */\nimport type * as AiError from \"effect/ai/AiError\"\nimport type * as LanguageModel from \"effect/ai/LanguageModel\"\nimport type * as Prompt from \"effect/ai/Prompt\"\nimport type * as Tool from \"effect/ai/Tool\"\nimport type * as Toolkit from \"effect/ai/Toolkit\"\nimport * as Effect from \"effect/Effect\"\nimport * as Option from \"effect/Option\"\nimport * as Stream from \"effect/Stream\"\nimport type * as Instructions from \"./Instructions.ts\"\nimport * as Loop from \"./internal/loop.ts\"\nimport * as Toolkits from \"./internal/toolkit.ts\"\n\n/**\n * Represents what the loop emits.\n *\n * For each model call, the loop emits the call's output. Then, for each of its tool calls, it\n * emits a `ToolStarted` before the call runs and the call's result.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Event = Loop.Event\n\n/**\n * Represents a chat's history as the model reads it.\n *\n * It holds the messages, and the last `seq` of the chat they cover.\n *\n * @category models\n * @since 0.1.0\n */\nexport type ChatHistory = Loop.ChatHistory\n\n/**\n * Represents how a step went, for deciding what comes next.\n *\n * @category models\n * @since 0.1.0\n */\nexport type StepResult = Loop.StepResult\n\n/**\n * Represents what a loop body emits, which is either a value or what to do next.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Step<A, S> = Loop.Step<A, S>\n\n/**\n * Emits a value from a loop body.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const value = Loop.value\n\n/**\n * Ends a loop body's step and continues the loop with the given state.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const next = Loop.next\n\n/**\n * Ends the loop.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const stop = Loop.stop\n\n/**\n * Runs a loop body from an initial state.\n *\n * It emits the body's values, and runs the body again with the state it passes to `next`, until\n * the body calls `stop`.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const loop = Loop.loop\n\ntype NoTools = Record<never, never>\n\n/**\n * Extracts the services a toolkit's tools need when they run, which are their handlers and the\n * services those handlers use.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type ToolkitServices<T extends Record<string, Tool.Any>> = Tool.HandlersFor<T> | Toolkits.ToolServices<T>\n\n/**\n * Represents the options for {@link step}.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface StepOptions<T extends Record<string, Tool.Any> = NoTools> {\n  /** The full system prompt, like `turn.instructions(text)`, optionally with span attributes. */\n  readonly instructions: string | Instructions.Resolved\n  /**\n   * The tools the model can call, in addition to the assistant's own tools in a turn. Their\n   * handlers come from the layer.\n   */\n  readonly toolkit?: Toolkit.Toolkit<T> | undefined\n  /**\n   * The current history, read at the start of the step. It is either messages, or a chat's\n   * history (`turn.history()`), whose `throughSeq` the step's `ModelOutput` records as how far\n   * the model had read.\n   */\n  readonly history: Effect.Effect<ReadonlyArray<Prompt.Message> | ChatHistory>\n  /**\n   * Defaults to `\"auto\"`, where a step without a tool call ends the loop. Forcing a call\n   * (`\"required\"`, or a tool by name) is refused by newer models, and with extended thinking.\n   */\n  readonly toolChoice?: LanguageModel.ToolChoice<string> | undefined\n}\n\n/**\n * Represents the options for {@link run}.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Options<T extends Record<string, Tool.Any> = NoTools> extends StepOptions<T> {\n  /** The model calls allowed. Defaults to 16. */\n  readonly maxSteps?: number | undefined\n}\n\nconst toolsOf = <T extends Record<string, Tool.Any>>(toolkit: Toolkit.Toolkit<T> | undefined) =>\n  Effect.map(Loop.TurnTools, (turn) => {\n    const own = toolkit === undefined ? Toolkits.empty : Toolkits.fromToolkit(toolkit)\n\n    return Option.match(turn, { onNone: () => own, onSome: (builtins) => Toolkits.merge(builtins, own) })\n  })\n\n/**\n * Runs one step of the agent loop, as a body for {@link loop}.\n *\n * **Details**\n *\n * The step calls the model with the current history and emits its `ModelOutput`. It then runs\n * the output's tool calls and emits a `ToolStarted` and a `ToolResult` for each. `then` receives\n * the step's result and decides what comes next, with `AssistantLoop.next(state)` or\n * `AssistantLoop.stop()`.\n *\n * A tool with Effect's `needsApproval` set fails the loop before the model is called: the\n * library doesn't run calls that wait for approval (see the guide on involving the user).\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const step = <T extends Record<string, Tool.Any> = NoTools, S = never, E2 = never, R2 = never>(\n  options: StepOptions<T>,\n  then: (result: StepResult) => Stream.Stream<Step<never, S>, E2, R2>\n): Stream.Stream<Step<Event, S>, AiError.AiError | E2, LanguageModel.LanguageModel | ToolkitServices<T> | R2> =>\n  Stream.unwrap(Effect.map(toolsOf(options.toolkit), (toolkit) => Loop.step({ ...options, toolkit }, then)))\n\n/**\n * Runs the agent loop as a stream.\n *\n * **Details**\n *\n * It runs {@link step} after step until the model is done and nothing new arrived while it\n * worked, or until it has made `maxSteps` model calls.\n *\n * **Example** (A turn's loop with a step limit)\n *\n * ```ts\n * import { AssistantLoop } from \"effect-assistant\"\n * import * as Layer from \"effect/Layer\"\n * import * as Stream from \"effect/Stream\"\n *\n * const instructions = \"You help a small marketing team.\"\n *\n * const MyAssistantLive = MyAssistant.toLayer((turn) =>\n *   AssistantLoop.run({\n *     instructions: turn.instructions(instructions),\n *     toolkit: MyTools, // the assistant's own tools are added to them\n *     history: turn.history(),\n *     maxSteps: 12\n *   }).pipe(Stream.concat(turn.replyIfOwed({ instructions })))\n * ).pipe(Layer.provide(MyToolsLive))\n * ```\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const run = <T extends Record<string, Tool.Any> = NoTools>(\n  options: Options<T>\n): Stream.Stream<Event, AiError.AiError, LanguageModel.LanguageModel | ToolkitServices<T>> =>\n  Stream.unwrap(Effect.map(toolsOf(options.toolkit), (toolkit) => Loop.run({ ...options, toolkit })))\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAoEA,MAAa,QAAQA;;;;;;;AAQrB,MAAa,OAAOC;;;;;;;AAQpB,MAAa,OAAOC;;;;;;;;;;AAWpB,MAAa,OAAOC;AAmDpB,MAAM,WAA+C,YACnD,OAAO,IAAIC,YAAiB,SAAS;CACnC,MAAM,MAAM,YAAY,KAAA,IAAYC,QAAiBC,YAAqB,OAAO;CAEjF,OAAO,OAAO,MAAM,MAAM;EAAE,cAAc;EAAK,SAAS,aAAaC,MAAe,UAAU,GAAG;CAAE,CAAC;AACtG,CAAC;;;;;;;;;;;;;;;;;AAkBH,MAAa,QACX,SACA,SAEA,OAAO,OAAO,OAAO,IAAI,QAAQ,QAAQ,OAAO,IAAI,YAAYC,OAAU;CAAE,GAAG;CAAS;AAAQ,GAAG,IAAI,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgC3G,MAAa,OACX,YAEA,OAAO,OAAO,OAAO,IAAI,QAAQ,QAAQ,OAAO,IAAI,YAAYC,MAAS;CAAE,GAAG;CAAS;AAAQ,CAAC,CAAC,CAAC"}
+{"version":3,"file":"AssistantLoop.js","names":["Loop.value","Loop.next","Loop.stop","Loop.loop","Loop.TurnTools","Toolkits.empty","Toolkits.fromToolkit","Toolkits.merge","Loop.step","Loop.run"],"sources":["../src/AssistantLoop.ts"],"sourcesContent":["/**\n * Runs the agent loop, which calls the model, runs its tool calls, and repeats.\n *\n * Most handlers use `turn.loop` or `run.loop`. This module is for a loop of your own: {@link run}\n * runs the loop until the model is done, and {@link step} is one step, as a body for\n * {@link loop}.\n *\n * Tools are a native toolkit (`effect/ai/Toolkit`) whose handlers come from the handler's layer.\n * In a turn, the assistant's own tools (`send_user_message`, `wait`, and the specialist tools)\n * are added to them.\n *\n * @since 0.1.0\n */\nimport type * as AiError from \"effect/ai/AiError\"\nimport type * as LanguageModel from \"effect/ai/LanguageModel\"\nimport type * as Prompt from \"effect/ai/Prompt\"\nimport type * as Tool from \"effect/ai/Tool\"\nimport type * as Toolkit from \"effect/ai/Toolkit\"\nimport * as Effect from \"effect/Effect\"\nimport * as Option from \"effect/Option\"\nimport * as Stream from \"effect/Stream\"\nimport type * as Instructions from \"./Instructions.ts\"\nimport * as Loop from \"./internal/loop.ts\"\nimport * as Toolkits from \"./internal/toolkit.ts\"\n\n/**\n * Represents what the loop emits.\n *\n * For each model call, the loop emits the call's output. Then, for each of its tool calls, it\n * emits a `ToolStarted` before the call runs and the call's result.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Event = Loop.Event\n\n/**\n * Represents a chat's history as the model reads it.\n *\n * It holds the messages, and the last `seq` of the chat they cover.\n *\n * @category models\n * @since 0.1.0\n */\nexport type ChatHistory = Loop.ChatHistory\n\n/**\n * Represents how a step went, for deciding what comes next.\n *\n * @category models\n * @since 0.1.0\n */\nexport type StepResult = Loop.StepResult\n\n/**\n * Represents what a loop body emits, which is either a value or what to do next.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Step<A, S> = Loop.Step<A, S>\n\n/**\n * Emits a value from a loop body.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const value = Loop.value\n\n/**\n * Ends a loop body's step and continues the loop with the given state.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const next = Loop.next\n\n/**\n * Ends the loop.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const stop = Loop.stop\n\n/**\n * Runs a loop body from an initial state.\n *\n * It emits the body's values, and runs the body again with the state it passes to `next`, until\n * the body calls `stop`.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const loop = Loop.loop\n\ntype NoTools = Record<never, never>\n\n/**\n * Extracts the services a toolkit's tools need when they run, which are their handlers and the\n * services those handlers use.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type ToolkitServices<T extends Record<string, Tool.Any>> = Tool.HandlersFor<T> | Toolkits.ToolServices<T>\n\n/**\n * Represents the options for {@link step}.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface StepOptions<T extends Record<string, Tool.Any> = NoTools> {\n  /** The full system prompt, like `turn.instructions(text)`, optionally with span attributes. */\n  readonly instructions: string | Instructions.Resolved\n  /**\n   * The tools the model can call, in addition to the assistant's own tools in a turn. Their\n   * handlers come from the layer.\n   */\n  readonly toolkit?: Toolkit.Toolkit<T> | undefined\n  /**\n   * The current history, read at the start of the step. It is either messages, or a chat's\n   * history (`turn.history()`), whose `throughSeq` the step's `ModelOutput` records as how far\n   * the model had read.\n   */\n  readonly history: Effect.Effect<ReadonlyArray<Prompt.Message> | ChatHistory>\n  /**\n   * Defaults to `\"auto\"`, where a step without a tool call ends the loop. Forcing a call\n   * (`\"required\"`, or a tool by name) is refused by newer models, and with extended thinking.\n   */\n  readonly toolChoice?: LanguageModel.ToolChoice<string> | undefined\n}\n\n/**\n * Represents the options for {@link run}.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Options<T extends Record<string, Tool.Any> = NoTools> extends StepOptions<T> {\n  /** The model calls allowed. Defaults to 16. */\n  readonly maxSteps?: number | undefined\n}\n\nconst toolsOf = <T extends Record<string, Tool.Any>>(toolkit: Toolkit.Toolkit<T> | undefined) =>\n  Effect.map(Loop.TurnTools, (turn) => {\n    const own = toolkit === undefined ? Toolkits.empty : Toolkits.fromToolkit(toolkit)\n\n    return Option.match(turn, { onNone: () => own, onSome: (builtins) => Toolkits.merge(builtins, own) })\n  })\n\n/**\n * Runs one step of the agent loop, as a body for {@link loop}.\n *\n * **Details**\n *\n * The step calls the model with the current history and emits its `ModelOutput`. It then runs\n * the output's tool calls and emits a `ToolStarted` and a `ToolResult` for each. `then` receives\n * the step's result and decides what comes next, with `AssistantLoop.next(state)` or\n * `AssistantLoop.stop()`.\n *\n * In a turn's loop, a call to a tool with Effect's `needsApproval` doesn't run: the step emits an\n * `ApprovalRequested` for it, and ends the turn, which waits for the user (see `ToolApproval`). A\n * call the user approved runs at the start of the next step, before the model is called. A\n * specialist's run can't wait for the user: such a call fails, and the run reads why.\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const step = <T extends Record<string, Tool.Any> = NoTools, S = never, E2 = never, R2 = never>(\n  options: StepOptions<T>,\n  then: (result: StepResult) => Stream.Stream<Step<never, S>, E2, R2>\n): Stream.Stream<Step<Event, S>, AiError.AiError | E2, LanguageModel.LanguageModel | ToolkitServices<T> | R2> =>\n  Stream.unwrap(Effect.map(toolsOf(options.toolkit), (toolkit) => Loop.step({ ...options, toolkit }, then)))\n\n/**\n * Runs the agent loop as a stream.\n *\n * **Details**\n *\n * It runs {@link step} after step until the model is done and nothing new arrived while it\n * worked, or until it has made `maxSteps` model calls.\n *\n * **Example** (A turn's loop with a step limit)\n *\n * ```ts\n * import { AssistantLoop } from \"effect-assistant\"\n * import * as Layer from \"effect/Layer\"\n * import * as Stream from \"effect/Stream\"\n *\n * const instructions = \"You help a small marketing team.\"\n *\n * const MyAssistantLive = MyAssistant.toLayer((turn) =>\n *   AssistantLoop.run({\n *     instructions: turn.instructions(instructions),\n *     toolkit: MyTools, // the assistant's own tools are added to them\n *     history: turn.history(),\n *     maxSteps: 12\n *   }).pipe(Stream.concat(turn.replyIfOwed({ instructions })))\n * ).pipe(Layer.provide(MyToolsLive))\n * ```\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const run = <T extends Record<string, Tool.Any> = NoTools>(\n  options: Options<T>\n): Stream.Stream<Event, AiError.AiError, LanguageModel.LanguageModel | ToolkitServices<T>> =>\n  Stream.unwrap(Effect.map(toolsOf(options.toolkit), (toolkit) => Loop.run({ ...options, toolkit })))\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAoEA,MAAa,QAAQA;;;;;;;AAQrB,MAAa,OAAOC;;;;;;;AAQpB,MAAa,OAAOC;;;;;;;;;;AAWpB,MAAa,OAAOC;AAmDpB,MAAM,WAA+C,YACnD,OAAO,IAAIC,YAAiB,SAAS;CACnC,MAAM,MAAM,YAAY,KAAA,IAAYC,QAAiBC,YAAqB,OAAO;CAEjF,OAAO,OAAO,MAAM,MAAM;EAAE,cAAc;EAAK,SAAS,aAAaC,MAAe,UAAU,GAAG;CAAE,CAAC;AACtG,CAAC;;;;;;;;;;;;;;;;;;;AAoBH,MAAa,QACX,SACA,SAEA,OAAO,OAAO,OAAO,IAAI,QAAQ,QAAQ,OAAO,IAAI,YAAYC,OAAU;CAAE,GAAG;CAAS;AAAQ,GAAG,IAAI,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgC3G,MAAa,OACX,YAEA,OAAO,OAAO,OAAO,IAAI,QAAQ,QAAQ,OAAO,IAAI,YAAYC,MAAS;CAAE,GAAG;CAAS;AAAQ,CAAC,CAAC,CAAC"}

package/dist/Compaction.d.ts

@@ -29,7 +29,7 @@ export interface Summary {
 export declare const inputTokens: (entries: ReadonlyArray<AnyEntry>) => number;
 /**
  * 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

package/dist/Compaction.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Compaction.d.ts","names":[],"sources":["../src/Compaction.ts"],"mappings":";;;;;;;;;;;;;;;;iBA8BiB;WACN;WACA;WACA;;;;;;;;;qBAUE,cAAW,SAAa,cAAc;;;;;;;;;qBAmBtC,YAAS,SACX,cAAc,WAAwB,uBAE9C,OAAO;;;;;;;;qBAoDG,gBAAa,SACf,cAAc,WAAwB,uBAE9C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAmEG,QAAK,YACH,mBAAmB,SAAS,aACxC;WAA0B;GAAc,SAC9B,cAAc,MAAgB,aACtC,cAAc,MAAgB,UAAU,OAAO"}
+{"version":3,"file":"Compaction.d.ts","names":[],"sources":["../src/Compaction.ts"],"mappings":";;;;;;;;;;;;;;;;iBAgCiB;WACN;WACA;WACA;;;;;;;;;qBAUE,cAAW,SAAa,cAAc;;;;;;;;;qBAmBtC,YAAS,SACX,cAAc,WAAwB,uBAE9C,OAAO;;;;;;;;qBAmEG,gBAAa,SACf,cAAc,WAAwB,uBAE9C,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAmEG,QAAK,YACH,mBAAmB,SAAS,aACxC;WAA0B;GAAc,SAC9B,cAAc,MAAgB,aACtC,cAAc,MAAgB,UAAU,OAAO"}

package/dist/Compaction.js

@@ -1,8 +1,10 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
 import { attachmentLine, isLibraryEvent } from "./AssistantEvent.js";
+import { fromEntries } from "./ToolApproval.js";
+import { toJsonText } from "./internal/schema.js";
 import { userText } from "./internal/history.js";
-import { fromEntries } from "./AssistantActivity.js";
-import { fromEntries as fromEntries$1 } from "./BlockKit.js";
+import { fromEntries as fromEntries$1 } from "./AssistantActivity.js";
+import { fromEntries as fromEntries$2 } from "./BlockKit.js";
 import * as Predicate from "effect/Predicate";
 import * as Option from "effect/Option";
 //#region src/Compaction.ts
@@ -25,7 +27,7 @@ const inputTokens = (entries) => {
 };
 /**
 * 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
@@ -34,13 +36,18 @@ const inputTokens = (entries) => {
 const openItems = (entries, throughSeq) => {
 	const seqOf = (found) => entries.find(({ event }) => found(event))?.seq ?? Number.POSITIVE_INFINITY;
 	const opened = (seq) => seq <= throughSeq;
-	const blocks = [...fromEntries$1(entries)].flatMap(([messageId, state]) => {
+	const blocks = [...fromEntries$2(entries)].flatMap(([messageId, state]) => {
 		const shown = entries.find(({ event }) => isLibraryEvent(event) && Predicate.isTagged(event, "AssistantMessage") && event.id === messageId);
 		const message = shown?.event;
 		return state.open && shown !== void 0 && opened(shown.seq) && message !== void 0 && isLibraryEvent(message) && Predicate.isTagged(message, "AssistantMessage") ? [`- message ${messageId}, a ${message.block?.kind} block: ${message.text}`] : [];
 	});
-	const specialists = [...fromEntries(entries).specialists.values()].flatMap((run) => opened(seqOf((event) => isLibraryEvent(event) && Predicate.isTagged(event, "SpecialistStarted") && event.runId === run.runId)) ? [`- your ${run.specialist} specialist (${run.runId}), working on: ${run.goal}`] : []);
-	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")}` : ""].filter((section) => section.length > 0);
+	const specialists = [...fromEntries$1(entries).specialists.values()].flatMap((run) => opened(seqOf((event) => isLibraryEvent(event) && Predicate.isTagged(event, "SpecialistStarted") && event.runId === run.runId)) ? [`- your ${run.specialist} specialist (${run.runId}), working on: ${run.goal}`] : []);
+	const approvals = [...fromEntries(entries).values()].flatMap((approval) => approval.status === "pending" && opened(seqOf((event) => 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")}` : "",
+		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/dist/Compaction.js.map

@@ -1 +1 @@
-{"version":3,"file":"Compaction.js","names":["AssistantEvent.isLibraryEvent","BlockKit.fromEntries","AssistantActivity.fromEntries","AssistantEvent.attachmentLine"],"sources":["../src/Compaction.ts"],"sourcesContent":["/**\n * This module provides what a long chat needs so that the model can read a summary in place of\n * everything before it.\n *\n * The app decides when to compact, which model writes the summary, and what the summary says.\n * Its handler reads the chat's entries, has a model write a summary, and stores the summary as one\n * of the assistant's own events (see {@link Summary}). Its loop then reads the chat through\n * {@link since}. {@link inputTokens} helps decide when the prompt has grown large enough to\n * compact. The log keeps every entry, so the user still sees the whole chat.\n *\n * @since 0.1.0\n */\nimport type * as Prompt from \"effect/ai/Prompt\"\nimport * as Option from \"effect/Option\"\nimport * as Predicate from \"effect/Predicate\"\nimport type * as Assistant from \"./Assistant.ts\"\nimport * as AssistantActivity from \"./AssistantActivity.ts\"\nimport * as AssistantEvent from \"./AssistantEvent.ts\"\nimport * as BlockKit from \"./BlockKit.ts\"\nimport { userText } from \"./internal/history.ts\"\n\n/**\n * Represents the fields a summary event must have: its text and the last `seq` it covers.\n *\n * Entries after `throughSeq` are kept as they are, so an input that arrived while the summary was\n * being written isn't lost.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Summary {\n  readonly _tag: string\n  readonly text: string\n  readonly throughSeq: number\n}\n\n/**\n * Returns the number of input tokens used by the chat's last model call, which shows how large\n * the prompt has grown. Returns 0 before the first call.\n *\n * @category utils\n * @since 0.1.0\n */\nexport const inputTokens = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): number => {\n  const last = entries.findLast(\n    ({ event }) =>\n      AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, \"ModelOutput\") && event.usage !== undefined\n  )?.event\n\n  return last !== undefined && AssistantEvent.isLibraryEvent(last) && Predicate.isTagged(last, \"ModelOutput\")\n    ? (last.usage?.inputTokens.total ?? 0)\n    : 0\n}\n\n/**\n * Returns the items that were open at `throughSeq` and are still open: blocks the user hasn't\n * answered, and specialists that are working. The result is text for\n * the model, or `None` when nothing is open.\n *\n * @category utils\n * @since 0.1.0\n */\nexport const openItems = (\n  entries: ReadonlyArray<AssistantEvent.AnyEntry>,\n  throughSeq: number\n): Option.Option<string> => {\n  const seqOf = (found: (event: AssistantEvent.AnyEntry[\"event\"]) => boolean) =>\n    entries.find(({ event }) => found(event))?.seq ?? Number.POSITIVE_INFINITY\n\n  const opened = (seq: number) => seq <= throughSeq\n\n  const blocks = [...BlockKit.fromEntries(entries)].flatMap(([messageId, state]) => {\n    const shown = entries.find(\n      ({ event }) =>\n        AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, \"AssistantMessage\") && event.id === messageId\n    )\n\n    const message = shown?.event\n\n    return state.open &&\n      shown !== undefined &&\n      opened(shown.seq) &&\n      message !== undefined &&\n      AssistantEvent.isLibraryEvent(message) &&\n      Predicate.isTagged(message, \"AssistantMessage\")\n      ? [`- message ${messageId}, a ${message.block?.kind} block: ${message.text}`]\n      : []\n  })\n\n  const specialists = [...AssistantActivity.fromEntries(entries).specialists.values()].flatMap((run) =>\n    opened(\n      seqOf(\n        (event) =>\n          AssistantEvent.isLibraryEvent(event) &&\n          Predicate.isTagged(event, \"SpecialistStarted\") &&\n          event.runId === run.runId\n      )\n    )\n      ? [`- your ${run.specialist} specialist (${run.runId}), working on: ${run.goal}`]\n      : []\n  )\n\n  const sections = [\n    blocks.length > 0 ? `Blocks the user hasn't answered:\\n${blocks.join(\"\\n\")}` : \"\",\n    specialists.length > 0 ? `Specialists still working:\\n${specialists.join(\"\\n\")}` : \"\"\n  ].filter((section) => section.length > 0)\n\n  return sections.length === 0 ? Option.none() : Option.some(sections.join(\"\\n\\n\"))\n}\n\n/**\n * Returns the files the user attached up to `throughSeq`, as lines of text for the model, or\n * `None` when there are none. A summary may leave out a file's id, which tools need.\n *\n * @category utils\n * @since 0.1.0\n */\nexport const attachedFiles = (\n  entries: ReadonlyArray<AssistantEvent.AnyEntry>,\n  throughSeq: number\n): Option.Option<string> => {\n  const lines = entries.flatMap(({ seq, event }) =>\n    seq <= throughSeq && AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, \"UserMessage\")\n      ? (event.attachments ?? []).map(AssistantEvent.attachmentLine)\n      : []\n  )\n\n  return lines.length === 0 ? Option.none() : Option.some(lines.join(\"\\n\"))\n}\n\n/**\n * Creates a history view that starts at the last summary.\n *\n * **Details**\n *\n * `isSummary` identifies the app's summary events. The model reads the last summary, the files\n * attached earlier ({@link attachedFiles}), and the items that are still open\n * ({@link openItems}), followed by the entries after the summary. When the chat has no summary,\n * the view returns every entry.\n *\n * The app's other events after the summary stay entries, which the model doesn't read: map those\n * it should read to messages after this view, as with any history view (see\n * `Assistant.HistoryView`). A summary the handler appends wakes no turn.\n *\n * **Example** (Compacting a long chat after each turn)\n *\n * ```ts\n * import { Assistant, type AssistantEvent, Compaction } from \"effect-assistant\"\n * import * as LanguageModel from \"effect/ai/LanguageModel\"\n * import * as Effect from \"effect/Effect\"\n * import * as Schema from \"effect/Schema\"\n * import * as Stream from \"effect/Stream\"\n *\n * class Summary extends Schema.TaggedClass<Summary>()(\"Summary\", {\n *   text: Schema.String,\n *   throughSeq: Schema.Int\n * }) {}\n *\n * declare const transcript: (entries: ReadonlyArray<AssistantEvent.AnyEntry>) => string\n *\n * export const MyAssistant = Assistant.make(\"my-assistant\", { events: [Summary] })\n *\n * const MyAssistantLive = MyAssistant.toLayer((turn) => {\n *   const compact = Effect.gen(function* () {\n *     const chat = yield* MyAssistant.Chat\n *     const entries = yield* chat.entries\n *\n *     if (Compaction.inputTokens(entries) < 100_000) return\n *\n *     const { text } = yield* LanguageModel.generateText({\n *       prompt: `Summarize this chat:\\n\\n${transcript(entries)}`\n *     })\n *\n *     yield* chat.append(Summary.make({ text, throughSeq: entries.at(-1)?.seq ?? 0 }))\n *   })\n *\n *   // After the reply, so the user doesn't wait for the summary.\n *   return Stream.concat(\n *     turn.loop({ instructions: \"Be brief.\", history: Compaction.since(Schema.is(Summary)) }),\n *     Stream.drain(Stream.fromEffect(compact))\n *   )\n * })\n * ```\n *\n * @category utils\n * @since 0.1.0\n */\nexport const since =\n  (isSummary: (event: unknown) => event is Summary) =>\n  <Events extends { readonly _tag: string }>(\n    entries: ReadonlyArray<Assistant.Entry<Events>>\n  ): ReadonlyArray<Assistant.Entry<Events> | Prompt.Message> => {\n    const last = entries.findLast(({ event }) => isSummary(event))?.event\n\n    if (last === undefined || !isSummary(last)) return entries\n\n    const open = Option.match(openItems(entries, last.throughSeq), {\n      onNone: () => \"\",\n      onSome: (items) => `\\n\\n<still_open>\\n${items}\\n</still_open>`\n    })\n\n    const files = Option.match(attachedFiles(entries, last.throughSeq), {\n      onNone: () => \"\",\n      onSome: (lines) => `\\n\\n<files_attached_earlier>\\n${lines}\\n</files_attached_earlier>`\n    })\n\n    return [\n      userText(`<earlier_in_this_chat>\\n${last.text}\\n</earlier_in_this_chat>${files}${open}`),\n      ...entries.filter(({ seq, event }) => seq > last.throughSeq && !isSummary(event))\n    ]\n  }\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA2CA,MAAa,eAAe,YAA4D;CACtF,MAAM,OAAO,QAAQ,UAClB,EAAE,YACDA,eAA8B,KAAK,KAAK,UAAU,SAAS,OAAO,aAAa,KAAK,MAAM,UAAU,KAAA,CACxG,CAAC,EAAE;CAEH,OAAO,SAAS,KAAA,KAAaA,eAA8B,IAAI,KAAK,UAAU,SAAS,MAAM,aAAa,IACrG,KAAK,OAAO,YAAY,SAAS,IAClC;AACN;;;;;;;;;AAUA,MAAa,aACX,SACA,eAC0B;CAC1B,MAAM,SAAS,UACb,QAAQ,MAAM,EAAE,YAAY,MAAM,KAAK,CAAC,CAAC,EAAE,OAAO,OAAO;CAE3D,MAAM,UAAU,QAAgB,OAAO;CAEvC,MAAM,SAAS,CAAC,GAAGC,cAAqB,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,WAAW;EAChF,MAAM,QAAQ,QAAQ,MACnB,EAAE,YACDD,eAA8B,KAAK,KAAK,UAAU,SAAS,OAAO,kBAAkB,KAAK,MAAM,OAAO,SAC1G;EAEA,MAAM,UAAU,OAAO;EAEvB,OAAO,MAAM,QACX,UAAU,KAAA,KACV,OAAO,MAAM,GAAG,KAChB,YAAY,KAAA,KACZA,eAA8B,OAAO,KACrC,UAAU,SAAS,SAAS,kBAAkB,IAC5C,CAAC,aAAa,UAAU,MAAM,QAAQ,OAAO,KAAK,UAAU,QAAQ,MAAM,IAC1E,CAAC;CACP,CAAC;CAED,MAAM,cAAc,CAAC,GAAGE,YAA8B,OAAO,CAAC,CAAC,YAAY,OAAO,CAAC,CAAC,CAAC,SAAS,QAC5F,OACE,OACG,UACCF,eAA8B,KAAK,KACnC,UAAU,SAAS,OAAO,mBAAmB,KAC7C,MAAM,UAAU,IAAI,KACxB,CACF,IACI,CAAC,UAAU,IAAI,WAAW,eAAe,IAAI,MAAM,iBAAiB,IAAI,MAAM,IAC9E,CAAC,CACP;CAEA,MAAM,WAAW,CACf,OAAO,SAAS,IAAI,qCAAqC,OAAO,KAAK,IAAI,MAAM,IAC/E,YAAY,SAAS,IAAI,+BAA+B,YAAY,KAAK,IAAI,MAAM,EACrF,CAAC,CAAC,QAAQ,YAAY,QAAQ,SAAS,CAAC;CAExC,OAAO,SAAS,WAAW,IAAI,OAAO,KAAK,IAAI,OAAO,KAAK,SAAS,KAAK,MAAM,CAAC;AAClF;;;;;;;;AASA,MAAa,iBACX,SACA,eAC0B;CAC1B,MAAM,QAAQ,QAAQ,SAAS,EAAE,KAAK,YACpC,OAAO,cAAcA,eAA8B,KAAK,KAAK,UAAU,SAAS,OAAO,aAAa,KAC/F,MAAM,eAAe,CAAC,EAAA,CAAG,IAAIG,cAA6B,IAC3D,CAAC,CACP;CAEA,OAAO,MAAM,WAAW,IAAI,OAAO,KAAK,IAAI,OAAO,KAAK,MAAM,KAAK,IAAI,CAAC;AAC1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2DA,MAAa,SACV,eAEC,YAC4D;CAC5D,MAAM,OAAO,QAAQ,UAAU,EAAE,YAAY,UAAU,KAAK,CAAC,CAAC,EAAE;CAEhE,IAAI,SAAS,KAAA,KAAa,CAAC,UAAU,IAAI,GAAG,OAAO;CAEnD,MAAM,OAAO,OAAO,MAAM,UAAU,SAAS,KAAK,UAAU,GAAG;EAC7D,cAAc;EACd,SAAS,UAAU,qBAAqB,MAAM;CAChD,CAAC;CAED,MAAM,QAAQ,OAAO,MAAM,cAAc,SAAS,KAAK,UAAU,GAAG;EAClE,cAAc;EACd,SAAS,UAAU,iCAAiC,MAAM;CAC5D,CAAC;CAED,OAAO,CACL,SAAS,2BAA2B,KAAK,KAAK,2BAA2B,QAAQ,MAAM,GACvF,GAAG,QAAQ,QAAQ,EAAE,KAAK,YAAY,MAAM,KAAK,cAAc,CAAC,UAAU,KAAK,CAAC,CAClF;AACF"}
+{"version":3,"file":"Compaction.js","names":["AssistantEvent.isLibraryEvent","BlockKit.fromEntries","AssistantActivity.fromEntries","ToolApproval.fromEntries","AssistantEvent.attachmentLine"],"sources":["../src/Compaction.ts"],"sourcesContent":["/**\n * This module provides what a long chat needs so that the model can read a summary in place of\n * everything before it.\n *\n * The app decides when to compact, which model writes the summary, and what the summary says.\n * Its handler reads the chat's entries, has a model write a summary, and stores the summary as one\n * of the assistant's own events (see {@link Summary}). Its loop then reads the chat through\n * {@link since}. {@link inputTokens} helps decide when the prompt has grown large enough to\n * compact. The log keeps every entry, so the user still sees the whole chat.\n *\n * @since 0.1.0\n */\nimport type * as Prompt from \"effect/ai/Prompt\"\nimport * as Option from \"effect/Option\"\nimport * as Predicate from \"effect/Predicate\"\nimport type * as Assistant from \"./Assistant.ts\"\nimport * as AssistantActivity from \"./AssistantActivity.ts\"\nimport * as AssistantEvent from \"./AssistantEvent.ts\"\nimport * as BlockKit from \"./BlockKit.ts\"\nimport { userText } from \"./internal/history.ts\"\nimport { toJsonText } from \"./internal/schema.ts\"\nimport * as ToolApproval from \"./ToolApproval.ts\"\n\n/**\n * Represents the fields a summary event must have: its text and the last `seq` it covers.\n *\n * Entries after `throughSeq` are kept as they are, so an input that arrived while the summary was\n * being written isn't lost.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Summary {\n  readonly _tag: string\n  readonly text: string\n  readonly throughSeq: number\n}\n\n/**\n * Returns the number of input tokens used by the chat's last model call, which shows how large\n * the prompt has grown. Returns 0 before the first call.\n *\n * @category utils\n * @since 0.1.0\n */\nexport const inputTokens = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): number => {\n  const last = entries.findLast(\n    ({ event }) =>\n      AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, \"ModelOutput\") && event.usage !== undefined\n  )?.event\n\n  return last !== undefined && AssistantEvent.isLibraryEvent(last) && Predicate.isTagged(last, \"ModelOutput\")\n    ? (last.usage?.inputTokens.total ?? 0)\n    : 0\n}\n\n/**\n * Returns the items that were open at `throughSeq` and are still open: blocks the user hasn't\n * answered, specialists that are working, and tool calls waiting for the user's approval. The result is text for\n * the model, or `None` when nothing is open.\n *\n * @category utils\n * @since 0.1.0\n */\nexport const openItems = (\n  entries: ReadonlyArray<AssistantEvent.AnyEntry>,\n  throughSeq: number\n): Option.Option<string> => {\n  const seqOf = (found: (event: AssistantEvent.AnyEntry[\"event\"]) => boolean) =>\n    entries.find(({ event }) => found(event))?.seq ?? Number.POSITIVE_INFINITY\n\n  const opened = (seq: number) => seq <= throughSeq\n\n  const blocks = [...BlockKit.fromEntries(entries)].flatMap(([messageId, state]) => {\n    const shown = entries.find(\n      ({ event }) =>\n        AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, \"AssistantMessage\") && event.id === messageId\n    )\n\n    const message = shown?.event\n\n    return state.open &&\n      shown !== undefined &&\n      opened(shown.seq) &&\n      message !== undefined &&\n      AssistantEvent.isLibraryEvent(message) &&\n      Predicate.isTagged(message, \"AssistantMessage\")\n      ? [`- message ${messageId}, a ${message.block?.kind} block: ${message.text}`]\n      : []\n  })\n\n  const specialists = [...AssistantActivity.fromEntries(entries).specialists.values()].flatMap((run) =>\n    opened(\n      seqOf(\n        (event) =>\n          AssistantEvent.isLibraryEvent(event) &&\n          Predicate.isTagged(event, \"SpecialistStarted\") &&\n          event.runId === run.runId\n      )\n    )\n      ? [`- your ${run.specialist} specialist (${run.runId}), working on: ${run.goal}`]\n      : []\n  )\n\n  const approvals = [...ToolApproval.fromEntries(entries).values()].flatMap((approval) =>\n    approval.status === \"pending\" &&\n    opened(\n      seqOf(\n        (event) =>\n          AssistantEvent.isLibraryEvent(event) &&\n          Predicate.isTagged(event, \"ApprovalRequested\") &&\n          event.callId === approval.request.callId\n      )\n    )\n      ? [`- your call to ${approval.request.tool} (${approval.request.callId}): ${toJsonText(approval.request.params)}`]\n      : []\n  )\n\n  const sections = [\n    blocks.length > 0 ? `Blocks the user hasn't answered:\\n${blocks.join(\"\\n\")}` : \"\",\n    specialists.length > 0 ? `Specialists still working:\\n${specialists.join(\"\\n\")}` : \"\",\n    approvals.length > 0 ? `Calls waiting for the user's approval:\\n${approvals.join(\"\\n\")}` : \"\"\n  ].filter((section) => section.length > 0)\n\n  return sections.length === 0 ? Option.none() : Option.some(sections.join(\"\\n\\n\"))\n}\n\n/**\n * Returns the files the user attached up to `throughSeq`, as lines of text for the model, or\n * `None` when there are none. A summary may leave out a file's id, which tools need.\n *\n * @category utils\n * @since 0.1.0\n */\nexport const attachedFiles = (\n  entries: ReadonlyArray<AssistantEvent.AnyEntry>,\n  throughSeq: number\n): Option.Option<string> => {\n  const lines = entries.flatMap(({ seq, event }) =>\n    seq <= throughSeq && AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, \"UserMessage\")\n      ? (event.attachments ?? []).map(AssistantEvent.attachmentLine)\n      : []\n  )\n\n  return lines.length === 0 ? Option.none() : Option.some(lines.join(\"\\n\"))\n}\n\n/**\n * Creates a history view that starts at the last summary.\n *\n * **Details**\n *\n * `isSummary` identifies the app's summary events. The model reads the last summary, the files\n * attached earlier ({@link attachedFiles}), and the items that are still open\n * ({@link openItems}), followed by the entries after the summary. When the chat has no summary,\n * the view returns every entry.\n *\n * The app's other events after the summary stay entries, which the model doesn't read: map those\n * it should read to messages after this view, as with any history view (see\n * `Assistant.HistoryView`). A summary the handler appends wakes no turn.\n *\n * **Example** (Compacting a long chat after each turn)\n *\n * ```ts\n * import { Assistant, type AssistantEvent, Compaction } from \"effect-assistant\"\n * import * as LanguageModel from \"effect/ai/LanguageModel\"\n * import * as Effect from \"effect/Effect\"\n * import * as Schema from \"effect/Schema\"\n * import * as Stream from \"effect/Stream\"\n *\n * class Summary extends Schema.TaggedClass<Summary>()(\"Summary\", {\n *   text: Schema.String,\n *   throughSeq: Schema.Int\n * }) {}\n *\n * declare const transcript: (entries: ReadonlyArray<AssistantEvent.AnyEntry>) => string\n *\n * export const MyAssistant = Assistant.make(\"my-assistant\", { events: [Summary] })\n *\n * const MyAssistantLive = MyAssistant.toLayer((turn) => {\n *   const compact = Effect.gen(function* () {\n *     const chat = yield* MyAssistant.Chat\n *     const entries = yield* chat.entries\n *\n *     if (Compaction.inputTokens(entries) < 100_000) return\n *\n *     const { text } = yield* LanguageModel.generateText({\n *       prompt: `Summarize this chat:\\n\\n${transcript(entries)}`\n *     })\n *\n *     yield* chat.append(Summary.make({ text, throughSeq: entries.at(-1)?.seq ?? 0 }))\n *   })\n *\n *   // After the reply, so the user doesn't wait for the summary.\n *   return Stream.concat(\n *     turn.loop({ instructions: \"Be brief.\", history: Compaction.since(Schema.is(Summary)) }),\n *     Stream.drain(Stream.fromEffect(compact))\n *   )\n * })\n * ```\n *\n * @category utils\n * @since 0.1.0\n */\nexport const since =\n  (isSummary: (event: unknown) => event is Summary) =>\n  <Events extends { readonly _tag: string }>(\n    entries: ReadonlyArray<Assistant.Entry<Events>>\n  ): ReadonlyArray<Assistant.Entry<Events> | Prompt.Message> => {\n    const last = entries.findLast(({ event }) => isSummary(event))?.event\n\n    if (last === undefined || !isSummary(last)) return entries\n\n    const open = Option.match(openItems(entries, last.throughSeq), {\n      onNone: () => \"\",\n      onSome: (items) => `\\n\\n<still_open>\\n${items}\\n</still_open>`\n    })\n\n    const files = Option.match(attachedFiles(entries, last.throughSeq), {\n      onNone: () => \"\",\n      onSome: (lines) => `\\n\\n<files_attached_earlier>\\n${lines}\\n</files_attached_earlier>`\n    })\n\n    return [\n      userText(`<earlier_in_this_chat>\\n${last.text}\\n</earlier_in_this_chat>${files}${open}`),\n      ...entries.filter(({ seq, event }) => seq > last.throughSeq && !isSummary(event))\n    ]\n  }\n"],"mappings":"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"}

package/dist/Skill.d.ts

@@ -1,7 +1,11 @@
 import { Instructions, Instructions_d_exports } from "./Instructions.js";
+import { ToolFailure, ToolFailure_d_exports } from "./ToolFailure.js";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
 import * as Tool from "effect/ai/Tool";
+import * as AiToolkit from "effect/ai/Toolkit";
 declare namespace Skill_d_exports {
-  export { Services, Skill, make, withCatalog };
+  export { LoadSkill, Services, Skill, Toolkit, make, toolkit };
 }
 /**
  * Represents a skill.
@@ -17,11 +21,6 @@ export interface Skill<R = never> {
   readonly description: string;
   /** Text, or an Effect resolved each time the skill is loaded. */
   readonly 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;
 }
 /**
  * Creates a skill from its name, a description of when to use it, and its instructions.
@@ -30,12 +29,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)
  *
@@ -48,30 +42,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
@@ -82,8 +52,6 @@ export declare const make: <R = never>(name: string, options: {
   readonly description: string;
   /** Text, or an Effect resolved each time the skill is loaded. */
   readonly 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>;
 /**
  * Extracts the services that skills need when they're loaded.
@@ -92,14 +60,88 @@ export declare const make: <R = never>(name: string, options: {
  * @since 0.1.0
  */
 export type Services<S> = S extends Skill<infer R> ? R : never;
+declare const loadSkill: (description: string) => Tool.Tool<"load_skill", {
+  readonly parameters: Schema.Struct<{
+    readonly name: Schema.String;
+  }>;
+  readonly success: Schema.String;
+  readonly failure: typeof ToolFailure;
+  readonly failureMode: "error";
+}, never>;
 /**
- * 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>;
+}
+/**
+ * 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 declare const withCatalog: <R>(prompt: string, skills: ReadonlyArray<Skill<R>>) => string;
+export declare const toolkit: <const Skills extends ReadonlyArray<Skill<unknown>>>(skills: Skills) => Toolkit<Services<Skills[number]>>;
 //#endregion
 export { Skill_d_exports };
 //# sourceMappingURL=Skill.d.ts.map

package/dist/Skill.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Skill.d.ts","names":[],"sources":["../src/Skill.ts"],"mappings":";;;;;;;;;;;;;iBAoBiB,MAAM;WACZ;;WAEA;;WAEA,cAAc,aAA0B;;;;;WAKxC,QAAQ,cAAc,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAyDzB,OAAQ,WAAS,cAChB;;WAGD;;WAEA,cAAc,aAA0B;;WAExC,QAAQ,cAAc,KAAK;MAErC,MAAM;;;;;;;YAQG,SAAS,KAAK,UAAU,YAAY,KAAK;;;;;;;;qBASxC,cAAe,GAAC,gBAAgB,QAAU,cAAc,MAAM"}
+{"version":3,"file":"Skill.d.ts","names":[],"sources":["../src/Skill.ts"],"mappings":";;;;;;;;;;;;;;;;;iBAyBiB,MAAM;WACZ;;WAEA;;WAEA,cAAc,aAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA4BtC,OAAQ,WAAS,cAChB;;WAGD;;WAEA,cAAc,aAA0B;MAElD,MAAM;;;;;;;YAQG,SAAS,KAAK,UAAU,YAAY,KAAK;cAE/C,YAAS,wBAAuB,KAAA;;;;;;;;;;;;;;YAc1B,YAAY,kBAAkB;;;;;;;;;iBAUzB,QAAQ,mBAAmB,UAAU;WAAmB,YAAY;;;WAE1E,OAAO,MAAM,MAAM,KAAK,8BAA8B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAgGpD,gBAAgB,eAAe,cAAc,iBACxD,QAAQ,WACL,QAAQ,SAAS"}

package/dist/Skill.js

@@ -1,8 +1,23 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { ToolFailure, fail } from "./ToolFailure.js";
+import { resolve } from "./Instructions.js";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Tool from "effect/ai/Tool";
+import * as AiToolkit from "effect/ai/Toolkit";
 //#region src/Skill.ts
+/**
+* Defines skills, which are playbooks with step-by-step instructions for a kind of task.
+*
+* 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
+*/
 var Skill_exports = /* @__PURE__ */ __exportAll({
 	make: () => make,
-	withCatalog: () => withCatalog
+	toolkit: () => toolkit
 });
 /**
 * Creates a skill from its name, a description of when to use it, and its instructions.
@@ -11,12 +26,7 @@ var Skill_exports = /* @__PURE__ */ __exportAll({
 *
 * 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)
 *
@@ -29,56 +39,95 @@ var Skill_exports = /* @__PURE__ */ __exportAll({
 * 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.`
 * })
+* ```
+*
+* @category constructors
+* @since 0.1.0
+*/
+const make = (name, options) => ({
+	name,
+	description: options.description,
+	instructions: options.instructions
+});
+const loadSkill = (description) => Tool.make("load_skill", {
+	description,
+	parameters: Schema.Struct({ name: Schema.String }),
+	success: Schema.String,
+	failure: ToolFailure
+});
+const catalog = (skills) => [
+	"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(skills) {
+	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();
+		return { load_skill: Effect.fnUntraced(function* ({ name }) {
+			const skill = byName.get(name);
+			if (skill === void 0) return yield* fail(`No skill named ${name}. The skills are: ${skills.map((known) => known.name).join(", ")}.`);
+			return (yield* resolve(skill.instructions).pipe(Effect.provideContext(context))).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, skills: [orderingCampaigns] })
-* )
+*   turn.loop({ instructions, toolkit: Toolkit.merge(MyTools, AssistantSkills) })
+* ).pipe(Layer.provide([MyToolsLive, AssistantSkills.layer]))
 * ```
 *
-* **Example** (Offering a skill only with the tools it uses)
+* **Example** (Offering each user the skills their role allows)
 *
 * ```ts
 * import { Skill } from "effect-assistant"
-* import * as Tool from "effect/ai/Tool"
-* import * as Schema from "effect/Schema"
+* import * as Effect from "effect/Effect"
+* import * as Stream from "effect/Stream"
+* import * as Toolkit from "effect/ai/Toolkit"
 *
-* const StartCampaign = Tool.make("start_campaign", {
-*   parameters: Schema.Struct({ campaignId: Schema.String, budget: Schema.Finite }),
-*   success: Schema.String
-* })
+* const MyAssistantLive = MyAssistant.toLayer((turn) =>
+*   Stream.unwrap(
+*     Effect.map(roleOf(turn.chatId), (role) => {
+*       const skills = Skill.toolkit(allSkills.filter((skill) => allowed(role, skill)))
 *
-* // 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]
-* })
+*       return turn
+*         .loop({ instructions, toolkit: Toolkit.merge(MyTools, skills) })
+*         .pipe(Stream.provide(skills.layer))
+*     })
+*   )
+* )
 * ```
 *
 * @category constructors
-* @since 0.1.0
-*/
-const make = (name, options) => ({
-	name,
-	description: options.description,
-	instructions: options.instructions,
-	tools: options.tools
-});
-/**
-* Returns the prompt with the skills' catalog appended, or the prompt unchanged when there are no
-* skills.
-*
-* @category utils
-* @since 0.1.0
+* @since 0.4.0
 */
-const withCatalog = (prompt, skills) => 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");
+const toolkit = toolkitOf;
 //#endregion
-export { Skill_exports, make, withCatalog };
+export { Skill_exports, make, toolkit };
 
 //# sourceMappingURL=Skill.js.map

package/dist/Skill.js.map

@@ -1 +1 @@
-{"version":3,"file":"Skill.js","names":[],"sources":["../src/Skill.ts"],"sourcesContent":["/**\n * Defines skills, which are playbooks with step-by-step instructions for a kind of task.\n *\n * A loop lists its skills as a catalog in the prompt, with each skill's name and description\n * ({@link withCatalog}). The model loads a skill's instructions with the `load_skill` tool when a\n * task matches.\n *\n * @since 0.1.0\n */\nimport type * as Tool from \"effect/ai/Tool\"\nimport type * as Instructions from \"./Instructions.ts\"\n\n/**\n * Represents a skill.\n *\n * `R` is the services its instructions need when they're loaded.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Skill<R = never> {\n  readonly name: string\n  /** When to use it, in one line. This is all the model sees until it loads the skill. */\n  readonly description: string\n  /** Text, or an Effect resolved each time the skill is loaded. */\n  readonly instructions: Instructions.Instructions<R>\n  /**\n   * The tools its instructions use. A loop offers the skill only when its toolkit has every one of\n   * them, matched by name. Unset, a loop always offers it.\n   */\n  readonly tools?: ReadonlyArray<Tool.Any> | undefined\n}\n\n/**\n * Creates a skill from its name, a description of when to use it, and its instructions.\n *\n * **Details**\n *\n * Write the description as a trigger (\"Use when…\"), since it's all the model sees until it loads\n * the skill. The instructions are text, or an Effect that is resolved each time the skill is\n * loaded.\n *\n * `tools` lists the tools the instructions use. A loop whose toolkit lacks any of them, matched by\n * name, leaves the skill out of its catalog and of `load_skill`, so a loop that gets its tools per\n * user (by role, say) never offers a playbook it can't follow. A tool that only `ToolDiscovery`\n * finds isn't in the toolkit, so it doesn't count. Without `tools`, every loop offers the skill.\n *\n * **Example** (Defining a playbook for ordering campaigns)\n *\n * ```ts\n * import { Skill } from \"effect-assistant\"\n *\n * const orderingCampaigns = Skill.make(\"Ordering a campaign\", {\n *   description: \"Use when the user wants to order or start a campaign.\",\n *   instructions: `1. Pick the product with list_campaign_products.\n * 2. You need who it should reach and a budget. Ask for what's missing, one question at a time.\n * 3. When you have both, call start_campaign.`\n * })\n *\n * const MyAssistantLive = MyAssistant.toLayer((turn) =>\n *   turn.loop({ instructions, skills: [orderingCampaigns] })\n * )\n * ```\n *\n * **Example** (Offering a skill only with the tools it uses)\n *\n * ```ts\n * import { Skill } from \"effect-assistant\"\n * import * as Tool from \"effect/ai/Tool\"\n * import * as Schema from \"effect/Schema\"\n *\n * const StartCampaign = Tool.make(\"start_campaign\", {\n *   parameters: Schema.Struct({ campaignId: Schema.String, budget: Schema.Finite }),\n *   success: Schema.String\n * })\n *\n * // Left out of a loop whose toolkit has no start_campaign, like a viewer's.\n * const orderingCampaigns = Skill.make(\"Ordering a campaign\", {\n *   description: \"Use when the user wants to order or start a campaign.\",\n *   instructions: \"When you know who it should reach and the budget, call start_campaign.\",\n *   tools: [StartCampaign]\n * })\n * ```\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = <R = never>(\n  name: string,\n  options: {\n    /** When to use it, in one line. This is all the model sees until it loads the skill. */\n    readonly description: string\n    /** Text, or an Effect resolved each time the skill is loaded. */\n    readonly instructions: Instructions.Instructions<R>\n    /** The tools its instructions use: a loop whose toolkit lacks one leaves the skill out. */\n    readonly tools?: ReadonlyArray<Tool.Any> | undefined\n  }\n): Skill<R> => ({ name, description: options.description, instructions: options.instructions, tools: options.tools })\n\n/**\n * Extracts the services that skills need when they're loaded.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type Services<S> = S extends Skill<infer R> ? R : never\n\n/**\n * Returns the prompt with the skills' catalog appended, or the prompt unchanged when there are no\n * skills.\n *\n * @category utils\n * @since 0.1.0\n */\nexport const withCatalog = <R>(prompt: string, skills: ReadonlyArray<Skill<R>>): string =>\n  skills.length === 0\n    ? prompt\n    : [\n        prompt,\n        \"\",\n        \"## Skills\",\n        \"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.\",\n        ...skills.map((skill) => `- ${skill.name}: ${skill.description}`)\n      ].join(\"\\n\")\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuFA,MAAa,QACX,MACA,aAQc;CAAE;CAAM,aAAa,QAAQ;CAAa,cAAc,QAAQ;CAAc,OAAO,QAAQ;AAAM;;;;;;;;AAiBnH,MAAa,eAAkB,QAAgB,WAC7C,OAAO,WAAW,IACd,SACA;CACE;CACA;CACA;CACA;CACA,GAAG,OAAO,KAAK,UAAU,KAAK,MAAM,KAAK,IAAI,MAAM,aAAa;AAClE,CAAC,CAAC,KAAK,IAAI"}
+{"version":3,"file":"Skill.js","names":["ToolFailure.ToolFailure","ToolFailure.fail","Instructions.resolve"],"sources":["../src/Skill.ts"],"sourcesContent":["/**\n * Defines skills, which are playbooks with step-by-step instructions for a kind of task.\n *\n * A list of skills becomes a toolkit with one tool, `load_skill` ({@link toolkit}). Its\n * description is the catalog, each skill's name and when to use it, and the model calls it to read\n * a skill's instructions when a task matches. Merge it into a loop's toolkit like any other.\n *\n * @since 0.1.0\n */\nimport * as Tool from \"effect/ai/Tool\"\nimport * as AiToolkit from \"effect/ai/Toolkit\"\nimport * as Effect from \"effect/Effect\"\nimport type * as Layer from \"effect/Layer\"\nimport * as Schema from \"effect/Schema\"\nimport * as Instructions from \"./Instructions.ts\"\nimport * as ToolFailure from \"./ToolFailure.ts\"\n\n/**\n * Represents a skill.\n *\n * `R` is the services its instructions need when they're loaded.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Skill<R = never> {\n  readonly name: string\n  /** When to use it, in one line. This is all the model sees until it loads the skill. */\n  readonly description: string\n  /** Text, or an Effect resolved each time the skill is loaded. */\n  readonly instructions: Instructions.Instructions<R>\n}\n\n/**\n * Creates a skill from its name, a description of when to use it, and its instructions.\n *\n * **Details**\n *\n * Write the description as a trigger (\"Use when…\"), since it's all the model sees until it loads\n * the skill. The instructions are text, or an Effect that is resolved each time the skill is\n * loaded. Offer skills to a loop with {@link toolkit}.\n *\n * **Example** (Defining a playbook for ordering campaigns)\n *\n * ```ts\n * import { Skill } from \"effect-assistant\"\n *\n * const orderingCampaigns = Skill.make(\"Ordering a campaign\", {\n *   description: \"Use when the user wants to order or start a campaign.\",\n *   instructions: `1. Pick the product with list_campaign_products.\n * 2. You need who it should reach and a budget. Ask for what's missing, one question at a time.\n * 3. When you have both, call start_campaign.`\n * })\n * ```\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = <R = never>(\n  name: string,\n  options: {\n    /** When to use it, in one line. This is all the model sees until it loads the skill. */\n    readonly description: string\n    /** Text, or an Effect resolved each time the skill is loaded. */\n    readonly instructions: Instructions.Instructions<R>\n  }\n): Skill<R> => ({ name, description: options.description, instructions: options.instructions })\n\n/**\n * Extracts the services that skills need when they're loaded.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type Services<S> = S extends Skill<infer R> ? R : never\n\nconst loadSkill = (description: string) =>\n  Tool.make(\"load_skill\", {\n    description,\n    parameters: Schema.Struct({ name: Schema.String }),\n    success: Schema.String,\n    failure: ToolFailure.ToolFailure\n  })\n\n/**\n * Represents the `load_skill` tool, which reads a skill's instructions by name.\n *\n * @category models\n * @since 0.4.0\n */\nexport type LoadSkill = ReturnType<typeof loadSkill>\n\n/**\n * Represents a list of skills as a toolkit: the `load_skill` tool, and the layer with its handler.\n *\n * `R` is the services the skills' instructions need, which the layer requires.\n *\n * @category models\n * @since 0.4.0\n */\nexport interface Toolkit<R = never> extends AiToolkit.Toolkit<{ readonly load_skill: LoadSkill }> {\n  /** The handler of `load_skill`, which resolves the instructions of these skills. */\n  readonly layer: Layer.Layer<Tool.Handler<\"load_skill\">, never, R>\n}\n\nconst catalog = (skills: ReadonlyArray<Skill<unknown>>): string =>\n  [\n    \"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.\",\n    \"\",\n    \"Skills:\",\n    ...skills.map((skill) => `- ${skill.name}: ${skill.description}`)\n  ].join(\"\\n\")\n\nfunction toolkitOf<const Skills extends ReadonlyArray<Skill<unknown>>>(\n  skills: Skills\n): Toolkit<Services<Skills[number]>>\n// The overload states what the layer requires: the services of these skills' instructions.\nfunction toolkitOf(skills: ReadonlyArray<Skill<unknown>>): Toolkit<unknown> {\n  const byName = new Map(skills.map((skill) => [skill.name, skill]))\n  const tools = AiToolkit.make(loadSkill(catalog(skills)))\n\n  const layer = tools.toLayer(\n    Effect.gen(function* () {\n      const context = yield* Effect.context<unknown>()\n\n      return {\n        load_skill: Effect.fnUntraced(function* ({ name }) {\n          const skill = byName.get(name)\n\n          if (skill === undefined) {\n            return yield* ToolFailure.fail(\n              `No skill named ${name}. The skills are: ${skills.map((known) => known.name).join(\", \")}.`\n            )\n          }\n\n          const resolved = yield* Instructions.resolve(skill.instructions).pipe(Effect.provideContext(context))\n\n          return resolved.text\n        })\n      }\n    })\n  )\n\n  return Object.assign(tools, { layer })\n}\n\n/**\n * Creates a toolkit from a list of skills: the `load_skill` tool, whose description lists each\n * skill's name and when to use it, and its handler's `layer`.\n *\n * **Details**\n *\n * Merge the toolkit into a loop's own with `Toolkit.merge`, and provide its `layer`, which requires\n * the services the skills' instructions need. The model loads a skill by name; a name that isn't\n * in the list is a failure the model reads, with the names there are.\n *\n * The handler resolves only the skills of its own list. To offer each user the skills they may\n * use, build the toolkit in the turn from that user's list, and provide its layer to the loop's\n * stream (`Stream.provide(skills.layer)`): building one does no work.\n *\n * **Example** (Giving an assistant its playbooks)\n *\n * ```ts\n * import { Skill } from \"effect-assistant\"\n * import * as Layer from \"effect/Layer\"\n * import * as Toolkit from \"effect/ai/Toolkit\"\n *\n * const AssistantSkills = Skill.toolkit([orderingCampaigns, sharingAssets])\n *\n * const MyAssistantLive = MyAssistant.toLayer((turn) =>\n *   turn.loop({ instructions, toolkit: Toolkit.merge(MyTools, AssistantSkills) })\n * ).pipe(Layer.provide([MyToolsLive, AssistantSkills.layer]))\n * ```\n *\n * **Example** (Offering each user the skills their role allows)\n *\n * ```ts\n * import { Skill } from \"effect-assistant\"\n * import * as Effect from \"effect/Effect\"\n * import * as Stream from \"effect/Stream\"\n * import * as Toolkit from \"effect/ai/Toolkit\"\n *\n * const MyAssistantLive = MyAssistant.toLayer((turn) =>\n *   Stream.unwrap(\n *     Effect.map(roleOf(turn.chatId), (role) => {\n *       const skills = Skill.toolkit(allSkills.filter((skill) => allowed(role, skill)))\n *\n *       return turn\n *         .loop({ instructions, toolkit: Toolkit.merge(MyTools, skills) })\n *         .pipe(Stream.provide(skills.layer))\n *     })\n *   )\n * )\n * ```\n *\n * @category constructors\n * @since 0.4.0\n */\nexport const toolkit: <const Skills extends ReadonlyArray<Skill<unknown>>>(\n  skills: Skills\n) => Toolkit<Services<Skills[number]>> = toolkitOf\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0DA,MAAa,QACX,MACA,aAMc;CAAE;CAAM,aAAa,QAAQ;CAAa,cAAc,QAAQ;AAAa;AAU7F,MAAM,aAAa,gBACjB,KAAK,KAAK,cAAc;CACtB;CACA,YAAY,OAAO,OAAO,EAAE,MAAM,OAAO,OAAO,CAAC;CACjD,SAAS,OAAO;CAChB,SAASA;AACX,CAAC;AAuBH,MAAM,WAAW,WACf;CACE;CACA;CACA;CACA,GAAG,OAAO,KAAK,UAAU,KAAK,MAAM,KAAK,IAAI,MAAM,aAAa;AAClE,CAAC,CAAC,KAAK,IAAI;AAMb,SAAS,UAAU,QAAyD;CAC1E,MAAM,SAAS,IAAI,IAAI,OAAO,KAAK,UAAU,CAAC,MAAM,MAAM,KAAK,CAAC,CAAC;CACjE,MAAM,QAAQ,UAAU,KAAK,UAAU,QAAQ,MAAM,CAAC,CAAC;CAEvD,MAAM,QAAQ,MAAM,QAClB,OAAO,IAAI,aAAa;EACtB,MAAM,UAAU,OAAO,OAAO,QAAiB;EAE/C,OAAO,EACL,YAAY,OAAO,WAAW,WAAW,EAAE,QAAQ;GACjD,MAAM,QAAQ,OAAO,IAAI,IAAI;GAE7B,IAAI,UAAU,KAAA,GACZ,OAAO,OAAOC,KACZ,kBAAkB,KAAK,oBAAoB,OAAO,KAAK,UAAU,MAAM,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,EAC1F;GAKF,QAAO,OAFiBC,QAAqB,MAAM,YAAY,CAAC,CAAC,KAAK,OAAO,eAAe,OAAO,CAAC,EAAA,CAEpF;EAClB,CAAC,EACH;CACF,CAAC,CACH;CAEA,OAAO,OAAO,OAAO,OAAO,EAAE,MAAM,CAAC;AACvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsDA,MAAa,UAE4B"}

package/dist/Specialist.d.ts

@@ -3,7 +3,6 @@ import { Instructions_d_exports, Resolved } from "./Instructions.js";
 import { AssistantLoop_d_exports, Event, ToolkitServices } from "./AssistantLoop.js";
 import { CurrentChat } from "./CurrentChat.js";
 import { RunId } from "./RunId.js";
-import { Skill } from "./Skill.js";
 import * as Context from "effect/Context";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
@@ -103,15 +102,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 | 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;
 }
@@ -131,8 +128,8 @@ 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>) => Stream.Stream<Event, AiError.AiError, LanguageModel.LanguageModel | ToolkitServices<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<Event, AiError.AiError, LanguageModel.LanguageModel | ToolkitServices<T>>;
 }
 /**
  * Represents a specialist's handler, which works on a brief and returns a stream of what the loop

package/dist/Specialist.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Specialist.d.ts","names":[],"sources":["../src/Specialist.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;cA2BM;;;;;;;iBAQW,WAAW;YAChB,gBAAgB;WACjB,MAAM;;WAEN;;WAEA,SAAS,QAAQ,IAAI,kBAAkB,OAAO;;;;;WAK9C,UAAU,WAAW,YAAY,WAAW,YACnD,QAAQ,QAAQ,GAAG,MAAM,OAAO,OAAO,QAAQ,GAAG,KAAK,GAAG,OACxD,cAAc,QAAQ,IAAI,IAAI,cAAc,KAAK,KAAK,sBACrD,MAAM,MAAM,kBAAkB,cAAc,QAAQ,IAAI,MAAM,QAAQ,eAAe,aAAa,IAAI;;;;;;;;;;;;;;YAejG,cAAc,eAAe;WAG1B;aACE;aACA,UAAU;;;;;;;;;;;;YAaf,aAAa,KAAK,QAAQ,GAAG,KAAK;;;;;;;YAQlC,MAAM;;;;;;;iBAQD,kBAAkB;WACxB,oBAAoB;;;;;;;;YASnB,UAAU,KAAK,UAAU,iBAAiB,QAAQ,kBAAkB;;;;;;;;YASpE,cAAc,cAAc,SAAS,cAAc;;;;;;;iBAQ9C,YAAY,UAAU,eAAe,KAAK,OAAO,sBAAsB;WAC7E,uBAAuB;;WAEvB,UAAU,QAAQ,QAAQ;;;;;WAK1B,SAAS,cAAc,MAAM;;WAE7B;;;;;;;;iBASM;WACN,OAAO;;WAEP,QAAQ;WACR,OAAO;;;;;WAKP,SAAS,OAAO,OAAO,cAAc,OAAO;;WAE5C,OAAO,UAAU,eAAe,KAAK,OAAO,sBAAsB,YACzE,SAAS,YAAY,GAAG,QACrB,OAAO,OACV,OACA,QAAQ,SACR,cAAc,gBAAgB,gBAA8B,KAAK;;;;;;;;;;;;YAczD,QAAQ,WAAW,KAAK,MAClC,KAAK,QAEH,OAAO,OAAO,gBAA8B,KAC5C,OAAO,OAAO,OAAO,OAAO,gBAA8B,aAAa;;;;;;;;;;iBAW1D;WACN,MAAM,OAAO,QACnB,KAAK,QAAQ,OAAO,OAAO,gBAA8B,qBAE1D,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA8CL,aAAc,qBAAmB,MACtC,MAAI;;WAGC;MAEV,WAAW;;;;;;;;;qBA0CD,OAAK,OAAA;;;;;;;;;;;;;YAoBN,eAAe,MAAM;;;;;;;iBAQhB;;WAEN;WACA,OAAO;;;;;;;;;;;;;;;;;;;qBAeL,wBAAwB;;;WAkBjB,QAAC,SAAS,iBAAiB,OAAO,OAAO,OAAO;;WAE9C,UAAC,OAAO,OAAO,iBAAiB,OAAO,gCAAgC;;WAE1E,OAAC,OAAO,UAAU,OAAO,aAAa;;;;;;;;;;qBAR5C,eAAe"}
+{"version":3,"file":"Specialist.d.ts","names":[],"sources":["../src/Specialist.ts"],"mappings":";;;;;;;;;;;;;;;;;;;cA0BM;;;;;;;iBAQW,WAAW;YAChB,gBAAgB;WACjB,MAAM;;WAEN;;WAEA,SAAS,QAAQ,IAAI,kBAAkB,OAAO;;;;;WAK9C,UAAU,WAAW,YAAY,WAAW,YACnD,QAAQ,QAAQ,GAAG,MAAM,OAAO,OAAO,QAAQ,GAAG,KAAK,GAAG,OACxD,cAAc,QAAQ,IAAI,IAAI,cAAc,KAAK,KAAK,sBACrD,MAAM,MAAM,kBAAkB,cAAc,QAAQ,IAAI,MAAM,QAAQ,eAAe,aAAa,IAAI;;;;;;;;;;;;;;YAejG,cAAc,eAAe;WAG1B;aACE;aACA,UAAU;;;;;;;;;;;;YAaf,aAAa,KAAK,QAAQ,GAAG,KAAK;;;;;;;YAQlC,MAAM;;;;;;;iBAQD,kBAAkB;WACxB,oBAAoB;;;;;;;;YASnB,UAAU,KAAK,UAAU,iBAAiB,QAAQ,kBAAkB;;;;;;;;YASpE,cAAc,cAAc,SAAS,cAAc;;;;;;;iBAQ9C,YAAY,UAAU,eAAe,KAAK,OAAO;WACvD,uBAAuB;;;;;WAKvB,UAAU,QAAQ,QAAQ;;WAE1B;;;;;;;;iBASM;WACN,OAAO;;WAEP,QAAQ;WACR,OAAO;;;;;WAKP,SAAS,OAAO,OAAO,cAAc,OAAO;;WAE5C,OAAO,UAAU,eAAe,KAAK,OAAO,sBACnD,SAAS,YAAY,OAClB,OAAO,OACV,OACA,QAAQ,SACR,cAAc,gBAAgB,gBAA8B;;;;;;;;;;;;YAcpD,QAAQ,WAAW,KAAK,MAClC,KAAK,QAEH,OAAO,OAAO,gBAA8B,KAC5C,OAAO,OAAO,OAAO,OAAO,gBAA8B,aAAa;;;;;;;;;;iBAW1D;WACN,MAAM,OAAO,QACnB,KAAK,QAAQ,OAAO,OAAO,gBAA8B,qBAE1D,MAAM,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA8CL,aAAc,qBAAmB,MACtC,MAAI;;WAGC;MAEV,WAAW;;;;;;;;;qBA0CD,OAAK,OAAA;;;;;;;;;;;;;YAoBN,eAAe,MAAM;;;;;;;iBAQhB;;WAEN;WACA,OAAO;;;;;;;;;;;;;;;;;;;qBAeL,wBAAwB;;;WAkBjB,QAAC,SAAS,iBAAiB,OAAO,OAAO,OAAO;;WAE9C,UAAC,OAAO,OAAO,iBAAiB,OAAO,gCAAgC;;WAE1E,OAAC,OAAO,UAAU,OAAO,aAAa;;;;;;;;;;qBAR5C,eAAe"}