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.

22.8 KB
Raw Blame
import * as Predicate from "effect/Predicate";
import { createAkeruDelegationControls } from "./delegation/AkeruDelegationControls.ts";
import { createAkeruDelegationDelivery } from "./delegation/AkeruDelegationDelivery.ts";
import * as NodeCrypto from "node:crypto";
import * as DateTime from "effect/DateTime";
import {
  AkeruDelegationPhase,
  AKERU_DELEGATION_CONTEXT_MAX_CHARS,
  AKERU_DELEGATION_MAX_CONCURRENCY,
  AKERU_DELEGATION_MAX_DEPTH,
  AKERU_TOOL_CATALOG,
  CommandId,
  DelegationId,
  MessageId,
  ProviderInstanceId,
  ThreadId,
  type AkeruDelegationAccessGrant,
  type AkeruDelegationFailureCode,
  type AkeruDelegationRecord,
  akeruDelegationStateOf,
  type AkeruToolInputSchemas,
  AkeruDelegationContextTooLongError,
  AkeruDelegationProviderUnsupportedError,
  type OrchestrationCommand,
  TurnId,
} from "@akeru/contracts";
import { driverSupportsDelegation } from "@akeru/shared/delegationProviders";
import { withoutErrorStack } from "@akeru/shared/errorText";
import { intersectDelegationAccess } from "./tools/AkeruToolAuthorization.ts";
import {
  type AkeruDelegationRuntimeOptions,
  type AkeruDelegationParent,
  phaseChildThreadId,
  phaseChildTurnId,
  isReachableFromThread,
  TERMINAL_PHASES,
  phaseStartedAt,
  type AkeruDelegationOrigin,
  childAccess,
  parentTurnRequestMessageId,
  type AkeruDelegationChildOutcome,
  childInstructions,
  isPendingWaiterTimeout,
  type AkeruDelegationHandle,
  type AkeruDelegationDispatch,
  isDispatchedDelegation,
} from "./delegation/AkeruDelegationPolicy.ts";

