effect-assistant 0.3.0 → 0.5.0

package/dist/ToolApproval.d.ts

@@ -0,0 +1,146 @@
+import { AnyEntry, ApprovalDecision, ApprovalRequested, AssistantEvent_d_exports, ToolOutcome } from "./AssistantEvent.js";
+import { CurrentChat } from "./CurrentChat.js";
+import { InputId, InputId_d_exports } from "./InputId.js";
+import * as Effect from "effect/Effect";
+declare namespace ToolApproval_d_exports {
+  export { State, Status, apply, approve, closeStale, decisionId, fromEntries, reject, staleApprovals };
+}
+/**
+ * Represents where a call that waits for approval stands: `"pending"` until the user decides,
+ * then `"approved"` or `"rejected"`, or `"expired"` when the user moved on.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export type Status = "pending" | "approved" | "rejected" | "expired";
+/**
+ * Represents a tool call that waited, or waits, for the user's approval.
+ *
+ * @category models
+ * @since 0.4.0
+ */
+export interface State {
+  readonly request: ApprovalRequested;
+  /** When the call started waiting, in epoch milliseconds. */
+  readonly at: number;
+  readonly status: Status;
+  /** The user's reason, when they rejected it with one. */
+  readonly reason: string | undefined;
+  /** How the approved call went, once it ran. */
+  readonly outcome: ToolOutcome | undefined;
+}
+/**
+ * Returns the approvals after one more entry. Fold a chat's entries in order, or use
+ * {@link fromEntries}.
+ *
+ * **Details**
+ *
+ * The first of a call's decision and its expiry counts: anything after it changes nothing.
+ *
+ * @category combinators
+ * @since 0.4.0
+ */
+export declare const apply: (states: ReadonlyMap<string, State>, entry: AnyEntry) => ReadonlyMap<string, State>;
+/**
+ * Returns every call that waited for approval in a chat, by call id, with where it stands.
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export declare const fromEntries: (entries: ReadonlyArray<AnyEntry>) => ReadonlyMap<string, State>;
+/**
+ * The id of a decision on a call: the same for every decision on it, so the chat stores one.
+ *
+ * @category utils
+ * @since 0.4.0
+ */
+export declare const decisionId: (callId: string) => InputId;
+/**
+ * Returns the input that approves a call waiting for the user's approval, to submit like a
+ * message. `approval` is the call's item on the chat's timeline, or anything with the call's id.
+ *
+ * **Example** (Approve and reject buttons on the client)
+ *
+ * ```tsx
+ * import { ToolApproval } from "effect-assistant"
+ *
+ * const buttons = (approval: { readonly id: string; readonly status: ToolApproval.Status }) =>
+ *   approval.status === "pending" ? (
+ *     <>
+ *       <button onClick={() => submit(ToolApproval.approve(approval))}>Approve</button>
+ *       <button onClick={() => submit(ToolApproval.reject(approval, { reason: "Not this week" }))}>Reject</button>
+ *     </>
+ *   ) : null
+ * ```
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export declare const approve: (approval: {
+  readonly id: string;
+}) => ApprovalDecision;
+/**
+ * Returns the input that rejects a call waiting for the user's approval, with an optional short
+ * reason the model reads.
+ *
+ * @see {@link approve} for an example
+ *
+ * @category constructors
+ * @since 0.4.0
+ */
+export declare const reject: (approval: {
+  readonly id: string;
+}, options?: {
+  readonly reason?: string | undefined;
+}) => ApprovalDecision;
+/**
+ * Returns the ids of the calls still waiting for approval after the user typed the given number
+ * of messages without deciding them.
+ *
+ * **Details**
+ *
+ * These are the calls {@link closeStale} closes.
+ *
+ * @category utils
+ * @since 0.4.0
+ */
+export declare const staleApprovals: (entries: ReadonlyArray<AnyEntry>, options: {
+  readonly messages: number;
+}) => ReadonlyArray<string>;
+/**
+ * Closes the calls the user moved on from, which still wait for approval after the given number
+ * of typed messages: they expire, and won't run.
+ *
+ * **Details**
+ *
+ * Run it from a turn, before or after its loop, like `BlockKit.closeStale`. It records an
+ * `ApprovalsExpired` event: the timeline shows the calls as expired, the model reads that they
+ * weren't approved, and a decision that arrives later isn't stored.
+ *
+ * **Example** (Closing calls the user moved on from, and stale blocks, every turn)
+ *
+ * ```ts
+ * import { BlockKit, ToolApproval } from "effect-assistant"
+ * import * as Effect from "effect/Effect"
+ *
+ * const MyAssistantLive = MyAssistant.toLayer(
+ *   Effect.fn(function* (turn) {
+ *     yield* BlockKit.closeStale({ messages: 10 })
+ *     yield* ToolApproval.closeStale({ messages: 10 })
+ *
+ *     return turn.loop({ instructions, toolkit: MyTools })
+ *   })
+ * )
+ * ```
+ *
+ * @see {@link staleApprovals} for the calls it closes
+ *
+ * @category utils
+ * @since 0.4.0
+ */
+export declare const closeStale: (options: {
+  readonly messages: number;
+}) => Effect.Effect<void, never, CurrentChat>;
+//#endregion
+export { ToolApproval_d_exports };
+//# sourceMappingURL=ToolApproval.d.ts.map

