effect-assistant 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+# effect-assistant
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A chat assistant on [Effect](https://effect.website) that behaves like a
+colleague. It keeps an append-only event log per chat, runs an
+interruptible agent loop over it, and talks to the user only through a
+`send_user_message` tool. It also supports specialists, skills, UI blocks,
+decisions, memory, and compaction. It runs in memory or as one Effect
+Cluster entity per chat.
+
+```bash
+pnpm add effect-assistant effect@^4.0.0 @effect/ai-anthropic@^4.0.0
+```
+
+The [README on GitHub](https://github.com/dbrxnds/effect-assistant#readme)
+has the simplest setup and the more extensive ones. The
+[docs](https://github.com/dbrxnds/effect-assistant/tree/main/apps/docs) have
+a guide per topic and the API reference.
+
+```bash
+pnpm --filter effect-assistant test            # the mechanics, on a scripted model
+pnpm --filter effect-assistant test:contract   # against a real model (ANTHROPIC_API_KEY in .env.local)
+pnpm --filter effect-assistant build           # dist, with declarations and source maps
+```

package/dist/AppEvent.d.ts

@@ -0,0 +1,111 @@
+import * as SchemaAST from "effect/SchemaAST";
+import * as Schema from "effect/Schema";
+declare namespace AppEvent_d_exports {
+  export { Any, AppEvent, EventSchema, Render, Type, make };
+}
+/**
+ * Schema for one of the application's own events.
+ *
+ * It is a tagged struct or class (`Schema.TaggedStruct`, `Schema.TaggedClass`) that needs no
+ * services.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type EventSchema = Schema.Codec<{
+  readonly _tag: string;
+}, {
+  readonly _tag: string;
+}> & {
+  readonly fields: {
+    readonly _tag: {
+      readonly ast: SchemaAST.AST;
+    };
+  };
+};
+/**
+ * Describes how the model reads an event.
+ *
+ * `"json"` shows the event's tag and fields as JSON. A function shows the text it returns for the
+ * event.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Render<A> = "json" | ((event: A) => string);
+/**
+ * Represents one of the application's events, registered with an assistant.
+ *
+ * It holds the event's schema and tag, whether storing it wakes a turn, and how the model reads
+ * it. A `render` of `undefined` means the model doesn't read it.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface AppEvent<S extends EventSchema = EventSchema> {
+  readonly schema: S;
+  readonly tag: string;
+  readonly wakes: boolean;
+  readonly render: Render<S["Type"]> | undefined;
+}
+/**
+ * Represents any registered event, for generic constraints.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type Any = AppEvent<any>;
+/**
+ * Extracts the type of a registered event's values.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type Type<E extends Any> = E["schema"]["Type"];
+/**
+ * Registers one of the application's events with an assistant.
+ *
+ * **Details**
+ *
+ * Storing the event wakes a turn only when `wakes` is `true`; it defaults to `false`. `render`
+ * defaults to `"json"` for an event that wakes a turn. An event that doesn't wake a turn and has
+ * no `render` isn't read by the model.
+ *
+ * The schema must be a tagged struct or class whose `_tag` is a string literal; `make` throws
+ * otherwise.
+ *
+ * **Example** (Registering an event that wakes a turn)
+ *
+ * ```ts
+ * import { AppEvent, Assistant, InputId } from "effect-assistant"
+ * import * as Schema from "effect/Schema"
+ *
+ * class OrderShipped extends Schema.TaggedClass<OrderShipped>()("OrderShipped", {
+ *   id: InputId.InputId,
+ *   orderId: Schema.String,
+ *   carrier: Schema.String
+ * }) {}
+ *
+ * export const MyAssistant = Assistant.make("my-assistant", {
+ *   events: [
+ *     AppEvent.make(OrderShipped, {
+ *       wakes: true,
+ *       render: (shipped) =>
+ *         `Order ${shipped.orderId} shipped with ${shipped.carrier}. Tell the user if it matters.`
+ *     })
+ *   ]
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: <S extends EventSchema>(schema: S, options?: {
+  /** Whether storing it starts a turn, like a user's message. Default false. */
+  readonly wakes?: boolean | undefined;
+  /** How the model reads it in its history. */
+  readonly render?: Render<S["Type"]> | undefined;
+}) => AppEvent<S>;
+//#endregion
+export { AppEvent_d_exports };
+//# sourceMappingURL=AppEvent.d.ts.map

package/dist/AppEvent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppEvent.d.ts","names":[],"sources":["../src/AppEvent.ts"],"mappings":";;;;;;;;;;;;;;YAuBY,cAAc,OAAO;WAAiB;;WAA2B;;WAClE;aAAmB;eAAiB,KAAK,UAAU;;;;;;;;;;;;;YAYlD,OAAO,gBAAgB,OAAO;;;;;;;;;;iBAWzB,SAAS,UAAU,cAAc;WACvC,QAAQ;WACR;WACA;WACA,QAAQ,OAAO;;;;;;;;YASd,MAAM;;;;;;;YAQN,KAAK,UAAU,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAgDrB,OAAQ,UAAU,aAAW,QAChC,GAAC;;WAGE;;WAEA,SAAS,OAAO;MAE1B,SAAS"}

package/dist/AppEvent.js

@@ -0,0 +1,71 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import * as Predicate from "effect/Predicate";
+import * as SchemaAST from "effect/SchemaAST";
+//#region src/AppEvent.ts
+/**
+* Registers an application's own events with an assistant.
+*
+* An app event is a tagged schema for something the application reports into a chat, such as a
+* workflow's progress, a webhook, a summary for compaction, or the draft the user opened.
+* {@link make} registers one with two choices: whether storing it wakes a turn (`wakes`), and
+* how the model reads it (`render`).
+*
+* @since 0.1.0
+*/
+var AppEvent_exports = /* @__PURE__ */ __exportAll({ make: () => make });
+const tagOf = (schema) => {
+	const ast = schema.fields._tag.ast;
+	if (SchemaAST.isLiteral(ast) && Predicate.isString(ast.literal)) return ast.literal;
+	throw new Error("An app event is a tagged struct or class.");
+};
+/**
+* Registers one of the application's events with an assistant.
+*
+* **Details**
+*
+* Storing the event wakes a turn only when `wakes` is `true`; it defaults to `false`. `render`
+* defaults to `"json"` for an event that wakes a turn. An event that doesn't wake a turn and has
+* no `render` isn't read by the model.
+*
+* The schema must be a tagged struct or class whose `_tag` is a string literal; `make` throws
+* otherwise.
+*
+* **Example** (Registering an event that wakes a turn)
+*
+* ```ts
+* import { AppEvent, Assistant, InputId } from "effect-assistant"
+* import * as Schema from "effect/Schema"
+*
+* class OrderShipped extends Schema.TaggedClass<OrderShipped>()("OrderShipped", {
+*   id: InputId.InputId,
+*   orderId: Schema.String,
+*   carrier: Schema.String
+* }) {}
+*
+* export const MyAssistant = Assistant.make("my-assistant", {
+*   events: [
+*     AppEvent.make(OrderShipped, {
+*       wakes: true,
+*       render: (shipped) =>
+*         `Order ${shipped.orderId} shipped with ${shipped.carrier}. Tell the user if it matters.`
+*     })
+*   ]
+* })
+* ```
+*
+* @category constructors
+* @since 0.1.0
+*/
+const make = (schema, options) => {
+	const wakes = options?.wakes ?? false;
+	return {
+		schema,
+		tag: tagOf(schema),
+		wakes,
+		render: options?.render ?? (wakes ? "json" : void 0)
+	};
+};
+//#endregion
+export { AppEvent_exports, make };
+
+//# sourceMappingURL=AppEvent.js.map

package/dist/AppEvent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AppEvent.js","names":[],"sources":["../src/AppEvent.ts"],"sourcesContent":["/**\n * Registers an application's own events with an assistant.\n *\n * An app event is a tagged schema for something the application reports into a chat, such as a\n * workflow's progress, a webhook, a summary for compaction, or the draft the user opened.\n * {@link make} registers one with two choices: whether storing it wakes a turn (`wakes`), and\n * how the model reads it (`render`).\n *\n * @since 0.1.0\n */\nimport * as Predicate from \"effect/Predicate\"\nimport type * as Schema from \"effect/Schema\"\nimport * as SchemaAST from \"effect/SchemaAST\"\n\n/**\n * Schema for one of the application's own events.\n *\n * It is a tagged struct or class (`Schema.TaggedStruct`, `Schema.TaggedClass`) that needs no\n * services.\n *\n * @category models\n * @since 0.1.0\n */\nexport type EventSchema = Schema.Codec<{ readonly _tag: string }, { readonly _tag: string }> & {\n  readonly fields: { readonly _tag: { readonly ast: SchemaAST.AST } }\n}\n\n/**\n * Describes how the model reads an event.\n *\n * `\"json\"` shows the event's tag and fields as JSON. A function shows the text it returns for the\n * event.\n *\n * @category models\n * @since 0.1.0\n */\nexport type Render<A> = \"json\" | ((event: A) => string)\n\n/**\n * Represents one of the application's events, registered with an assistant.\n *\n * It holds the event's schema and tag, whether storing it wakes a turn, and how the model reads\n * it. A `render` of `undefined` means the model doesn't read it.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface AppEvent<S extends EventSchema = EventSchema> {\n  readonly schema: S\n  readonly tag: string\n  readonly wakes: boolean\n  readonly render: Render<S[\"Type\"]> | undefined\n}\n\n/**\n * Represents any registered event, for generic constraints.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type Any = AppEvent<any>\n\n/**\n * Extracts the type of a registered event's values.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type Type<E extends Any> = E[\"schema\"][\"Type\"]\n\nconst tagOf = (schema: EventSchema): string => {\n  const ast = schema.fields._tag.ast\n\n  if (SchemaAST.isLiteral(ast) && Predicate.isString(ast.literal)) return ast.literal\n\n  throw new Error(\"An app event is a tagged struct or class.\")\n}\n\n/**\n * Registers one of the application's events with an assistant.\n *\n * **Details**\n *\n * Storing the event wakes a turn only when `wakes` is `true`; it defaults to `false`. `render`\n * defaults to `\"json\"` for an event that wakes a turn. An event that doesn't wake a turn and has\n * no `render` isn't read by the model.\n *\n * The schema must be a tagged struct or class whose `_tag` is a string literal; `make` throws\n * otherwise.\n *\n * **Example** (Registering an event that wakes a turn)\n *\n * ```ts\n * import { AppEvent, Assistant, InputId } from \"effect-assistant\"\n * import * as Schema from \"effect/Schema\"\n *\n * class OrderShipped extends Schema.TaggedClass<OrderShipped>()(\"OrderShipped\", {\n *   id: InputId.InputId,\n *   orderId: Schema.String,\n *   carrier: Schema.String\n * }) {}\n *\n * export const MyAssistant = Assistant.make(\"my-assistant\", {\n *   events: [\n *     AppEvent.make(OrderShipped, {\n *       wakes: true,\n *       render: (shipped) =>\n *         `Order ${shipped.orderId} shipped with ${shipped.carrier}. Tell the user if it matters.`\n *     })\n *   ]\n * })\n * ```\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = <S extends EventSchema>(\n  schema: S,\n  options?: {\n    /** Whether storing it starts a turn, like a user's message. Default false. */\n    readonly wakes?: boolean | undefined\n    /** How the model reads it in its history. */\n    readonly render?: Render<S[\"Type\"]> | undefined\n  }\n): AppEvent<S> => {\n  const wakes = options?.wakes ?? false\n\n  return {\n    schema,\n    tag: tagOf(schema),\n    wakes,\n    render: options?.render ?? (wakes ? \"json\" : undefined)\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAsEA,MAAM,SAAS,WAAgC;CAC7C,MAAM,MAAM,OAAO,OAAO,KAAK;CAE/B,IAAI,UAAU,UAAU,GAAG,KAAK,UAAU,SAAS,IAAI,OAAO,GAAG,OAAO,IAAI;CAE5E,MAAM,IAAI,MAAM,2CAA2C;AAC7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,MAAa,QACX,QACA,YAMgB;CAChB,MAAM,QAAQ,SAAS,SAAS;CAEhC,OAAO;EACL;EACA,KAAK,MAAM,MAAM;EACjB;EACA,QAAQ,SAAS,WAAW,QAAQ,SAAS,KAAA;CAC/C;AACF"}

