effect-assistant 0.0.0-stage → 0.2.0

package/dist/ToolDiscovery.js

@@ -0,0 +1,140 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { toJson } from "./internal/schema.js";
+import { AssistantToolCall } from "./AssistantToolCall.js";
+import { needingApproval, needsApprovalMessage, runNative } from "./internal/toolkit.js";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Response from "effect/ai/Response";
+import * as Tool from "effect/ai/Tool";
+import * as Toolkit from "effect/ai/Toolkit";
+//#region src/ToolDiscovery.ts
+/**
+* Turns a catalog toolkit into two tools, so the prompt doesn't carry every tool definition.
+*
+* `search_tools` finds tools by what the model needs to do and returns their names, descriptions,
+* and input schemas. `execute_tool` validates an input and runs one of them. {@link make} returns
+* the two tools as a native toolkit, and {@link layer} their handlers.
+*
+* @since 0.1.0
+*/
+var ToolDiscovery_exports = /* @__PURE__ */ __exportAll({
+	layer: () => layer,
+	make: () => make
+});
+const words = (text) => new Set(text.toLowerCase().split(/[^a-z0-9]+/).filter((word) => word.length >= 3));
+const score = (query, text) => {
+	const target = [...words(text)];
+	const matches = (word) => target.some((t) => t === word || word.length >= 4 && (t.startsWith(word) || word.startsWith(t)));
+	return [...query].filter(matches).length;
+};
+const search = (tools, query, limit) => {
+	const queryWords = words(query);
+	const ranked = tools.flatMap((tool) => {
+		const hits = score(queryWords, `${tool.name} ${Tool.getDescription(tool) ?? ""}`);
+		return hits > 0 ? [{
+			tool,
+			score: hits
+		}] : [];
+	}).sort((a, b) => b.score - a.score);
+	return (ranked.length > 0 ? ranked.map((hit) => hit.tool) : tools).slice(0, limit);
+};
+const SearchTools = Tool.make("search_tools", {
+	description: "Search for more tools by what you need to do. Returns their names, descriptions, and input schemas; call one with execute_tool.",
+	parameters: Schema.Struct({ query: Schema.String.annotate({ description: "What you need to do, in a few words." }) }),
+	success: Schema.Array(Schema.Struct({
+		name: Schema.String,
+		description: Schema.optional(Schema.String),
+		inputSchema: Schema.Json
+	}))
+});
+const ExecuteTool = Tool.make("execute_tool", {
+	description: "Run a tool found with search_tools. Pass its name and an input matching its input schema.",
+	parameters: Schema.Struct({
+		name: Schema.String,
+		input: Schema.Record(Schema.String, Schema.Json)
+	}),
+	success: Schema.Json,
+	failure: Schema.Json,
+	dependencies: [AssistantToolCall]
+});
+const requiring = () => (tool) => tool;
+/**
+* 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.
+*
+* A catalog tool with Effect's `needsApproval` set fails the layer when it is built, as it would
+* fail a loop: the library doesn't run calls that wait for approval.
+*
+* **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
+*/
+const make = (_catalog) => Toolkit.make(SearchTools, requiring()(ExecuteTool));
+/**
+* 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
+*/
+const layer = (catalog) => make(catalog).toLayer(Effect.gen(function* () {
+	const resolved = yield* catalog;
+	const definitions = Object.values(resolved.tools);
+	const needingApproval$1 = needingApproval(definitions);
+	if (needingApproval$1.length > 0) return yield* Effect.die(needsApprovalMessage(needingApproval$1));
+	return {
+		search_tools: ({ query }) => Effect.sync(() => search(definitions, query, 5).map((tool) => ({
+			name: tool.name,
+			description: Tool.getDescription(tool),
+			inputSchema: toJson(Tool.getJsonSchema(tool))
+		}))),
+		execute_tool: Effect.fnUntraced(function* ({ name, input }) {
+			const outer = yield* AssistantToolCall;
+			const call = Response.makePart("tool-call", {
+				id: `${outer.callId}:${name}`,
+				name,
+				params: input,
+				providerExecuted: false
+			});
+			const { outcome, result } = yield* runNative(resolved, call);
+			return outcome === "failure" ? yield* Effect.fail(result) : result;
+		})
+	};
+}));
+//#endregion
+export { ToolDiscovery_exports, layer, make };
+
+//# sourceMappingURL=ToolDiscovery.js.map