package/dist/ToolApproval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolApproval.d.ts","names":[],"sources":["../src/ToolApproval.ts"],"mappings":";;;;;;;;;;;;;;YA0BY;;;;;;;iBAQK;WACN,SAAS;;WAET;WACA,QAAQ;;WAER;;WAEA,SAAS;;;;;;;;;;;;;qBAmBP,QAAK,QACR,oBAAoB,QAAM,OAC3B,aACN,oBAAoB;;;;;;;qBA0DV,cAAW,SAAa,cAAc,cAA2B,oBAAoB;;;;;;;qBASrF,aAAU,mBAAqB;;;;;;;;;;;;;;;;;;;;;;qBAuB/B,UAAO;WAAyB;MAAe;;;;;;;;;;qBAY/C,SAAM;WACI;GAAY;WACZ;MACpB;;;;;;;;;;;;qBAqBU,iBAAc,SAChB,cAAc,WAAwB;WAC3B;MACnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAkDU,aAAU;WAAsD;MAK3E,OAAA,oBAAA"}

package/dist/ToolApproval.js

@@ -0,0 +1,201 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import { fromKey } from "./InputId.js";
+import { ApprovalDecision, ApprovalsExpired, isLibraryEvent } from "./AssistantEvent.js";
+import { CurrentChat } from "./CurrentChat.js";
+import * as Effect from "effect/Effect";
+import * as Predicate from "effect/Predicate";
+//#region src/ToolApproval.ts
+/**
+* Tool calls that wait for the user's approval.
+*
+* A tool made with Effect's `needsApproval` doesn't run when the model calls it in a turn: the
+* call waits ({@link AssistantEvent.ApprovalRequested}), the turn ends, and the chat's timeline
+* shows it to the user. Their decision, built with {@link approve} or {@link reject} and submitted
+* like a message, wakes a turn: an approved call runs then, with its params and id, and a rejected
+* one doesn't. A call the user moved on from expires ({@link closeStale}, like `BlockKit.closeStale`). On the timeline, every
+* call is an item with its tool's name and where it stands: only the yes or no, since the
+* assistant's message says what it asks.
+*
+* @since 0.4.0
+*/
+var ToolApproval_exports = /* @__PURE__ */ __exportAll({
+	apply: () => apply,
+	approve: () => approve,
+	closeStale: () => closeStale,
+	decisionId: () => decisionId,
+	fromEntries: () => fromEntries,
+	reject: () => reject,
+	staleApprovals: () => staleApprovals
+});
+const decided = (state, decision) => decision.reason === void 0 ? {
+	...state,
+	status: decision.decision
+} : {
+	...state,
+	status: decision.decision,
+	reason: decision.reason
+};
+/**
+* Returns the approvals after one more entry. Fold a chat's entries in order, or use
+* {@link fromEntries}.
+*
+* **Details**
+*
+* The first of a call's decision and its expiry counts: anything after it changes nothing.
+*
+* @category combinators
+* @since 0.4.0
+*/
+const apply = (states, entry) => {
+	const { event } = entry;
+	if (!isLibraryEvent(event)) return states;
+	if (Predicate.isTagged(event, "ApprovalRequested")) return states.has(event.callId) ? states : new Map(states).set(event.callId, {
+		request: event,
+		at: entry.at,
+		status: "pending",
+		reason: void 0,
+		outcome: void 0
+	});
+	if (Predicate.isTagged(event, "ApprovalDecision")) {
+		const state = states.get(event.callId);
+		return state === void 0 || state.status !== "pending" ? states : new Map(states).set(event.callId, decided(state, event));
+	}
+	if (Predicate.isTagged(event, "ApprovalsExpired")) {
+		const expired = event.callIds.flatMap((callId) => {
+			const state = states.get(callId);
+			return state === void 0 || state.status !== "pending" ? [] : [{
+				...state,
+				status: "expired"
+			}];
+		});
+		if (expired.length === 0) return states;
+		const next = new Map(states);
+		for (const state of expired) next.set(state.request.callId, state);
+		return next;
+	}
+	if (Predicate.isTagged(event, "ToolResult")) {
+		const state = states.get(event.callId);
+		return state === void 0 || state.status !== "approved" ? states : new Map(states).set(event.callId, {
+			...state,
+			outcome: event.outcome
+		});
+	}
+	return states;
+};
+/**
+* Returns every call that waited for approval in a chat, by call id, with where it stands.
+*
+* @category constructors
+* @since 0.4.0
+*/
+const fromEntries = (entries) => entries.reduce(apply, /* @__PURE__ */ new Map());
+/**
+* The id of a decision on a call: the same for every decision on it, so the chat stores one.
+*
+* @category utils
+* @since 0.4.0
+*/
+const decisionId = (callId) => fromKey(`approval:${callId}`);
+/**
+* Returns the input that approves a call waiting for the user's approval, to submit like a
+* message. `approval` is the call's item on the chat's timeline, or anything with the call's id.
+*
+* **Example** (Approve and reject buttons on the client)
+*
+* ```tsx
+* import { ToolApproval } from "effect-assistant"
+*
+* const buttons = (approval: { readonly id: string; readonly status: ToolApproval.Status }) =>
+*   approval.status === "pending" ? (
+*     <>
+*       <button onClick={() => submit(ToolApproval.approve(approval))}>Approve</button>
+*       <button onClick={() => submit(ToolApproval.reject(approval, { reason: "Not this week" }))}>Reject</button>
+*     </>
+*   ) : null
+* ```
+*
+* @category constructors
+* @since 0.4.0
+*/
+const approve = (approval) => ApprovalDecision.make({
+	id: decisionId(approval.id),
+	callId: approval.id,
+	decision: "approved"
+});
+/**
+* Returns the input that rejects a call waiting for the user's approval, with an optional short
+* reason the model reads.
+*
+* @see {@link approve} for an example
+*
+* @category constructors
+* @since 0.4.0
+*/
+const reject = (approval, options) => options?.reason === void 0 ? ApprovalDecision.make({
+	id: decisionId(approval.id),
+	callId: approval.id,
+	decision: "rejected"
+}) : ApprovalDecision.make({
+	id: decisionId(approval.id),
+	callId: approval.id,
+	decision: "rejected",
+	reason: options.reason
+});
+/**
+* Returns the ids of the calls still waiting for approval after the user typed the given number
+* of messages without deciding them.
+*
+* **Details**
+*
+* These are the calls {@link closeStale} closes.
+*
+* @category utils
+* @since 0.4.0
+*/
+const staleApprovals = (entries, options) => {
+	return [...fromEntries(entries).values()].flatMap((state) => {
+		if (state.status !== "pending") return [];
+		const requested = entries.findIndex(({ event }) => isLibraryEvent(event) && Predicate.isTagged(event, "ApprovalRequested") && event.callId === state.request.callId);
+		return entries.slice(requested + 1).filter(({ event }) => Predicate.isTagged(event, "UserMessage")).length >= options.messages ? [state.request.callId] : [];
+	});
+};
+/**
+* Closes the calls the user moved on from, which still wait for approval after the given number
+* of typed messages: they expire, and won't run.
+*
+* **Details**
+*
+* Run it from a turn, before or after its loop, like `BlockKit.closeStale`. It records an
+* `ApprovalsExpired` event: the timeline shows the calls as expired, the model reads that they
+* weren't approved, and a decision that arrives later isn't stored.
+*
+* **Example** (Closing calls the user moved on from, and stale blocks, every turn)
+*
+* ```ts
+* import { BlockKit, ToolApproval } from "effect-assistant"
+* import * as Effect from "effect/Effect"
+*
+* const MyAssistantLive = MyAssistant.toLayer(
+*   Effect.fn(function* (turn) {
+*     yield* BlockKit.closeStale({ messages: 10 })
+*     yield* ToolApproval.closeStale({ messages: 10 })
+*
+*     return turn.loop({ instructions, toolkit: MyTools })
+*   })
+* )
+* ```
+*
+* @see {@link staleApprovals} for the calls it closes
+*
+* @category utils
+* @since 0.4.0
+*/
+const closeStale = Effect.fn(function* (options) {
+	const chat = yield* CurrentChat;
+	const stale = staleApprovals(yield* chat.entries, options);
+	if (stale.length > 0) yield* chat.append(ApprovalsExpired.make({ callIds: stale }));
+});
+//#endregion
+export { ToolApproval_exports, apply, approve, closeStale, decisionId, fromEntries, reject, staleApprovals };
+
+//# sourceMappingURL=ToolApproval.js.map

