effect-assistant 0.0.0-stage → 0.2.0

package/dist/AssistantLoop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssistantLoop.d.ts","names":[],"sources":["../src/AssistantLoop.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;YAkCY,QAAQ;;;;;;;;;YAUR,cAAc;;;;;;;YAQd,aAAa;;;;;;;YAQb,KAAK,GAAG,KAAK,OAAU,GAAG;;;;;;;qBAQzB,cAAK;;;;;;;qBAQL,aAAI;;;;;;;qBAQJ,aAAI;;;;;;;;;;qBAWJ,aAAI;KAEZ,UAAU;;;;;;;;YASH,gBAAgB,UAAU,eAAe,KAAK,QAAQ,KAAK,YAAY,KAAK,aAAsB;;;;;;;iBAQ7F,YAAY,UAAU,eAAe,KAAK,OAAO;;WAEvD,uBAAuB;;;;;WAKvB,UAAU,QAAQ,QAAQ;;;;;;WAM1B,SAAS,OAAO,OAAO,cAAc,OAAO,WAAW;;;;;WAKvD,aAAa,cAAc;;;;;;;;iBASrB,QAAQ,UAAU,eAAe,KAAK,OAAO,iBAAiB,YAAY;;WAEhF;;;;;;;;;;;;;;;;;;qBA0BE,OAAQ,UAAU,eAAe,KAAK,OAAO,SAAS,WAAW,YAAY,YAAU,SACzF,YAAY,IAAE,OAChB,QAAQ,eAAe,OAAO,OAAO,YAAY,IAAI,IAAI,QAC/D,OAAO,OAAO,KAAK,OAAO,IAAI,QAAQ,UAAU,IAAI,cAAc,gBAAgB,gBAAgB,KAAK;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAiC7F,MAAO,UAAU,eAAe,KAAK,OAAO,SAAO,SACrD,QAAQ,OAChB,OAAO,OAAO,OAAO,QAAQ,SAAS,cAAc,gBAAgB,gBAAgB"}

package/dist/AssistantLoop.js

@@ -0,0 +1,111 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { empty, fromToolkit, merge } from "./internal/toolkit.js";
+import { TurnTools, loop as loop$1, next as next$1, run as run$1, step as step$1, stop as stop$1, value as value$1 } from "./internal/loop.js";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import * as Option from "effect/Option";
+//#region src/AssistantLoop.ts
+var AssistantLoop_exports = /* @__PURE__ */ __exportAll({
+	loop: () => loop,
+	next: () => next,
+	run: () => run,
+	step: () => step,
+	stop: () => stop,
+	value: () => value
+});
+/**
+* Emits a value from a loop body.
+*
+* @category constructors
+* @since 0.1.0
+*/
+const value = value$1;
+/**
+* Ends a loop body's step and continues the loop with the given state.
+*
+* @category constructors
+* @since 0.1.0
+*/
+const next = next$1;
+/**
+* Ends the loop.
+*
+* @category constructors
+* @since 0.1.0
+*/
+const stop = stop$1;
+/**
+* Runs a loop body from an initial state.
+*
+* It emits the body's values, and runs the body again with the state it passes to `next`, until
+* the body calls `stop`.
+*
+* @category constructors
+* @since 0.1.0
+*/
+const loop = loop$1;
+const toolsOf = (toolkit) => Effect.map(TurnTools, (turn) => {
+	const own = toolkit === void 0 ? empty : fromToolkit(toolkit);
+	return Option.match(turn, {
+		onNone: () => own,
+		onSome: (builtins) => merge(builtins, own)
+	});
+});
+/**
+* Runs one step of the agent loop, as a body for {@link loop}.
+*
+* **Details**
+*
+* The step calls the model with the current history and emits its `ModelOutput`. It then runs
+* the output's tool calls and emits a `ToolStarted` and a `ToolResult` for each. `then` receives
+* the step's result and decides what comes next, with `AssistantLoop.next(state)` or
+* `AssistantLoop.stop()`.
+*
+* A tool with Effect's `needsApproval` set fails the loop before the model is called: the
+* library doesn't run calls that wait for approval (see the guide on involving the user).
+*
+* @category constructors
+* @since 0.1.0
+*/
+const step = (options, then) => Stream.unwrap(Effect.map(toolsOf(options.toolkit), (toolkit) => step$1({
+	...options,
+	toolkit
+}, then)));
+/**
+* Runs the agent loop as a stream.
+*
+* **Details**
+*
+* It runs {@link step} after step until the model is done and nothing new arrived while it
+* worked, or until it has made `maxSteps` model calls.
+*
+* **Example** (A turn's loop with a step limit)
+*
+* ```ts
+* import { AssistantLoop } from "effect-assistant"
+* import * as Layer from "effect/Layer"
+* import * as Stream from "effect/Stream"
+*
+* const instructions = "You help a small marketing team."
+*
+* const MyAssistantLive = MyAssistant.toLayer((turn) =>
+*   AssistantLoop.run({
+*     instructions: turn.instructions(instructions),
+*     toolkit: MyTools, // the assistant's own tools are added to them
+*     history: turn.history(),
+*     maxSteps: 12
+*   }).pipe(Stream.concat(turn.replyIfOwed({ instructions })))
+* ).pipe(Layer.provide(MyToolsLive))
+* ```
+*
+* @category constructors
+* @since 0.1.0
+*/
+const run = (options) => Stream.unwrap(Effect.map(toolsOf(options.toolkit), (toolkit) => run$1({
+	...options,
+	toolkit
+})));
+//#endregion
+export { AssistantLoop_exports, loop, next, run, step, stop, value };
+
+//# sourceMappingURL=AssistantLoop.js.map