package/dist/ToolDiscovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolDiscovery.js","names":["needingApproval","Toolkits.needingApproval","Toolkits.needsApprovalMessage","Toolkits.runNative"],"sources":["../src/ToolDiscovery.ts"],"sourcesContent":["/**\n * Turns a catalog toolkit into two tools, so the prompt doesn't carry every tool definition.\n *\n * `search_tools` finds tools by what the model needs to do and returns their names, descriptions,\n * and input schemas. `execute_tool` validates an input and runs one of them. {@link make} returns\n * the two tools as a native toolkit, and {@link layer} their handlers.\n *\n * @since 0.1.0\n */\nimport * as Response from \"effect/ai/Response\"\nimport * as Tool from \"effect/ai/Tool\"\nimport * as Toolkit from \"effect/ai/Toolkit\"\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\nimport { AssistantToolCall } from \"./AssistantToolCall.ts\"\nimport { toJson } from \"./internal/schema.ts\"\nimport * as Toolkits from \"./internal/toolkit.ts\"\n\nconst words = (text: string): ReadonlySet<string> =>\n  new Set(\n    text\n      .toLowerCase()\n      .split(/[^a-z0-9]+/)\n      .filter((word) => word.length >= 3)\n  )\n\nconst score = (query: ReadonlySet<string>, text: string): number => {\n  const target = [...words(text)]\n\n  const matches = (word: string) =>\n    target.some((t) => t === word || (word.length >= 4 && (t.startsWith(word) || word.startsWith(t))))\n\n  return [...query].filter(matches).length\n}\n\n// Everything when nothing matches, so the model can pick or search again.\nconst search = (tools: ReadonlyArray<Tool.Any>, query: string, limit: number): ReadonlyArray<Tool.Any> => {\n  const queryWords = words(query)\n\n  const ranked = tools\n    .flatMap((tool) => {\n      const hits = score(queryWords, `${tool.name} ${Tool.getDescription(tool) ?? \"\"}`)\n\n      return hits > 0 ? [{ tool, score: hits }] : []\n    })\n    .sort((a, b) => b.score - a.score)\n\n  return (ranked.length > 0 ? ranked.map((hit) => hit.tool) : tools).slice(0, limit)\n}\n\nconst SearchTools = Tool.make(\"search_tools\", {\n  description:\n    \"Search for more tools by what you need to do. Returns their names, descriptions, and input schemas; call one with execute_tool.\",\n  parameters: Schema.Struct({\n    query: Schema.String.annotate({ description: \"What you need to do, in a few words.\" })\n  }),\n  success: Schema.Array(\n    Schema.Struct({\n      name: Schema.String,\n      description: Schema.optional(Schema.String),\n      inputSchema: Schema.Json\n    })\n  )\n})\n\nconst ExecuteTool = Tool.make(\"execute_tool\", {\n  description: \"Run a tool found with search_tools. Pass its name and an input matching its input schema.\",\n  parameters: Schema.Struct({\n    name: Schema.String,\n    input: Schema.Record(Schema.String, Schema.Json)\n  }),\n  success: Schema.Json,\n  // The tool's failure is this call's, so the loop sees it failed (a `wait: true` message doesn't\n  // end the turn).\n  failure: Schema.Json,\n  dependencies: [AssistantToolCall]\n})\n\n// A tool's requirements are a covariant phantom type, so one that needs nothing is one that needs\n// any.\nconst requiring =\n  <R>() =>\n  <N extends string, C extends (Tool.Any extends Tool.Tool<string, infer K, unknown> ? K : never), R0>(\n    tool: Tool.Tool<N, C, R0>\n  ): Tool.Tool<N, C, R0 | R> =>\n    tool\n\n/**\n * Creates the `search_tools` and `execute_tool` tools over a catalog toolkit, as a native toolkit.\n *\n * **Details**\n *\n * Merge the toolkit into the loop's, and provide {@link layer} for the same catalog, which has\n * the tools' handlers. A catalog tool's services are `execute_tool`'s, so the turn provides them\n * as it does for any tool.\n *\n * A catalog tool with Effect's `needsApproval` set fails the layer when it is built, as it would\n * fail a loop: the library doesn't run calls that wait for approval.\n *\n * **Example** (Finding rarely used tools when needed)\n *\n * ```ts\n * import { ToolDiscovery } from \"effect-assistant\"\n * import * as Toolkit from \"effect/ai/Toolkit\"\n * import * as Layer from \"effect/Layer\"\n *\n * // OfficeTools is a big toolkit, found when needed. CommonTools stays in the prompt.\n * const OfficeDiscovery = ToolDiscovery.make(OfficeTools)\n * const OfficeDiscoveryLive = ToolDiscovery.layer(OfficeTools).pipe(Layer.provide(OfficeToolsLive))\n *\n * const MyAssistantLive = MyAssistant.toLayer((turn) =>\n *   turn.loop({\n *     instructions,\n *     toolkit: Toolkit.merge(CommonTools, OfficeDiscovery)\n *   })\n * ).pipe(Layer.provide([CommonToolsLive, OfficeDiscoveryLive]))\n * ```\n *\n * @see {@link layer} for the tools' handlers\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const make = <T extends Record<string, Tool.Any>>(\n  // Only its type is used here, for `execute_tool`'s services: `layer` runs its tools.\n  _catalog: Toolkit.Toolkit<T>\n) => Toolkit.make(SearchTools, requiring<Toolkits.ToolServices<T>>()(ExecuteTool))\n\n/**\n * Creates the layer with the handlers of the `search_tools` and `execute_tool` tools over a\n * catalog toolkit.\n *\n * **Details**\n *\n * The layer needs the catalog's handlers. It provides the handlers of the toolkit that\n * {@link make} returns for the same catalog: handlers are keyed by tool name, so the two calls\n * don't need to share a value. Give both the same catalog.\n *\n * @see {@link make} for the toolkit and an example\n *\n * @category layers\n * @since 0.1.0\n */\nexport const layer = <T extends Record<string, Tool.Any>>(catalog: Toolkit.Toolkit<T>) =>\n  make(catalog).toLayer(\n    Effect.gen(function* () {\n      const resolved = yield* catalog\n      const definitions = Object.values(resolved.tools)\n      const needingApproval = Toolkits.needingApproval(definitions)\n\n      if (needingApproval.length > 0) return yield* Effect.die(Toolkits.needsApprovalMessage(needingApproval))\n\n      return {\n        search_tools: ({ query }) =>\n          Effect.sync(() =>\n            search(definitions, query, 5).map((tool) => ({\n              name: tool.name,\n              description: Tool.getDescription(tool),\n              inputSchema: toJson(Tool.getJsonSchema(tool))\n            }))\n          ),\n        execute_tool: Effect.fnUntraced(function* ({ name, input }) {\n          // Named after the call that runs it: the same id when a crash runs that call again.\n          const outer = yield* AssistantToolCall\n\n          const call = Response.makePart(\"tool-call\", {\n            id: `${outer.callId}:${name}`,\n            name,\n            params: input,\n            providerExecuted: false\n          })\n\n          const { outcome, result } = yield* Toolkits.runNative(resolved, call)\n\n          return outcome === \"failure\" ? yield* Effect.fail(result) : result\n        })\n      }\n    })\n  )\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAkBA,MAAM,SAAS,SACb,IAAI,IACF,KACG,YAAY,CAAC,CACb,MAAM,YAAY,CAAC,CACnB,QAAQ,SAAS,KAAK,UAAU,CAAC,CACtC;AAEF,MAAM,SAAS,OAA4B,SAAyB;CAClE,MAAM,SAAS,CAAC,GAAG,MAAM,IAAI,CAAC;CAE9B,MAAM,WAAW,SACf,OAAO,MAAM,MAAM,MAAM,QAAS,KAAK,UAAU,MAAM,EAAE,WAAW,IAAI,KAAK,KAAK,WAAW,CAAC,EAAG;CAEnG,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC;AACpC;AAGA,MAAM,UAAU,OAAgC,OAAe,UAA2C;CACxG,MAAM,aAAa,MAAM,KAAK;CAE9B,MAAM,SAAS,MACZ,SAAS,SAAS;EACjB,MAAM,OAAO,MAAM,YAAY,GAAG,KAAK,KAAK,GAAG,KAAK,eAAe,IAAI,KAAK,IAAI;EAEhF,OAAO,OAAO,IAAI,CAAC;GAAE;GAAM,OAAO;EAAK,CAAC,IAAI,CAAC;CAC/C,CAAC,CAAC,CACD,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,KAAK;CAEnC,QAAQ,OAAO,SAAS,IAAI,OAAO,KAAK,QAAQ,IAAI,IAAI,IAAI,MAAA,CAAO,MAAM,GAAG,KAAK;AACnF;AAEA,MAAM,cAAc,KAAK,KAAK,gBAAgB;CAC5C,aACE;CACF,YAAY,OAAO,OAAO,EACxB,OAAO,OAAO,OAAO,SAAS,EAAE,aAAa,uCAAuC,CAAC,EACvF,CAAC;CACD,SAAS,OAAO,MACd,OAAO,OAAO;EACZ,MAAM,OAAO;EACb,aAAa,OAAO,SAAS,OAAO,MAAM;EAC1C,aAAa,OAAO;CACtB,CAAC,CACH;AACF,CAAC;AAED,MAAM,cAAc,KAAK,KAAK,gBAAgB;CAC5C,aAAa;CACb,YAAY,OAAO,OAAO;EACxB,MAAM,OAAO;EACb,OAAO,OAAO,OAAO,OAAO,QAAQ,OAAO,IAAI;CACjD,CAAC;CACD,SAAS,OAAO;CAGhB,SAAS,OAAO;CAChB,cAAc,CAAC,iBAAiB;AAClC,CAAC;AAID,MAAM,mBAGF,SAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCJ,MAAa,QAEX,aACG,QAAQ,KAAK,aAAa,UAAoC,CAAC,CAAC,WAAW,CAAC;;;;;;;;;;;;;;;;AAiBjF,MAAa,SAA6C,YACxD,KAAK,OAAO,CAAC,CAAC,QACZ,OAAO,IAAI,aAAa;CACtB,MAAM,WAAW,OAAO;CACxB,MAAM,cAAc,OAAO,OAAO,SAAS,KAAK;CAChD,MAAMA,oBAAkBC,gBAAyB,WAAW;CAE5D,IAAID,kBAAgB,SAAS,GAAG,OAAO,OAAO,OAAO,IAAIE,qBAA8BF,iBAAe,CAAC;CAEvG,OAAO;EACL,eAAe,EAAE,YACf,OAAO,WACL,OAAO,aAAa,OAAO,CAAC,CAAC,CAAC,KAAK,UAAU;GAC3C,MAAM,KAAK;GACX,aAAa,KAAK,eAAe,IAAI;GACrC,aAAa,OAAO,KAAK,cAAc,IAAI,CAAC;EAC9C,EAAE,CACJ;EACF,cAAc,OAAO,WAAW,WAAW,EAAE,MAAM,SAAS;GAE1D,MAAM,QAAQ,OAAO;GAErB,MAAM,OAAO,SAAS,SAAS,aAAa;IAC1C,IAAI,GAAG,MAAM,OAAO,GAAG;IACvB;IACA,QAAQ;IACR,kBAAkB;GACpB,CAAC;GAED,MAAM,EAAE,SAAS,WAAW,OAAOG,UAAmB,UAAU,IAAI;GAEpE,OAAO,YAAY,YAAY,OAAO,OAAO,KAAK,MAAM,IAAI;EAC9D,CAAC;CACH;AACF,CAAC,CACH"}

