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.

18.4 KB
Raw Blame
import { ProviderDriverKind } from "@akeru/contracts";
import { ProviderInstanceId } from "@akeru/contracts";
import type { AkeruToolRuntime } from "../../AkeruToolRuntime.ts";
import type { ProviderServiceError } from "../../Errors.ts";
import type { AkeruRuntimeSeam } from "../../AkeruRuntimeSeam.ts";
import type { AgentControllerLiveOptions } from "./Options.ts";

import {
  EventId,
  RuntimeRequestId,
  TurnId,
  type BotId,
  type AkeruCreateRoutineInput,
  type ProviderRuntimeEvent,
  ThreadId,
  type AkeruMemoryThreadAccess,
} from "@akeru/contracts";

import * as Deferred from "effect/Deferred";

import * as Effect from "effect/Effect";

import { type AkeruChannelRuntime } from "../../AkeruChannelRuntime.ts";
import { type AkeruBotStateRuntime } from "../../AkeruBotStateRuntime.ts";
import { AkeruMemoryTurnHarness, type AkeruMemoryTurn } from "../../AkeruMemoryTurnHarness.ts";
import { type AkeruDelegationChildOutcome } from "../../AkeruDelegationRuntime.ts";
import type { AkeruWorkerRuntime } from "../../AkeruWorkerRuntime.ts";

import type { PendingWaiters } from "../../PendingWaiters.ts";
import {
  createAkeruPluginRuntime,
  type AkeruPluginRuntimeOptions,
} from "../../AkeruCatalogToolHandlers.ts";

import { type AkeruToolSession } from "../../AkeruToolRuntime.ts";

import { AgentControllerRuntimeError } from "../../Errors.ts";

import { LegacyProviderBridge } from "../../Services/LegacyProviderBridge.ts";

import {
  type ActiveTurn,
  type PendingTurn,
  type ActiveSession,
  type PendingApproval,
  type WorkerOrchestration,
} from "./State.ts";