package/dist/ToolApproval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolApproval.js","names":["AssistantEvent.isLibraryEvent","InputId.fromKey"],"sources":["../src/ToolApproval.ts"],"sourcesContent":["/**\n * Tool calls that wait for the user's approval.\n *\n * A tool made with Effect's `needsApproval` doesn't run when the model calls it in a turn: the\n * call waits ({@link AssistantEvent.ApprovalRequested}), the turn ends, and the chat's timeline\n * shows it to the user. Their decision, built with {@link approve} or {@link reject} and submitted\n * like a message, wakes a turn: an approved call runs then, with its params and id, and a rejected\n * one doesn't. A call the user moved on from expires ({@link closeStale}, like `BlockKit.closeStale`). On the timeline, every\n * call is an item with its tool's name and where it stands: only the yes or no, since the\n * assistant's message says what it asks.\n *\n * @since 0.4.0\n */\nimport * as Effect from \"effect/Effect\"\nimport * as Predicate from \"effect/Predicate\"\nimport * as AssistantEvent from \"./AssistantEvent.ts\"\nimport { CurrentChat } from \"./CurrentChat.ts\"\nimport * as InputId from \"./InputId.ts\"\n\n/**\n * Represents where a call that waits for approval stands: `\"pending\"` until the user decides,\n * then `\"approved\"` or `\"rejected\"`, or `\"expired\"` when the user moved on.\n *\n * @category models\n * @since 0.4.0\n */\nexport type Status = \"pending\" | \"approved\" | \"rejected\" | \"expired\"\n\n/**\n * Represents a tool call that waited, or waits, for the user's approval.\n *\n * @category models\n * @since 0.4.0\n */\nexport interface State {\n  readonly request: AssistantEvent.ApprovalRequested\n  /** When the call started waiting, in epoch milliseconds. */\n  readonly at: number\n  readonly status: Status\n  /** The user's reason, when they rejected it with one. */\n  readonly reason: string | undefined\n  /** How the approved call went, once it ran. */\n  readonly outcome: AssistantEvent.ToolOutcome | undefined\n}\n\nconst decided = (state: State, decision: AssistantEvent.ApprovalDecision): State =>\n  decision.reason === undefined\n    ? { ...state, status: decision.decision }\n    : { ...state, status: decision.decision, reason: decision.reason }\n\n/**\n * Returns the approvals after one more entry. Fold a chat's entries in order, or use\n * {@link fromEntries}.\n *\n * **Details**\n *\n * The first of a call's decision and its expiry counts: anything after it changes nothing.\n *\n * @category combinators\n * @since 0.4.0\n */\nexport const apply = (\n  states: ReadonlyMap<string, State>,\n  entry: AssistantEvent.AnyEntry\n): ReadonlyMap<string, State> => {\n  const { event } = entry\n\n  if (!AssistantEvent.isLibraryEvent(event)) return states\n\n  if (Predicate.isTagged(event, \"ApprovalRequested\")) {\n    return states.has(event.callId)\n      ? states\n      : new Map(states).set(event.callId, {\n          request: event,\n          at: entry.at,\n          status: \"pending\",\n          reason: undefined,\n          outcome: undefined\n        })\n  }\n\n  if (Predicate.isTagged(event, \"ApprovalDecision\")) {\n    const state = states.get(event.callId)\n\n    return state === undefined || state.status !== \"pending\"\n      ? states\n      : new Map(states).set(event.callId, decided(state, event))\n  }\n\n  if (Predicate.isTagged(event, \"ApprovalsExpired\")) {\n    const expired = event.callIds.flatMap((callId) => {\n      const state = states.get(callId)\n\n      return state === undefined || state.status !== \"pending\" ? [] : [{ ...state, status: \"expired\" as const }]\n    })\n\n    if (expired.length === 0) return states\n\n    const next = new Map(states)\n\n    for (const state of expired) next.set(state.request.callId, state)\n\n    return next\n  }\n\n  if (Predicate.isTagged(event, \"ToolResult\")) {\n    const state = states.get(event.callId)\n\n    return state === undefined || state.status !== \"approved\"\n      ? states\n      : new Map(states).set(event.callId, { ...state, outcome: event.outcome })\n  }\n\n  return states\n}\n\n/**\n * Returns every call that waited for approval in a chat, by call id, with where it stands.\n *\n * @category constructors\n * @since 0.4.0\n */\nexport const fromEntries = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): ReadonlyMap<string, State> =>\n  entries.reduce(apply, new Map<string, State>())\n\n/**\n * The id of a decision on a call: the same for every decision on it, so the chat stores one.\n *\n * @category utils\n * @since 0.4.0\n */\nexport const decisionId = (callId: string): InputId.InputId => InputId.fromKey(`approval:${callId}`)\n\n/**\n * Returns the input that approves a call waiting for the user's approval, to submit like a\n * message. `approval` is the call's item on the chat's timeline, or anything with the call's id.\n *\n * **Example** (Approve and reject buttons on the client)\n *\n * ```tsx\n * import { ToolApproval } from \"effect-assistant\"\n *\n * const buttons = (approval: { readonly id: string; readonly status: ToolApproval.Status }) =>\n *   approval.status === \"pending\" ? (\n *     <>\n *       <button onClick={() => submit(ToolApproval.approve(approval))}>Approve</button>\n *       <button onClick={() => submit(ToolApproval.reject(approval, { reason: \"Not this week\" }))}>Reject</button>\n *     </>\n *   ) : null\n * ```\n *\n * @category constructors\n * @since 0.4.0\n */\nexport const approve = (approval: { readonly id: string }): AssistantEvent.ApprovalDecision =>\n  AssistantEvent.ApprovalDecision.make({ id: decisionId(approval.id), callId: approval.id, decision: \"approved\" })\n\n/**\n * Returns the input that rejects a call waiting for the user's approval, with an optional short\n * reason the model reads.\n *\n * @see {@link approve} for an example\n *\n * @category constructors\n * @since 0.4.0\n */\nexport const reject = (\n  approval: { readonly id: string },\n  options?: { readonly reason?: string | undefined }\n): AssistantEvent.ApprovalDecision =>\n  options?.reason === undefined\n    ? AssistantEvent.ApprovalDecision.make({ id: decisionId(approval.id), callId: approval.id, decision: \"rejected\" })\n    : AssistantEvent.ApprovalDecision.make({\n        id: decisionId(approval.id),\n        callId: approval.id,\n        decision: \"rejected\",\n        reason: options.reason\n      })\n\n/**\n * Returns the ids of the calls still waiting for approval after the user typed the given number\n * of messages without deciding them.\n *\n * **Details**\n *\n * These are the calls {@link closeStale} closes.\n *\n * @category utils\n * @since 0.4.0\n */\nexport const staleApprovals = (\n  entries: ReadonlyArray<AssistantEvent.AnyEntry>,\n  options: { readonly messages: number }\n): ReadonlyArray<string> => {\n  const states = fromEntries(entries)\n\n  return [...states.values()].flatMap((state) => {\n    if (state.status !== \"pending\") return []\n\n    const requested = entries.findIndex(\n      ({ event }) =>\n        AssistantEvent.isLibraryEvent(event) &&\n        Predicate.isTagged(event, \"ApprovalRequested\") &&\n        event.callId === state.request.callId\n    )\n\n    const typed = entries.slice(requested + 1).filter(({ event }) => Predicate.isTagged(event, \"UserMessage\")).length\n\n    return typed >= options.messages ? [state.request.callId] : []\n  })\n}\n\n/**\n * Closes the calls the user moved on from, which still wait for approval after the given number\n * of typed messages: they expire, and won't run.\n *\n * **Details**\n *\n * Run it from a turn, before or after its loop, like `BlockKit.closeStale`. It records an\n * `ApprovalsExpired` event: the timeline shows the calls as expired, the model reads that they\n * weren't approved, and a decision that arrives later isn't stored.\n *\n * **Example** (Closing calls the user moved on from, and stale blocks, every turn)\n *\n * ```ts\n * import { BlockKit, ToolApproval } from \"effect-assistant\"\n * import * as Effect from \"effect/Effect\"\n *\n * const MyAssistantLive = MyAssistant.toLayer(\n *   Effect.fn(function* (turn) {\n *     yield* BlockKit.closeStale({ messages: 10 })\n *     yield* ToolApproval.closeStale({ messages: 10 })\n *\n *     return turn.loop({ instructions, toolkit: MyTools })\n *   })\n * )\n * ```\n *\n * @see {@link staleApprovals} for the calls it closes\n *\n * @category utils\n * @since 0.4.0\n */\nexport const closeStale = Effect.fn(function* (options: { readonly messages: number }) {\n  const chat = yield* CurrentChat\n  const stale = staleApprovals(yield* chat.entries, options)\n\n  if (stale.length > 0) yield* chat.append(AssistantEvent.ApprovalsExpired.make({ callIds: stale }))\n})\n"],"mappings":"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"}

