effect-assistant 0.0.0-stage → 0.1.0

package/dist/Skill.js.map

@@ -0,0 +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"}

package/dist/Specialist.d.ts

@@ -0,0 +1,267 @@
+import { ChatId } from "./ChatId.js";
+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";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+import * as Scope from "effect/Scope";
+import * as Prompt from "effect/ai/Prompt";
+import * as Tool from "effect/ai/Tool";
+import * as Toolkit from "effect/ai/Toolkit";
+import * as LanguageModel from "effect/ai/LanguageModel";
+import * as AiError from "effect/ai/AiError";
+declare namespace Specialist_d_exports {
+  export { Any, Brief, Built, CheckServices, Handler, HandlerOf, LoopOptions, Run, RunServices, Runner, SpawnRequest, Specialist, SpecialistError, SpecialistHandler, ToolHandlers, make };
+}
+declare const TypeId = "~effect-assistant/Specialist";
+/**
+ * Represents a specialist's definition.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Specialist<Name extends string = string> {
+  readonly [TypeId]: typeof TypeId;
+  readonly name: Name;
+  /** When to use the specialist. The assistant sees this. */
+  readonly description: string;
+  /** The key of the specialist's handler, as `toLayer` provides it. */
+  readonly Handler: Context.Key<SpecialistHandler<Name>, Built>;
+  /**
+   * Provides the specialist's handler. The handler may use the {@link RunServices} and the
+   * services its build Effect required (see {@link CheckServices}).
+   */
+  readonly toLayer: <R = never, RE = never, E = never, RX = never>(build: (Handler<R, RE> | Effect.Effect<Handler<R, RE>, E, RX>) & CheckServices<Exclude<R | RE, RunServices | RX | Tool.Handler<string>>>) => Layer.Layer<SpecialistHandler<Name>, never, Exclude<RX, Scope.Scope | CurrentChat> | ToolHandlers<R | RE>>;
+}
+/**
+ * Represents the check `toLayer` applies to the services a handler uses.
+ *
+ * **Details**
+ *
+ * Every service a handler uses must be one the run (or turn) provides, or one its build Effect
+ * required, which the layer provides. A handler that uses any other service gets this type
+ * error, which names those services.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type CheckServices<Undeclared> = [Undeclared] extends [never] ? unknown : {
+  readonly "~undeclaredServices": {
+    readonly error: "The handler uses services that neither the turn provides nor its build Effect requires";
+    readonly services: Undeclared;
+  };
+};
+/**
+ * Extracts the tool handlers (`Toolkit.toLayer`) that a handler's loop uses.
+ *
+ * They are requirements of the layer, so `Layer.provide(MyToolsLive)` provides them, and a
+ * missing one is a type error.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type ToolHandlers<R> = Extract<R, Tool.Handler<string>>;
+/**
+ * Represents any specialist.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type Any = Specialist<any>;
+/**
+ * Identifies a specialist's handler in a context.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface SpecialistHandler<Name extends string> {
+  readonly _SpecialistHandler: Name;
+}
+/**
+ * Extracts the handlers that these specialists need.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type HandlerOf<S> = S extends Specialist<infer Name> ? SpecialistHandler<Name> : never;
+/**
+ * The services a run provides to its handler, which are its chat, the chat's runner, and the
+ * model.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type RunServices = CurrentChat | Runner | LanguageModel.LanguageModel;
+/**
+ * Represents the options for `run.loop`.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface LoopOptions<T extends Record<string, Tool.Any> = Record<never, never>, RS = 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. */
+  readonly skills?: ReadonlyArray<Skill<RS>> | undefined;
+  /** The model calls allowed per brief. Defaults to 8. */
+  readonly maxSteps?: number | undefined;
+}
+/**
+ * Represents one run of a specialist on a brief, as its handler sees it.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Run {
+  readonly runId: RunId;
+  /** The chat the run belongs to, which is the chat of the turn that spawned it. */
+  readonly chatId: ChatId;
+  readonly brief: Brief;
+  /**
+   * The run's history, with the brief, what the run did so far, and the messages sent to it since
+   * (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>;
+}
+/**
+ * Represents a specialist's handler, which works on a brief and returns a stream of what the loop
+ * did.
+ *
+ * It may return the stream from an Effect. `R` is the services the stream needs, and `RE` the
+ * services the Effect needs.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Handler<R = never, RE = R> = (run: Run) => Stream.Stream<Event, unknown, R> | Effect.Effect<Stream.Stream<Event, unknown, R>, unknown, RE>;
+/**
+ * Represents a specialist's handler as its layer provides it.
+ *
+ * `open` runs the build for a chat (once per chat activation, see `CurrentChat`) and returns
+ * the handler with the layer's services already provided.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Built {
+  readonly open: Effect.Effect<(run: Run) => Stream.Stream<Event, unknown, RunServices>, never, Scope.Scope | CurrentChat>;
+}
+/**
+ * Creates a specialist from its name and a description of when to use it.
+ *
+ * **Details**
+ *
+ * The specialist's `toLayer` provides its handler, which is usually `run.loop` with the
+ * specialist's own instructions and tools. List the specialist in `Assistant.make`'s
+ * `specialists`, and provide its layer to the assistant's.
+ *
+ * **Example** (Defining a research specialist)
+ *
+ * ```ts
+ * import { Assistant, Specialist } from "effect-assistant"
+ * import * as Layer from "effect/Layer"
+ *
+ * const Research = Specialist.make("research", {
+ *   description: "Researches past campaigns and orders. Give it the question and any context."
+ * })
+ *
+ * const ResearchLive = Research.toLayer((run) =>
+ *   run.loop({
+ *     instructions: "Answer with the findings and numbers the colleague needs, in a few lines.",
+ *     toolkit: ResearchTools
+ *   })
+ * ).pipe(Layer.provide(ResearchToolsLive))
+ *
+ * export const MyAssistant = Assistant.make("my-assistant", { specialists: [Research] })
+ *
+ * const MyAssistantLive = MyAssistant.toLayer((turn) => turn.loop({ instructions })).pipe(
+ *   Layer.provide(ResearchLive)
+ * )
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: <const Name extends string>(name: Name, options: {
+  /** When to use it. The assistant sees this. */
+  readonly description: string;
+}) => Specialist<Name>;
+/**
+ * Schema for the brief the assistant gives a specialist.
+ *
+ * Only `goal` is required.
+ *
+ * @category schemas
+ * @since 0.1.0
+ */
+export declare const Brief: Schema.Struct<{
+  readonly goal: Schema.String;
+  readonly context: Schema.optional<Schema.String>;
+  readonly successCriteria: Schema.optional<Schema.String>;
+  readonly report: Schema.optional<Schema.String>;
+  readonly limits: Schema.optional<Schema.String>;
+}>;
+/**
+ * Represents the brief the assistant gives a specialist.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Brief = typeof Brief.Type;
+/**
+ * Represents a request to start a specialist run in the runner's chat.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface SpawnRequest {
+  /** The specialist's name. */
+  readonly specialist: string;
+  readonly brief: Brief;
+}
+declare const SpecialistError_base: Schema.Class<SpecialistError, Schema.Struct<{
+  readonly _tag: Schema.tag<"SpecialistError">;
+  readonly reason: Schema.Literals<readonly ["UnknownSpecialist", "RunNotFound", "NotRunning"]>;
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Represents why a run request can't be carried out.
+ *
+ * **Details**
+ *
+ * The `reason` says which request failed: `"UnknownSpecialist"` when `spawn` names no specialist
+ * of the assistant, `"RunNotFound"` when `message` names a run that is gone, and `"NotRunning"`
+ * when `stop` names a run that isn't running. The `message` is written for the model.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class SpecialistError extends SpecialistError_base {}
+declare const Runner_base: Context.ServiceClass<Runner, "effect-assistant/Specialist/Runner", {
+  /** Starts a run and returns its id. */
+  readonly spawn: (request: SpawnRequest) => Effect.Effect<RunId, SpecialistError>;
+  /** Steers a running run, or continues a finished one. */
+  readonly message: (runId: RunId, text: string) => Effect.Effect<"steered" | "continued", SpecialistError>;
+  /** Interrupts a running run. */
+  readonly stop: (runId: RunId) => Effect.Effect<void, SpecialistError>;
+}>;
+/**
+ * Service that runs a chat's specialists and keeps finished runs warm for follow-ups.
+ *
+ * The engine provides it to every turn. The specialist tools use it, and a handler can too.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class Runner extends Runner_base {}
+//#endregion
+export { Specialist_d_exports };
+//# sourceMappingURL=Specialist.d.ts.map

package/dist/Specialist.d.ts.map

@@ -0,0 +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"}

package/dist/Specialist.js

@@ -0,0 +1,119 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Schema from "effect/Schema";
+import * as Stream from "effect/Stream";
+//#region src/Specialist.ts
+var Specialist_exports = /* @__PURE__ */ __exportAll({
+	Brief: () => Brief,
+	Runner: () => Runner,
+	SpecialistError: () => SpecialistError,
+	make: () => make
+});
+const TypeId = "~effect-assistant/Specialist";
+const toStream = (result) => Effect.isEffect(result) ? Stream.unwrap(result) : result;
+/**
+* Creates a specialist from its name and a description of when to use it.
+*
+* **Details**
+*
+* The specialist's `toLayer` provides its handler, which is usually `run.loop` with the
+* specialist's own instructions and tools. List the specialist in `Assistant.make`'s
+* `specialists`, and provide its layer to the assistant's.
+*
+* **Example** (Defining a research specialist)
+*
+* ```ts
+* import { Assistant, Specialist } from "effect-assistant"
+* import * as Layer from "effect/Layer"
+*
+* const Research = Specialist.make("research", {
+*   description: "Researches past campaigns and orders. Give it the question and any context."
+* })
+*
+* const ResearchLive = Research.toLayer((run) =>
+*   run.loop({
+*     instructions: "Answer with the findings and numbers the colleague needs, in a few lines.",
+*     toolkit: ResearchTools
+*   })
+* ).pipe(Layer.provide(ResearchToolsLive))
+*
+* export const MyAssistant = Assistant.make("my-assistant", { specialists: [Research] })
+*
+* const MyAssistantLive = MyAssistant.toLayer((turn) => turn.loop({ instructions })).pipe(
+*   Layer.provide(ResearchLive)
+* )
+* ```
+*
+* @category constructors
+* @since 0.1.0
+*/
+const make = (name, options) => {
+	const Handler = Context.Service(`effect-assistant/Specialist/${name}`);
+	function toLayer(build) {
+		return Layer.effect(Handler, Effect.gen(function* () {
+			const context = yield* Effect.context();
+			return { open: Effect.gen(function* () {
+				const handler = Effect.isEffect(build) ? yield* build : build;
+				return (run) => Stream.provideContext(toStream(handler(run)), context);
+			}).pipe(Effect.provideContext(context), Effect.orDie) };
+		}));
+	}
+	return {
+		[TypeId]: TypeId,
+		name,
+		description: options.description,
+		Handler,
+		toLayer
+	};
+};
+/**
+* Schema for the brief the assistant gives a specialist.
+*
+* Only `goal` is required.
+*
+* @category schemas
+* @since 0.1.0
+*/
+const Brief = Schema.Struct({
+	goal: Schema.String.annotate({ description: "What to find out or do." }),
+	context: Schema.optional(Schema.String).annotate({ description: "What it needs to know. It can't see this chat." }),
+	successCriteria: Schema.optional(Schema.String).annotate({ description: "When it is done." }),
+	report: Schema.optional(Schema.String).annotate({ description: "What to put in the answer, and how." }),
+	limits: Schema.optional(Schema.String).annotate({ description: "Hard limits for this job, like read-only or a deadline." })
+});
+/**
+* Represents why a run request can't be carried out.
+*
+* **Details**
+*
+* The `reason` says which request failed: `"UnknownSpecialist"` when `spawn` names no specialist
+* of the assistant, `"RunNotFound"` when `message` names a run that is gone, and `"NotRunning"`
+* when `stop` names a run that isn't running. The `message` is written for the model.
+*
+* @category errors
+* @since 0.1.0
+*/
+var SpecialistError = class extends Schema.Error("effect-assistant/Specialist/SpecialistError")({
+	_tag: Schema.tag("SpecialistError"),
+	reason: Schema.Literals([
+		"UnknownSpecialist",
+		"RunNotFound",
+		"NotRunning"
+	]),
+	message: Schema.String
+}) {};
+/**
+* Service that runs a chat's specialists and keeps finished runs warm for follow-ups.
+*
+* The engine provides it to every turn. The specialist tools use it, and a handler can too.
+*
+* @category services
+* @since 0.1.0
+*/
+var Runner = class extends Context.Service()("effect-assistant/Specialist/Runner") {};
+//#endregion
+export { Brief, Runner, SpecialistError, Specialist_exports, make };
+
+//# sourceMappingURL=Specialist.js.map

package/dist/Specialist.js.map

@@ -0,0 +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"}

package/dist/ToolDiscovery.d.ts

@@ -0,0 +1,108 @@
+import { AssistantToolCall } from "./AssistantToolCall.js";
+import { ToolServices, toolkit_d_exports } from "./internal/toolkit.js";
+import * as Schema from "effect/Schema";
+import * as Tool from "effect/ai/Tool";
+import * as Toolkit from "effect/ai/Toolkit";
+declare namespace ToolDiscovery_d_exports {
+  export { layer, make };
+}
+/**
+ * Creates the `search_tools` and `execute_tool` tools over a catalog toolkit, as a native toolkit.
+ *
+ * **Details**
+ *
+ * Merge the toolkit into the loop's, and provide {@link layer} for the same catalog, which has
+ * the tools' handlers. A catalog tool's services are `execute_tool`'s, so the turn provides them
+ * as it does for any tool.
+ *
+ * `execute_tool` doesn't run a tool that needs the user's decision; keep such tools in the loop's
+ * toolkit directly.
+ *
+ * **Example** (Finding rarely used tools when needed)
+ *
+ * ```ts
+ * import { ToolDiscovery } from "effect-assistant"
+ * import * as Toolkit from "effect/ai/Toolkit"
+ * import * as Layer from "effect/Layer"
+ *
+ * // OfficeTools is a big toolkit, found when needed. CommonTools stays in the prompt.
+ * const OfficeDiscovery = ToolDiscovery.make(OfficeTools)
+ * const OfficeDiscoveryLive = ToolDiscovery.layer(OfficeTools).pipe(Layer.provide(OfficeToolsLive))
+ *
+ * const MyAssistantLive = MyAssistant.toLayer((turn) =>
+ *   turn.loop({
+ *     instructions,
+ *     toolkit: Toolkit.merge(CommonTools, OfficeDiscovery)
+ *   })
+ * ).pipe(Layer.provide([CommonToolsLive, OfficeDiscoveryLive]))
+ * ```
+ *
+ * @see {@link layer} for the tools' handlers
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: <T extends Record<string, Tool.Any>>(_catalog: Toolkit.Toolkit<T>) => Toolkit.Toolkit<{
+  readonly execute_tool: Tool.Tool<"execute_tool", {
+    readonly parameters: Schema.Struct<{
+      readonly name: Schema.String;
+      readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>;
+    readonly success: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly failure: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly failureMode: "error";
+  }, AssistantToolCall | ToolServices<T>>;
+  readonly search_tools: Tool.Tool<"search_tools", {
+    readonly parameters: Schema.Struct<{
+      readonly query: Schema.String;
+    }>;
+    readonly success: Schema.$Array<Schema.Struct<{
+      readonly name: Schema.String;
+      readonly description: Schema.optional<Schema.String>;
+      readonly inputSchema: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>>;
+    readonly failure: Schema.Never;
+    readonly failureMode: "error";
+  }, never>;
+}>;
+/**
+ * Creates the layer with the handlers of the `search_tools` and `execute_tool` tools over a
+ * catalog toolkit.
+ *
+ * **Details**
+ *
+ * The layer needs the catalog's handlers. It provides the handlers of the toolkit that
+ * {@link make} returns for the same catalog: handlers are keyed by tool name, so the two calls
+ * don't need to share a value. Give both the same catalog.
+ *
+ * @see {@link make} for the toolkit and an example
+ *
+ * @category layers
+ * @since 0.1.0
+ */
+export declare const layer: <T extends Record<string, Tool.Any>>(catalog: Toolkit.Toolkit<T>) => import("effect/Layer").Layer<Tool.HandlersFor<{
+  readonly execute_tool: Tool.Tool<"execute_tool", {
+    readonly parameters: Schema.Struct<{
+      readonly name: Schema.String;
+      readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    }>;
+    readonly success: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly failure: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    readonly failureMode: "error";
+  }, AssistantToolCall | ToolServices<T>>;
+  readonly search_tools: Tool.Tool<"search_tools", {
+    readonly parameters: Schema.Struct<{
+      readonly query: Schema.String;
+    }>;
+    readonly success: Schema.$Array<Schema.Struct<{
+      readonly name: Schema.String;
+      readonly description: Schema.optional<Schema.String>;
+      readonly inputSchema: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+    }>>;
+    readonly failure: Schema.Never;
+    readonly failureMode: "error";
+  }, never>;
+}>, never, Exclude<Tool.HandlersFor<T>, import("effect/Scope").Scope>>;
+//#endregion
+export { ToolDiscovery_d_exports };
+//# sourceMappingURL=ToolDiscovery.d.ts.map

package/dist/ToolDiscovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolDiscovery.d.ts","names":[],"sources":["../src/ToolDiscovery.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA2Ha,OAAQ,UAAU,eAAe,KAAK,MAAI,UAE3C,QAAQ,QAAQ,OAAE,QAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAkBjB,QAAS,UAAU,eAAe,KAAK,MAAI,SAAW,QAAQ,QAAQ,8BAAE,MAAA,KAAA;;;;;;;;;;;;;;;;;;;;;;WA2ClF,QAAA,KAAA,YAAA,2BAAA"}