Skip to content

Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.

6.7 KB
Raw Blame
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Schedule from "effect/Schedule";
import * as Semaphore from "effect/Semaphore";
import * as Scope from "effect/Scope";
import {
  type BotMemoryAccess,
  type BotMemoryReviewInput,
  type BotMemoryReviewReservation,
  type BotMemoryStore,
  formatBotMemoryPrompt,
} from "../memory/BotMemory.ts";
import { formatAutomaticBotMemoryReview } from "../memory/BotMemoryReview.ts";
import type { AkeruMemoryToolHandler } from "../memory/BotMemoryToolHandlers.ts";

export type AkeruMemoryReviewMode = "foreground" | "deferred";

export interface AkeruMemoryTurnAdmission {
  readonly access: BotMemoryAccess;
  readonly input: BotMemoryReviewInput;
  /**
   * When false the bot-private `MEMORY.md` is withheld from the supplied prompt
   * context, matching the "Private bot memory" setting. User and group memory
   * are unaffected.
   */
  readonly privateBotMemory?: boolean;
}

/**
 * Provider-neutral memory lifecycle for one admitted bot turn.
 *
 * Provider transports decide only where to deliver `context` and whether review execution is
 * foreground or deferred. Claim ownership, successful-prompt accounting, exact tool-call
 * verification, retries, and cleanup stay here.
 */
export class AkeruMemoryTurn {
  readonly context: string;
  readonly reviewIncluded: boolean;
  readonly access: BotMemoryAccess;

  private readonly store: BotMemoryStore;
  private readonly reservation: BotMemoryReviewReservation;
  get reviewCallContractSatisfied(): boolean {
    return this.successfulMemoryCalls === 1;
  }

  private successfulMemoryCalls = 0;
  private foregroundState: "pending" | "succeeded" | "failed" = "pending";
  private reviewSettled = false;
  private readonly semaphore = Effect.runPromise(Semaphore.make(1));
  private readonly scope: Scope.Scope;
  private scopeClosed = false;

  constructor(
    store: BotMemoryStore,
    access: BotMemoryAccess,
    reservation: BotMemoryReviewReservation,
    context: string,
    scope: Scope.Scope,
  ) {
    this.store = store;
    this.access = access;
    this.reservation = reservation;
    this.context = context;
    this.reviewIncluded = reservation.memoryReviewIncluded;
    this.scope = scope;
  }

  wrapMemoryHandler(handler: AkeruMemoryToolHandler): AkeruMemoryToolHandler {
    if (!this.reviewIncluded) return handler;

    return async (input) => {
      const result = await handler(input);
      this.successfulMemoryCalls += 1;

      return result;
    };
  }

  async freshReviewContext(): Promise<string> {
    const snapshot = formatBotMemoryPrompt(await this.store.readPromptSnapshot(this.access));

    return [snapshot, this.reviewInstruction()].filter(Boolean).join("\n\n");
  }

  async finishForeground(succeeded: boolean, mode: AkeruMemoryReviewMode): Promise<void> {
    return this.exclusive(async () => {
      if (this.foregroundState === "pending") {
        if (succeeded) {
          await this.store.recordSuccessfulPrompt(this.reservation);
          this.foregroundState = "succeeded";
        } else {
          this.foregroundState = "failed";
        }
      }

      if (this.foregroundState === "failed") {
        await this.settleReview(false);

        return;
      }

      if (!this.reviewIncluded) {
        await this.closeScope();

        return;
      }

      if (mode === "foreground") {
        await this.settleReview(this.reviewCallContractSatisfied);
      }
    });
  }

  async finishDeferredReview(succeeded: boolean): Promise<void> {
    return this.exclusive(async () => {
      await this.settleReview(
        this.foregroundState === "succeeded" && succeeded && this.reviewCallContractSatisfied,
      );
    });
  }

  async close(): Promise<void> {
    return this.abandon();
  }

  async abandon(): Promise<void> {
    return this.exclusive(async () => {
      if (this.foregroundState === "pending") this.foregroundState = "failed";
      await this.settleReview(false);
    });
  }

  private reviewInstruction(): string {
    return this.reviewIncluded
      ? formatAutomaticBotMemoryReview(this.access.groupId !== null, this.reservation.reviewInputs)
      : "";
  }

  private async settleReview(completed: boolean): Promise<void> {
    if (this.reviewSettled) return;

    if (this.reviewIncluded) await this.store.settleReviewClaim(this.reservation, completed);
    this.reviewSettled = true;
    await this.closeScope();
  }

  private async closeScope(): Promise<void> {
    if (this.scopeClosed) return;
    this.scopeClosed = true;
    await Effect.runPromise(Scope.close(this.scope, Exit.void));
  }

  async settleFromScope(): Promise<void> {
    if (this.reviewSettled) return;

    if (this.reviewIncluded) await this.store.settleReviewClaim(this.reservation, false);
    this.reviewSettled = true;
  }

  private exclusive(operation: () => Promise<void>): Promise<void> {
    return this.semaphore.then((semaphore) =>
      Effect.runPromise(Semaphore.withPermit(semaphore)(Effect.promise(operation))),
    );
  }
}

export class AkeruMemoryTurnHarness {
  private readonly store: BotMemoryStore;

  constructor(store: BotMemoryStore) {
    this.store = store;
  }

  async admit({
    access,
    input,
    privateBotMemory,
  }: AkeruMemoryTurnAdmission): Promise<AkeruMemoryTurn> {
    const reservation = await this.store.reserveReviewCadence(access.botId, input);
    const scope = await Effect.runPromise(Scope.make());

    try {
      const promptSnapshot = await this.store.readPromptSnapshot(access);

      const snapshot = formatBotMemoryPrompt(
        privateBotMemory === false
          ? { ...promptSnapshot, memory: { ...promptSnapshot.memory, content: "", charCount: 0 } }
          : promptSnapshot,
      );

      const review = reservation.memoryReviewIncluded
        ? formatAutomaticBotMemoryReview(access.groupId !== null, reservation.reviewInputs)
        : "";

      const turn = new AkeruMemoryTurn(
        this.store,
        access,
        reservation,
        [snapshot, review].filter(Boolean).join("\n\n"),
        scope,
      );

      const store = this.store;
      await Effect.runPromise(
        Effect.gen(function* () {
          yield* Effect.acquireRelease(Effect.succeed(turn), () =>
            Effect.promise(() => turn.settleFromScope()),
          );

          if (turn.reviewIncluded) {
            yield* Effect.promise(() =>
              store.renewReviewClaim(reservation).catch(() => false),
            ).pipe(Effect.repeat(Schedule.fixed("20 seconds")), Effect.asVoid, Effect.forkScoped);
          }
        }).pipe(Effect.provideService(Scope.Scope, scope)),
      );

      return turn;
    } catch (cause) {
      await Effect.runPromise(Scope.close(scope, Exit.void));
      await this.store.settleReviewCadence(reservation, false);
      throw cause;
    }
  }
}