package/dist/ToolFailure.d.ts

@@ -0,0 +1,66 @@
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+declare namespace ToolFailure_d_exports {
+  export { ToolFailure, fail };
+}
+declare const ToolFailure_base: Schema.Class<ToolFailure, Schema.Struct<{
+  readonly _tag: Schema.tag<"ToolFailure">;
+  readonly message: Schema.String;
+  readonly reason: Schema.optional<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Represents a tool's failure, written for the model.
+ *
+ * It holds a message that says what went wrong and, optionally, a `reason` the model can tell
+ * apart, such as `"NotFound"` or `"OverBudget"`. The library's own reasons are PascalCase, like
+ * `"ToolNotFoundError"`.
+ *
+ * @category errors
+ * @since 0.1.0
+ */
+export declare class ToolFailure extends ToolFailure_base {}
+/**
+ * Fails a tool's handler with a message for the model.
+ *
+ * **Details**
+ *
+ * The tool must declare `failure: ToolFailure.ToolFailure`. The model reads the failure as the
+ * call's result, with its `reason` when one is given.
+ *
+ * **Example** (Failing a tool call the model can correct)
+ *
+ * ```ts
+ * import { ToolFailure } from "effect-assistant"
+ * import * as Tool from "effect/ai/Tool"
+ * import * as Toolkit from "effect/ai/Toolkit"
+ * import * as Effect from "effect/Effect"
+ * import * as Schema from "effect/Schema"
+ *
+ * const budgets = new Map([["Oslo", 1200]])
+ *
+ * const BudgetTools = Toolkit.make(
+ *   Tool.make("office_budget", {
+ *     description: "The budget left for an office.",
+ *     parameters: Schema.Struct({ office: Schema.String }),
+ *     success: Schema.Number,
+ *     failure: ToolFailure.ToolFailure
+ *   })
+ * )
+ *
+ * const BudgetToolsLive = BudgetTools.toLayer({
+ *   office_budget: ({ office }) =>
+ *     Effect.fromNullishOr(budgets.get(office)).pipe(
+ *       Effect.catch(() => ToolFailure.fail(`No office named ${office}.`, { reason: "NotFound" }))
+ *     )
+ * })
+ * ```
+ *
+ * @category constructors
+ * @since 0.1.0
+ */
+export declare const fail: (message: string, options?: {
+  readonly reason?: string | undefined;
+}) => Effect.Effect<never, ToolFailure>;
+//#endregion
+export { ToolFailure_d_exports };
+//# sourceMappingURL=ToolFailure.d.ts.map

package/dist/ToolFailure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolFailure.d.ts","names":[],"sources":["../src/ToolFailure.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;qBAsBa,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBA6CpB,OAAI,iBACA;WACM;MACpB,OAAO,cAAc"}

package/dist/ToolFailure.js

@@ -0,0 +1,79 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+//#region src/ToolFailure.ts
+/**
+* Defines the failure a tool returns to the model.
+*
+* A {@link ToolFailure} carries a message the model reads and adapts to, such as "No office named
+* Paris", instead of failing the turn. Tools declare it as their `failure` schema and fail with
+* {@link fail}.
+*
+* @since 0.1.0
+*/
+var ToolFailure_exports = /* @__PURE__ */ __exportAll({
+	ToolFailure: () => ToolFailure,
+	fail: () => fail
+});
+/**
+* Represents a tool's failure, written for the model.
+*
+* It holds a message that says what went wrong and, optionally, a `reason` the model can tell
+* apart, such as `"NotFound"` or `"OverBudget"`. The library's own reasons are PascalCase, like
+* `"ToolNotFoundError"`.
+*
+* @category errors
+* @since 0.1.0
+*/
+var ToolFailure = class extends Schema.Error("effect-assistant/ToolFailure/ToolFailure")({
+	_tag: Schema.tag("ToolFailure"),
+	message: Schema.String,
+	reason: Schema.optional(Schema.String)
+}) {};
+/**
+* Fails a tool's handler with a message for the model.
+*
+* **Details**
+*
+* The tool must declare `failure: ToolFailure.ToolFailure`. The model reads the failure as the
+* call's result, with its `reason` when one is given.
+*
+* **Example** (Failing a tool call the model can correct)
+*
+* ```ts
+* import { ToolFailure } from "effect-assistant"
+* import * as Tool from "effect/ai/Tool"
+* import * as Toolkit from "effect/ai/Toolkit"
+* import * as Effect from "effect/Effect"
+* import * as Schema from "effect/Schema"
+*
+* const budgets = new Map([["Oslo", 1200]])
+*
+* const BudgetTools = Toolkit.make(
+*   Tool.make("office_budget", {
+*     description: "The budget left for an office.",
+*     parameters: Schema.Struct({ office: Schema.String }),
+*     success: Schema.Number,
+*     failure: ToolFailure.ToolFailure
+*   })
+* )
+*
+* const BudgetToolsLive = BudgetTools.toLayer({
+*   office_budget: ({ office }) =>
+*     Effect.fromNullishOr(budgets.get(office)).pipe(
+*       Effect.catch(() => ToolFailure.fail(`No office named ${office}.`, { reason: "NotFound" }))
+*     )
+* })
+* ```
+*
+* @category constructors
+* @since 0.1.0
+*/
+const fail = (message, options) => Effect.fail(options?.reason === void 0 ? new ToolFailure({ message }) : new ToolFailure({
+	message,
+	reason: options.reason
+}));
+//#endregion
+export { ToolFailure, ToolFailure_exports, fail };
+
+//# sourceMappingURL=ToolFailure.js.map

package/dist/ToolFailure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolFailure.js","names":[],"sources":["../src/ToolFailure.ts"],"sourcesContent":["/**\n * Defines the failure a tool returns to the model.\n *\n * A {@link ToolFailure} carries a message the model reads and adapts to, such as \"No office named\n * Paris\", instead of failing the turn. Tools declare it as their `failure` schema and fail with\n * {@link fail}.\n *\n * @since 0.1.0\n */\nimport * as Effect from \"effect/Effect\"\nimport * as Schema from \"effect/Schema\"\n\n/**\n * Represents a tool's failure, written for the model.\n *\n * It holds a message that says what went wrong and, optionally, a `reason` the model can tell\n * apart, such as `\"NotFound\"` or `\"OverBudget\"`. The library's own reasons are PascalCase, like\n * `\"ToolNotFoundError\"`.\n *\n * @category errors\n * @since 0.1.0\n */\nexport class ToolFailure extends Schema.Error<ToolFailure>(\"effect-assistant/ToolFailure/ToolFailure\")({\n  _tag: Schema.tag(\"ToolFailure\"),\n  message: Schema.String,\n  reason: Schema.optional(Schema.String)\n}) {}\n\n/**\n * Fails a tool's handler with a message for the model.\n *\n * **Details**\n *\n * The tool must declare `failure: ToolFailure.ToolFailure`. The model reads the failure as the\n * call's result, with its `reason` when one is given.\n *\n * **Example** (Failing a tool call the model can correct)\n *\n * ```ts\n * import { ToolFailure } from \"effect-assistant\"\n * import * as Tool from \"effect/ai/Tool\"\n * import * as Toolkit from \"effect/ai/Toolkit\"\n * import * as Effect from \"effect/Effect\"\n * import * as Schema from \"effect/Schema\"\n *\n * const budgets = new Map([[\"Oslo\", 1200]])\n *\n * const BudgetTools = Toolkit.make(\n *   Tool.make(\"office_budget\", {\n *     description: \"The budget left for an office.\",\n *     parameters: Schema.Struct({ office: Schema.String }),\n *     success: Schema.Number,\n *     failure: ToolFailure.ToolFailure\n *   })\n * )\n *\n * const BudgetToolsLive = BudgetTools.toLayer({\n *   office_budget: ({ office }) =>\n *     Effect.fromNullishOr(budgets.get(office)).pipe(\n *       Effect.catch(() => ToolFailure.fail(`No office named ${office}.`, { reason: \"NotFound\" }))\n *     )\n * })\n * ```\n *\n * @category constructors\n * @since 0.1.0\n */\nexport const fail = (\n  message: string,\n  options?: { readonly reason?: string | undefined }\n): Effect.Effect<never, ToolFailure> =>\n  Effect.fail(\n    options?.reason === undefined ? new ToolFailure({ message }) : new ToolFailure({ message, reason: options.reason })\n  )\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAsBA,IAAa,cAAb,cAAiC,OAAO,MAAmB,0CAA0C,CAAC,CAAC;CACrG,MAAM,OAAO,IAAI,aAAa;CAC9B,SAAS,OAAO;CAChB,QAAQ,OAAO,SAAS,OAAO,MAAM;AACvC,CAAC,CAAC,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCJ,MAAa,QACX,SACA,YAEA,OAAO,KACL,SAAS,WAAW,KAAA,IAAY,IAAI,YAAY,EAAE,QAAQ,CAAC,IAAI,IAAI,YAAY;CAAE;CAAS,QAAQ,QAAQ;AAAO,CAAC,CACpH"}