package/dist/AssistantLoop.js.map

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

package/dist/AssistantToolCall.d.ts

@@ -0,0 +1,32 @@
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+declare namespace AssistantToolCall_d_exports {
+  export { AssistantToolCall, idempotencyKey };
+}
+declare const AssistantToolCall_base: Context.ServiceClass<AssistantToolCall, "effect-assistant/AssistantToolCall", {
+  /** The call's id, as the model wrote it. It stays the same when a crash runs the call again. */
+  readonly callId: string;
+  /** The tool's name. */
+  readonly tool: string;
+}>;
+/**
+ * Service that describes the tool call a tool runs for.
+ *
+ * The agent loop provides it to every call.
+ *
+ * @category services
+ * @since 0.1.0
+ */
+export declare class AssistantToolCall extends AssistantToolCall_base {}
+/**
+ * Gets an idempotency key for what the current tool call does outside the chat.
+ *
+ * The key is the same every time the call runs, and different for every other call.
+ *
+ * @category accessors
+ * @since 0.1.0
+ */
+export declare const idempotencyKey: Effect.Effect<string, never, AssistantToolCall>;
+//#endregion
+export { AssistantToolCall_d_exports };
+//# sourceMappingURL=AssistantToolCall.d.ts.map

package/dist/AssistantToolCall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssistantToolCall.d.ts","names":[],"sources":["../src/AssistantToolCall.ts"],"mappings":";;;;;;;WAuBqB;;WAEF;;;;;;;;;;qBANN,0BAA0B;;;;;;;;;qBAkB1B,gBAAgB,OAAO,sBAAsB"}

package/dist/AssistantToolCall.js

@@ -0,0 +1,37 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import * as Context from "effect/Context";
+//#region src/AssistantToolCall.ts
+/**
+* Gives a tool the call it runs for.
+*
+* The {@link AssistantToolCall} service holds the call's id and the tool's name, and
+* {@link idempotencyKey} derives a key for anything the call does outside the chat.
+*
+* @since 0.1.0
+*/
+var AssistantToolCall_exports = /* @__PURE__ */ __exportAll({
+	AssistantToolCall: () => AssistantToolCall,
+	idempotencyKey: () => idempotencyKey
+});
+/**
+* Service that describes the tool call a tool runs for.
+*
+* The agent loop provides it to every call.
+*
+* @category services
+* @since 0.1.0
+*/
+var AssistantToolCall = class extends Context.Service()("effect-assistant/AssistantToolCall") {};
+/**
+* Gets an idempotency key for what the current tool call does outside the chat.
+*
+* The key is the same every time the call runs, and different for every other call.
+*
+* @category accessors
+* @since 0.1.0
+*/
+const idempotencyKey = AssistantToolCall.useSync((call) => `tool-call:${call.callId}`);
+//#endregion
+export { AssistantToolCall, AssistantToolCall_exports, idempotencyKey };
+
+//# sourceMappingURL=AssistantToolCall.js.map

