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.

16.9 KB
Raw Blame
import * as Predicate from "effect/Predicate";
import { describe } from "vite-plus/test";
import {
  DelegationId,
  McpServerId,
  MessageId,
  ThreadId,
  TurnId,
  AkeruDelegationRecord,
  AkeruToolInputSchemas,
  type OrchestrationCommand,
} from "@akeru/contracts";
import * as Schema from "effect/Schema";
import { expect, it } from "vite-plus/test";
import {
  createAkeruDelegationRuntime,
  type AkeruDelegationChildOutcome,
} from "./AkeruDelegationRuntime.ts";
import { intersectDelegationAccess } from "./AkeruToolRuntime.ts";
import {
  CHILD_BOT_ID,
  CHILD_TURN_ID,
  NOW,
  PARENT_BOT_ID,
  PARENT_THREAD_ID,
  PARENT_TURN_ID,
  access,
  delegation,
  harness,
  parent,
  request,
  snapshot,
  thread,
} from "./testUtils/delegationHarness.ts";

const encodeDelegationRecord = Schema.encodeUnknownSync(AkeruDelegationRecord);

const decodeDelegationRecord = Schema.decodeUnknownSync(AkeruDelegationRecord);

const decodeSendToAgent = Schema.decodeUnknownSync(AkeruToolInputSchemas.SendToAgent);

describe("delegation access", () => {
  it("intersects MCP disables, user-computer capability, tools, and memory scopes", () => {
    const grant = intersectDelegationAccess({
      parent: access({
        allowedToolIds: ["Read", "ExternalRead", "SendToAgent"],
        memoryScopes: ["private", "project"],
        hasUserComputer: false,
        enabledMcpServerIds: [McpServerId.make("web"), McpServerId.make("email")],
        disabledMcpServerIds: [McpServerId.make("parent-disabled")],
      }),
      child: access({
        allowedToolIds: ["Read", "ExternalRead"],
        memoryScopes: ["project", "group"],
        hasUserComputer: true,
        enabledMcpServerIds: [McpServerId.make("web")],
        disabledMcpServerIds: [McpServerId.make("child-disabled")],
      }),
      requested: request({
        allowedToolIds: ["Read", "ExternalRead"],
        memoryScopes: ["project"],
        mcpServerIds: [McpServerId.make("web"), McpServerId.make("email")],
      }) as never,
    });

    expect(grant).toMatchObject({
      allowedToolIds: ["Read", "ExternalRead"],
      memoryScopes: ["project"],
      hasUserComputer: false,
      enabledMcpServerIds: ["web"],
      disabledMcpServerIds: ["parent-disabled", "child-disabled"],
    });
  });
});