package/dist/_virtual/_rolldown/runtime.js

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll };

package/dist/index.d.ts

@@ -0,0 +1,24 @@
+import { AppEvent_d_exports } from "./AppEvent.js";
+import { ChatId_d_exports } from "./ChatId.js";
+import { AssistantEvent_d_exports } from "./AssistantEvent.js";
+import { ChatLog_d_exports } from "./ChatLog.js";
+import { Instructions_d_exports } from "./Instructions.js";
+import { AssistantToolCall_d_exports } from "./AssistantToolCall.js";
+import { AssistantLoop_d_exports } from "./AssistantLoop.js";
+import { Block_d_exports } from "./Block.js";
+import { ChatView_d_exports } from "./ChatView.js";
+import { CurrentChat_d_exports } from "./CurrentChat.js";
+import { BlockKit_d_exports } from "./BlockKit.js";
+import { RunId_d_exports } from "./RunId.js";
+import { Skill_d_exports } from "./Skill.js";
+import { Specialist_d_exports } from "./Specialist.js";
+import { AssistantEngine_d_exports } from "./AssistantEngine.js";
+import { Chats_d_exports } from "./Chats.js";
+import { Assistant_d_exports } from "./Assistant.js";
+import { AssistantActivity_d_exports } from "./AssistantActivity.js";
+import { Compaction_d_exports } from "./Compaction.js";
+import { InputId_d_exports } from "./InputId.js";
+import { ToolFailure_d_exports } from "./ToolFailure.js";
+import { Memory_d_exports } from "./Memory.js";
+import { ToolDiscovery_d_exports } from "./ToolDiscovery.js";
+export { AppEvent_d_exports as AppEvent, Assistant_d_exports as Assistant, AssistantActivity_d_exports as AssistantActivity, AssistantEngine_d_exports as AssistantEngine, AssistantEvent_d_exports as AssistantEvent, AssistantLoop_d_exports as AssistantLoop, AssistantToolCall_d_exports as AssistantToolCall, Block_d_exports as Block, BlockKit_d_exports as BlockKit, ChatId_d_exports as ChatId, ChatLog_d_exports as ChatLog, ChatView_d_exports as ChatView, Chats_d_exports as Chats, Compaction_d_exports as Compaction, CurrentChat_d_exports as CurrentChat, InputId_d_exports as InputId, Instructions_d_exports as Instructions, Memory_d_exports as Memory, RunId_d_exports as RunId, Skill_d_exports as Skill, Specialist_d_exports as Specialist, ToolDiscovery_d_exports as ToolDiscovery, ToolFailure_d_exports as ToolFailure };