package/dist/AssistantToolCall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AssistantToolCall.js","names":[],"sources":["../src/AssistantToolCall.ts"],"sourcesContent":["/**\n * Gives a tool the call it runs for.\n *\n * The {@link AssistantToolCall} service holds the call's id and the tool's name, and\n * {@link idempotencyKey} derives a key for anything the call does outside the chat.\n *\n * @since 0.1.0\n */\nimport * as Context from \"effect/Context\"\nimport type * as Effect from \"effect/Effect\"\n\n/**\n * Service that describes the tool call a tool runs for.\n *\n * The agent loop provides it to every call.\n *\n * @category services\n * @since 0.1.0\n */\nexport class AssistantToolCall extends Context.Service<\n  AssistantToolCall,\n  {\n    /** The call's id, as the model wrote it. It stays the same when a crash runs the call again. */\n    readonly callId: string\n    /** The tool's name. */\n    readonly tool: string\n  }\n>()(\"effect-assistant/AssistantToolCall\") {}\n\n/**\n * Gets an idempotency key for what the current tool call does outside the chat.\n *\n * The key is the same every time the call runs, and different for every other call.\n *\n * @category accessors\n * @since 0.1.0\n */\nexport const idempotencyKey: Effect.Effect<string, never, AssistantToolCall> = AssistantToolCall.useSync(\n  (call) => `tool-call:${call.callId}`\n)\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAmBA,IAAa,oBAAb,cAAuC,QAAQ,QAQ7C,CAAC,CAAC,oCAAoC,CAAC,CAAC,CAAC;;;;;;;;;AAU3C,MAAa,iBAAkE,kBAAkB,SAC9F,SAAS,aAAa,KAAK,QAC9B"}

package/dist/Block.d.ts

@@ -0,0 +1,69 @@
+import * as Schema from "effect/Schema";
+declare namespace Block_d_exports {
+  export { Any, Block, Codec, make };
+}
+/**
+ * Schema that a block's props or answer can use.
+ *
+ * It is any codec that needs no services, since the client decodes and encodes with it too.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type Codec = Schema.Codec<any, any>;
+/**
+ * Represents a kind of UI block.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface Block<Kind extends string = string, Props extends Codec = Codec, Answer extends Codec = Codec> {
+  readonly kind: Kind;
+  /** When to use the block. The assistant sees this. */
+  readonly description: string;
+  /** The props the assistant fills in. */
+  readonly props: Props;
+  /** What using the block sends back, or `undefined` for a display-only card. */
+  readonly answer: Answer | undefined;
+}
+/**
+ * Represents any block, for generic constraints.
+ *
+ * @category utility types
+ * @since 0.1.0
+ */
+export type Any = Block;
+/**
+ * Creates a block.
+ *
+ * **Details**
+ *
+ * A block without an `answer` schema is a display-only card. Put the block in the assistant's
+ * `BlockKit` so the assistant can use it.
+ *
+ * **Example** (Defining a block with options to pick from)
+ *
+ * ```ts
+ * import { Assistant, Block, BlockKit } from "effect-assistant"
+ * import * as Schema from "effect/Schema"
+ *
+ * const PickOne = Block.make("pick_one", {
+ *   description: "Options to pick from, when the user chooses between a few.",
+ *   props: Schema.Struct({ options: Schema.Array(Schema.String) }),
+ *   answer: Schema.Struct({ picked: Schema.String })
+ * })
+ *
+ * export const MyAssistant = Assistant.make("my-assistant", { blocks: BlockKit.make([PickOne]) })
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: <const Kind extends string, Props extends Codec, Answer extends Codec = Schema.Never>(kind: Kind, options: {
+  readonly description: string;
+  readonly props: Props;
+  readonly answer?: Answer | undefined;
+}) => Block<Kind, Props, Answer>;
+//#endregion
+export { Block_d_exports };
+//# sourceMappingURL=Block.d.ts.map

package/dist/Block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Block.d.ts","names":[],"sources":["../src/Block.ts"],"mappings":";;;;;;;;;;;;YAmBY,QAAQ,OAAO;;;;;;;iBAQV,MAAM,8BAA8B,cAAc,QAAQ,OAAO,eAAe,QAAQ;WAC9F,MAAM;;WAEN;;WAEA,OAAO;;WAEP,QAAQ;;;;;;;;YASP,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA4BL,aAAc,qBAAqB,cAAc,OAAO,eAAe,QAAQ,OAAO,OAAK,MAChG,MAAI;WAEC;WACA,OAAO;WACP,SAAS;MAEnB,MAAM,MAAM,OAAO"}

package/dist/Block.js

@@ -0,0 +1,39 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+//#region src/Block.ts
+var Block_exports = /* @__PURE__ */ __exportAll({ make: () => make });
+/**
+* Creates a block.
+*
+* **Details**
+*
+* A block without an `answer` schema is a display-only card. Put the block in the assistant's
+* `BlockKit` so the assistant can use it.
+*
+* **Example** (Defining a block with options to pick from)
+*
+* ```ts
+* import { Assistant, Block, BlockKit } from "effect-assistant"
+* import * as Schema from "effect/Schema"
+*
+* const PickOne = Block.make("pick_one", {
+*   description: "Options to pick from, when the user chooses between a few.",
+*   props: Schema.Struct({ options: Schema.Array(Schema.String) }),
+*   answer: Schema.Struct({ picked: Schema.String })
+* })
+*
+* export const MyAssistant = Assistant.make("my-assistant", { blocks: BlockKit.make([PickOne]) })
+* ```
+*
+* @category constructors
+* @since 0.1.0
+*/
+const make = (kind, options) => ({
+	kind,
+	description: options.description,
+	props: options.props,
+	answer: options.answer
+});
+//#endregion
+export { Block_exports, make };
+
+//# sourceMappingURL=Block.js.map

