effect-assistant 0.2.0 → 0.4.0

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"));
 };
 /**
@@ -64,10 +71,14 @@ const attachedFiles = (entries, throughSeq) => {
 * ({@link openItems}), followed by the entries after the summary. When the chat has no summary,
 * the view returns every entry.
 *
+* The app's other events after the summary stay entries, which the model doesn't read: map those
+* it should read to messages after this view, as with any history view (see
+* `Assistant.HistoryView`). A summary the handler appends wakes no turn.
+*
 * **Example** (Compacting a long chat after each turn)
 *
 * ```ts
-* import { AppEvent, Assistant, type AssistantEvent, Compaction } from "effect-assistant"
+* import { Assistant, type AssistantEvent, Compaction } from "effect-assistant"
 * import * as LanguageModel from "effect/ai/LanguageModel"
 * import * as Effect from "effect/Effect"
 * import * as Schema from "effect/Schema"
@@ -80,7 +91,7 @@ const attachedFiles = (entries, throughSeq) => {
 *
 * declare const transcript: (entries: ReadonlyArray<AssistantEvent.AnyEntry>) => string
 *
-* export const MyAssistant = Assistant.make("my-assistant", { events: [AppEvent.make(Summary)] })
+* export const MyAssistant = Assistant.make("my-assistant", { events: [Summary] })
 *
 * const MyAssistantLive = MyAssistant.toLayer((turn) => {
 *   const compact = Effect.gen(function* () {

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 * **Example** (Compacting a long chat after each turn)\n *\n * ```ts\n * import { AppEvent, 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: [AppEvent.make(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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"}
+{"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/CurrentChat.d.ts

@@ -16,7 +16,8 @@ declare const CurrentChat_base: Context.ServiceClass<CurrentChat, "effect-assist
   /**
    * Appends events after the chat's last entry and sends them to the chat's subscribers. The
    * events can be the library's or the assistant's own (registered with its `events` option),
-   * such as a summary. An event that wakes a turn is handled by the next turn.
+   * such as a summary. An app event appended here wakes no turn: only one that comes in through
+   * the assistant's `submit` does.
    */
   readonly append: (...events: ReadonlyArray<{
     readonly _tag: string;

package/dist/CurrentChat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CurrentChat.d.ts","names":[],"sources":["../src/CurrentChat.ts"],"mappings":";;;;;;;;WAgCqB,QAAA;;;;;;WAMC,SAAA,OAAO,OAAO,cAAc;;;;;;WAM7B,YAAI,QAAQ;aAAyB;SAAoB,OAAO;;;;;;;;;;;;;;qBAfxE,oBAAoB"}
+{"version":3,"file":"CurrentChat.d.ts","names":[],"sources":["../src/CurrentChat.ts"],"mappings":";;;;;;;;WAgCqB,QAAA;;;;;;WAMC,SAAA,OAAO,OAAO,cAAc;;;;;;;WAO7B,YAAI,QAAQ;aAAyB;SAAoB,OAAO;;;;;;;;;;;;;;qBAhBxE,oBAAoB"}

package/dist/CurrentChat.js.map

@@ -1 +1 @@
-{"version":3,"file":"CurrentChat.js","names":[],"sources":["../src/CurrentChat.ts"],"sourcesContent":["/**\n * This module provides the `CurrentChat` service, which gives code that runs inside a chat\n * access to that chat: its id, its entries, and a way to append to it.\n *\n * A turn's handler, its tools, and its specialists' runs get the chat with `yield* CurrentChat`.\n * Inside a specialist's run, it is the chat the run belongs to, which is the chat of the turn\n * that spawned the run. The service doesn't carry an assistant's event types, so code that\n * doesn't know the assistant, such as a shared tool, can use it. Code that knows the assistant\n * can use `MyAssistant.Chat`, which is the same chat typed with the assistant's events.\n *\n * @since 0.1.0\n */\nimport * as Context from \"effect/Context\"\nimport type * as Effect from \"effect/Effect\"\nimport type * as AssistantEvent from \"./AssistantEvent.ts\"\nimport type { ChatId } from \"./ChatId.ts\"\n\n/**\n * Service that represents the chat the current code runs in.\n *\n * **Details**\n *\n * In a turn, it is the chat the turn runs in. In a specialist's run, and in its handler's build,\n * it is the chat the run belongs to: the chat of the turn that spawned the run. A run's tools\n * read and append to that chat.\n *\n * @category services\n * @since 0.1.0\n */\nexport class CurrentChat extends Context.Service<\n  CurrentChat,\n  {\n    readonly chatId: ChatId\n    /**\n     * The chat's entries so far, in order. They include the library's events and the assistant's\n     * own events, decoded; check for these with `Schema.is(MyEvent)` or `instanceof`. An app event\n     * that no longer decodes is left out.\n     */\n    readonly entries: Effect.Effect<ReadonlyArray<AssistantEvent.AnyEntry>>\n    /**\n     * Appends events after the chat's last entry and sends them to the chat's subscribers. The\n     * events can be the library's or the assistant's own (registered with its `events` option),\n     * such as a summary. An event that wakes a turn is handled by the next turn.\n     */\n    readonly append: (...events: ReadonlyArray<{ readonly _tag: string }>) => Effect.Effect<void>\n  }\n>()(\"effect-assistant/CurrentChat\") {}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,IAAa,cAAb,cAAiC,QAAQ,QAiBvC,CAAC,CAAC,8BAA8B,CAAC,CAAC,CAAC"}
+{"version":3,"file":"CurrentChat.js","names":[],"sources":["../src/CurrentChat.ts"],"sourcesContent":["/**\n * This module provides the `CurrentChat` service, which gives code that runs inside a chat\n * access to that chat: its id, its entries, and a way to append to it.\n *\n * A turn's handler, its tools, and its specialists' runs get the chat with `yield* CurrentChat`.\n * Inside a specialist's run, it is the chat the run belongs to, which is the chat of the turn\n * that spawned the run. The service doesn't carry an assistant's event types, so code that\n * doesn't know the assistant, such as a shared tool, can use it. Code that knows the assistant\n * can use `MyAssistant.Chat`, which is the same chat typed with the assistant's events.\n *\n * @since 0.1.0\n */\nimport * as Context from \"effect/Context\"\nimport type * as Effect from \"effect/Effect\"\nimport type * as AssistantEvent from \"./AssistantEvent.ts\"\nimport type { ChatId } from \"./ChatId.ts\"\n\n/**\n * Service that represents the chat the current code runs in.\n *\n * **Details**\n *\n * In a turn, it is the chat the turn runs in. In a specialist's run, and in its handler's build,\n * it is the chat the run belongs to: the chat of the turn that spawned the run. A run's tools\n * read and append to that chat.\n *\n * @category services\n * @since 0.1.0\n */\nexport class CurrentChat extends Context.Service<\n  CurrentChat,\n  {\n    readonly chatId: ChatId\n    /**\n     * The chat's entries so far, in order. They include the library's events and the assistant's\n     * own events, decoded; check for these with `Schema.is(MyEvent)` or `instanceof`. An app event\n     * that no longer decodes is left out.\n     */\n    readonly entries: Effect.Effect<ReadonlyArray<AssistantEvent.AnyEntry>>\n    /**\n     * Appends events after the chat's last entry and sends them to the chat's subscribers. The\n     * events can be the library's or the assistant's own (registered with its `events` option),\n     * such as a summary. An app event appended here wakes no turn: only one that comes in through\n     * the assistant's `submit` does.\n     */\n    readonly append: (...events: ReadonlyArray<{ readonly _tag: string }>) => Effect.Effect<void>\n  }\n>()(\"effect-assistant/CurrentChat\") {}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,IAAa,cAAb,cAAiC,QAAQ,QAkBvC,CAAC,CAAC,8BAA8B,CAAC,CAAC,CAAC"}

package/dist/Instructions.js

@@ -1,6 +1,6 @@
 import { __exportAll } from "./_virtual/_rolldown/runtime.js";
-import * as Predicate from "effect/Predicate";
 import * as Effect from "effect/Effect";
+import * as Predicate from "effect/Predicate";
 //#region src/Instructions.ts
 /**
 * Defines the instructions that tell an assistant, specialist, or skill what to do.

package/dist/Skill.d.ts

@@ -1,6 +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.
@@ -24,7 +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.
+ * loaded. Offer skills to a loop with {@link toolkit}.
  *
  * **Example** (Defining a playbook for ordering campaigns)
  *
@@ -37,10 +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] })
- * )
  * ```
  *
  * @category constructors
@@ -59,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":";;;;;;;;;;;;iBAmBiB,MAAM;WACZ;;WAEA;;WAEA,cAAc,aAA0B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAgCtC,OAAQ,WAAS,cAChB;;WAGD;;WAEA,cAAc,aAA0B;MAElD,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,7 +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.
+* loaded. Offer skills to a loop with {@link toolkit}.
 *
 * **Example** (Defining a playbook for ordering campaigns)
 *
@@ -24,10 +39,6 @@ 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.`
 * })
-*
-* const MyAssistantLive = MyAssistant.toLayer((turn) =>
-*   turn.loop({ instructions, skills: [orderingCampaigns] })
-* )
 * ```
 *
 * @category constructors
@@ -38,21 +49,85 @@ const make = (name, options) => ({
 	description: options.description,
 	instructions: options.instructions
 });
-/**
-* Returns the prompt with the skills' catalog appended, or the prompt unchanged when there are no
-* skills.
-*
-* @category utils
-* @since 0.1.0
-*/
-const withCatalog = (prompt, skills) => skills.length === 0 ? prompt : [
-	prompt,
+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",
-	"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:",
 	...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, 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
+*/
+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 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\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 * **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 * @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\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwDA,MAAa,QACX,MACA,aAMc;CAAE;CAAM,aAAa,QAAQ;CAAa,cAAc,QAAQ;AAAa;;;;;;;;AAiB7F,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,12 +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. */
+  /**
+   * The loop's tools, as a native toolkit whose handlers come from the layer. Merge in a
+   * `Skill.toolkit(...)` for playbooks.
+   */
   readonly toolkit?: Toolkit.Toolkit<T> | undefined;
-  /** Playbooks, listed as a catalog in the prompt and loaded with `load_skill` when one matches. */
-  readonly skills?: ReadonlyArray<Skill<RS>> | undefined;
   /** The model calls allowed per brief. Defaults to 8. */
   readonly maxSteps?: number | undefined;
 }
@@ -128,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;;WAE1B,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"}

package/dist/Specialist.js.map

@@ -1 +1 @@
-{"version":3,"file":"Specialist.js","names":[],"sources":["../src/Specialist.ts"],"sourcesContent":["/**\n * Defines specialists, which are focused agents an assistant hands work to in the background.\n *\n * A specialist has a definition, created with {@link make}, that gives its name and when to use\n * it, and a handler, provided with its `toLayer`, that works on a {@link Brief} as a loop. The\n * {@link Runner} service starts, steers, and stops a chat's specialist runs.\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 Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as Schema from \"effect/Schema\"\nimport type * as Scope from \"effect/Scope\"\nimport * as Stream from \"effect/Stream\"\nimport type * as AssistantLoop from \"./AssistantLoop.ts\"\nimport type { ChatId } from \"./ChatId.ts\"\nimport type { CurrentChat } from \"./CurrentChat.ts\"\nimport type * as Instructions from \"./Instructions.ts\"\nimport type { RunId } from \"./RunId.ts\"\nimport type { Skill } from \"./Skill.ts\"\n\nconst TypeId = \"~effect-assistant/Specialist\"\n\n/**\n * Represents a specialist's definition.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Specialist<Name extends string = string> {\n  readonly [TypeId]: typeof TypeId\n  readonly name: Name\n  /** When to use the specialist. The assistant sees this. */\n  readonly description: string\n  /** The key of the specialist's handler, as `toLayer` provides it. */\n  readonly Handler: Context.Key<SpecialistHandler<Name>, Built>\n  /**\n   * Provides the specialist's handler. The handler may use the {@link RunServices} and the\n   * services its build Effect required (see {@link CheckServices}).\n   */\n  readonly toLayer: <R = never, RE = never, E = never, RX = never>(\n    build: (Handler<R, RE> | Effect.Effect<Handler<R, RE>, E, RX>) &\n      CheckServices<Exclude<R | RE, RunServices | RX | Tool.Handler<string>>>\n  ) => Layer.Layer<SpecialistHandler<Name>, never, Exclude<RX, Scope.Scope | CurrentChat> | ToolHandlers<R | RE>>\n}\n\n/**\n * Represents the check `toLayer` applies to the services a handler uses.\n *\n * **Details**\n *\n * Every service a handler uses must be one the run (or turn) provides, or one its build Effect\n * required, which the layer provides. A handler that uses any other service gets this type\n * error, which names those services.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type CheckServices<Undeclared> = [Undeclared] extends [never]\n  ? unknown\n  : {\n      readonly \"~undeclaredServices\": {\n        readonly error: \"The handler uses services that neither the turn provides nor its build Effect requires\"\n        readonly services: Undeclared\n      }\n    }\n\n/**\n * Extracts the tool handlers (`Toolkit.toLayer`) that a handler's loop uses.\n *\n * They are requirements of the layer, so `Layer.provide(MyToolsLive)` provides them, and a\n * missing one is a type error.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type ToolHandlers<R> = Extract<R, Tool.Handler<string>>\n\n/**\n * Represents any specialist.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type Any = Specialist<any>\n\n/**\n * Identifies a specialist's handler in a context.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface SpecialistHandler<Name extends string> {\n  readonly _SpecialistHandler: Name\n}\n\n/**\n * Extracts the handlers that these specialists need.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type HandlerOf<S> = S extends Specialist<infer Name> ? SpecialistHandler<Name> : never\n\n/**\n * The services a run provides to its handler, which are its chat, the chat's runner, and the\n * model.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type RunServices = CurrentChat | Runner | LanguageModel.LanguageModel\n\n/**\n * Represents the options for `run.loop`.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface LoopOptions<T extends Record<string, Tool.Any> = Record<never, never>, RS = never> {\n  readonly instructions: string | Instructions.Resolved\n  /** The loop's tools, as a native toolkit whose handlers come from the layer. */\n  readonly toolkit?: Toolkit.Toolkit<T> | undefined\n  /** Playbooks, listed as a catalog in the prompt and loaded with `load_skill` when one matches. */\n  readonly skills?: ReadonlyArray<Skill<RS>> | undefined\n  /** The model calls allowed per brief. Defaults to 8. */\n  readonly maxSteps?: number | undefined\n}\n\n/**\n * Represents one run of a specialist on a brief, as its handler sees it.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Run {\n  readonly runId: RunId\n  /** The chat the run belongs to, which is the chat of the turn that spawned it. */\n  readonly chatId: ChatId\n  readonly brief: Brief\n  /**\n   * The run's history, with the brief, what the run did so far, and the messages sent to it since\n   * (follow-ups and steering). Read it before every model call, as the loop does.\n   */\n  readonly history: Effect.Effect<ReadonlyArray<Prompt.Message>>\n  /** Runs the agent loop over the run's history, with the given instructions, tools, and skills. */\n  readonly loop: <T extends Record<string, Tool.Any> = Record<never, never>, RS = never>(\n    options: LoopOptions<T, RS>\n  ) => Stream.Stream<\n    AssistantLoop.Event,\n    AiError.AiError,\n    LanguageModel.LanguageModel | AssistantLoop.ToolkitServices<T> | RS\n  >\n}\n\n/**\n * Represents a specialist's handler, which works on a brief and returns a stream of what the loop\n * did.\n *\n * It may return the stream from an Effect. `R` is the services the stream needs, and `RE` the\n * services the Effect needs.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Handler<R = never, RE = R> = (\n  run: Run\n) =>\n  | Stream.Stream<AssistantLoop.Event, unknown, R>\n  | Effect.Effect<Stream.Stream<AssistantLoop.Event, unknown, R>, unknown, RE>\n\n/**\n * Represents a specialist's handler as its layer provides it.\n *\n * `open` runs the build for a chat (once per chat activation, see `CurrentChat`) and returns\n * the handler with the layer's services already provided.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Built {\n  readonly open: Effect.Effect<\n    (run: Run) => Stream.Stream<AssistantLoop.Event, unknown, RunServices>,\n    never,\n    Scope.Scope | CurrentChat\n  >\n}\n\nconst toStream = <R, RE>(\n  result:\n    | Stream.Stream<AssistantLoop.Event, unknown, R>\n    | Effect.Effect<Stream.Stream<AssistantLoop.Event, unknown, R>, unknown, RE>\n): Stream.Stream<AssistantLoop.Event, unknown, R | RE> => (Effect.isEffect(result) ? Stream.unwrap(result) : result)\n\n/**\n * Creates a specialist from its name and a description of when to use it.\n *\n * **Details**\n *\n * The specialist's `toLayer` provides its handler, which is usually `run.loop` with the\n * specialist's own instructions and tools. List the specialist in `Assistant.make`'s\n * `specialists`, and provide its layer to the assistant's.\n *\n * **Example** (Defining a research specialist)\n *\n * ```ts\n * import { Assistant, Specialist } from \"effect-assistant\"\n * import * as Layer from \"effect/Layer\"\n *\n * const Research = Specialist.make(\"research\", {\n *   description: \"Researches past campaigns and orders. Give it the question and any context.\"\n * })\n *\n * const ResearchLive = Research.toLayer((run) =>\n *   run.loop({\n *     instructions: \"Answer with the findings and numbers the colleague needs, in a few lines.\",\n *     toolkit: ResearchTools\n *   })\n * ).pipe(Layer.provide(ResearchToolsLive))\n *\n * export const MyAssistant = Assistant.make(\"my-assistant\", { specialists: [Research] })\n *\n * const MyAssistantLive = MyAssistant.toLayer((turn) => turn.loop({ instructions })).pipe(\n *   Layer.provide(ResearchLive)\n * )\n * ```\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = <const Name extends string>(\n  name: Name,\n  options: {\n    /** When to use it. The assistant sees this. */\n    readonly description: string\n  }\n): Specialist<Name> => {\n  const Handler = Context.Service<SpecialistHandler<Name>, Built>(`effect-assistant/Specialist/${name}`)\n\n  // The signature checks what the handler uses (`CheckServices`); the layer's services, which the\n  // build required, are provided to it and to every run's stream, so what's left is the run\n  // services.\n  function toLayer<R = never, RE = never, E = never, RX = never>(\n    build: (Handler<R, RE> | Effect.Effect<Handler<R, RE>, E, RX>) &\n      CheckServices<Exclude<R | RE, RunServices | RX | Tool.Handler<string>>>\n  ): Layer.Layer<SpecialistHandler<Name>, never, Exclude<RX, Scope.Scope | CurrentChat> | ToolHandlers<R | RE>>\n  function toLayer(\n    build: Handler<any, any> | Effect.Effect<Handler<any, any>, unknown, any>\n  ): Layer.Layer<SpecialistHandler<Name>, never, any> {\n    return Layer.effect(\n      Handler,\n      Effect.gen(function* () {\n        const context = yield* Effect.context()\n\n        return {\n          // The build runs per chat activation, in the chat; here it only keeps the layer's\n          // services for it.\n          open: Effect.gen(function* () {\n            const handler = Effect.isEffect(build) ? yield* build : build\n\n            return (run: Run) => Stream.provideContext(toStream(handler(run)), context)\n          }).pipe(Effect.provideContext(context), Effect.orDie)\n        }\n      })\n    )\n  }\n\n  return { [TypeId]: TypeId, name, description: options.description, Handler, toLayer }\n}\n\n/**\n * Schema for the brief the assistant gives a specialist.\n *\n * Only `goal` is required.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const Brief = Schema.Struct({\n  goal: Schema.String.annotate({ description: \"What to find out or do.\" }),\n  context: Schema.optional(Schema.String).annotate({\n    description: \"What it needs to know. It can't see this chat.\"\n  }),\n  successCriteria: Schema.optional(Schema.String).annotate({ description: \"When it is done.\" }),\n  report: Schema.optional(Schema.String).annotate({\n    description: \"What to put in the answer, and how.\"\n  }),\n  limits: Schema.optional(Schema.String).annotate({\n    description: \"Hard limits for this job, like read-only or a deadline.\"\n  })\n})\n\n/**\n * Represents the brief the assistant gives a specialist.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Brief = typeof Brief.Type\n\n/**\n * Represents a request to start a specialist run in the runner's chat.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface SpawnRequest {\n  /** The specialist's name. */\n  readonly specialist: string\n  readonly brief: Brief\n}\n\n/**\n * Represents why a run request can't be carried out.\n *\n * **Details**\n *\n * The `reason` says which request failed: `\"UnknownSpecialist\"` when `spawn` names no specialist\n * of the assistant, `\"RunNotFound\"` when `message` names a run that is gone, and `\"NotRunning\"`\n * when `stop` names a run that isn't running. The `message` is written for the model.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class SpecialistError extends Schema.Error<SpecialistError>(\"effect-assistant/Specialist/SpecialistError\")({\n  _tag: Schema.tag(\"SpecialistError\"),\n  reason: Schema.Literals([\"UnknownSpecialist\", \"RunNotFound\", \"NotRunning\"]),\n  message: Schema.String\n}) {}\n\n/**\n * Service that runs a chat's specialists and keeps finished runs warm for follow-ups.\n *\n * The engine provides it to every turn. The specialist tools use it, and a handler can too.\n *\n * @category services\n * @since 0.1.0\n */\nexport class Runner extends Context.Service<\n  Runner,\n  {\n    /** Starts a run and returns its id. */\n    readonly spawn: (request: SpawnRequest) => Effect.Effect<RunId, SpecialistError>\n    /** Steers a running run, or continues a finished one. */\n    readonly message: (runId: RunId, text: string) => Effect.Effect<\"steered\" | \"continued\", SpecialistError>\n    /** Interrupts a running run. */\n    readonly stop: (runId: RunId) => Effect.Effect<void, SpecialistError>\n  }\n>()(\"effect-assistant/Specialist/Runner\") {}\n"],"mappings":";;;;;;;;;;;;;AA2BA,MAAM,SAAS;AAuKf,MAAM,YACJ,WAGyD,OAAO,SAAS,MAAM,IAAI,OAAO,OAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsC7G,MAAa,QACX,MACA,YAIqB;CACrB,MAAM,UAAU,QAAQ,QAAwC,+BAA+B,MAAM;CASrG,SAAS,QACP,OACkD;EAClD,OAAO,MAAM,OACX,SACA,OAAO,IAAI,aAAa;GACtB,MAAM,UAAU,OAAO,OAAO,QAAQ;GAEtC,OAAO,EAGL,MAAM,OAAO,IAAI,aAAa;IAC5B,MAAM,UAAU,OAAO,SAAS,KAAK,IAAI,OAAO,QAAQ;IAExD,QAAQ,QAAa,OAAO,eAAe,SAAS,QAAQ,GAAG,CAAC,GAAG,OAAO;GAC5E,CAAC,CAAC,CAAC,KAAK,OAAO,eAAe,OAAO,GAAG,OAAO,KAAK,EACtD;EACF,CAAC,CACH;CACF;CAEA,OAAO;GAAG,SAAS;EAAQ;EAAM,aAAa,QAAQ;EAAa;EAAS;CAAQ;AACtF;;;;;;;;;AAUA,MAAa,QAAQ,OAAO,OAAO;CACjC,MAAM,OAAO,OAAO,SAAS,EAAE,aAAa,0BAA0B,CAAC;CACvE,SAAS,OAAO,SAAS,OAAO,MAAM,CAAC,CAAC,SAAS,EAC/C,aAAa,iDACf,CAAC;CACD,iBAAiB,OAAO,SAAS,OAAO,MAAM,CAAC,CAAC,SAAS,EAAE,aAAa,mBAAmB,CAAC;CAC5F,QAAQ,OAAO,SAAS,OAAO,MAAM,CAAC,CAAC,SAAS,EAC9C,aAAa,sCACf,CAAC;CACD,QAAQ,OAAO,SAAS,OAAO,MAAM,CAAC,CAAC,SAAS,EAC9C,aAAa,0DACf,CAAC;AACH,CAAC;;;;;;;;;;;;;AAkCD,IAAa,kBAAb,cAAqC,OAAO,MAAuB,6CAA6C,CAAC,CAAC;CAChH,MAAM,OAAO,IAAI,iBAAiB;CAClC,QAAQ,OAAO,SAAS;EAAC;EAAqB;EAAe;CAAY,CAAC;CAC1E,SAAS,OAAO;AAClB,CAAC,CAAC,CAAC,CAAC;;;;;;;;;AAUJ,IAAa,SAAb,cAA4B,QAAQ,QAUlC,CAAC,CAAC,oCAAoC,CAAC,CAAC,CAAC"}
+{"version":3,"file":"Specialist.js","names":[],"sources":["../src/Specialist.ts"],"sourcesContent":["/**\n * Defines specialists, which are focused agents an assistant hands work to in the background.\n *\n * A specialist has a definition, created with {@link make}, that gives its name and when to use\n * it, and a handler, provided with its `toLayer`, that works on a {@link Brief} as a loop. The\n * {@link Runner} service starts, steers, and stops a chat's specialist runs.\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 Context from \"effect/Context\"\nimport * as Effect from \"effect/Effect\"\nimport * as Layer from \"effect/Layer\"\nimport * as Schema from \"effect/Schema\"\nimport type * as Scope from \"effect/Scope\"\nimport * as Stream from \"effect/Stream\"\nimport type * as AssistantLoop from \"./AssistantLoop.ts\"\nimport type { ChatId } from \"./ChatId.ts\"\nimport type { CurrentChat } from \"./CurrentChat.ts\"\nimport type * as Instructions from \"./Instructions.ts\"\nimport type { RunId } from \"./RunId.ts\"\n\nconst TypeId = \"~effect-assistant/Specialist\"\n\n/**\n * Represents a specialist's definition.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Specialist<Name extends string = string> {\n  readonly [TypeId]: typeof TypeId\n  readonly name: Name\n  /** When to use the specialist. The assistant sees this. */\n  readonly description: string\n  /** The key of the specialist's handler, as `toLayer` provides it. */\n  readonly Handler: Context.Key<SpecialistHandler<Name>, Built>\n  /**\n   * Provides the specialist's handler. The handler may use the {@link RunServices} and the\n   * services its build Effect required (see {@link CheckServices}).\n   */\n  readonly toLayer: <R = never, RE = never, E = never, RX = never>(\n    build: (Handler<R, RE> | Effect.Effect<Handler<R, RE>, E, RX>) &\n      CheckServices<Exclude<R | RE, RunServices | RX | Tool.Handler<string>>>\n  ) => Layer.Layer<SpecialistHandler<Name>, never, Exclude<RX, Scope.Scope | CurrentChat> | ToolHandlers<R | RE>>\n}\n\n/**\n * Represents the check `toLayer` applies to the services a handler uses.\n *\n * **Details**\n *\n * Every service a handler uses must be one the run (or turn) provides, or one its build Effect\n * required, which the layer provides. A handler that uses any other service gets this type\n * error, which names those services.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type CheckServices<Undeclared> = [Undeclared] extends [never]\n  ? unknown\n  : {\n      readonly \"~undeclaredServices\": {\n        readonly error: \"The handler uses services that neither the turn provides nor its build Effect requires\"\n        readonly services: Undeclared\n      }\n    }\n\n/**\n * Extracts the tool handlers (`Toolkit.toLayer`) that a handler's loop uses.\n *\n * They are requirements of the layer, so `Layer.provide(MyToolsLive)` provides them, and a\n * missing one is a type error.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type ToolHandlers<R> = Extract<R, Tool.Handler<string>>\n\n/**\n * Represents any specialist.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type Any = Specialist<any>\n\n/**\n * Identifies a specialist's handler in a context.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface SpecialistHandler<Name extends string> {\n  readonly _SpecialistHandler: Name\n}\n\n/**\n * Extracts the handlers that these specialists need.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type HandlerOf<S> = S extends Specialist<infer Name> ? SpecialistHandler<Name> : never\n\n/**\n * The services a run provides to its handler, which are its chat, the chat's runner, and the\n * model.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type RunServices = CurrentChat | Runner | LanguageModel.LanguageModel\n\n/**\n * Represents the options for `run.loop`.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface LoopOptions<T extends Record<string, Tool.Any> = Record<never, never>> {\n  readonly instructions: string | Instructions.Resolved\n  /**\n   * The loop's tools, as a native toolkit whose handlers come from the layer. Merge in a\n   * `Skill.toolkit(...)` for playbooks.\n   */\n  readonly toolkit?: Toolkit.Toolkit<T> | undefined\n  /** The model calls allowed per brief. Defaults to 8. */\n  readonly maxSteps?: number | undefined\n}\n\n/**\n * Represents one run of a specialist on a brief, as its handler sees it.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Run {\n  readonly runId: RunId\n  /** The chat the run belongs to, which is the chat of the turn that spawned it. */\n  readonly chatId: ChatId\n  readonly brief: Brief\n  /**\n   * The run's history, with the brief, what the run did so far, and the messages sent to it since\n   * (follow-ups and steering). Read it before every model call, as the loop does.\n   */\n  readonly history: Effect.Effect<ReadonlyArray<Prompt.Message>>\n  /** Runs the agent loop over the run's history, with the given instructions and tools. */\n  readonly loop: <T extends Record<string, Tool.Any> = Record<never, never>>(\n    options: LoopOptions<T>\n  ) => Stream.Stream<\n    AssistantLoop.Event,\n    AiError.AiError,\n    LanguageModel.LanguageModel | AssistantLoop.ToolkitServices<T>\n  >\n}\n\n/**\n * Represents a specialist's handler, which works on a brief and returns a stream of what the loop\n * did.\n *\n * It may return the stream from an Effect. `R` is the services the stream needs, and `RE` the\n * services the Effect needs.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Handler<R = never, RE = R> = (\n  run: Run\n) =>\n  | Stream.Stream<AssistantLoop.Event, unknown, R>\n  | Effect.Effect<Stream.Stream<AssistantLoop.Event, unknown, R>, unknown, RE>\n\n/**\n * Represents a specialist's handler as its layer provides it.\n *\n * `open` runs the build for a chat (once per chat activation, see `CurrentChat`) and returns\n * the handler with the layer's services already provided.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Built {\n  readonly open: Effect.Effect<\n    (run: Run) => Stream.Stream<AssistantLoop.Event, unknown, RunServices>,\n    never,\n    Scope.Scope | CurrentChat\n  >\n}\n\nconst toStream = <R, RE>(\n  result:\n    | Stream.Stream<AssistantLoop.Event, unknown, R>\n    | Effect.Effect<Stream.Stream<AssistantLoop.Event, unknown, R>, unknown, RE>\n): Stream.Stream<AssistantLoop.Event, unknown, R | RE> => (Effect.isEffect(result) ? Stream.unwrap(result) : result)\n\n/**\n * Creates a specialist from its name and a description of when to use it.\n *\n * **Details**\n *\n * The specialist's `toLayer` provides its handler, which is usually `run.loop` with the\n * specialist's own instructions and tools. List the specialist in `Assistant.make`'s\n * `specialists`, and provide its layer to the assistant's.\n *\n * **Example** (Defining a research specialist)\n *\n * ```ts\n * import { Assistant, Specialist } from \"effect-assistant\"\n * import * as Layer from \"effect/Layer\"\n *\n * const Research = Specialist.make(\"research\", {\n *   description: \"Researches past campaigns and orders. Give it the question and any context.\"\n * })\n *\n * const ResearchLive = Research.toLayer((run) =>\n *   run.loop({\n *     instructions: \"Answer with the findings and numbers the colleague needs, in a few lines.\",\n *     toolkit: ResearchTools\n *   })\n * ).pipe(Layer.provide(ResearchToolsLive))\n *\n * export const MyAssistant = Assistant.make(\"my-assistant\", { specialists: [Research] })\n *\n * const MyAssistantLive = MyAssistant.toLayer((turn) => turn.loop({ instructions })).pipe(\n *   Layer.provide(ResearchLive)\n * )\n * ```\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = <const Name extends string>(\n  name: Name,\n  options: {\n    /** When to use it. The assistant sees this. */\n    readonly description: string\n  }\n): Specialist<Name> => {\n  const Handler = Context.Service<SpecialistHandler<Name>, Built>(`effect-assistant/Specialist/${name}`)\n\n  // The signature checks what the handler uses (`CheckServices`); the layer's services, which the\n  // build required, are provided to it and to every run's stream, so what's left is the run\n  // services.\n  function toLayer<R = never, RE = never, E = never, RX = never>(\n    build: (Handler<R, RE> | Effect.Effect<Handler<R, RE>, E, RX>) &\n      CheckServices<Exclude<R | RE, RunServices | RX | Tool.Handler<string>>>\n  ): Layer.Layer<SpecialistHandler<Name>, never, Exclude<RX, Scope.Scope | CurrentChat> | ToolHandlers<R | RE>>\n  function toLayer(\n    build: Handler<any, any> | Effect.Effect<Handler<any, any>, unknown, any>\n  ): Layer.Layer<SpecialistHandler<Name>, never, any> {\n    return Layer.effect(\n      Handler,\n      Effect.gen(function* () {\n        const context = yield* Effect.context()\n\n        return {\n          // The build runs per chat activation, in the chat; here it only keeps the layer's\n          // services for it.\n          open: Effect.gen(function* () {\n            const handler = Effect.isEffect(build) ? yield* build : build\n\n            return (run: Run) => Stream.provideContext(toStream(handler(run)), context)\n          }).pipe(Effect.provideContext(context), Effect.orDie)\n        }\n      })\n    )\n  }\n\n  return { [TypeId]: TypeId, name, description: options.description, Handler, toLayer }\n}\n\n/**\n * Schema for the brief the assistant gives a specialist.\n *\n * Only `goal` is required.\n *\n * @category schemas\n * @since 0.1.0\n */\nexport const Brief = Schema.Struct({\n  goal: Schema.String.annotate({ description: \"What to find out or do.\" }),\n  context: Schema.optional(Schema.String).annotate({\n    description: \"What it needs to know. It can't see this chat.\"\n  }),\n  successCriteria: Schema.optional(Schema.String).annotate({ description: \"When it is done.\" }),\n  report: Schema.optional(Schema.String).annotate({\n    description: \"What to put in the answer, and how.\"\n  }),\n  limits: Schema.optional(Schema.String).annotate({\n    description: \"Hard limits for this job, like read-only or a deadline.\"\n  })\n})\n\n/**\n * Represents the brief the assistant gives a specialist.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Brief = typeof Brief.Type\n\n/**\n * Represents a request to start a specialist run in the runner's chat.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface SpawnRequest {\n  /** The specialist's name. */\n  readonly specialist: string\n  readonly brief: Brief\n}\n\n/**\n * Represents why a run request can't be carried out.\n *\n * **Details**\n *\n * The `reason` says which request failed: `\"UnknownSpecialist\"` when `spawn` names no specialist\n * of the assistant, `\"RunNotFound\"` when `message` names a run that is gone, and `\"NotRunning\"`\n * when `stop` names a run that isn't running. The `message` is written for the model.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class SpecialistError extends Schema.Error<SpecialistError>(\"effect-assistant/Specialist/SpecialistError\")({\n  _tag: Schema.tag(\"SpecialistError\"),\n  reason: Schema.Literals([\"UnknownSpecialist\", \"RunNotFound\", \"NotRunning\"]),\n  message: Schema.String\n}) {}\n\n/**\n * Service that runs a chat's specialists and keeps finished runs warm for follow-ups.\n *\n * The engine provides it to every turn. The specialist tools use it, and a handler can too.\n *\n * @category services\n * @since 0.1.0\n */\nexport class Runner extends Context.Service<\n  Runner,\n  {\n    /** Starts a run and returns its id. */\n    readonly spawn: (request: SpawnRequest) => Effect.Effect<RunId, SpecialistError>\n    /** Steers a running run, or continues a finished one. */\n    readonly message: (runId: RunId, text: string) => Effect.Effect<\"steered\" | \"continued\", SpecialistError>\n    /** Interrupts a running run. */\n    readonly stop: (runId: RunId) => Effect.Effect<void, SpecialistError>\n  }\n>()(\"effect-assistant/Specialist/Runner\") {}\n"],"mappings":";;;;;;;;;;;;;AA0BA,MAAM,SAAS;AAwKf,MAAM,YACJ,WAGyD,OAAO,SAAS,MAAM,IAAI,OAAO,OAAO,MAAM,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsC7G,MAAa,QACX,MACA,YAIqB;CACrB,MAAM,UAAU,QAAQ,QAAwC,+BAA+B,MAAM;CASrG,SAAS,QACP,OACkD;EAClD,OAAO,MAAM,OACX,SACA,OAAO,IAAI,aAAa;GACtB,MAAM,UAAU,OAAO,OAAO,QAAQ;GAEtC,OAAO,EAGL,MAAM,OAAO,IAAI,aAAa;IAC5B,MAAM,UAAU,OAAO,SAAS,KAAK,IAAI,OAAO,QAAQ;IAExD,QAAQ,QAAa,OAAO,eAAe,SAAS,QAAQ,GAAG,CAAC,GAAG,OAAO;GAC5E,CAAC,CAAC,CAAC,KAAK,OAAO,eAAe,OAAO,GAAG,OAAO,KAAK,EACtD;EACF,CAAC,CACH;CACF;CAEA,OAAO;GAAG,SAAS;EAAQ;EAAM,aAAa,QAAQ;EAAa;EAAS;CAAQ;AACtF;;;;;;;;;AAUA,MAAa,QAAQ,OAAO,OAAO;CACjC,MAAM,OAAO,OAAO,SAAS,EAAE,aAAa,0BAA0B,CAAC;CACvE,SAAS,OAAO,SAAS,OAAO,MAAM,CAAC,CAAC,SAAS,EAC/C,aAAa,iDACf,CAAC;CACD,iBAAiB,OAAO,SAAS,OAAO,MAAM,CAAC,CAAC,SAAS,EAAE,aAAa,mBAAmB,CAAC;CAC5F,QAAQ,OAAO,SAAS,OAAO,MAAM,CAAC,CAAC,SAAS,EAC9C,aAAa,sCACf,CAAC;CACD,QAAQ,OAAO,SAAS,OAAO,MAAM,CAAC,CAAC,SAAS,EAC9C,aAAa,0DACf,CAAC;AACH,CAAC;;;;;;;;;;;;;AAkCD,IAAa,kBAAb,cAAqC,OAAO,MAAuB,6CAA6C,CAAC,CAAC;CAChH,MAAM,OAAO,IAAI,iBAAiB;CAClC,QAAQ,OAAO,SAAS;EAAC;EAAqB;EAAe;CAAY,CAAC;CAC1E,SAAS,OAAO;AAClB,CAAC,CAAC,CAAC,CAAC;;;;;;;;;AAUJ,IAAa,SAAb,cAA4B,QAAQ,QAUlC,CAAC,CAAC,oCAAoC,CAAC,CAAC,CAAC"}