package/dist/index.js

@@ -0,0 +1,24 @@
+import { AppEvent_exports } from "./AppEvent.js";
+import { ChatId_exports } from "./ChatId.js";
+import { InputId_exports } from "./InputId.js";
+import { RunId_exports } from "./RunId.js";
+import { AssistantEvent_exports } from "./AssistantEvent.js";
+import { ChatLog_exports } from "./ChatLog.js";
+import { CurrentChat_exports } from "./CurrentChat.js";
+import { Chats_exports } from "./Chats.js";
+import { Specialist_exports } from "./Specialist.js";
+import { AssistantToolCall_exports } from "./AssistantToolCall.js";
+import { ToolFailure_exports } from "./ToolFailure.js";
+import { Skill_exports } from "./Skill.js";
+import { Instructions_exports } from "./Instructions.js";
+import { AssistantEngine_exports } from "./AssistantEngine.js";
+import { Assistant_exports } from "./Assistant.js";
+import { AssistantActivity_exports } from "./AssistantActivity.js";
+import { AssistantLoop_exports } from "./AssistantLoop.js";
+import { Block_exports } from "./Block.js";
+import { BlockKit_exports } from "./BlockKit.js";
+import { ChatView_exports } from "./ChatView.js";
+import { Compaction_exports } from "./Compaction.js";
+import { Memory_exports } from "./Memory.js";
+import { ToolDiscovery_exports } from "./ToolDiscovery.js";
+export { AppEvent_exports as AppEvent, Assistant_exports as Assistant, AssistantActivity_exports as AssistantActivity, AssistantEngine_exports as AssistantEngine, AssistantEvent_exports as AssistantEvent, AssistantLoop_exports as AssistantLoop, AssistantToolCall_exports as AssistantToolCall, Block_exports as Block, BlockKit_exports as BlockKit, ChatId_exports as ChatId, ChatLog_exports as ChatLog, ChatView_exports as ChatView, Chats_exports as Chats, Compaction_exports as Compaction, CurrentChat_exports as CurrentChat, InputId_exports as InputId, Instructions_exports as Instructions, Memory_exports as Memory, RunId_exports as RunId, Skill_exports as Skill, Specialist_exports as Specialist, ToolDiscovery_exports as ToolDiscovery, ToolFailure_exports as ToolFailure };

package/dist/internal/chat.js