package/dist/Block.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Block.js","names":[],"sources":["../src/Block.ts"],"sourcesContent":["/**\n * Defines UI blocks that an assistant can put in a message.\n *\n * A block is a bit of UI for when a structured answer is easier than typing, such as options to\n * pick from, a yes or no, or a small input. The assistant fills in its `props`, and\n * using the block sends back a value typed by its `answer` schema.\n *\n * @since 0.1.0\n */\nimport type * as Schema from \"effect/Schema\"\n\n/**\n * Schema that a block's props or answer can use.\n *\n * It is any codec that needs no services, since the client decodes and encodes with it too.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type Codec = Schema.Codec<any, any>\n\n/**\n * Represents a kind of UI block.\n *\n * @category models\n * @since 0.1.0\n */\nexport interface Block<Kind extends string = string, Props extends Codec = Codec, Answer extends Codec = Codec> {\n  readonly kind: Kind\n  /** When to use the block. The assistant sees this. */\n  readonly description: string\n  /** The props the assistant fills in. */\n  readonly props: Props\n  /** What using the block sends back, or `undefined` for a display-only card. */\n  readonly answer: Answer | undefined\n}\n\n/**\n * Represents any block, for generic constraints.\n *\n * @category utility types\n * @since 0.1.0\n */\nexport type Any = Block\n\n/**\n * Creates a block.\n *\n * **Details**\n *\n * A block without an `answer` schema is a display-only card. Put the block in the assistant's\n * `BlockKit` so the assistant can use it.\n *\n * **Example** (Defining a block with options to pick from)\n *\n * ```ts\n * import { Assistant, Block, BlockKit } from \"effect-assistant\"\n * import * as Schema from \"effect/Schema\"\n *\n * const PickOne = Block.make(\"pick_one\", {\n *   description: \"Options to pick from, when the user chooses between a few.\",\n *   props: Schema.Struct({ options: Schema.Array(Schema.String) }),\n *   answer: Schema.Struct({ picked: Schema.String })\n * })\n *\n * export const MyAssistant = Assistant.make(\"my-assistant\", { blocks: BlockKit.make([PickOne]) })\n * ```\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = <const Kind extends string, Props extends Codec, Answer extends Codec = Schema.Never>(\n  kind: Kind,\n  options: {\n    readonly description: string\n    readonly props: Props\n    readonly answer?: Answer | undefined\n  }\n): Block<Kind, Props, Answer> => ({\n  kind,\n  description: options.description,\n  props: options.props,\n  answer: options.answer\n})\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuEA,MAAa,QACX,MACA,aAKgC;CAChC;CACA,aAAa,QAAQ;CACrB,OAAO,QAAQ;CACf,QAAQ,QAAQ;AAClB"}

package/dist/BlockKit.d.ts