package/dist/Assistant.d.ts

@@ -0,0 +1,403 @@
+import { Any as Any$1, AppEvent_d_exports, Type } from "./AppEvent.js";
+import { ChatId } from "./ChatId.js";
+import { AssistantEvent, AssistantEvent_d_exports, Input } from "./AssistantEvent.js";
+import { Instructions_d_exports, Resolved } from "./Instructions.js";
+import { AssistantLoop_d_exports, ChatHistory, Event, ToolkitServices } from "./AssistantLoop.js";
+import { CurrentChat } from "./CurrentChat.js";
+import { BlockKit, BlockKit_d_exports } from "./BlockKit.js";
+import { Skill } from "./Skill.js";
+import { Any as Any$2, CheckServices, HandlerOf, Runner, Specialist_d_exports, ToolHandlers } from "./Specialist.js";
+import { AssistantEngine } from "./AssistantEngine.js";
+import { Chats_d_exports, GetChatError } from "./Chats.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 Assistant_d_exports {
+  export { Any, Assistant, Chat, ChatIdentifier, Entry, Handler, HandlerServices, HistoryView, Identifier, LoopOptions, ReplyOptions, Service, Turn, TurnServices, isAssistant, make };
+}
+declare const TypeId: "~effect-assistant/Assistant";
+/**
+ * Represents the services that a turn provides to its tools, its loop, and its specialists. These
+ * are the turn's chat (`CurrentChat`) and the chat's specialist runner (`Specialist.Runner`).
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type TurnServices = CurrentChat | Runner;
+/**
+ * Represents the options accepted by `turn.loop`.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface LoopOptions<T extends Record<string, Tool.Any> = Record<never, never>, RS = never, Events = never> {
+  /** The assistant's role and rules. The loop places `Instructions.protocol` before them. */
+  readonly instructions: string | Resolved;
+  /**
+   * Tools the model can use in addition to the assistant's own. This is an `effect/ai` toolkit,
+   * and its handlers come from the layer. Combine several toolkits with `Toolkit.merge`, for
+   * example `Memory.Tools` or a `ToolDiscovery.make(...)` toolkit together with your own.
+   */
+  readonly toolkit?: Toolkit.Toolkit<T> | undefined;
+  /**
+   * Playbooks the model can follow. The prompt lists them as a catalog, and the model loads one
+   * with `load_skill` when a task matches it.
+   */
+  readonly skills?: ReadonlyArray<Skill<RS>> | undefined;
+  /** The maximum number of model calls per turn. Defaults to 16. */
+  readonly maxSteps?: number | undefined;
+  /** The message the reply pass gives the model when the turn would end without a reply. */
+  readonly replyNudge?: string | undefined;
+  /**
+   * Selects which of the chat's entries the model reads, for example only those since the last
+   * summary. Defaults to all entries.
+   */
+  readonly history?: HistoryView<Events> | undefined;
+}
+/**
+ * Represents a function that selects which of a chat's entries the model reads, and what else it
+ * reads with them.
+ *
+ * **Details**
+ *
+ * The function receives the chat's entries and returns, in order, a mix of entries and
+ * `Prompt.Message`s. The model reads the returned entries the same way it reads the full history,
+ * and reads each prompt message unchanged.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type HistoryView<Events = never> = (entries: ReadonlyArray<Entry<Events>>) => ReadonlyArray<Entry<Events> | Prompt.Message>;
+/**
+ * Represents an entry in a chat's log, with the assistant's own events decoded to their types.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Entry<Events = never> {
+  readonly chatId: ChatId;
+  readonly seq: number;
+  readonly at: number;
+  readonly event: AssistantEvent | Events;
+}
+/**
+ * Represents the options accepted by `turn.replyIfOwed`.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface ReplyOptions {
+  /** The assistant's instructions, as passed to `turn.loop`. `Instructions.protocol` is added. */
+  readonly instructions: string | Resolved;
+  /**
+   * The message given to the model after the history. Defaults to a message saying that it
+   * hasn't replied yet and should reply now.
+   */
+  readonly nudge?: string | undefined;
+}
+/**
+ * Represents one turn, as the assistant's handler receives it.
+ *
+ * `Events` is the type of the app's own events that the assistant registered with its `events`
+ * option.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Turn<Events = never> {
+  readonly chatId: ChatId;
+  /**
+   * Returns the model's history, built from the chat's entries (all of them, or those a view
+   * keeps), together with how far into the chat it reaches.
+   *
+   * Read it before every model call, as the loop does. Each step records how far its model call
+   * read, and the turn ends once it has handled what the model saw. An input that arrived after
+   * that is handled by the next turn.
+   */
+  readonly history: (view?: HistoryView<Events>) => Effect.Effect<ChatHistory>;
+  /**
+   * Returns the full system prompt for the given instructions. It contains
+   * `Instructions.protocol`, the instructions, and the specialist runs that are working now.
+   */
+  readonly instructions: (instructions: string | Resolved) => Resolved;
+  /**
+   * Runs the agent loop over the chat. The loop uses `Instructions.protocol`, the assistant's own
+   * tools, and the instructions, tools, and skills in `options`. Every step is a tool call, and
+   * the loop ends with `replyIfOwed`.
+   */
+  readonly loop: <T extends Record<string, Tool.Any> = Record<never, never>, RS = never>(options: LoopOptions<T, RS, Events>) => Stream.Stream<Event, AiError.AiError, LanguageModel.LanguageModel | TurnServices | ToolkitServices<T> | RS>;
+  /**
+   * Runs one more pass when the turn would otherwise end without a reply to the user's latest
+   * message. In this pass the model can only reply.
+   *
+   * The stream is empty when no reply is owed, or when an input arrived that the next turn will
+   * read. `loop` runs this pass with its own prompt and tools, so the pass reuses the cached
+   * prompt.
+   */
+  readonly replyIfOwed: (options: ReplyOptions) => Stream.Stream<Event, AiError.AiError, LanguageModel.LanguageModel | TurnServices>;
+}
+/**
+ * Represents an assistant's handler, which runs a turn and returns it as a stream of the loop's
+ * events.
+ *
+ * The handler may return the stream directly or from an Effect. `R` is the services the stream
+ * requires, and `RE` is the services the Effect requires.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Handler<R = never, RE = R, Events = never> = (turn: Turn<Events>) => Stream.Stream<Event, unknown, R> | Effect.Effect<Stream.Stream<Event, unknown, R>, unknown, RE>;
+/**
+ * Computes the services an assistant's handler needs beyond those its turns provide (the turn
+ * services and `LanguageModel`) and its tools' handlers (which its layer requires). These are the
+ * services that its build Effect must require.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type HandlerServices<R> = Exclude<R, TurnServices | LanguageModel.LanguageModel | Tool.Handler<string>>;
+/**
+ * Identifies an assistant's service in a context. Each assistant has its own identifier, keyed by
+ * its name.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Identifier<Name extends string> {
+  readonly "~effect-assistant/Assistant": Name;
+}
+/**
+ * Identifies, in a context, the chat that an assistant's turns run in.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface ChatIdentifier<Name extends string> {
+  readonly "~effect-assistant/Assistant/Chat": Name;
+}
+/**
+ * Represents the chat that a turn of this assistant runs in, typed with the assistant's events.
+ *
+ * Use `yield* MyAssistant.Chat` in the handler, in the handler's build, or in a tool that its
+ * turns run. Code that doesn't know the assistant uses `CurrentChat` instead.
+ *
+ * @see {@link CurrentChat} for the same chat without the assistant's event types
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Chat<Events = never> {
+  readonly chatId: ChatId;
+  /**
+   * The chat's entries so far, in order. They include the library's events and the assistant's
+   * own events, typed.
+   */
+  readonly entries: Effect.Effect<ReadonlyArray<Entry<Events>>>;
+  /**
+   * 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, such as a summary. An event that wakes a
+   * turn is handled by the next turn.
+   */
+  append(...events: ReadonlyArray<AssistantEvent | Events>): Effect.Effect<void>;
+}
+/**
+ * Represents the service that `yield* MyAssistant` returns. It gives code outside a chat, such as
+ * a server or a workflow, access to the assistant's chats. Code that runs inside a chat uses
+ * `CurrentChat` instead.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Service<Events = never> {
+  /**
+   * Stores an input or one of the assistant's own events, then returns. Examples are a user's
+   * message or block answer, a workflow's progress, or the draft the user opened. The assistant
+   * works on events that wake a turn in the background.
+   *
+   * Fails with `GetChatError` when the app's `Chats` service reports that the chat can't be used,
+   * because the app doesn't know the chat or has deleted it.
+   */
+  submit(chatId: ChatId, input: Input | Events): Effect.Effect<void, GetChatError>;
+  /**
+   * Streams the chat's stored entries, then live ones, with the assistant's own events decoded.
+   * A reader that already has the earlier entries passes `after` and receives only the entries
+   * after that `seq`.
+   *
+   * For a chat client, pipe the whole log into `ChatView.updates(MyAssistant, { after })`, which
+   * streams the chat as its user sees it. Its `after` goes there, not here: the view of a message
+   * depends on earlier entries.
+   */
+  readonly subscribe: (chatId: ChatId, options?: {
+    readonly after?: number | undefined;
+  }) => Stream.Stream<Entry<Events>>;
+  /**
+   * Deletes a chat by storing a `ChatDeleted` event and stopping everything that works in it.
+   *
+   * **Details**
+   *
+   * A turn or specialist run working in the chat stops, and subscribers' streams end with the
+   * `ChatDeleted` event. After that the chat stores nothing more: a later input, a run's report,
+   * or a workflow's event for it is dropped without an error. The log is kept, and removing it is
+   * up to the app. Deleting a chat a second time does nothing.
+   *
+   * When the app's `Chats` service reports a chat as deleted, the assistant deletes it in the same
+   * way the next time it checks. It checks before an input is stored and before each model call.
+   */
+  readonly delete: (chatId: ChatId) => Effect.Effect<void>;
+}
+/**
+ * Represents an assistant's definition.
+ *
+ * The definition holds what callers and the UI need to know about the assistant, builds its
+ * handler's layer, and is the key of its service (`yield* MyAssistant`). `Events` is the type of
+ * the app's own events that the assistant registered.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Assistant<Name extends string = string, Specs extends Any$2 = never, Events = never> extends Context.Service<Identifier<Name>, Service<Events>> {
+  readonly [TypeId]: typeof TypeId;
+  readonly name: Name;
+  readonly blocks: BlockKit | undefined;
+  /** The specialists the assistant can hand work to. */
+  readonly specialists: ReadonlyArray<Specs>;
+  /** The app's own events the assistant registered. */
+  readonly events: ReadonlyArray<Any$1>;
+  /**
+   * Creates a layer that registers the assistant's handler with the engine and provides the
+   * assistant's service.
+   *
+   * **Details**
+   *
+   * `build` is the handler, or an Effect that returns it. The handler may use the turn services,
+   * `LanguageModel`, its tools' handlers (which the layer then requires), and services that its
+   * build Effect required (see `Specialist.CheckServices`). The layer requires the
+   * `AssistantEngine`, the `LanguageModel`, and each specialist's handler
+   * (`Research.toLayer(...)`).
+   *
+   * **Example** (Providing an assistant's handler)
+   *
+   * ```ts
+   * import { Assistant, AssistantEngine, ChatLog } from "effect-assistant"
+   * import type * as LanguageModel from "effect/ai/LanguageModel"
+   * import * as Layer from "effect/Layer"
+   *
+   * declare const ModelLive: Layer.Layer<LanguageModel.LanguageModel>
+   *
+   * export const MyAssistant = Assistant.make("my-assistant")
+   *
+   * const MyAssistantLive = MyAssistant.toLayer((turn) =>
+   *   turn.loop({ instructions: "You help a small team. Be brief." })
+   * )
+   *
+   * const AppLive = MyAssistantLive.pipe(
+   *   Layer.provide(ModelLive),
+   *   Layer.provideMerge(AssistantEngine.layerMemory),
+   *   Layer.provideMerge(ChatLog.layerMemory)
+   * )
+   * ```
+   */
+  readonly toLayer: <R = never, RE = never, E = never, RX = never>(build: (Handler<R, RE, Events> | Effect.Effect<Handler<R, RE, Events>, E, RX>) & CheckServices<Exclude<HandlerServices<R | RE>, RX | ChatIdentifier<Name>>>) => Layer.Layer<Identifier<Name>, never, AssistantEngine | LanguageModel.LanguageModel | HandlerOf<Specs> | Exclude<RX, Scope.Scope | CurrentChat | ChatIdentifier<Name>> | ToolHandlers<R | RE>>;
+  /**
+   * A layer that provides the assistant's service without its handler.
+   *
+   * **When to use**
+   *
+   * Use it in a process that submits to chats that another process runs, such as a web server in
+   * front of a cluster.
+   *
+   * **Example** (Serving clients in front of a cluster)
+   *
+   * ```ts
+   * import { Assistant, AssistantEngine } from "effect-assistant"
+   * import * as Layer from "effect/Layer"
+   *
+   * export const MyAssistant = Assistant.make("my-assistant")
+   *
+   * // Requires `ChatLog` and `Sharding`. The cluster's runners run the chats.
+   * const MyAssistantClient = MyAssistant.layerClient.pipe(
+   *   Layer.provide(AssistantEngine.layerCluster)
+   * )
+   * ```
+   */
+  readonly layerClient: Layer.Layer<Identifier<Name>, never, AssistantEngine>;
+  /**
+   * The key of the chat that the assistant's turns run in, typed with its events. See
+   * {@link Chat}.
+   */
+  readonly Chat: Context.Service<ChatIdentifier<Name>, Chat<Events>>;
+  /** A schema that encodes the chat's entries to JSON, including the assistant's own events. */
+  readonly Entry: Schema.Codec<Entry<Events>, Schema.Json>;
+}
+/**
+ * Represents any assistant, for use in generic constraints.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type Any = Assistant<any, any, any>;
+/**
+ * Returns `true` when the value is an assistant's definition, created with {@link make}.
+ *
+ * @category guards
+ * @since 0.1.0
+ */
+export declare const isAssistant: (u: unknown) => u is Any;
+/**
+ * Creates an assistant definition from its name, its UI blocks, its specialists, and the app's own
+ * events it stores (see `AppEvent`).
+ *
+ * **Details**
+ *
+ * The definition holds no code that runs turns. Provide a handler with its `toLayer`, then yield
+ * the definition to get the assistant's {@link Service}.
+ *
+ * **Example** (Defining an assistant and submitting a message)
+ *
+ * ```ts
+ * import { Assistant, AssistantEvent, ChatId } from "effect-assistant"
+ * import * as Effect from "effect/Effect"
+ *
+ * export const MyAssistant = Assistant.make("my-assistant")
+ *
+ * const program = Effect.gen(function* () {
+ *   const assistant = yield* MyAssistant
+ *   const chatId = yield* ChatId.make()
+ *
+ *   yield* assistant.submit(chatId, AssistantEvent.UserMessage.make({ text: "Weather in Oslo?" }))
+ * })
+ * ```
+ *
+ * @see {@link Assistant} for the definition's members
+ * @see {@link Service} for what `yield* MyAssistant` returns
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: <const Name extends string, const Specs extends ReadonlyArray<Any$2> = readonly [], const Events extends ReadonlyArray<Any$1> = readonly []>(name: Name, options?: {
+  /** UI blocks the assistant can add to its messages. */
+  readonly blocks?: BlockKit | undefined;
+  /**
+   * The specialists the assistant can hand work to. Each specialist's `toLayer` must be
+   * provided to the assistant's layer.
+   */
+  readonly specialists?: Specs | undefined;
+  /**
+   * The app's own events, each created with `AppEvent.make(schema, { wakes, render })`.
+   * `submit` and the chat's `append` store them, and the chat's `entries` read them back,
+   * decoded. Events that wake a turn are inputs, and the model reads each event that has a
+   * `render`.
+   */
+  readonly events?: Events | undefined;
+}) => Assistant<Name, Specs[number], Type<Events[number]>>;
+//#endregion
+export { Assistant_d_exports };
+//# sourceMappingURL=Assistant.d.ts.map