describe("AkeruDelegationRuntime", () => {
  it("sends a bot message through its active thread", async () => {
    const test = harness(
      snapshot({
        threads: [
          thread(PARENT_THREAD_ID, PARENT_BOT_ID, {
            latestTurn: {
              turnId: PARENT_TURN_ID,
              state: "running",
              requestedAt: NOW,
              startedAt: NOW,
              completedAt: null,
              assistantMessageId: null,
            },
          }),
        ],
      }),
    );

    await expect(
      test.runtime.sendToUser(parent(), { message: "The export is ready." }),
    ).resolves.toMatchObject({
      toolId: "SendToUser",
      phase: "success",
      threadId: PARENT_THREAD_ID,
      botId: PARENT_BOT_ID,
    });
    expect(test.commands.slice(-2)).toMatchObject([
      {
        type: "thread.message.assistant.delta",
        threadId: PARENT_THREAD_ID,
        turnId: PARENT_TURN_ID,
        delta: "The export is ready.",
      },
      {
        type: "thread.message.assistant.complete",
        threadId: PARENT_THREAD_ID,
        turnId: PARENT_TURN_ID,
      },
    ]);
  });

  it("persists a completed record that decodes with the child turn", async () => {
    const test = harness();
    await test.runtime.send(parent(), request() as never);
    await test.runtime.drain();

    const persisted = test.state.delegations.at(-1);
    const encoded = encodeDelegationRecord(persisted);
    const decoded = decodeDelegationRecord(encoded);
    expect(decoded.phase).toMatchObject({
      _tag: "Completed",
      childTurnId: CHILD_TURN_ID,
      result: { summary: "The delegated answer.", childTurnId: CHILD_TURN_ID },
    });
  });

  it("anchors the record on the parent turn's user message", async () => {
    const latestTurn = (turnId: TurnId) => ({
      turnId,
      state: "running" as const,
      requestedAt: NOW,
      startedAt: NOW,
      completedAt: null,
      assistantMessageId: null,
      requestMessageId: MessageId.make("message-user"),
    });

    const anchored = harness(
      snapshot({
        threads: [
          thread(PARENT_THREAD_ID, PARENT_BOT_ID, { latestTurn: latestTurn(PARENT_TURN_ID) }),
        ],
      }),
    );

    await anchored.runtime.send(parent(), request() as never);
    expect(anchored.state.delegations.at(-1)).toMatchObject({
      anchorMessageId: "message-user",
      retryOfDelegationId: null,
      trigger: "bot",
    });

    const otherTurn = harness(
      snapshot({
        threads: [
          thread(PARENT_THREAD_ID, PARENT_BOT_ID, {
            latestTurn: latestTurn(TurnId.make("turn-other")),
          }),
        ],
      }),
    );

    await otherTurn.runtime.send(parent(), request() as never);
    expect(otherTurn.state.delegations.at(-1)?.anchorMessageId).toBeNull();
  });

  it("keeps work a bot sent with keep running after its turn ends", async () => {
    const test = harness();
    const child = Promise.withResolvers<AkeruDelegationChildOutcome>();

    const runtime = createAkeruDelegationRuntime({
      readSnapshot: async () => test.state,
      dispatch: test.dispatch,
      awaitChild: () => child.promise,
      interruptChild: async () => undefined,
      now: () => NOW,
      id: (() => {
        let next = 100;

        return () => String(++next);
      })(),
    });

    const input = decodeSendToAgent(request({ keep: true }));

    const handle = await runtime.send(parent(), input);
    expect(test.state.delegations.at(-1)).toMatchObject({ keep: true });

    await runtime.parentFinished({
      threadId: PARENT_THREAD_ID,
      turnId: PARENT_TURN_ID,
      failed: false,
    });
    expect(test.state.delegations.at(-1)?.phase._tag).toBe("Running");

    child.resolve({ state: "completed", turnId: CHILD_TURN_ID, summary: "Done later." });
    await runtime.drain();
    expect(test.state.delegations.at(-1)).toMatchObject({
      delegationId: handle.delegationId,
      phase: { _tag: "Completed", result: { summary: "Done later." } },
    });
  });

  it("retries failed work as a new record and never changes the original", async () => {
    const original = delegation(DelegationId.make("delegation-original"), {
      anchorMessageId: MessageId.make("message-user"),
      access: access({ memoryScopes: ["project"], allowedToolIds: ["Read"] }),
      phase: {
        _tag: "Failed",
        childThreadId: ThreadId.make("child-old"),
        childTurnId: CHILD_TURN_ID,
        startedAt: NOW,
        completedAt: NOW,
        failure: { failureCode: "child_failed", message: "The child failed." },
        acknowledgedAt: null,
      },
    });

    const test = harness(snapshot({ delegations: [original] }));

    const handle = await test.runtime.dispatchDelegation({
      _tag: "Retry",
      delegationId: original.delegationId,
    });

    await test.runtime.drain();

    expect(test.state.delegations[0]).toEqual(original);
    expect(
      test.commands.filter(
        (command) =>
          (command.type === "delegation.state.set" || command.type === "delegation.create") &&
          command.delegation.delegationId === original.delegationId,
      ),
    ).toEqual([]);

    const retried = test.state.delegations.find(
      (entry) => entry.delegationId === handle.delegationId,
    );

    expect(retried).toMatchObject({
      retryOfDelegationId: original.delegationId,
      anchorMessageId: "message-user",
      trigger: "bot",
      parentBotId: PARENT_BOT_ID,
      childBotId: CHILD_BOT_ID,
      parentTurnId: PARENT_TURN_ID,
      ancestorBotIds: [PARENT_BOT_ID],
      depth: 1,
      task: original.task,
      access: original.access,
      phase: { _tag: "Completed" },
    });

    await expect(
      test.runtime.dispatchDelegation({ _tag: "Retry", delegationId: handle.delegationId }),
    ).rejects.toThrow("Only failed or canceled bot work can be retried.");
    await expect(
      test.runtime.dispatchDelegation({ _tag: "Retry", delegationId: original.delegationId }),
    ).rejects.toThrow("already retried");
  });

  it("fails new bot work whose child turn cannot start, so it stays retryable", async () => {
    const base = harness();

    const test = harness(snapshot(), undefined, {
      dispatch: async (command) => {
        if (command.type === "thread.turn.start") throw new Error("provider unavailable");
        await base.dispatch(command);
      },
      readSnapshot: async () => base.state as never,
    });

    await expect(test.runtime.send(parent(), request() as never)).rejects.toThrow(
      "provider unavailable",
    );
    expect(base.state.delegations.at(-1)?.phase).toMatchObject({
      _tag: "Failed",
      failure: { failureCode: "internal", message: "provider unavailable" },
    });
  });

  it("starts scheduled work from the owner chat that its turn end leaves running", async () => {
    const test = harness(
      snapshot({
        threads: [
          thread(PARENT_THREAD_ID, PARENT_BOT_ID, {
            latestTurn: {
              turnId: PARENT_TURN_ID,
              state: "running",
              requestedAt: NOW,
              startedAt: NOW,
              completedAt: null,
              assistantMessageId: null,
              requestMessageId: MessageId.make("message-user"),
            },
            messages: [
              {
                id: MessageId.make("message-last"),
                role: "assistant",
                text: "Earlier reply.",
                turnId: PARENT_TURN_ID,
                streaming: false,
                createdAt: NOW,
                updatedAt: NOW,
              },
            ],
          }),
        ],
      }),
    );

    const child = Promise.withResolvers<AkeruDelegationChildOutcome>();

    const runtime = createAkeruDelegationRuntime({
      readSnapshot: async () => test.state,
      dispatch: test.dispatch,
      awaitChild: () => child.promise,
      interruptChild: async () => undefined,
      now: () => NOW,
      id: (() => {
        let next = 200;

        return () => String(++next);
      })(),
    });

    await runtime.dispatchDelegation({
      _tag: "Scheduled",
      parentThreadId: PARENT_THREAD_ID,
      parentBotId: PARENT_BOT_ID,
      childBotId: CHILD_BOT_ID,
      task: "Summarize the inbox.",
      expectedResult: "Three bullet points.",
      runtimeMode: "approval-required",
    });
    expect(test.state.delegations.at(-1)).toMatchObject({
      trigger: "scheduled",
      retryOfDelegationId: null,
      anchorMessageId: "message-last",
      parentBotId: PARENT_BOT_ID,
      parentDelegationId: null,
      depth: 1,
      access: { memoryScopes: [], runtimeMode: "approval-required" },
    });
    // The card keeps its own turn, so the running chat turn cannot move it.
    expect(test.state.delegations.at(-1)?.parentTurnId).not.toBe(PARENT_TURN_ID);

    await runtime.parentFinished({
      threadId: PARENT_THREAD_ID,
      turnId: PARENT_TURN_ID,
      failed: true,
    });
    expect(test.state.delegations.at(-1)?.phase._tag).toBe("Running");

    child.resolve({ state: "completed", turnId: CHILD_TURN_ID, summary: "Inbox summary." });
    await runtime.drain();
    expect(test.state.delegations.at(-1)?.phase._tag).toBe("Completed");
  });

  it("deletes the child thread when authoritative delegation admission fails", async () => {
    const commands: OrchestrationCommand[] = [];

    const runtime = createAkeruDelegationRuntime({
      readSnapshot: async () => snapshot(),
      dispatch: async (command) => {
        commands.push(command);

        if (command.type === "delegation.create") throw new Error("Delegation limit reached.");
      },
      awaitChild: async () => ({ state: "completed", turnId: CHILD_TURN_ID, summary: "Done." }),
      interruptChild: async () => undefined,
      now: () => NOW,
      id: () => String(commands.length + 1),
    });

    await expect(runtime.send(parent(), request() as never)).rejects.toThrow(
      "Delegation limit reached.",
    );
    expect(commands.map((command) => command.type)).toEqual([
      "thread.create",
      "delegation.create",
      "thread.delete",
    ]);
  });

  it("grants only the memory scopes the parent holds and the request names", async () => {
    const scoped = harness();
    await scoped.runtime.send(parent(), request({ memoryScopes: ["project"] }) as never);
    expect(scoped.state.delegations.at(-1)?.access.memoryScopes).toEqual(["project"]);

    const omitted = harness();
    await omitted.runtime.send(parent(), request() as never);
    expect(omitted.state.delegations.at(-1)?.access.memoryScopes).toEqual([]);

    await expect(
      harness().runtime.send(parent(), request({ memoryScopes: ["group"] }) as never),
    ).rejects.toThrow("parent turn grant");
  });

  it("preserves blocked state and persists child failure", async () => {
    const blocked = harness(snapshot(), {
      state: "blocked",
      turnId: CHILD_TURN_ID,
      error: "Access denied.",
    });

    await blocked.runtime.send(parent(), request() as never);
    await blocked.runtime.drain();
    expect(blocked.state.delegations.at(-1)).toMatchObject({
      phase: { _tag: "Blocked", reason: "Access denied." },
      billedBotId: CHILD_BOT_ID,
    });

    const failed = harness(snapshot(), {
      state: "failed",
      turnId: CHILD_TURN_ID,
      error: "Provider failed.",
    });

    await failed.runtime.send(parent(), request() as never);
    await failed.runtime.drain();
    expect(failed.state.delegations.at(-1)).toMatchObject({
      phase: { _tag: "Failed", failure: { failureCode: "child_failed" }, acknowledgedAt: null },
      billedBotId: CHILD_BOT_ID,
    });
  });

  it("stores one readable line when the child fails with a stack", async () => {
    const failed = harness(snapshot(), {
      state: "failed",
      turnId: CHILD_TURN_ID,
      error: [
        "ProviderValidationError: Provider instance 'codex' is disabled in Akeru Bot settings.",
        "    at disabledProviderError (file:///srv/akeru/apps/server/src/provider/Layers/AgentController.ts:584:10)",
        "    at ensureSessionForThread (file:///srv/akeru/apps/server/src/orchestration/Layers/ProviderCommandReactor.ts:1282:28)",
      ].join("\n"),
    });

    await failed.runtime.send(parent(), request() as never);
    await failed.runtime.drain();
    const message = "Provider instance 'codex' is disabled in Akeru Bot settings.";
    expect(failed.state.delegations.at(-1)).toMatchObject({
      phase: { _tag: "Failed", failure: { failureCode: "child_failed", message } },
    });

    const delivered = failed.commands.flatMap((command) =>
      command.type === "thread.activity.append" && command.activity.kind === "delegation.failed"
        ? [command.activity.summary]
        : [],
    );

    expect(delivered).toEqual([message]);
  });

  it("runs a second delegation to a busy child bot in its own child chat", async () => {
    const test = harness();
    const children: Array<PromiseWithResolvers<AkeruDelegationChildOutcome>> = [];

    const runtime = createAkeruDelegationRuntime({
      readSnapshot: async () => test.state,
      dispatch: test.dispatch,
      awaitChild: () => {
        const child = Promise.withResolvers<AkeruDelegationChildOutcome>();
        children.push(child);

        return child.promise;
      },
      interruptChild: async () => undefined,
      now: () => NOW,
      id: (() => {
        let value = 0;

        return () => String(++value);
      })(),
    });

    const first = await runtime.send(parent(), request() as never);
    const second = await runtime.send(parent(), request({ task: "A follow-up." }) as never);
    expect(second.delegationId).not.toBe(first.delegationId);
    expect(second.childThreadId).not.toBe(first.childThreadId);
    expect(test.state.delegations.map((entry) => entry.phase._tag)).toEqual(["Running", "Running"]);

    children[1]!.resolve({ state: "completed", turnId: CHILD_TURN_ID, summary: "Second." });
    children[0]!.resolve({ state: "completed", turnId: CHILD_TURN_ID, summary: "First." });
    await runtime.drain();
    expect(
      test.state.delegations.map((entry) =>
        Predicate.isTagged(entry.phase, "Completed") ? entry.phase.result.summary : null,
      ),
    ).toEqual(["First.", "Second."]);
  });

  it("keeps children from an earlier completed turn when a later turn is interrupted", async () => {
    const childThreadId = ThreadId.make("earlier-child");

    const earlier = delegation(DelegationId.make("earlier"), {
      parentTurnId: TurnId.make("turn-earlier"),
      phase: { _tag: "Running", childThreadId, childTurnId: null, startedAt: NOW, progress: null },
    });

    const test = harness(snapshot({ delegations: [earlier] }));

    await test.runtime.parentFinished({
      threadId: PARENT_THREAD_ID,
      turnId: PARENT_TURN_ID,
      failed: false,
    });

    expect(test.state.delegations[0]?.phase._tag).toBe("Running");
    expect(test.commands).toEqual([]);
  });
});