@@ -0,0 +1,180 @@
+import { AnyEntry, AssistantEvent_d_exports, BlockAnswer } from "./AssistantEvent.js";
+import { Any, Block_d_exports } from "./Block.js";
+import { AssistantMessage, ChatView_d_exports } from "./ChatView.js";
+import { CurrentChat } from "./CurrentChat.js";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+declare namespace BlockKit_d_exports {
+  export { BlockKit, RenderArgs, RenderOptions, Renderers, State, apply, closeStale, fromEntries, make, staleBlocks, toClient };
+}
+/**
+ * Represents a catalog of blocks, with a lookup by kind.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface BlockKit<Blocks extends Any = Any> {
+  readonly blocks: ReadonlyArray<Blocks>;
+  readonly byKind: ReadonlyMap<string, Blocks>;
+}
+/**
+ * Creates a kit from blocks.
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const make: <const Blocks extends ReadonlyArray<Any>>(blocks: Blocks) => BlockKit<Blocks[number]>;
+type KindOf<B> = B extends {
+  readonly kind: infer K extends string;
+} ? K : never;
+type BlockOf<Kit extends BlockKit, K> = Extract<Kit["blocks"][number], {
+  readonly kind: K;
+}>;
+type PropsOf<B> = B extends {
+  readonly props: Schema.Top;
+} ? B["props"]["Type"] : never;
+type AnswerOf<B> = B extends {
+  readonly answer: infer A;
+} ? (A extends Schema.Top ? A["Type"] : never) : never;
+/**
+ * Represents the state of a message's block.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface State {
+  readonly open: boolean;
+  /** The user's answer, if they used the block. */
+  readonly answer: BlockAnswer | undefined;
+}
+/**
+ * Returns the block states after one more event.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export declare const apply: (states: ReadonlyMap<string, State>, event: {
+  readonly _tag: string;
+}) => ReadonlyMap<string, State>;
+/**
+ * Returns the state of every message's block, by message id.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export declare const fromEntries: (entries: ReadonlyArray<AnyEntry>) => ReadonlyMap<string, State>;
+/**
+ * Returns the ids of the messages whose blocks are still open after the user typed the given
+ * number of messages without using them.
+ *
+ * **Details**
+ *
+ * These are the blocks {@link closeStale} closes.
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export declare const staleBlocks: (entries: ReadonlyArray<AnyEntry>, options: {
+  readonly messages: number;
+}) => ReadonlyArray<string>;
+/**
+ * Closes the blocks the user moved on from, which are still open after the given number of typed
+ * messages.
+ *
+ * **Details**
+ *
+ * Run it from a turn, before or after its loop. It records a `BlocksClosed` event, so every
+ * client folds the blocks closed.
+ *
+ * @see {@link staleBlocks} for the blocks it closes
+ *
+ * @category utils
+ * @since 0.1.0
+ */
+export declare const closeStale: (options: {
+  readonly messages: number;
+}) => Effect.Effect<void, never, CurrentChat>;
+/**
+ * Represents what a renderer receives for one block.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface RenderArgs<B> {
+  /**
+   * The id of the message the block is on. A block whose button calls your API can key the work
+   * on it, with the chat's id, so the work runs once per block.
+   */
+  readonly messageId: string;
+  readonly text: string;
+  readonly props: PropsOf<B>;
+  /**
+   * Whether the block is open. It is `false` once the block is answered, with the block or in
+   * words; show it read-only then.
+   */
+  readonly open: boolean;
+  /** The user's answer, if they used the block. */
+  readonly answer: AnswerOf<B> | undefined;
+  /** Sends an answer. Only call it while `open`. */
+  readonly respond: (answer: AnswerOf<B>) => void;
+}
+/**
+ * Represents a renderer for every kind in a kit.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export type Renderers<Kit extends BlockKit, Out> = { readonly [K in KindOf<Kit["blocks"][number]>]: (args: RenderArgs<BlockOf<Kit, K>>) => Out; };
+/**
+ * Represents the options for rendering one message's block.
+ *
+ * @category models
+ * @since 0.1.0
+ */
+export interface RenderOptions {
+  /** Submits an answer, for example over RPC. */
+  readonly respond: (answer: BlockAnswer) => void;
+}
+/**
+ * Creates a client-side renderer for the blocks on a chat view's messages
+ * (`ChatView.AssistantMessage`).
+ *
+ * **Details**
+ *
+ * The renderers are type-checked, so every kind in the kit needs one, and each receives typed
+ * `props` and `answer`. A renderer's `respond` builds a `BlockAnswer` input, with the answer
+ * encoded by the block's answer schema, and passes it to the `respond` option to submit.
+ *
+ * The returned function returns `undefined` for a message without a block, or with a block it
+ * can't decode or has no renderer for.
+ *
+ * **Example** (Rendering blocks with React)
+ *
+ * ```tsx
+ * import { BlockKit } from "effect-assistant"
+ * import type { ReactNode } from "react"
+ *
+ * const Blocks = BlockKit.make([PickOne, OrderDraft])
+ *
+ * const renderBlock = BlockKit.toClient<typeof Blocks, ReactNode>(Blocks, {
+ *   pick_one: ({ props, open, respond }) =>
+ *     props.options.map((option) => (
+ *       <button key={option} disabled={!open} onClick={() => respond({ picked: option })}>
+ *         {option}
+ *       </button>
+ *     )),
+ *   // No answer schema: the button calls the app's own API with the props the user sees.
+ *   order_draft: ({ props }) => <button onClick={() => placeOrder(props)}>Place order</button>
+ * })
+ *
+ * // For each AssistantMessage in the chat's view:
+ * renderBlock(message, { respond: (answer) => submit(answer) })
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare function toClient<Kit extends BlockKit, Out>(kit: Kit, renderers: Renderers<Kit, Out>): (message: AssistantMessage, options: RenderOptions) => Out | undefined;
+//#endregion
+export { BlockKit_d_exports };
+//# sourceMappingURL=BlockKit.d.ts.map

package/dist/BlockKit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BlockKit.d.ts","names":[],"sources":["../src/BlockKit.ts"],"mappings":";;;;;;;;;;;;;;;iBA0BiB,SAAS,eAAe,MAAY;WAC1C,QAAQ,cAAc;WACtB,QAAQ,oBAAoB;;;;;;;;qBAS1B,aAAc,eAAe,cAAc,MAAU,QAAU,WAAS,SAAS;KAKzF,OAAO,KAAK;WAAqB,YAAY;IAAqB;KAElE,QAAQ,YAAY,UAAU,KAAK,QAAQ;WAAkC,MAAM;;KAEnF,QAAQ,KAAK;WAAqB,OAAO,OAAO;IAAQ;KAExD,SAAS,KAAK;WAAqB,cAAc;KAAO,UAAU,OAAO,MAAM;;;;;;;iBAQnE;WACN;;WAEA,QAAQ;;;;;;;;qBASN,QAAK,QACR,oBAAoB,QAAM;WAChB;MACjB,oBAAoB;;;;;;;qBAkCV,cAAW,SAAa,cAAc,cAA2B,oBAAoB;;;;;;;;;;;;qBAmBrF,cAAW,SACb,cAAc,WAAwB;WAC3B;MACnB;;;;;;;;;;;;;;;qBA+BU,aAAU;WAAsD;MAK3E,OAAA,oBAAA;;;;;;;iBAQe,WAAW;;;;;WAKjB;WACA;WACA,OAAO,QAAQ;;;;;WAKf;;WAEA,QAAQ,SAAS;;WAEjB,UAAU,QAAQ,SAAS;;;;;;;;YAS1B,UAAU,YAAY,UAAU,mBAChC,KAAK,OAAO,0BAA0B,MAAM,WAAW,QAAQ,KAAK,QAAQ;;;;;;;iBASvE;;WAEN,UAAU,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBA0Cb,SAAS,YAAY,UAAU,KAC7C,KAAK,KACL,WAAW,UAAU,KAAK,QACxB,SAAS,kBAA2B,SAAS,kBAAkB"}

package/dist/BlockKit.js

@@ -0,0 +1,148 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { fromKey } from "./InputId.js";
+import { BlockAnswer, BlocksClosed, isLibraryEvent } from "./AssistantEvent.js";
+import { CurrentChat } from "./CurrentChat.js";
+import * as Predicate from "effect/Predicate";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Option from "effect/Option";
+//#region src/BlockKit.ts
+/**
+* Groups the blocks an assistant may put in its messages, and renders them on the client.
+*
+* A kit is created with {@link make} and passed to `Assistant.make`. {@link fromEntries} computes
+* the state of every message's block from a chat's log, {@link closeStale} closes the blocks the
+* user moved on from, and {@link toClient} creates a client-side renderer with one function per
+* block kind.
+*
+* @since 0.1.0
+*/
+var BlockKit_exports = /* @__PURE__ */ __exportAll({
+	apply: () => apply,
+	closeStale: () => closeStale,
+	fromEntries: () => fromEntries,
+	make: () => make,
+	staleBlocks: () => staleBlocks,
+	toClient: () => toClient
+});
+/**
+* Creates a kit from blocks.
+*
+* @category constructors
+* @since 0.1.0
+*/
+const make = (blocks) => ({
+	blocks,
+	byKind: new Map(blocks.map((block) => [block.kind, block]))
+});
+/**
+* Returns the block states after one more event.
+*
+* @category utils
+* @since 0.1.0
+*/
+const apply = (states, event) => {
+	if (!isLibraryEvent(event)) return states;
+	const close = (ids) => {
+		const open = ids.filter((id) => states.get(id)?.open === true);
+		if (open.length === 0) return states;
+		const next = new Map(states);
+		for (const id of open) next.set(id, {
+			open: false,
+			answer: void 0
+		});
+		return next;
+	};
+	if (Predicate.isTagged(event, "BlocksClosed")) return close(event.messageIds);
+	if (Predicate.isTagged(event, "AssistantMessage")) {
+		const closed = close(event.closes ?? []);
+		return event.block === void 0 ? closed : new Map(closed).set(event.id, {
+			open: true,
+			answer: void 0
+		});
+	}
+	if (!Predicate.isTagged(event, "BlockAnswer") || states.get(event.messageId)?.open !== true) return states;
+	return new Map(states).set(event.messageId, {
+		open: false,
+		answer: event
+	});
+};
+/**
+* Returns the state of every message's block, by message id.
+*
+* @category utils
+* @since 0.1.0
+*/
+const fromEntries = (entries) => {
+	let states = /* @__PURE__ */ new Map();
+	for (const entry of entries) states = apply(states, entry.event);
+	return states;
+};
+/**
+* Returns the ids of the messages whose blocks are still open after the user typed the given
+* number of messages without using them.
+*
+* **Details**
+*
+* These are the blocks {@link closeStale} closes.
+*
+* @category utils
+* @since 0.1.0
+*/
+const staleBlocks = (entries, options) => {
+	return [...fromEntries(entries)].flatMap(([id, state]) => state.open ? [id] : []).filter((id) => {
+		const shown = entries.findIndex(({ event }) => isLibraryEvent(event) && Predicate.isTagged(event, "AssistantMessage") && event.id === id);
+		if (shown === -1) return false;
+		return entries.slice(shown + 1).filter(({ event }) => Predicate.isTagged(event, "UserMessage")).length >= options.messages;
+	});
+};
+/**
+* Closes the blocks the user moved on from, which are still open after the given number of typed
+* messages.
+*
+* **Details**
+*
+* Run it from a turn, before or after its loop. It records a `BlocksClosed` event, so every
+* client folds the blocks closed.
+*
+* @see {@link staleBlocks} for the blocks it closes
+*
+* @category utils
+* @since 0.1.0
+*/
+const closeStale = Effect.fn(function* (options) {
+	const chat = yield* CurrentChat;
+	const stale = staleBlocks(yield* chat.entries, options);
+	if (stale.length > 0) yield* chat.append(BlocksClosed.make({ messageIds: stale }));
+});
+function toClient(kit, renderers) {
+	return (message, options) => {
+		if (message.block === void 0) return void 0;
+		const { kind } = message.block;
+		const block = kit.byKind.get(kind);
+		const render = renderers[kind];
+		if (block === void 0 || render === void 0) return void 0;
+		const props = Schema.decodeUnknownOption(block.props)(message.block.props);
+		if (Option.isNone(props)) return void 0;
+		const given = message.block.answer;
+		const answerCodec = block.answer === void 0 ? void 0 : Schema.toCodecJson(block.answer);
+		const answer = given === void 0 || answerCodec === void 0 ? Option.none() : Schema.decodeUnknownOption(answerCodec)(given);
+		return render({
+			messageId: message.id,
+			text: message.text,
+			props: props.value,
+			open: message.block.status === "open",
+			answer: Option.getOrUndefined(answer),
+			respond: (value) => options.respond(BlockAnswer.make({
+				id: fromKey(`${message.id}:answer`),
+				messageId: message.id,
+				kind,
+				value: answerCodec === void 0 ? value : Schema.encodeUnknownSync(answerCodec)(value)
+			}))
+		});
+	};
+}
+//#endregion
+export { BlockKit_exports, apply, closeStale, fromEntries, make, staleBlocks, toClient };
+
+//# sourceMappingURL=BlockKit.js.map