export function createAkeruDelegationRuntime(options: AkeruDelegationRuntimeOptions) {
  const now = options.now ?? (() => DateTime.formatIso(DateTime.nowUnsafe()));
  const id = options.id ?? (() => NodeCrypto.randomUUID());
  const accessByThread = new Map<ThreadId, AkeruDelegationAccessGrant>();
  const watchers = new Set<Promise<void>>();

  const activeByParent = new Map<
    ThreadId,
    Map<DelegationId, { threadId: ThreadId; turnId: TurnId | null }>
  >();

  const dispatch = (command: OrchestrationCommand) =>
    options.dispatch(command).then(() => undefined);

  const commandId = (label: string) => CommandId.make(`delegation:${label}:${id()}`);

  const { sendToUser, deliver, postGroupResult } = createAkeruDelegationDelivery(
    options,
    now,
    id,
    commandId,
    dispatch,
  );

  const setState = async (delegation: AkeruDelegationRecord) => {
    await dispatch({
      type: "delegation.state.set",
      commandId: commandId(akeruDelegationStateOf(delegation.phase)),
      delegation,
    });
  };

  const { create, check, stop } = createAkeruDelegationControls(
    options,
    now,
    id,
    commandId,
    dispatch,
    setState,
  );

  // Every failure lands here, so the card and the parent's activity get one
  // readable line whatever error produced it. A stack never reaches the
  // record; the provider reactor logs the full cause of a failed start.
  const fail = async (
    delegation: AkeruDelegationRecord,
    failureCode: AkeruDelegationFailureCode,
    detail: string,
  ) => {
    const message = withoutErrorStack(detail) || "The bot work failed.";
    const completedAt = now();

    const failed: AkeruDelegationRecord = {
      ...delegation,
      phase: AkeruDelegationPhase.cases.Failed.make({
        childThreadId: phaseChildThreadId(delegation),
        childTurnId: phaseChildTurnId(delegation),
        startedAt: phaseStartedAt(delegation),
        completedAt,
        failure: { failureCode, message },
        acknowledgedAt: null,
      }),
      updatedAt: completedAt,
    };

    await setState(failed);
    await deliver(failed, message);

    return failed;
  };

  const send = async (
    parent: AkeruDelegationParent,
    request: (typeof AkeruToolInputSchemas.SendToAgent)["Type"],
    origin?: AkeruDelegationOrigin,
  ) => {
    const snapshot = await options.readSnapshot();
    const parentThread = snapshot.threads.find((thread) => thread.id === parent.threadId);
    const bot = snapshot.bots.find((candidate) => candidate.id === request.botId);

    if (!parentThread || !bot || bot.archivedAt !== null) {
      throw new Error("The target bot is not available in this workspace.");
    }

    if (bot.id === parent.botId || parent.ancestorBotIds.includes(bot.id)) {
      throw new Error("Bot work would create a self-call or cycle.");
    }

    if (parent.depth >= AKERU_DELEGATION_MAX_DEPTH) {
      throw new Error(`Bot work depth cannot exceed ${AKERU_DELEGATION_MAX_DEPTH}.`);
    }

    const active = snapshot.delegations.filter(
      (delegation) =>
        delegation.parentThreadId === parent.threadId &&
        !TERMINAL_PHASES.has(delegation.phase._tag),
    );

    if (active.length >= AKERU_DELEGATION_MAX_CONCURRENCY) {
      throw new Error(
        `A turn cannot run more than ${AKERU_DELEGATION_MAX_CONCURRENCY} bot work items.`,
      );
    }

    if (
      request.context !== undefined &&
      request.context.length > AKERU_DELEGATION_CONTEXT_MAX_CHARS
    ) {
      throw new AkeruDelegationContextTooLongError({
        length: request.context.length,
        maxLength: AKERU_DELEGATION_CONTEXT_MAX_CHARS,
      });
    }

    if (!isReachableFromThread(snapshot, parentThread, bot)) {
      throw new Error("The target bot is not available in the current group.");
    }

    const modelSelection =
      bot.engine === null
        ? parentThread.modelSelection
        : {
            instanceId: ProviderInstanceId.make(bot.engine.provider),
            model: bot.engine.model,
            ...(bot.engine.options ? { options: bot.engine.options } : {}),
          };

    if (options.providerDriverKind) {
      const driverKind = await options.providerDriverKind(modelSelection.instanceId);

      if (driverKind === null) {
        throw new Error("The target bot is not available in this workspace.");
      }

      if (!driverSupportsDelegation(driverKind)) {
        throw new AkeruDelegationProviderUnsupportedError({ botName: bot.name, driverKind });
      }
    }

    const grant = intersectDelegationAccess({
      parent: parent.access,
      child: childAccess(bot, parent.access.enabledMcpServerIds, request.memoryScopes),
      requested: request,
    });

    const delegationId = DelegationId.make(`delegation-${id()}`);
    const childThreadId = ThreadId.make(`delegation-thread-${id()}`);
    const createdAt = now();
    await dispatch({
      type: "thread.create",
      commandId: commandId("thread"),
      threadId: childThreadId,
      projectId: parentThread.projectId,
      // A child is a direct thread of the target bot, even when a group chat
      // sent the work; the group sees the result as an attributed message.
      botId: bot.id,
      groupId: null,
      parentThreadId: parent.threadId,
      parentDelegationId: delegationId,
      title: `Bot work for ${bot.name}`,
      modelSelection,
      runtimeMode: grant.runtimeMode,
      interactionMode: "default",
      branch: null,
      worktreePath: null,
      createdAt,
    });

    let delegation: AkeruDelegationRecord = {
      delegationId,
      parentDelegationId: parent.parentDelegationId,
      parentBotId: parent.botId,
      childBotId: bot.id,
      parentThreadId: parent.threadId,
      parentTurnId: parent.turnId,
      ancestorBotIds: [...parent.ancestorBotIds, parent.botId],
      depth: parent.depth + 1,
      task: request.task,
      expectedResult: request.expectedResult,
      deadline: request.deadline ?? null,
      access: grant,
      billedBotId: bot.id,
      keep: request.keep ?? false,
      anchorMessageId: origin
        ? origin.anchorMessageId
        : parentTurnRequestMessageId(parentThread, parent.turnId),
      retryOfDelegationId: origin?.retryOfDelegationId ?? null,
      trigger: origin?.trigger ?? "bot",
      createdAt,
      updatedAt: createdAt,
      phase: AkeruDelegationPhase.cases.Queued.make({}),
    };

    try {
      await dispatch({
        type: "delegation.create",
        commandId: commandId("create"),
        delegation,
      });
    } catch (cause) {
      await dispatch({
        type: "thread.delete",
        commandId: commandId("cleanup"),
        threadId: childThreadId,
      });
      throw cause;
    }

    const startedAt = now();
    delegation = {
      ...delegation,
      phase: AkeruDelegationPhase.cases.Running.make({
        childThreadId,
        childTurnId: null,
        startedAt,
        progress: null,
      }),
      updatedAt: startedAt,
    };
    const byParent = activeByParent.get(parent.threadId) ?? new Map();

    const forget = () => {
      accessByThread.delete(childThreadId);
      byParent.delete(delegationId);

      if (byParent.size === 0) activeByParent.delete(parent.threadId);
    };

    let childOutcome: Promise<AkeruDelegationChildOutcome> | undefined;

    try {
      await setState(delegation);
      accessByThread.set(childThreadId, grant);
      byParent.set(delegationId, { threadId: childThreadId, turnId: null });
      activeByParent.set(parent.threadId, byParent);
      await deliver(delegation, `Sent bot work to ${bot.name}.`);
      // The waiter must exist before the child turn starts: a child that ends
      // quickly reports its outcome once, and an outcome with no waiter is lost.
      childOutcome = options.awaitChild(childThreadId, request.deadline ?? null);
      childOutcome.catch(() => undefined);
      await dispatch({
        type: "thread.turn.start",
        commandId: commandId("turn"),
        threadId: childThreadId,
        message: {
          messageId: MessageId.make(`delegation-message-${id()}`),
          role: "user",
          text: childInstructions({
            task: request.task,
            expectedResult: request.expectedResult,
            deadline: request.deadline ?? null,
            context: request.context,
          }),
          attachments: [],
        },
        runtimeMode: grant.runtimeMode,
        interactionMode: "default",
        createdAt: now(),
      });
    } catch (cause) {
      // The record exists but nothing watches it, so it fails now and stays retryable.
      forget();

      const latest = (await options.readSnapshot()).delegations.find(
        (entry) => entry.delegationId === delegationId,
      );

      if (latest !== undefined && !TERMINAL_PHASES.has(latest.phase._tag)) {
        await fail(
          latest,
          "internal",
          cause instanceof Error ? cause.message : String(cause),
        ).catch(() => undefined);
      }

      throw cause;
    }

    const watch = async () => {
      // StopAgent or a parent interrupt may have settled the record while the
      // child ran, and a keep-cancel may have stamped the record meanwhile.
      // Completion writes must build on the latest stored record: rebuilding
      // from `delegation` would reset keep/ownership fields and trip the
      // decider's immutability invariant.
      const latestRecord = async () => {
        const latest = (await options.readSnapshot()).delegations.find(
          (entry) => entry.delegationId === delegationId,
        );

        return latest !== undefined && !TERMINAL_PHASES.has(latest.phase._tag) ? latest : undefined;
      };

      try {
        const outcome = await (childOutcome ??
          options.awaitChild(childThreadId, request.deadline ?? null));

        const current = activeByParent.get(parent.threadId)?.get(delegationId);
        const latest = await latestRecord();

        if (!current || latest === undefined) return;
        const record = latest;
        current.turnId = outcome.turnId;

        if (outcome.state !== "completed" || !outcome.summary?.trim()) {
          if (outcome.state === "blocked") {
            const blocked: AkeruDelegationRecord = {
              ...record,
              phase: AkeruDelegationPhase.cases.Blocked.make({
                childThreadId,
                childTurnId: outcome.turnId,
                startedAt,
                reason: outcome.error ?? "The bot is blocked.",
              }),
              updatedAt: now(),
            };

            await setState(blocked);
            await deliver(blocked, outcome.error ?? "The bot is blocked.");

            return;
          }

          await fail(
            {
              ...record,
              phase: AkeruDelegationPhase.cases.Running.make({
                childThreadId,
                childTurnId: outcome.turnId,
                startedAt,
                progress: null,
              }),
            },
            "child_failed",
            outcome.error ?? "The bot did not return a result.",
          );

          return;
        }

        const completedAt = now();

        const result = {
          summary: outcome.summary.trim(),
          childThreadId,
          childTurnId: outcome.turnId,
        };

        const completed: AkeruDelegationRecord = {
          ...record,
          phase: AkeruDelegationPhase.cases.Completed.make({
            childThreadId,
            childTurnId: outcome.turnId,
            startedAt,
            completedAt,
            result,
            acknowledgedAt: null,
          }),
          updatedAt: completedAt,
        };

        await setState(completed);
        // The result is recorded, so a failed usage write must not keep it
        // from reaching the chat.
        await Promise.resolve()
          .then(() =>
            options.recordUsage?.({
              botId: bot.id,
              threadId: childThreadId,
              turnId: outcome.turnId,
              category: "delegated",
              inputTokens: outcome.usage?.inputTokens ?? 0,
              outputTokens: outcome.usage?.outputTokens ?? 0,
            }),
          )
          .catch((cause) => options.onWatchError?.(delegationId, cause));
        await deliver(completed, result.summary);

        if (parentThread.groupId !== null) {
          // The result is already recorded; a group that cannot take the
          // message (deleted, bot removed) must not turn it into a failure.
          await postGroupResult({
            delegationId,
            threadId: parent.threadId,
            botId: bot.id,
            parentBotId: parent.botId,
            task: request.task,
            summary: result.summary,
          }).catch((cause) => options.onWatchError?.(delegationId, cause));
        }
      } catch (cause) {
        const latest = await latestRecord();

        if (latest === undefined) return;

        // The waiter also times out a silent child that has no deadline.
        const timeout =
          isPendingWaiterTimeout(cause) ||
          (request.deadline !== undefined && Date.parse(request.deadline) <= Date.parse(now()));

        if (timeout) await options.interruptChild(childThreadId, null);
        await fail(
          latest,
          timeout ? "timeout" : "internal",
          cause instanceof Error ? cause.message : String(cause),
        );
      } finally {
        forget();
      }
    };

    const watching = watch()
      .catch((cause) => options.onWatchError?.(delegationId, cause))
      .finally(() => watchers.delete(watching));

    watchers.add(watching);

    const handle: AkeruDelegationHandle = {
      delegationId,
      childThreadId,
      childBotId: bot.id,
      name: bot.name,
      phase: "running",
    };

    return handle;
  };

  /**
   * Starts bot work that no live parent turn owns. The record reuses the parent
   * chain the original (or the routine's owner chat) implies, so the decider's
   * depth, cycle, and cap rules apply unchanged. `parentFinished` leaves these
   * records alone; they settle on the child's outcome or a cancel.
   */
  const dispatchDelegation = async (input: AkeruDelegationDispatch) => {
    const snapshot = await options.readSnapshot();

    if (Predicate.isTagged(input, "Retry")) {
      const original = snapshot.delegations.find(
        (delegation) => delegation.delegationId === input.delegationId,
      );

      if (!original) throw new Error("The bot work to retry no longer exists.");

      if (
        !Predicate.isTagged(original.phase, "Failed") &&
        !Predicate.isTagged(original.phase, "Canceled")
      ) {
        throw new Error("Only failed or canceled bot work can be retried.");
      }

      // Two retries accepted before either started must not both start work.
      if (
        snapshot.delegations.some(
          (delegation) => delegation.retryOfDelegationId === original.delegationId,
        )
      ) {
        throw new Error("This bot work was already retried. Use the newer card instead.");
      }

      const deadline =
        original.deadline !== null && Date.parse(original.deadline) > Date.parse(now())
          ? original.deadline
          : undefined;

      return send(
        {
          threadId: original.parentThreadId,
          turnId: original.parentTurnId,
          botId: original.parentBotId,
          parentDelegationId: original.parentDelegationId,
          ancestorBotIds: original.ancestorBotIds.slice(0, -1),
          depth: original.depth - 1,
          access: original.access,
        },
        {
          botId: original.childBotId,
          task: original.task,
          expectedResult: original.expectedResult,
          ...(deadline ? { deadline } : {}),
          allowedToolIds: original.access.allowedToolIds,
          memoryScopes: original.access.memoryScopes,
          mcpServerIds: original.access.enabledMcpServerIds,
          sandbox: original.access.sandbox,
          runtimeMode: original.access.runtimeMode,
          approvalCeiling: original.access.approvalCeiling,
          keep: original.keep,
        },
        {
          trigger: original.trigger,
          retryOfDelegationId: original.delegationId,
          anchorMessageId: original.anchorMessageId,
        },
      );
    }

    const parentThread = snapshot.threads.find((thread) => thread.id === input.parentThreadId);
    const owner = snapshot.bots.find((bot) => bot.id === input.parentBotId);

    if (!parentThread || !owner || owner.archivedAt !== null) {
      throw new Error("The routine's chat or bot is not available.");
    }

    // The owner's default grant, the same one an ordinary turn in this chat gets.
    const access: AkeruDelegationAccessGrant = {
      allowedToolIds: AKERU_TOOL_CATALOG.map((tool) => tool.id),
      memoryScopes: ["private", "bot", "project", "group", "workspace"],
      sandbox: owner.sandbox,
      runtimeMode: input.runtimeMode,
      hasUserComputer: owner.sandbox === "local",
      enabledMcpServerIds: (snapshot.mcpServers ?? [])
        .filter((server) => server.enabled && !owner.disabledMcpServerIds.includes(server.id))
        .map((server) => server.id),
      disabledMcpServerIds: owner.disabledMcpServerIds,
      approvalCeiling: "secrets",
    };

    return send(
      {
        threadId: parentThread.id,
        // Scheduled work belongs to no chat turn, so the chat's current turn neither
        // moves its card nor cancels it when that turn ends.
        turnId: TurnId.make(`scheduled-${id()}`),
        botId: owner.id,
        parentDelegationId: null,
        ancestorBotIds: [],
        depth: 0,
        access,
      },
      { botId: input.childBotId, task: input.task, expectedResult: input.expectedResult },
      {
        trigger: "scheduled",
        retryOfDelegationId: null,
        // The card sits where the chat was when the routine fired.
        anchorMessageId: parentThread.messages.at(-1)?.id ?? null,
      },
    );
  };

  // Settles only the children the ended turn started. Children from earlier,
  // completed turns keep running and report to the chat when they finish.
  const parentFinished = async (input: {
    readonly threadId: ThreadId;
    readonly turnId: TurnId;
    readonly failed: boolean;
    readonly keep?: ReadonlySet<DelegationId>;
  }) => {
    const snapshot = await options.readSnapshot();

    const records = snapshot.delegations.filter(
      (delegation) =>
        delegation.parentThreadId === input.threadId &&
        delegation.parentTurnId === input.turnId &&
        !isDispatchedDelegation(delegation) &&
        !TERMINAL_PHASES.has(delegation.phase._tag),
    );

    const children = activeByParent.get(input.threadId);

    for (const record of records) {
      const keep = record.keep || input.keep?.has(record.delegationId) === true;
      const child = children?.get(record.delegationId);
      const childThreadId = child?.threadId ?? phaseChildThreadId(record);

      // A failed parent turn must record Failed straight from the open phase:
      // canceling first would land the record in the terminal Canceled phase
      // and the follow-up state.set would hit the rejected Canceled -> Failed
      // transition. The cancel command stays for interrupted turns and for
      // marking kept children.
      if (input.failed ? keep : true) {
        await dispatch({
          type: "delegation.cancel",
          commandId: commandId("cancel"),
          delegationId: record.delegationId,
          keep,
          createdAt: now(),
        });
      }

      if (keep) continue;
      children?.delete(record.delegationId);

      if (childThreadId) accessByThread.delete(childThreadId);

      if (input.failed) {
        // A child that finished between the snapshot read and this write must
        // not be sent back to Failed, and a rejected write must not stop the
        // remaining children from being failed and interrupted.
        try {
          const latest = (await options.readSnapshot()).delegations.find(
            (entry) => entry.delegationId === record.delegationId,
          );

          if (latest === undefined || TERMINAL_PHASES.has(latest.phase._tag)) continue;

          // The child stops even when its Failed record cannot be written.
          try {
            await fail(latest, "parent_failed", "The parent turn failed.");
          } finally {
            const latestChildThreadId = phaseChildThreadId(latest) ?? childThreadId;

            if (latestChildThreadId) {
              await options.interruptChild(
                latestChildThreadId,
                child?.turnId ?? phaseChildTurnId(latest),
              );
            }
          }
        } catch (cause) {
          options.onWatchError?.(record.delegationId, cause);
        }
      }
    }

    if (children?.size === 0) activeByParent.delete(input.threadId);
  };

  return {
    create,
    check,
    send,
    dispatchDelegation,
    stop,
    sendToUser,
    parentFinished,
    readSnapshot: options.readSnapshot,
    /** Resolves once every background child watch has recorded its outcome. */
    drain: async () => {
      while (watchers.size > 0) await Promise.all(watchers);
    },
    accessForThread: (threadId: ThreadId) => accessByThread.get(threadId),
  };
}

export type AkeruDelegationRuntime = ReturnType<typeof createAkeruDelegationRuntime>;

export {
  type AkeruDelegationParent,
  type AkeruDelegationChildOutcome,
  type AkeruDelegationRuntimeOptions,
  type AkeruDelegationDispatch,
  type AkeruGroupResultSkipReason,
  type AkeruDelegationHandle,
} from "./delegation/AkeruDelegationPolicy.ts";