effect-assistant 0.0.0-stage → 0.1.0

package/src/index.ts

@@ -0,0 +1,130 @@
+/**
+ * effect-assistant: a colleague assistant on Effect.
+ *
+ * @since 0.1.0
+ */
+
+/**
+ * @since 0.1.0
+ */
+export * as AppEvent from "./AppEvent.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as Assistant from "./Assistant.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as AssistantActivity from "./AssistantActivity.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as AssistantEngine from "./AssistantEngine.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as AssistantEvent from "./AssistantEvent.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as AssistantLoop from "./AssistantLoop.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as AssistantToolCall from "./AssistantToolCall.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as Block from "./Block.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as BlockKit from "./BlockKit.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as ChatId from "./ChatId.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as ChatLog from "./ChatLog.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as Chats from "./Chats.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as ChatView from "./ChatView.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as Compaction from "./Compaction.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as CurrentChat from "./CurrentChat.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as Decision from "./Decision.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as DecisionId from "./DecisionId.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as InputId from "./InputId.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as Instructions from "./Instructions.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as Memory from "./Memory.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as RunId from "./RunId.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as Skill from "./Skill.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as Specialist from "./Specialist.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as ToolDiscovery from "./ToolDiscovery.ts"
+
+/**
+ * @since 0.1.0
+ */
+export * as ToolFailure from "./ToolFailure.ts"

package/src/internal/chat.ts

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

package/src/internal/decisions.ts

@@ -0,0 +1,131 @@
+import * as Response from "effect/ai/Response"
+import * as Context from "effect/Context"
+import * as Data from "effect/Data"
+import type * as Effect from "effect/Effect"
+import * as Option from "effect/Option"
+import * as Predicate from "effect/Predicate"
+import * as Schema from "effect/Schema"
+import * as AssistantEvent from "../AssistantEvent.ts"
+import * as BlockKit from "../BlockKit.ts"
+import * as Decision from "../Decision.ts"
+import type { InputId } from "../InputId.ts"
+
+// Only a turn's loop parks calls and runs approved ones. A turn's specialists inherit its context, so their runs set
+// it back to none.
+/** @internal */
+export const TurnDecisions = Context.Reference<
+  Option.Option<{
+    readonly approved: Effect.Effect<ReadonlyArray<AssistantEvent.ToolCallPart>>
+  }>
+>("effect-assistant/TurnDecisions", { defaultValue: Option.none })
+
+/** @internal */
+export interface Decided {
+  readonly request: AssistantEvent.DecisionRequested
+  readonly outcome: AssistantEvent.DecisionOutcome
+}
+
+/** @internal */
+export type Verdict = Data.TaggedEnum<{
+  Store: Record<never, never>
+  Refuse: { readonly reason: string }
+  Decide: { readonly decided: ReadonlyArray<Decided>; readonly answer: InputId }
+}>
+
+const Verdicts = Data.taggedEnum<Verdict>()
+
+const store = Verdicts.Store()
+
+const refuse = (reason: string) => Verdicts.Refuse({ reason })
+
+const decodeProps = Schema.decodeUnknownOption(Decision.Props)
+
+const decodeAnswer = Schema.decodeUnknownOption(Decision.Answer)
+
+const messageOf = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, id: string) =>
+  entries
+    .map(({ event }) => event)
+    .find(
+      (event): event is AssistantEvent.AssistantMessage =>
+        AssistantEvent.isLibraryEvent(event) && Predicate.isTagged(event, "AssistantMessage") && event.id === id
+    )
+
+const answerVerdict = (entries: ReadonlyArray<AssistantEvent.AnyEntry>, answer: AssistantEvent.BlockAnswer) => {
+  const message = messageOf(entries, answer.messageId)
+  const onDecisionBlock = message?.block?.kind === Decision.kind
+
+  if (!onDecisionBlock && answer.kind !== Decision.kind) return store
+
+  if (message?.block === undefined || !onDecisionBlock || answer.kind !== Decision.kind) {
+    return refuse(`${answer.messageId} has no decision block.`)
+  }
+
+  if (BlockKit.fromEntries(entries).get(message.id)?.open !== true)
+    return refuse(`The block on ${message.id} is closed.`)
+
+  const props = decodeProps(message.block.props)
+  const value = decodeAnswer(answer.value)
+
+  if (Option.isNone(props) || Option.isNone(value)) return refuse(`That isn't an answer to the block on ${message.id}.`)
+
+  const asked = props.value.decisionIds
+  const given = Object.keys(value.value.decisions)
+
+  if (given.length !== asked.length || !given.every((id) => asked.some((askedId) => askedId === id))) {
+    return refuse(`An answer decides exactly the decisions its block asks for: ${asked.join(", ")}.`)
+  }
+
+  const states = Decision.fromEntries(entries)
+  const decided: Array<Decided> = []
+
+  for (const id of asked) {
+    const state = states.get(id)
+    const outcome = value.value.decisions[id]
+
+    if (state === undefined || outcome === undefined) return refuse(`No decision ${id}.`)
+
+    if (state.outcome !== undefined) return refuse(`${id} is already decided.`)
+
+    decided.push({ request: state.request, outcome })
+  }
+
+  return Verdicts.Decide({ decided, answer: answer.id })
+}
+
+/** @internal */
+export const verdict = (
+  entries: ReadonlyArray<AssistantEvent.AnyEntry>,
+  input: AssistantEvent.Input | AssistantEvent.StoredAppEvent
+): Verdict =>
+  AssistantEvent.isLibraryEvent(input) && Predicate.isTagged(input, "BlockAnswer")
+    ? answerVerdict(entries, input)
+    : store
+
+// A restart can cut the chat off between storing an answer and resolving what it decided.
+/** @internal */
+export const unresolved = (
+  entries: ReadonlyArray<AssistantEvent.AnyEntry>
+): ReadonlyArray<Decided & { readonly answer: InputId }> =>
+  [...Decision.fromEntries(entries).values()].flatMap((state) =>
+    state.outcome !== undefined && state.answer !== undefined && !state.resolved
+      ? [{ request: state.request, outcome: state.outcome, answer: state.answer }]
+      : []
+  )
+
+// They run with the ids and params the model gave them, before the model's next step.
+/** @internal */
+export const approvedCalls = (
+  entries: ReadonlyArray<AssistantEvent.AnyEntry>
+): ReadonlyArray<AssistantEvent.ToolCallPart> =>
+  [...Decision.fromEntries(entries).values()].flatMap(({ request, outcome, resolved, result }) =>
+    resolved && outcome === "approved" && result === undefined
+      ? [
+          Response.makePart("tool-call", {
+            id: request.origin.callId,
+            name: request.origin.tool,
+            params: request.origin.params,
+            providerExecuted: false
+          })
+        ]
+      : []
+  )