@@ -0,0 +1,177 @@
+import { ChatDeleted, isInput, isLibraryEvent } from "../AssistantEvent.js";
+import { ChatLog } from "../ChatLog.js";
+import { CurrentChat } from "../CurrentChat.js";
+import { Chats } from "../Chats.js";
+import { Runner } from "../Specialist.js";
+import { decodeEntries, encode, isRegistered } from "./events.js";
+import { needsTurn } from "./history.js";
+import { makeRunner } from "./specialists.js";
+import { run } from "./turns.js";
+import * as Predicate from "effect/Predicate";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import * as Exit from "effect/Exit";
+import * as Scope from "effect/Scope";
+import * as Ref from "effect/Ref";
+import * as Cause from "effect/Cause";
+import * as Deferred from "effect/Deferred";
+import * as Fiber from "effect/Fiber";
+import * as FiberSet from "effect/FiberSet";
+import * as PubSub from "effect/PubSub";
+import * as Semaphore from "effect/Semaphore";
+import * as SynchronizedRef from "effect/SynchronizedRef";
+//#region src/internal/chat.ts
+const idOf = (event) => isLibraryEvent(event) ? isInput(event) ? event.id : void 0 : Predicate.hasProperty(event, "id") && Predicate.isString(event.id) ? event.id : void 0;
+const makeChannelPubSub = Effect.acquireRelease(PubSub.unbounded(), PubSub.shutdown);
+const makeHolding = Effect.fnUntraced(function* (keepAlive) {
+	const holds = yield* SynchronizedRef.make(0);
+	const acquire = SynchronizedRef.updateEffect(holds, Effect.fnUntraced(function* (n) {
+		if (n !== 0) return n + 1;
+		yield* keepAlive(true);
+		return 1;
+	}));
+	const release = SynchronizedRef.updateEffect(holds, Effect.fnUntraced(function* (n) {
+		if (n !== 1) return n - 1;
+		yield* keepAlive(false);
+		return 0;
+	}));
+	return (effect) => Effect.acquireUseRelease(acquire, () => effect, (_, exit) => Exit.hasInterrupts(exit) ? Effect.void : release);
+});
+const isChatDeleted = (entry) => Predicate.isTagged(entry.event, "ChatDeleted");
+const deletedChat = (entries) => ({
+	submit: () => Effect.void,
+	submitInBackground: () => Effect.void,
+	resume: Effect.void,
+	stream: (after) => Stream.fromIterable(entries.filter((entry) => entry.seq > after)),
+	delete: Effect.void
+});
+const refused = (input, why) => Effect.logDebug(`assistant chat ${why}: ${input._tag} not stored`);
+/** @internal */
+const make = Effect.fnUntraced(function* (options) {
+	const { registration, chatId } = options;
+	const { app } = registration.definition;
+	const { wakes } = app;
+	const storage = yield* ChatLog;
+	const chats = yield* Chats;
+	const initial = yield* storage.read(chatId);
+	if (initial.some(isChatDeleted)) return deletedChat(initial);
+	const channel = yield* makeChannelPubSub;
+	const writes = yield* Semaphore.make(1);
+	const turnsLock = yield* Semaphore.make(1);
+	const holding = yield* makeHolding(options.keepAlive);
+	const deleted = yield* Deferred.make();
+	const working = yield* Scope.fork(yield* Effect.scope);
+	const inWorking = Effect.provideService(Scope.Scope, working);
+	const background = yield* inWorking(FiberSet.make());
+	const requests = yield* inWorking(FiberSet.make());
+	const isDeleted = Deferred.isDone(deleted);
+	const entries = yield* Ref.make(initial);
+	const write = Effect.fnUntraced(function* (events) {
+		const unknown = events.find((event) => !isLibraryEvent(event) && !isRegistered(app, event));
+		if (unknown !== void 0) return yield* Effect.die(`${unknown._tag} isn't one of the ${registration.definition.name} assistant's events.`);
+		if (yield* isDeleted) return [];
+		return yield* stored(events);
+	});
+	const stored = Effect.fnUntraced(function* (events) {
+		const stored = yield* storage.append(chatId, events);
+		yield* Ref.update(entries, (all) => [...all, ...stored]);
+		yield* PubSub.publishAll(channel, stored);
+		return stored;
+	}, Effect.uninterruptible);
+	const chat = {
+		chatId,
+		entries: Ref.get(entries),
+		append: (events) => Semaphore.withPermit(writes)(write(events))
+	};
+	const toStored = (event) => isLibraryEvent(event) ? Effect.succeed(event) : isRegistered(app, event) ? encode(app, event) : Effect.die(`${event._tag} isn't one of the ${registration.definition.name} assistant's events.`);
+	const handle = {
+		chatId,
+		entries: Effect.map(chat.entries, (all) => decodeEntries(app, all)),
+		append: (...events) => Effect.asVoid(Effect.flatMap(Effect.forEach(events, toStored), chat.append))
+	};
+	const checkAvailable = chats.get(chatId).pipe(Effect.as(true), Effect.catchTag("GetChatError", (unavailable) => unavailable.reason === "Deleted" ? Effect.as(Effect.suspend(() => remove), false) : Effect.succeed(false)));
+	const store = Effect.fnUntraced(function* (input) {
+		if (yield* isDeleted) return yield* refused(input, "is deleted");
+		if (!(yield* checkAvailable)) return yield* refused(input, "is unavailable");
+		yield* Semaphore.withPermit(writes)(Effect.gen(function* () {
+			if (yield* isDeleted) return yield* refused(input, "is deleted");
+			const id = idOf(input);
+			if (id !== void 0 && (yield* Ref.get(entries)).some(({ event }) => idOf(event) === id)) return;
+			yield* write([input]);
+		}));
+	});
+	const handler = yield* inWorking(Effect.provideService(registration.open(handle), CurrentChat, handle));
+	const specialists = yield* Effect.forEach(registration.specialists, Effect.fnUntraced(function* ({ specialist, built }) {
+		return {
+			specialist,
+			handler: yield* inWorking(Effect.provideService(built.open, CurrentChat, handle))
+		};
+	}));
+	const inBackground = (effect) => FiberSet.run(background, holding(effect)).pipe(Effect.asVoid);
+	const inRequest = Effect.fnUntraced(function* (effect) {
+		const fiber = yield* FiberSet.run(requests, effect);
+		const exit = yield* Fiber.await(fiber).pipe(Effect.onInterrupt(() => Fiber.interrupt(fiber)));
+		if (Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause)) return yield* Effect.failCause(exit.cause);
+	}, Effect.orDie);
+	const drain = Semaphore.withPermit(turnsLock)(Effect.gen(function* () {
+		while (!(yield* isDeleted) && needsTurn(yield* chat.entries, wakes)) yield* run({
+			registration,
+			handler,
+			chat,
+			services,
+			checkOpen: Effect.asVoid(checkAvailable)
+		});
+	}));
+	const runner = yield* inWorking(makeRunner({
+		chat,
+		handle,
+		specialists,
+		model: registration.model,
+		holding,
+		report: Effect.fnUntraced(function* (finished) {
+			yield* store(finished);
+			yield* inBackground(drain);
+		})
+	}));
+	const services = Context.make(CurrentChat, handle).pipe(Context.add(Runner, runner), Context.merge(registration.model));
+	const remove = Effect.gen(function* () {
+		if (!(yield* Semaphore.withPermit(writes)(Effect.gen(function* () {
+			if (yield* isDeleted) return false;
+			yield* stored([ChatDeleted.make({})]);
+			return yield* Deferred.succeed(deleted, void 0);
+		})).pipe(Effect.uninterruptible))) return;
+		const closing = yield* Effect.forkDetach(Effect.gen(function* () {
+			yield* Scope.close(working, Exit.void);
+			yield* options.keepAlive(false);
+		}));
+		yield* Fiber.await(closing);
+	});
+	yield* checkAvailable;
+	return {
+		submit: Effect.fnUntraced(function* (input) {
+			yield* store(input);
+			yield* inRequest(drain);
+		}),
+		submitInBackground: Effect.fnUntraced(function* (input) {
+			yield* store(input);
+			yield* inBackground(drain);
+		}),
+		resume: Effect.gen(function* () {
+			if (needsTurn(yield* chat.entries, wakes)) yield* inBackground(drain);
+		}),
+		stream: (after) => Stream.unwrap(Effect.gen(function* () {
+			const subscription = yield* PubSub.subscribe(channel);
+			const all = yield* chat.entries;
+			const stored = all.filter((entry) => entry.seq > after);
+			const last = stored.at(-1)?.seq ?? after;
+			if (all.some(isChatDeleted)) return Stream.fromIterable(stored);
+			return Stream.concat(Stream.fromIterable(stored), Stream.fromSubscription(subscription).pipe(Stream.filter((entry) => entry.seq > last))).pipe(Stream.takeUntil(isChatDeleted));
+		})),
+		delete: remove
+	};
+});
+//#endregion
+export { make };
+
+//# sourceMappingURL=chat.js.map