package/dist/Assistant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Assistant.d.ts","names":[],"sources":["../src/Assistant.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;cAwCM;;;;;;;;YASM,eAAe,cAAc;;;;;;;iBAQxB,YAAY,UAAU,eAAe,KAAK,OAAO,sBAAsB,YAAY;;WAEzF,uBAAuB;;;;;;WAMvB,UAAU,QAAQ,QAAQ;;;;;WAK1B,SAAS,cAAc,MAAM;;WAE7B;;WAEA;;;;;WAKA,UAAU,YAAY;;;;;;;;;;;;;;;YAgBrB,YAAY,mBACtB,SAAS,cAAc,MAAM,aAC1B,cAAc,MAAM,UAAU,OAAO;;;;;;;iBAQzB,MAAM;WACZ,QAAQ;WACR;WACA;WACA,OAAO,iBAAgC;;;;;;;;iBASjC;;WAEN,uBAAuB;;;;;WAKvB;;;;;;;;;;;iBAYM,KAAK;WACX,QAAQ;;;;;;;;;WASR,UAAU,OAAO,YAAY,YAAY,OAAO,OAAO;;;;;WAKvD,eAAe,uBAAuB,aAA0B;;;;;;WAMhE,OAAO,UAAU,eAAe,KAAK,OAAO,sBAAsB,YACzE,SAAS,YAAY,GAAG,IAAI,YACzB,OAAO,OACV,OACA,QAAQ,SACR,cAAc,gBAAgB,eAAe,gBAA8B,KAAK;;;;;;;;;WAUzE,cACP,SAAS,iBACN,OAAO,OAAO,OAAqB,QAAQ,SAAS,cAAc,gBAAgB;;;;;;;;;;;;YAa7E,QAAQ,WAAW,KAAK,GAAG,mBACrC,MAAM,KAAK,YAET,OAAO,OAAO,gBAA8B,KAC5C,OAAO,OAAO,OAAO,OAAO,gBAA8B,aAAa;;;;;;;;;YAU/D,gBAAgB,KAAK,QAAQ,GAAG,eAAe,cAAc,gBAAgB,KAAK;;;;;;;;iBAe7E,WAAW;WACjB,+BAA+B;;;;;;;;iBASzB,eAAe;WACrB,oCAAoC;;;;;;;;;;;;;iBAc9B,KAAK;WACX,QAAQ;;;;;WAKR,SAAS,OAAO,OAAO,cAAc,MAAM;;;;;;EAMpD,UAAU,QAAQ,cAAc,iBAAgC,UAAU,OAAO;;;;;;;;;;iBAWlE,QAAQ;;;;;;;;;EAUvB,OAAO,QAAQ,QAAQ,OAAO,QAAuB,SAAS,OAAO,aAAa;;;;;;;;;;WAUzE,YACP,QAAQ,QACR;aAAqB;QAClB,OAAO,OAAO,MAAM;;;;;;;;;;;;;;WAchB,SAAS,QAAQ,WAAW,OAAO;;;;;;;;;;;;iBAa7B,UACf,8BACA,cAAc,eACd,wBACQ,QAAQ,QAAQ,WAAW,OAAO,QAAQ;YACxC,gBAAgB;WACjB,MAAM;WACN,QAAQ;;WAER,aAAa,cAAc;;WAE3B,QAAQ,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAmCtB,UAAU,WAAW,YAAY,WAAW,YACnD,QAAQ,QAAQ,GAAG,IAAI,UAAU,OAAO,OAAO,QAAQ,GAAG,IAAI,SAAS,GAAG,OACxE,cAAyB,QAAQ,gBAAgB,IAAI,KAAK,KAAK,eAAe,YAC7E,MAAM,MACT,WAAW,cAET,kBACA,cAAc,gBACd,UAAqB,SACrB,QAAQ,IAAI,MAAM,QAAQ,cAAc,eAAe,SACvD,aAAwB,IAAI;;;;;;;;;;;;;;;;;;;;;;;WAwBvB,aAAa,MAAM,MAAM,WAAW,cAAc;;;;;WAKlD,MAAM,QAAQ,QAAQ,eAAe,OAAO,KAAK;;WAEjD,OAAO,OAAO,MAAM,MAAM,SAAS,OAAO;;;;;;;;YASzC,MAAM;;;;;;;qBAQL,cAAW,eAAiB,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA8CjC,aACL,2BACA,cAAc,cAAc,4BAC5B,eAAe,cAAc,sBAA2B,MAExD,MAAI;;WAGC,SAAS;;;;;WAKT,cAAc;;;;;;;WAOd,SAAS;MAEnB,UAAU,MAAM,eAAe,KAAc"}