export function createTurnLifecycle(deps: {
  readonly runPromise: AkeruRuntimeSeam["runPromise"];
  readonly forkPromise: AkeruRuntimeSeam["forkPromise"];
  readonly fork: AkeruRuntimeSeam["fork"];
  readonly pendingRoutineRequests: PendingWaiters<
    {
      readonly threadId: string;
      readonly input: AkeruCreateRoutineInput;
      readonly timezone: string;
    },
    unknown,
    Error
  >;
  readonly creatingRoutineReviews: Map<string, string>;
  readonly publish: (event: ProviderRuntimeEvent) => void;
  readonly baseEvent: (
    threadId: ThreadId,
    active: Pick<ActiveSession, "provider" | "providerInstanceId">,
    turnId?: TurnId,
  ) => {
    turnId?: TurnId;
    eventId: EventId;
    provider: ProviderDriverKind;
    providerInstanceId: ProviderInstanceId;
    threadId: ThreadId;
    createdAt: string;
  };
  readonly toolRuntime: AkeruToolRuntime;
  readonly memoryUsageByThread: Map<string, { readonly botId: BotId; turnId: TurnId }>;
  readonly publishSessionState: (
    threadId: ThreadId,
    active: ActiveSession,
    state: "ready" | "running" | "waiting" | "stopped" | "error",
    reason?: string,
  ) => void;
  readonly sessionFailureDetail: (
    active: Pick<ActiveSession, "mcpServerIds">,
    cause: unknown,
  ) => string;
  readonly stopSessionWithResources: (
    input: { readonly threadId: ThreadId },
    destroyResources: boolean,
  ) => Effect.Effect<void, ProviderServiceError | AgentControllerRuntimeError, never>;
  readonly memorySettings: () =>
    | Effect.Effect<
        | { enabled: boolean; privateBotMemory: boolean; sharedProjectMemory: "auto" | "ask" }
        | { enabled: boolean; privateBotMemory: boolean; sharedProjectMemory: "ask" },
        never,
        never
      >
    | Effect.Effect<
        {
          readonly enabled: true;
          readonly privateBotMemory: true;
          readonly sharedProjectMemory: "ask";
        },
        never,
        never
      >;
  readonly refreshEntityMemoryAccess: (
    access: AkeruMemoryThreadAccess | undefined,
  ) => Promise<AkeruMemoryThreadAccess | undefined>;
  readonly memoryTurnHarness: AkeruMemoryTurnHarness;
  readonly mastraReservationKey: (threadId: ThreadId, turnId: TurnId) => string;
  readonly mastraMemoryTurns: Map<string, AkeruMemoryTurn>;
  readonly entityMemoryContext: (access: AkeruMemoryThreadAccess | undefined) => Promise<string>;
  readonly legacyProviderBridge: LegacyProviderBridge["Service"];
  readonly startPendingTurn: (active: ActiveSession, pending: PendingTurn) => void;
  readonly queueTurnMemory: (threadId: ThreadId, active: ActiveSession, turn: ActiveTurn) => void;
  readonly completeAssistantMessages: (
    threadId: ThreadId,
    active: ActiveSession,
    turn: ActiveTurn,
  ) => void;
  readonly resolveChildWaiter: (threadId: ThreadId, outcome: AkeruDelegationChildOutcome) => void;
  readonly workerRuntime: AkeruWorkerRuntime;
  readonly wired: () => {
    readonly channelRuntime?: AkeruChannelRuntime;
    readonly pluginRuntime?: ReturnType<typeof createAkeruPluginRuntime>;
    readonly pluginRuntimeOptions?: AkeruPluginRuntimeOptions;
    readonly botStateRuntime?: AkeruBotStateRuntime;
    readonly delegationRuntime?: AgentControllerLiveOptions["delegationRuntime"];
    readonly workerOrchestration?: WorkerOrchestration;
  };
  readonly failureDetail: (cause: unknown) => string;
}) {
  const turnStillWaiting = (threadId: string, active: ActiveSession) =>
    active.pendingApprovals.size > 0 ||
    (active.activeTurn?.suspendedToolCalls.size ?? 0) > 0 ||
    deps.pendingRoutineRequests.entries().some(([, request]) => request.threadId === threadId) ||
    [...deps.creatingRoutineReviews.values()].includes(threadId);

  const cancelPendingApproval = (
    threadId: ThreadId,
    active: ActiveSession,
    requestId: string,
    pending: PendingApproval,
  ) => {
    deps.publish({
      ...deps.baseEvent(threadId, active, active.activeTurn?.turnId),
      requestId: RuntimeRequestId.make(requestId),
      type: "request.resolved",
      payload: {
        requestType: "dynamic_tool_call",
        decision: "cancel",
        actor: "system",
        target: pending.toolName,
        action: pending.action,
        outcome: "cancelled",
      },
    });
  };

  const cancelAllPendingApprovals = (threadId: ThreadId, active: ActiveSession) => {
    for (const [requestId, pending] of active.pendingApprovals) {
      cancelPendingApproval(threadId, active, requestId, pending);
    }

    active.pendingApprovals.clear();
    active.approvalRequests.clear();
    deps.toolRuntime.clearApprovals(String(threadId));
  };

  const beginPendingTurn = (
    active: ActiveSession,
    { threadId, turnId, botUsage, hiddenWake }: PendingTurn,
  ) => {
    const key = String(threadId);

    if (botUsage) {
      deps.memoryUsageByThread.set(key, { ...botUsage, turnId });
    } else {
      deps.memoryUsageByThread.delete(key);
    }

    active.activeTurn = {
      turnId,
      assistantMessages: new Map(),
      waiting: false,
      suspendedToolCalls: new Set(),
      finished: false,
      inputTokens: 0,
      outputTokens: 0,
      reasoningTokens: 0,
      memoryQueued: false,
      assistantText: "",
    };
    active.status = "running";
    deps.publish({
      ...deps.baseEvent(threadId, active, turnId),
      type: "turn.started",
      payload: { model: active.model, ...(hiddenWake ? { hiddenWake: true } : {}) },
    });
    deps.publishSessionState(threadId, active, "running");
  };

  const failActiveTurn = async (
    active: ActiveSession,
    threadId: ThreadId,
    turnId: TurnId,
    cause: unknown,
  ) => {
    if (active.activeTurn?.turnId !== turnId) return;
    const detail = deps.sessionFailureDetail(active, cause);
    deps.publish({
      ...deps.baseEvent(threadId, active, turnId),
      type: "runtime.error",
      payload: { message: detail, class: "provider_error" },
    });
    finishTurn(threadId, active, "failed", detail);
    await deps.runPromise(
      deps.stopSessionWithResources({ threadId }, false).pipe(
        Effect.catchCause((resetCause) =>
          Effect.logWarning("provider session reset failed", {
            threadId,
            cause: resetCause,
          }),
        ),
      ),
    );
  };

  const handlePendingTurnFailure = (
    active: ActiveSession,
    pending: PendingTurn,
    cause: unknown,
  ) => {
    const ownsAdmission = active.admittingTurn?.turnId === pending.turnId;
    const ownsActiveTurn = active.activeTurn?.turnId === pending.turnId;

    if (!ownsAdmission && !ownsActiveTurn) return Promise.resolve();

    if (ownsAdmission) {
      active.admittingTurn = null;
    }

    if (!active.activeTurn) beginPendingTurn(active, pending);

    return failActiveTurn(active, pending.threadId, pending.turnId, cause);
  };

  const startAdmittedPendingTurn = (active: ActiveSession, pending: PendingTurn) => {
    const { threadId, turnId, message } = pending;

    if (active.admittingTurn?.turnId !== turnId) return;

    const dispatch: Promise<void> = (async () => {
      const settings = pending.memoryAccess
        ? await deps.runPromise(deps.memorySettings())
        : undefined;

      // The settings read is asynchronous; the turn may have been interrupted
      // while it was pending. Only mutate session state if this admission
      // still owns the turn.
      if (active.admittingTurn?.turnId !== turnId) return;

      const memoryAccess =
        pending.memoryAccess && settings?.enabled ? pending.memoryAccess : undefined;

      // Entity memory rides on durable memory access. With Memory off (or a
      // delegated turn without memory) the turn runs without memory, so group
      // membership is only checked when memory is actually in play.
      const entityMemoryAccess = memoryAccess
        ? await deps.refreshEntityMemoryAccess(pending.entityMemoryAccess)
        : undefined;

      if (memoryAccess && pending.entityMemoryAccess && !entityMemoryAccess) {
        active.admittingTurn = null;
        beginPendingTurn(active, pending);
        await failActiveTurn(
          active,
          pending.threadId,
          pending.turnId,
          new Error("The bot is no longer a member of this group."),
        );

        return;
      }

      if (settings) active.privateBotMemory = settings.privateBotMemory;
      active.memoryAccess = memoryAccess;

      if (!memoryAccess) {
        // Memory was turned off after the turn was queued: drop the memory
        // tool handler so the bot cannot read or change facts. A delegated
        // turn never has durable access, so it keeps the handler its grant
        // built; that handler checks the Memory setting on every call.
        const toolSession = { ...pending.toolSession };

        if (pending.memoryAccess) delete toolSession.memoryHandlers;
        active.toolSession = toolSession;
        deps.toolRuntime.registerSession(String(threadId), active.toolSession);
        const { persistentMemoryContext, ...stateWithoutMemory } = active.session.state.get();

        if (pending.delegationResults) {
          await active.session.state.set({
            ...stateWithoutMemory,
            persistentMemoryContext: pending.delegationResults,
          });
        } else if (persistentMemoryContext) {
          await active.session.state.set(stateWithoutMemory);
        }

        if (active.admittingTurn?.turnId !== turnId) return;
        active.admittingTurn = null;
        beginPendingTurn(active, pending);
        await active.session.sendMessage(message);

        return;
      }

      {
        active.toolSession = pending.toolSession;

        const memoryTurn = await deps.memoryTurnHarness.admit({
          access: memoryAccess,
          input: {
            threadId: String(threadId),
            groupId: memoryAccess.groupId === null ? null : String(memoryAccess.groupId),
            text: pending.reviewInput.slice(0, 4_000),
          },
          privateBotMemory: active.privateBotMemory,
        });

        const reservationKey = deps.mastraReservationKey(threadId, turnId);
        deps.mastraMemoryTurns.set(reservationKey, memoryTurn);
        let accepted = false;
        let reviewToolSession: AkeruToolSession | undefined;

        try {
          const memoryHandler = pending.toolSession.memoryHandlers?.memory;

          if (memoryTurn.reviewIncluded && memoryHandler) {
            reviewToolSession = {
              ...pending.toolSession,
              memoryHandlers: {
                memory: memoryTurn.wrapMemoryHandler(memoryHandler),
              },
            };
            active.toolSession = reviewToolSession;
          }

          deps.toolRuntime.registerSession(String(threadId), active.toolSession);
          const currentState = active.session.state.get();

          const { persistentMemoryContext: _priorMemoryContext, ...stateWithoutMemory } =
            currentState;

          const entityPacket = await deps.entityMemoryContext(entityMemoryAccess);

          const persistentMemoryContext = [
            memoryTurn.context,
            entityPacket,
            pending.delegationResults,
          ]
            .filter(Boolean)
            .join("\n\n");

          await active.session.state.set({
            ...stateWithoutMemory,
            ...(persistentMemoryContext ? { persistentMemoryContext } : {}),
          });

          if (active.admittingTurn?.turnId !== turnId) return;
          active.admittingTurn = null;
          beginPendingTurn(active, pending);
          await active.session.sendMessage(message);
          accepted = true;
        } finally {
          await memoryTurn.finishForeground(accepted, "foreground");

          if (reviewToolSession && active.toolSession === reviewToolSession) {
            active.toolSession = active.configuredToolSession;
            deps.toolRuntime.registerSession(String(threadId), active.toolSession);
          }

          if (deps.mastraMemoryTurns.get(reservationKey) === memoryTurn) {
            deps.mastraMemoryTurns.delete(reservationKey);
          }
        }
      }
    })();

    active.pendingDispatches.add(dispatch);
    void dispatch.then(
      () => active.pendingDispatches.delete(dispatch),
      () => active.pendingDispatches.delete(dispatch),
    );
    deps.forkPromise(
      "Akeru turn dispatch failed.",
      () =>
        dispatch.then(() => {
          const turn = active.activeTurn;

          if (turn?.turnId === turnId && !turn.waiting) {
            finishTurn(threadId, active, "completed");
          }
        }),
      {
        annotations: { threadId, turnId },
        onFailure: (cause) => handlePendingTurnFailure(active, pending, cause),
      },
    );
  };

  const admitPendingTurn = (active: ActiveSession, pending: PendingTurn) => {
    active.admittingTurn = pending;

    return deps.legacyProviderBridge
      .dispatchIfEnabled(active.providerInstanceId, "AgentController.startPendingTurn", () =>
        startAdmittedPendingTurn(active, pending),
      )
      .pipe(
        Effect.onInterrupt(() =>
          Effect.sync(() => {
            if (active.admittingTurn?.turnId !== pending.turnId) return;
            active.admittingTurn = null;
            const nextTurn = active.pendingTurns.shift();

            if (nextTurn) deps.startPendingTurn(active, nextTurn);
          }),
        ),
      );
  };

  // Ends the current admission generation and cancels turns still preparing in it.
  const endTurnAdmissionGeneration = (active: ActiveSession) => {
    active.turnAdmissionGeneration += 1;
    Deferred.doneUnsafe(active.turnPreparationCancelled, Effect.void);
    active.turnPreparationCancelled = Deferred.makeUnsafe<void>();
  };

  const finishTurn = (
    threadId: ThreadId,
    active: ActiveSession,
    state: "completed" | "failed" | "interrupted",
    errorMessage?: string,
  ) => {
    const turn = active.activeTurn;

    if (!turn || turn.finished) return;
    deps.queueTurnMemory(threadId, active, turn);
    turn.finished = true;
    deps.completeAssistantMessages(threadId, active, turn);
    cancelAllPendingApprovals(threadId, active);
    deps.publish({
      ...deps.baseEvent(threadId, active, turn.turnId),
      type: "turn.completed",
      payload: {
        state,
        ...(errorMessage ? { errorMessage } : {}),
      },
    });
    deps.resolveChildWaiter(threadId, {
      state: state === "completed" ? "completed" : "failed",
      turnId: turn.turnId,
      ...(state === "completed" && turn.assistantText.trim()
        ? { summary: turn.assistantText.trim() }
        : { error: errorMessage ?? `The delegated turn ${state}.` }),
      usage: { inputTokens: turn.inputTokens, outputTokens: turn.outputTokens },
    });
    deps.fork(
      "Akeru worker could not record its turn outcome.",
      deps.workerRuntime.childTurnFinished(threadId, {
        state: state === "completed" ? "completed" : "failed",
        ...(state === "completed" && turn.assistantText.trim()
          ? { summary: turn.assistantText.trim() }
          : { error: errorMessage ?? `The worker turn ${state}.` }),
      }),
      { threadId, turnId: turn.turnId },
    );
    deps.fork(
      "Akeru workers could not settle after the parent turn.",
      deps.workerRuntime.parentTurnEnded(threadId, turn.turnId),
      {
        threadId,
        turnId: turn.turnId,
      },
    );
    const delegationRuntime = deps.wired().delegationRuntime;

    if (state !== "completed" && delegationRuntime) {
      deps.forkPromise(
        "Akeru delegated work could not settle after the parent turn.",
        () =>
          delegationRuntime.parentFinished({
            threadId,
            turnId: turn.turnId,
            failed: state === "failed",
          }),
        {
          annotations: { threadId, turnId: turn.turnId },
          onFailure: (cause) => {
            deps.publish({
              ...deps.baseEvent(threadId, active, turn.turnId),
              type: "runtime.error",
              payload: { message: deps.failureDetail(cause), class: "provider_error" },
            });
          },
        },
      );
    }

    for (const [requestId, request] of deps.pendingRoutineRequests.entries()) {
      if (request.threadId !== String(threadId)) continue;
      deps.pendingRoutineRequests.reject(
        requestId,
        new Error("The routine review ended before it received a response."),
      );
    }

    active.activeTurn = null;
    const nextTurn = active.pendingTurns.shift();

    if (nextTurn) {
      deps.startPendingTurn(active, nextTurn);
    } else if (state === "failed") {
      // Keep the failure visible until the next turn; publishing ready here
      // would overwrite the error state that turn.completed just recorded.
      deps.publishSessionState(threadId, active, "error", errorMessage);
    } else {
      deps.publishSessionState(threadId, active, "ready");
    }
  };

  return {
    turnStillWaiting,
    cancelPendingApproval,
    cancelAllPendingApprovals,
    beginPendingTurn,
    failActiveTurn,
    handlePendingTurnFailure,
    startAdmittedPendingTurn,
    admitPendingTurn,
    endTurnAdmissionGeneration,
    finishTurn,
  };
}