package/dist/internal/chat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.js","names":["AssistantEvent.isLibraryEvent","AssistantEvent.isInput","Chats.Chats","AppEvents.isRegistered","AppEvents.encode","AppEvents.decodeEntries","History.needsTurn","Turns.run","Specialists.makeRunner","SpecialistService.Runner"],"sources":["../../src/internal/chat.ts"],"sourcesContent":["import * as Cause from \"effect/Cause\"\nimport * as Context from \"effect/Context\"\nimport * as Deferred from \"effect/Deferred\"\nimport * as Effect from \"effect/Effect\"\nimport * as Exit from \"effect/Exit\"\nimport * as Fiber from \"effect/Fiber\"\nimport * as FiberSet from \"effect/FiberSet\"\nimport * as Predicate from \"effect/Predicate\"\nimport * as PubSub from \"effect/PubSub\"\nimport * as Ref from \"effect/Ref\"\nimport * as Scope from \"effect/Scope\"\nimport * as Semaphore from \"effect/Semaphore\"\nimport * as Stream from \"effect/Stream\"\nimport * as SynchronizedRef from \"effect/SynchronizedRef\"\nimport * as AssistantEvent from \"../AssistantEvent.ts\"\nimport type { ChatId } from \"../ChatId.ts\"\nimport { ChatLog } from \"../ChatLog.ts\"\nimport { CurrentChat } from \"../CurrentChat.ts\"\nimport * as Chats from \"../Chats.ts\"\nimport * as SpecialistService from \"../Specialist.ts\"\nimport * as AppEvents from \"./events.ts\"\nimport * as History from \"./history.ts\"\nimport * as Specialists from \"./specialists.ts\"\nimport * as Turns from \"./turns.ts\"\nimport type { Writer } from \"./writer.ts\"\n\nconst idOf = (event: { readonly _tag: string }): string | undefined =>\n  AssistantEvent.isLibraryEvent(event)\n    ? AssistantEvent.isInput(event)\n      ? event.id\n      : undefined\n    : Predicate.hasProperty(event, \"id\") && Predicate.isString(event.id)\n      ? event.id\n      : undefined\n\nconst makeChannelPubSub = Effect.acquireRelease(PubSub.unbounded<AssistantEvent.Entry>(), PubSub.shutdown)\n\nconst makeHolding = Effect.fnUntraced(function* (keepAlive: (enabled: boolean) => Effect.Effect<void>) {\n  const holds = yield* SynchronizedRef.make(0)\n\n  const acquire = SynchronizedRef.updateEffect(\n    holds,\n    Effect.fnUntraced(function* (n: number) {\n      if (n !== 0) return n + 1\n\n      yield* keepAlive(true)\n\n      return 1\n    })\n  )\n\n  const release = SynchronizedRef.updateEffect(\n    holds,\n    Effect.fnUntraced(function* (n: number) {\n      if (n !== 1) return n - 1\n\n      yield* keepAlive(false)\n\n      return 0\n    })\n  )\n\n  return (effect: Effect.Effect<void>) =>\n    Effect.acquireUseRelease(\n      acquire,\n      () => effect,\n      // An interrupted effect (a shutdown) keeps its hold, so the chat starts again and picks up where it was cut off.\n      (_, exit) => (Exit.hasInterrupts(exit) ? Effect.void : release)\n    )\n})\n\n/** @internal */\nexport interface Chat {\n  readonly submit: (input: AssistantEvent.Input | AssistantEvent.StoredAppEvent) => Effect.Effect<void>\n  readonly submitInBackground: (input: AssistantEvent.Input | AssistantEvent.StoredAppEvent) => Effect.Effect<void>\n  // For inputs no turn has read, like a report stored during a shutdown.\n  readonly resume: Effect.Effect<void>\n  readonly stream: (after: number) => Stream.Stream<AssistantEvent.Entry>\n  // Stops what works in the chat and ends its subscribers' streams; its log stays.\n  readonly delete: Effect.Effect<void>\n}\n\nconst isChatDeleted = (entry: AssistantEvent.Entry) => Predicate.isTagged(entry.event, \"ChatDeleted\")\n\nconst deletedChat = (entries: ReadonlyArray<AssistantEvent.Entry>): Chat => ({\n  submit: () => Effect.void,\n  submitInBackground: () => Effect.void,\n  resume: Effect.void,\n  stream: (after) => Stream.fromIterable(entries.filter((entry) => entry.seq > after)),\n  delete: Effect.void\n})\n\nconst refused = (input: { readonly _tag: string }, why: string) =>\n  Effect.logDebug(`assistant chat ${why}: ${input._tag} not stored`)\n\n/** @internal */\nexport const make = Effect.fnUntraced(function* (options: {\n  readonly registration: Turns.Registration\n  readonly chatId: ChatId\n  readonly keepAlive: (enabled: boolean) => Effect.Effect<void>\n}) {\n  const { registration, chatId } = options\n  const { app } = registration.definition\n  const { wakes } = app\n  const storage = yield* ChatLog\n  const chats = yield* Chats.Chats\n  const initial = yield* storage.read(chatId)\n\n  if (initial.some(isChatDeleted)) return deletedChat(initial)\n\n  const channel = yield* makeChannelPubSub\n  const writes = yield* Semaphore.make(1)\n  const turnsLock = yield* Semaphore.make(1)\n  const holding = yield* makeHolding(options.keepAlive)\n  const deleted = yield* Deferred.make<undefined>()\n  // So deleting the chat stops all its work: its turns, runs, and the builds' resources.\n  const working = yield* Scope.fork(yield* Effect.scope)\n  const inWorking = Effect.provideService(Scope.Scope, working)\n  const background = yield* inWorking(FiberSet.make())\n  const requests = yield* inWorking(FiberSet.make())\n\n  const isDeleted = Deferred.isDone(deleted)\n\n  // The chat is its log's only writer, so it reads the log once and turns read memory.\n  const entries = yield* Ref.make(initial)\n\n  // Every writer goes through here, one at a time, so each append is numbered after the last. After a delete it\n  // stores nothing.\n  const write = Effect.fnUntraced(function* (\n    events: ReadonlyArray<AssistantEvent.AssistantEvent | AssistantEvent.StoredAppEvent>\n  ) {\n    const unknown = events.find((event) => !AssistantEvent.isLibraryEvent(event) && !AppEvents.isRegistered(app, event))\n\n    if (unknown !== undefined) {\n      return yield* Effect.die(`${unknown._tag} isn't one of the ${registration.definition.name} assistant's events.`)\n    }\n\n    if (yield* isDeleted) return []\n\n    return yield* stored(events)\n  })\n\n  // Uninterruptible: a stored append must reach memory and the subscribers too, or a turn misses it and replies twice.\n  const stored = Effect.fnUntraced(function* (\n    events: ReadonlyArray<AssistantEvent.AssistantEvent | AssistantEvent.StoredAppEvent>\n  ) {\n    const stored = yield* storage.append(chatId, events)\n\n    yield* Ref.update(entries, (all) => [...all, ...stored])\n    yield* PubSub.publishAll(channel, stored)\n\n    return stored\n  }, Effect.uninterruptible)\n\n  const chat: Writer = {\n    chatId,\n    entries: Ref.get(entries),\n    append: (events) => Semaphore.withPermit(writes)(write(events))\n  }\n\n  const toStored = (event: {\n    readonly _tag: string\n  }): Effect.Effect<AssistantEvent.AssistantEvent | AssistantEvent.StoredAppEvent> =>\n    AssistantEvent.isLibraryEvent(event)\n      ? Effect.succeed(event)\n      : AppEvents.isRegistered(app, event)\n        ? AppEvents.encode(app, event)\n        : Effect.die(`${event._tag} isn't one of the ${registration.definition.name} assistant's events.`)\n\n  // What handlers, tools, and runs see: the assistant's own events decoded, and encoded when appended.\n  const handle: Turns.TypedChat = {\n    chatId,\n    entries: Effect.map(chat.entries, (all) => AppEvents.decodeEntries(app, all)),\n    append: (...events) => Effect.asVoid(Effect.flatMap(Effect.forEach(events, toStored), chat.append))\n  }\n\n  // A chat the app deleted is deleted here too, which stops what works in it: a turn that checks stops there.\n  const checkAvailable: Effect.Effect<boolean> = chats.get(chatId).pipe(\n    Effect.as(true),\n    Effect.catchTag(\"GetChatError\", (unavailable) =>\n      unavailable.reason === \"Deleted\"\n        ? Effect.as(\n            Effect.suspend(() => remove),\n            false\n          )\n        : Effect.succeed(false)\n    )\n  )\n\n  const store = Effect.fnUntraced(function* (input: AssistantEvent.Input | AssistantEvent.StoredAppEvent) {\n    if (yield* isDeleted) return yield* refused(input, \"is deleted\")\n\n    if (!(yield* checkAvailable)) return yield* refused(input, \"is unavailable\")\n\n    // Checked under the write lock: a retry that arrives while the first submit is storing is stored once.\n    yield* Semaphore.withPermit(writes)(\n      Effect.gen(function* () {\n        if (yield* isDeleted) return yield* refused(input, \"is deleted\")\n\n        const id = idOf(input)\n\n        if (id !== undefined && (yield* Ref.get(entries)).some(({ event }) => idOf(event) === id)) return\n\n        yield* write([input])\n      })\n    )\n  })\n\n  // The handlers' builds run in the chat's working scope: what they set up lives until the chat closes or is deleted.\n  const handler = yield* inWorking(Effect.provideService(registration.open(handle), CurrentChat, handle))\n\n  const specialists = yield* Effect.forEach(\n    registration.specialists,\n    Effect.fnUntraced(function* ({ specialist, built }) {\n      const handler = yield* inWorking(Effect.provideService(built.open, CurrentChat, handle))\n\n      return { specialist, handler }\n    })\n  )\n\n  const inBackground = (effect: Effect.Effect<void>) => FiberSet.run(background, holding(effect)).pipe(Effect.asVoid)\n\n  // A request's turns run in the working scope too, so a delete stops them; the request ends quietly then.\n  const inRequest = Effect.fnUntraced(function* (effect: Effect.Effect<void>) {\n    const fiber = yield* FiberSet.run(requests, effect)\n    const exit = yield* Fiber.await(fiber).pipe(Effect.onInterrupt(() => Fiber.interrupt(fiber)))\n\n    if (Exit.isFailure(exit) && !Cause.hasInterruptsOnly(exit.cause)) {\n      return yield* Effect.failCause(exit.cause)\n    }\n  }, Effect.orDie)\n\n  const drain: Effect.Effect<void> = Semaphore.withPermit(turnsLock)(\n    Effect.gen(function* () {\n      while (!(yield* isDeleted) && History.needsTurn(yield* chat.entries, wakes)) {\n        yield* Turns.run({ registration, handler, chat, services, checkOpen: Effect.asVoid(checkAvailable) })\n      }\n    })\n  )\n\n  const runner = yield* inWorking(\n    Specialists.makeRunner({\n      chat,\n      handle,\n      specialists,\n      model: registration.model,\n      holding,\n      report: Effect.fnUntraced(function* (finished) {\n        yield* store(finished)\n        yield* inBackground(drain)\n      })\n    })\n  )\n\n  const services = Context.make(CurrentChat, handle).pipe(\n    Context.add(SpecialistService.Runner, runner),\n    Context.merge(registration.model)\n  )\n\n  const remove = Effect.gen(function* () {\n    // Under the write lock: an append in flight is stored before the `ChatDeleted`; none comes after.\n    const first = yield* Semaphore.withPermit(writes)(\n      Effect.gen(function* () {\n        if (yield* isDeleted) return false\n\n        yield* stored([AssistantEvent.ChatDeleted.make({})])\n\n        return yield* Deferred.succeed(deleted, undefined)\n      })\n    ).pipe(Effect.uninterruptible)\n\n    if (!first) return\n\n    // Its own fiber: a tool that deletes its own chat is in the working scope, and closing it interrupts that tool.\n    // Interrupted work keeps its hold (see `makeHolding`), so the chat lets go of it here.\n    const closing = yield* Effect.forkDetach(\n      Effect.gen(function* () {\n        yield* Scope.close(working, Exit.void)\n        yield* options.keepAlive(false)\n      })\n    )\n\n    yield* Fiber.await(closing)\n  })\n\n  // A chat the app deleted while it was closed is deleted now, so its subscribers hear it.\n  yield* checkAvailable\n\n  const chatApi: Chat = {\n    submit: Effect.fnUntraced(function* (input) {\n      yield* store(input)\n      yield* inRequest(drain)\n    }),\n    submitInBackground: Effect.fnUntraced(function* (input) {\n      yield* store(input)\n      yield* inBackground(drain)\n    }),\n    resume: Effect.gen(function* () {\n      if (History.needsTurn(yield* chat.entries, wakes)) yield* inBackground(drain)\n    }),\n    stream: (after) =>\n      Stream.unwrap(\n        Effect.gen(function* () {\n          // Subscribes before it reads, so nothing appended in between is missed.\n          const subscription = yield* PubSub.subscribe(channel)\n          const all = yield* chat.entries\n          const stored = all.filter((entry) => entry.seq > after)\n          const last = stored.at(-1)?.seq ?? after\n\n          // Deleted: what the reader hasn't seen, then the end. Otherwise the stream ends with the `ChatDeleted`.\n          if (all.some(isChatDeleted)) return Stream.fromIterable(stored)\n\n          return Stream.concat(\n            Stream.fromIterable(stored),\n            Stream.fromSubscription(subscription).pipe(Stream.filter((entry) => entry.seq > last))\n          ).pipe(Stream.takeUntil(isChatDeleted))\n        })\n      ),\n    delete: remove\n  }\n\n  return chatApi\n})\n"],"mappings":"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"}

