effect-assistant 0.2.0 → 0.4.0

package/src/internal/turns.ts

@@ -1,6 +1,6 @@
 import type * as LanguageModel from "effect/ai/LanguageModel"
+import * as Response from "effect/ai/Response"
 import type * as Tool from "effect/ai/Tool"
-import type * as Prompt from "effect/ai/Prompt"
 import * as Cause from "effect/Cause"
 import * as Context from "effect/Context"
 import * as Effect from "effect/Effect"
@@ -8,6 +8,7 @@ import * as Exit from "effect/Exit"
 import { identity } from "effect/Function"
 import * as Option from "effect/Option"
 import * as Predicate from "effect/Predicate"
+import * as Ref from "effect/Ref"
 import * as Schema from "effect/Schema"
 import type * as Scope from "effect/Scope"
 import * as Stream from "effect/Stream"
@@ -19,8 +20,7 @@ import * as Loop from "./loop.ts"
 import type * as BlockKit from "../BlockKit.ts"
 import type { CurrentChat } from "../CurrentChat.ts"
 import * as Instructions from "../Instructions.ts"
-import * as Skill from "../Skill.ts"
-import * as Skills from "./skills.ts"
+import * as ToolApproval from "../ToolApproval.ts"
 import type * as Specialist from "../Specialist.ts"
 import * as AppEvents from "./events.ts"
 import * as History from "./history.ts"
@@ -125,35 +125,22 @@ const failureMessage = (cause: Cause.Cause<unknown>): string =>
     onSome: ({ _tag, raw }) => `${_tag ?? "Error"}: ${Predicate.isString(raw) ? raw : toJsonText(raw)}`
   })
 
-const lastSeq = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, otherwise: number) => entries.at(-1)?.seq ?? otherwise
-
-const toHistory = (
-  viewed: ReadonlyArray<Assistant.Entry<any> | Prompt.Message>,
-  app: AppEvents.AppEvents
-): ReadonlyArray<Prompt.Message> => {
-  const out: Array<Prompt.Message> = []
-  let run: Array<AssistantEvent.AnyEntry> = []
-
-  const flush = () => {
-    out.push(...History.fromEntries(run, (event) => AppEvents.read(app, event)))
-    run = []
-  }
-
-  for (const item of viewed) {
-    if (isEntry(item)) run.push(item)
-    else {
-      flush()
-      out.push(item)
-    }
-  }
-
-  flush()
-
-  return out
-}
+// Approved, and not run yet: also one a crash cut off while it ran, which runs again with the same id.
+const approvedCalls = (entries: ReadonlyArray<AssistantEvent.AnyEntry>): ReadonlyArray<AssistantEvent.ToolCallPart> =>
+  [...ToolApproval.fromEntries(entries).values()].flatMap(({ request, status, outcome }) =>
+    status === "approved" && outcome === undefined
+      ? [
+          Response.makePart("tool-call", {
+            id: request.callId,
+            name: request.tool,
+            params: request.params,
+            providerExecuted: false
+          })
+        ]
+      : []
+  )
 
-const isEntry = (item: Assistant.Entry<any> | Prompt.Message): item is Assistant.Entry<any> =>
-  Predicate.hasProperty(item, "seq")
+const lastSeq = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, otherwise: number) => entries.at(-1)?.seq ?? otherwise
 
 // The handler's stream can end between a step's output and its tools, or while they run. An interrupted turn (a
 // shutdown) leaves its calls open instead: the next turn runs them again.
@@ -164,7 +151,7 @@ const closeOpenCalls = Effect.fnUntraced(function* (chat: Writer, startSeq: numb
     entries.flatMap(({ event }) => (Predicate.isTagged(event, "ToolStarted") ? [event.callId] : []))
   )
 
-  const open = History.unansweredCalls(History.fromEntries(entries, () => undefined))
+  const open = History.unansweredCalls(History.fromEntries(entries))
 
   if (open.length === 0) return
 
@@ -196,13 +183,13 @@ const handledThrough = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, startSe
     startSeq
   )
 