package/dist/ToolDiscovery.d.ts

@@ -1,4 +1,5 @@
 import { AssistantToolCall } from "./AssistantToolCall.js";
+import { ToolServices, toolkit_d_exports } from "./internal/toolkit.js";
 import * as Schema from "effect/Schema";
 import * as Tool from "effect/ai/Tool";
 import * as Toolkit from "effect/ai/Toolkit";
@@ -14,8 +15,9 @@ declare namespace ToolDiscovery_d_exports {
  * 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.
+ * A catalog tool with Effect's `needsApproval` set fails the layer when it is built: a call
+ * through `execute_tool` can't wait for the user's approval. Give such a tool to the loop's toolkit
+ * directly (see `ToolApproval`).
  *
  * **Example** (Finding rarely used tools when needed)
  *
@@ -50,7 +52,7 @@ export declare const make: <T extends Record<string, Tool.Any>>(_catalog: Toolki
     readonly success: Schema.Codec<Schema.Json, Schema.Json, never, never>;
     readonly failure: Schema.Codec<Schema.Json, Schema.Json, never, never>;
     readonly failureMode: "error";
-  }, AssistantToolCall | Exclude<Tool.HandlerServices<T[keyof T]>, AssistantToolCall>>;
+  }, AssistantToolCall | ToolServices<T>>;
   readonly search_tools: Tool.Tool<"search_tools", {
     readonly parameters: Schema.Struct<{
       readonly query: Schema.String;
@@ -88,7 +90,7 @@ export declare const layer: <T extends Record<string, Tool.Any>>(catalog: Toolki
     readonly success: Schema.Codec<Schema.Json, Schema.Json, never, never>;
     readonly failure: Schema.Codec<Schema.Json, Schema.Json, never, never>;
     readonly failureMode: "error";
-  }, AssistantToolCall | Exclude<Tool.HandlerServices<T[keyof T]>, AssistantToolCall>>;
+  }, AssistantToolCall | ToolServices<T>>;
   readonly search_tools: Tool.Tool<"search_tools", {
     readonly parameters: Schema.Struct<{
       readonly query: Schema.String;

package/dist/ToolDiscovery.d.ts.map

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

package/dist/ToolDiscovery.js

@@ -1,7 +1,7 @@
 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 { needingApproval, runNative } from "./internal/toolkit.js";
 import * as Effect from "effect/Effect";
 import * as Schema from "effect/Schema";
 import * as Response from "effect/ai/Response";
@@ -67,8 +67,9 @@ const requiring = () => (tool) => tool;
 * 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.
+* A catalog tool with Effect's `needsApproval` set fails the layer when it is built: a call
+* through `execute_tool` can't wait for the user's approval. Give such a tool to the loop's toolkit
+* directly (see `ToolApproval`).
 *
 * **Example** (Finding rarely used tools when needed)
 *
@@ -114,7 +115,7 @@ 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));
+	if (needingApproval$1.length > 0) return yield* Effect.die(`${needingApproval$1.join(", ")} ${needingApproval$1.length === 1 ? "sets" : "set"} needsApproval, and a call through execute_tool can't wait for the user's approval. Give it to the loop's toolkit instead of ToolDiscovery's catalog.`);
 	return {
 		search_tools: ({ query }) => Effect.sync(() => search(definitions, query, 5).map((tool) => ({
 			name: tool.name,

package/dist/ToolDiscovery.js.map

@@ -1 +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"}
+{"version":3,"file":"ToolDiscovery.js","names":["needingApproval","Toolkits.needingApproval","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: a call\n * through `execute_tool` can't wait for the user's approval. Give such a tool to the loop's toolkit\n * directly (see `ToolApproval`).\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) {\n        return yield* Effect.die(\n          `${needingApproval.join(\", \")} ${needingApproval.length === 1 ? \"sets\" : \"set\"} needsApproval, and a call through execute_tool can't wait for the user's approval. Give it to the loop's toolkit instead of ToolDiscovery's catalog.`\n        )\n      }\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":"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"}

package/dist/ToolResult.d.ts

@@ -0,0 +1,56 @@
+import * as Context from "effect/Context";
+import * as Schema from "effect/Schema";
+import * as Tool from "effect/ai/Tool";
+declare namespace ToolResult_d_exports {
+  export { ModelView, modelView };
+}
+type Schemas = {
+  readonly parameters: Schema.Top;
+  readonly success: Schema.Top;
+  readonly failure: Schema.Top;
+  readonly failureMode: Tool.FailureMode;
+};
+declare const ModelView_base: Context.ServiceClass<ModelView, "effect-assistant/ToolResult/ModelView", (success: any) => Schema.Json>;
+/**
+ * Annotation for what the model reads of a tool's success, set with {@link modelView}.
+ *
+ * @category annotations
+ * @since 0.5.0
+ */
+export declare class ModelView extends ModelView_base {}
+/**
+ * Sets what the model reads of a tool's success. The chat's log keeps the whole success.
+ *
+ * **Details**
+ *
+ * The view gets the success as the tool's success schema decodes it, and returns the JSON the
+ * model reads instead. Failures reach the model as they are.
+ *
+ * **Example** (Keeping image URLs out of the model's context)
+ *
+ * ```ts
+ * import * as Tool from "effect/ai/Tool"
+ * import * as Schema from "effect/Schema"
+ * import { ToolResult } from "effect-assistant"
+ *
+ * const Asset = Schema.Struct({ id: Schema.String, name: Schema.String, imageUrl: Schema.String })
+ *
+ * export const SearchAssets = ToolResult.modelView(
+ *   Tool.make("search_assets", {
+ *     parameters: Schema.Struct({ query: Schema.String }),
+ *     success: Schema.Struct({ items: Schema.Array(Asset) })
+ *   }),
+ *   (result) => ({ items: result.items.map(({ id, name }) => ({ id, name })) })
+ * )
+ * ```
+ *
+ * @category annotations
+ * @since 0.5.0
+ */
+export declare const modelView: {
+  <Config extends Schemas>(view: (success: Config["success"]["Type"]) => Schema.Json): <Name extends string, R>(tool: Tool.Tool<Name, Config, R>) => Tool.Tool<Name, Config, R>;
+  <Name extends string, Config extends Schemas, R>(tool: Tool.Tool<Name, Config, R>, view: (success: Config["success"]["Type"]) => Schema.Json): Tool.Tool<Name, Config, R>;
+};
+//#endregion
+export { ToolResult_d_exports };
+//# sourceMappingURL=ToolResult.d.ts.map

package/dist/ToolResult.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolResult.d.ts","names":[],"sources":["../src/ToolResult.ts"],"mappings":";;;;;;KAmBK;WACM,YAAY,OAAO;WACnB,SAAS,OAAO;WAChB,SAAS,OAAO;WAChB,aAAa,KAAK;;cASuC,gBAAA,QAAA,aAAA,qDAAA,iBAAQ,OAAO;;;;;;;qBAAtE,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;qBAiClB;GACV,eAAe,SACd,OAAO,SAAS,8BAA8B,OAAO,QACnD,qBAAqB,GAAG,MAAM,KAAK,KAAK,MAAM,QAAQ,OAAO,KAAK,KAAK,MAAM,QAAQ;GACxF,qBAAqB,eAAe,SAAS,GAC5C,MAAM,KAAK,KAAK,MAAM,QAAQ,IAC9B,OAAO,SAAS,8BAA8B,OAAO,OACpD,KAAK,KAAK,MAAM,QAAQ"}

package/dist/ToolResult.js

@@ -0,0 +1,49 @@
+import { __exportAll } from "./_virtual/_rolldown/runtime.js";
+import * as Context from "effect/Context";
+import { dual } from "effect/Function";
+//#region src/ToolResult.ts
+var ToolResult_exports = /* @__PURE__ */ __exportAll({
+	ModelView: () => ModelView,
+	modelView: () => modelView
+});
+/**
+* Annotation for what the model reads of a tool's success, set with {@link modelView}.
+*
+* @category annotations
+* @since 0.5.0
+*/
+var ModelView = class extends Context.Service()("effect-assistant/ToolResult/ModelView") {};
+/**
+* Sets what the model reads of a tool's success. The chat's log keeps the whole success.
+*
+* **Details**
+*
+* The view gets the success as the tool's success schema decodes it, and returns the JSON the
+* model reads instead. Failures reach the model as they are.
+*
+* **Example** (Keeping image URLs out of the model's context)
+*
+* ```ts
+* import * as Tool from "effect/ai/Tool"
+* import * as Schema from "effect/Schema"
+* import { ToolResult } from "effect-assistant"
+*
+* const Asset = Schema.Struct({ id: Schema.String, name: Schema.String, imageUrl: Schema.String })
+*
+* export const SearchAssets = ToolResult.modelView(
+*   Tool.make("search_assets", {
+*     parameters: Schema.Struct({ query: Schema.String }),
+*     success: Schema.Struct({ items: Schema.Array(Asset) })
+*   }),
+*   (result) => ({ items: result.items.map(({ id, name }) => ({ id, name })) })
+* )
+* ```
+*
+* @category annotations
+* @since 0.5.0
+*/
+const modelView = dual(2, (tool, view) => tool.annotate(ModelView, view));
+//#endregion
+export { ModelView, ToolResult_exports, modelView };
+
+//# sourceMappingURL=ToolResult.js.map

package/dist/ToolResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolResult.js","names":[],"sources":["../src/ToolResult.ts"],"sourcesContent":["/**\n * Shapes what the model reads of a tool's result.\n *\n * A tool's success goes into the chat's log in full. {@link modelView} gives the model a smaller\n * view of it, so fields only the app's UI needs (an image URL, a file id) stay out of its context\n * and out of what it might copy into its replies.\n *\n * A tool whose results the assistant's blocks show (`Block.fromToolResult`) also gets a `resultId`\n * in what the model reads. The model passes it in a `tool_result` block to show that result, and\n * the client draws it from the full result in the log.\n *\n * @since 0.5.0\n */\nimport type * as Tool from \"effect/ai/Tool\"\nimport * as Context from \"effect/Context\"\nimport { dual } from \"effect/Function\"\nimport type * as Schema from \"effect/Schema\"\n\n// The tool's schemas, as `Tool.Tool` constrains them.\ntype Schemas = {\n  readonly parameters: Schema.Top\n  readonly success: Schema.Top\n  readonly failure: Schema.Top\n  readonly failureMode: Tool.FailureMode\n}\n\n/**\n * Annotation for what the model reads of a tool's success, set with {@link modelView}.\n *\n * @category annotations\n * @since 0.5.0\n */\nexport class ModelView extends Context.Service<ModelView, (success: any) => Schema.Json>()(\n  \"effect-assistant/ToolResult/ModelView\"\n) {}\n\n/**\n * Sets what the model reads of a tool's success. The chat's log keeps the whole success.\n *\n * **Details**\n *\n * The view gets the success as the tool's success schema decodes it, and returns the JSON the\n * model reads instead. Failures reach the model as they are.\n *\n * **Example** (Keeping image URLs out of the model's context)\n *\n * ```ts\n * import * as Tool from \"effect/ai/Tool\"\n * import * as Schema from \"effect/Schema\"\n * import { ToolResult } from \"effect-assistant\"\n *\n * const Asset = Schema.Struct({ id: Schema.String, name: Schema.String, imageUrl: Schema.String })\n *\n * export const SearchAssets = ToolResult.modelView(\n *   Tool.make(\"search_assets\", {\n *     parameters: Schema.Struct({ query: Schema.String }),\n *     success: Schema.Struct({ items: Schema.Array(Asset) })\n *   }),\n *   (result) => ({ items: result.items.map(({ id, name }) => ({ id, name })) })\n * )\n * ```\n *\n * @category annotations\n * @since 0.5.0\n */\nexport const modelView: {\n  <Config extends Schemas>(\n    view: (success: Config[\"success\"][\"Type\"]) => Schema.Json\n  ): <Name extends string, R>(tool: Tool.Tool<Name, Config, R>) => Tool.Tool<Name, Config, R>\n  <Name extends string, Config extends Schemas, R>(\n    tool: Tool.Tool<Name, Config, R>,\n    view: (success: Config[\"success\"][\"Type\"]) => Schema.Json\n  ): Tool.Tool<Name, Config, R>\n} = dual(\n  2,\n  <Name extends string, Config extends Schemas, R>(\n    tool: Tool.Tool<Name, Config, R>,\n    view: (success: Config[\"success\"][\"Type\"]) => Schema.Json\n  ): Tool.Tool<Name, Config, R> => tool.annotate(ModelView, view)\n)\n"],"mappings":";;;;;;;;;;;;;;AAgCA,IAAa,YAAb,cAA+B,QAAQ,QAAkD,CAAC,CACxF,uCACF,CAAC,CAAC,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BH,MAAa,YAQT,KACF,IAEE,MACA,SAC+B,KAAK,SAAS,WAAW,IAAI,CAChE"}

package/dist/index.d.ts

@@ -9,7 +9,6 @@ import { Timeline_d_exports } from "./Timeline.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";
@@ -19,5 +18,8 @@ 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 { Skill_d_exports } from "./Skill.js";
+import { ToolApproval_d_exports } from "./ToolApproval.js";
 import { ToolDiscovery_d_exports } from "./ToolDiscovery.js";
-export { 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, 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, Timeline_d_exports as Timeline, ToolDiscovery_d_exports as ToolDiscovery, ToolFailure_d_exports as ToolFailure };
+import { ToolResult_d_exports } from "./ToolResult.js";
+export { 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, 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, Timeline_d_exports as Timeline, ToolApproval_d_exports as ToolApproval, ToolDiscovery_d_exports as ToolDiscovery, ToolFailure_d_exports as ToolFailure, ToolResult_d_exports as ToolResult };