package/dist/internal/events.d.ts

@@ -0,0 +1,46 @@
+import { Any, AppEvent_d_exports, EventSchema, Render } from "../AppEvent.js";
+import { AnyEntry, AssistantEvent_d_exports } from "../AssistantEvent.js";
+import { Assistant_d_exports, Entry } from "../Assistant.js";
+import * as Effect from "effect/Effect";
+import * as Schema from "effect/Schema";
+import * as Option from "effect/Option";
+declare namespace events_d_exports {
+  export { AppEvents, DecodedEntries, decodeEntries, decodeEntry, encode, isRegistered, make, read };
+}
+/** @internal */
+export interface AppEvents {
+  readonly byTag: ReadonlyMap<string, Registered>;
+  readonly wakes: ReadonlySet<string>;
+}
+interface Registered {
+  readonly schema: EventSchema;
+  readonly render: Render<{
+    readonly _tag: string;
+  }> | undefined;
+}
+/** @internal */
+export declare const make: (events: ReadonlyArray<Any>) => AppEvents;
+/** @internal */
+export declare const encode: (app: AppEvents, event: {
+  readonly _tag: string;
+}) => Effect.Effect<{
+  readonly [x: string]: Schema.Json;
+  readonly _tag: string & import("effect/Brand").Brand<"~effect-assistant/AppTag">;
+}, never, never>;
+/** @internal */
+export declare const isRegistered: (app: AppEvents, event: {
+  readonly _tag: string;
+}) => boolean;
+/** @internal */
+export declare const decodeEntry: (app: AppEvents, entry: AnyEntry) => Option.Option<Entry<any>>;
+/** @internal */
+export declare const decodeEntries: (app: AppEvents, entries: ReadonlyArray<AnyEntry>) => ReadonlyArray<Entry<any>>;
+/** @internal */
+export type DecodedEntries = ReturnType<typeof decodeEntries>;
+/** @internal */
+export declare const read: (app: AppEvents, event: {
+  readonly _tag: string;
+}) => string | undefined;
+//#endregion
+export { events_d_exports };
+//# sourceMappingURL=events.d.ts.map