-// Fails visibly when the user's latest input got no reply; an input that arrived after what its model read gets the
-// next turn, which replies.
-const finishTurn = Effect.fnUntraced(function* (chat: Writer, read: number, wakes: ReadonlySet<string>) {
+// A turn that ran the loop fails visibly when the user's latest input got no reply; an input that arrived after what
+// its model read gets the next turn, which replies. A handler that ended without the loop decided that itself.
+const finishTurn = Effect.fnUntraced(function* (chat: Writer, read: number, ranLoop: boolean) {
   const entries = yield* chat.entries
 
   const end =
-    History.owesReply(entries, read) && !History.unreadAfter(entries, read, wakes)
+    ranLoop && History.owesReply(entries, read) && !History.unreadAfter(entries, read)
       ? AssistantEvent.TurnFailed.make({ throughSeq: read, message: silentTurnMessage })
       : AssistantEvent.TurnCompleted.make({ throughSeq: read })
 
@@ -222,11 +209,15 @@ const makeTurnApi = (
   registration: Registration,
   chat: Writer,
   startSeq: number,
-  checkOpen: Effect.Effect<void>
+  checkOpen: Effect.Effect<void>,
+  ranLoop: Ref.Ref<boolean>
 ): Assistant.Turn<any> => {
   const { definition, builtins } = registration
   const { app } = definition
 
+  const running = <A, E, R>(stream: Stream.Stream<A, E, R>) =>
+    Stream.unwrap(Ref.set(ranLoop, true).pipe(Effect.as(stream)))
+
   // With how far into the chat it goes: the step records it on the model's output.
   // Read before every model call: a chat the app deleted meanwhile stops here.
   const history = Effect.fnUntraced(function* (view: Assistant.HistoryView<any> = identity) {
@@ -235,7 +226,7 @@ const makeTurnApi = (
     const all = yield* chat.entries
 
     const read: AssistantLoop.ChatHistory = {
-      messages: toHistory(view(AppEvents.decodeEntries(app, all)), app),
+      messages: History.fromEntries(view(AppEvents.decodeEntries(app, all))),
       throughSeq: lastSeq(all, startSeq)
     }
 
@@ -258,7 +249,7 @@ const makeTurnApi = (
         const through = handledThrough(all, startSeq)
 
         // Something arrived after what the loop's model read: the next turn reads it with the full loop, and replies.
-        if (History.unreadAfter(all, through, app.wakes)) return Stream.empty
+        if (History.unreadAfter(all, through)) return Stream.empty
 
         const owed = History.owesReply(all, through)
         const undelivered = !owed && History.owesDelivery(all, through)
@@ -282,7 +273,7 @@ const makeTurnApi = (
 
             return {
               messages: [
-                ...toHistory(options.view(AppEvents.decodeEntries(app, entries)), app),
+                ...History.fromEntries(options.view(AppEvents.decodeEntries(app, entries))),
                 History.userText(nudge)
               ],
               throughSeq: lastSeq(entries, startSeq)
@@ -290,27 +281,27 @@ const makeTurnApi = (
           }),
           // A second step, for a reply after a call it was refused.
           maxSteps: 2
-        })
+          // The loop ran the approved calls; a pass that can only reply runs none.
+        }).pipe(Stream.provideService(Loop.TurnApprovals, Option.none()))
       })
     )
 
   const replyIfOwed = (options: Assistant.ReplyOptions) =>
-    replyPass({
-      instructions: instructions(options.instructions),
-      toolkit: builtins,
-      view: identity,
-      nudge: options.nudge
-    })
+    running(
+      replyPass({
+        instructions: instructions(options.instructions),
+        toolkit: builtins,
+        view: identity,
+        nudge: options.nudge
+      })
+    )
 
-  const prepare = <T extends Record<string, Tool.Any>, RS>(options: Assistant.LoopOptions<T, RS, any>) => {
-    const skills = options.skills ?? []
+  const prepare = <T extends Record<string, Tool.Any>>(options: Assistant.LoopOptions<T, any>) => {
+    const own = Toolkits.fromToolkitOrEmpty(options.toolkit)
 
     return {
-      system: mapText(instructions(options.instructions), (text) => Skill.withCatalog(text, skills)),
-      toolkit: Toolkits.merge(
-        Toolkits.merge(builtins, Skills.toTools(skills)),
-        Toolkits.fromToolkitOrEmpty(options.toolkit)
-      ),
+      system: instructions(options.instructions),
+      toolkit: Toolkits.merge(builtins, own),
       view: options.history ?? identity
     }
   }
@@ -334,7 +325,7 @@ const makeTurnApi = (
               maxSteps: options.maxSteps ?? 16
             })
 
-      return Stream.concat(loop, replyPass({ instructions: system, toolkit, view, nudge: options.replyNudge }))
+      return running(Stream.concat(loop, replyPass({ instructions: system, toolkit, view, nudge: options.replyNudge })))
     }
   }
 }
@@ -353,7 +344,7 @@ export const run = Effect.fnUntraced(
     const { chat } = options
     const before = yield* chat.entries
 
-    yield* Telemetry.agentInput(History.unhandledInputs(before, options.registration.definition.app.wakes))
+    yield* Telemetry.agentInput(History.unhandledInputs(before))
 
     const assistant = options.registration.definition.name
     const traceId = yield* Telemetry.currentTraceId
@@ -368,7 +359,8 @@ export const run = Effect.fnUntraced(
     ])
 
     const startSeq = lastSeq(started, 0)
-    const turn = makeTurnApi(options.registration, chat, startSeq, options.checkOpen)
+    const ranLoop = yield* Ref.make(false)
+    const turn = makeTurnApi(options.registration, chat, startSeq, options.checkOpen, ranLoop)
 
     const record = (event: AssistantLoop.Event) => chat.append([event])
 
@@ -380,12 +372,14 @@ export const run = Effect.fnUntraced(
         Loop.TurnTools,
         Option.some(Toolkits.provide(options.registration.builtins, options.services))
       ),
+      // A turn's loop waits for the user's approval, and runs the calls they approved.
+      Effect.provideService(Loop.TurnApprovals, Option.some({ approved: Effect.map(chat.entries, approvedCalls) })),
       Effect.provideContext(options.services),
       Effect.matchCauseEffect({
         onSuccess: Effect.fnUntraced(function* () {
           const all = yield* chat.entries
 
-          yield* finishTurn(chat, handledThrough(all, startSeq), options.registration.definition.app.wakes)
+          yield* finishTurn(chat, handledThrough(all, startSeq), yield* Ref.get(ranLoop))
         }),
         onFailure: (cause) => failTurn(chat, cause)
       })

package/dist/AppEvent.d.ts

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

package/dist/AppEvent.d.ts.map

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

package/dist/AppEvent.js

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

package/dist/AppEvent.js.map

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