Skip to content

Linger is An Open-Source Personal Agent That Runs Fully on Your PC. We aim to break Big Tech’s grip on AI by bringing powerful local AI to everyday computers through efficient model–harness co-design, so everyone can run their own.

13.9 KB
Raw Blame
import { afterEach, describe, expect, it, vi } from "vitest";

import type { ExecutionContextRecord } from "../../../src/agent/executor/context-ref.js";
import { TeamHubExecutionContextStore } from "../../../src/agent/executor/context-store.js";
import {
  TeamHubRuntimeStateError,
  type RuntimeContext,
} from "../../../src/agent/executor/teamhub-runtime-state-client.js";
import { createTeamHubRuntimeStateClientFake } from "../test-support/teamhub-runtime-state-client.js";

// Native Promise timers do not follow Vitest's global fake clock.
vi.mock("node:timers/promises", async (importOriginal) => {
  const timers = await importOriginal<typeof import("node:timers/promises")>();
  const { fakeTimerDelay } =
    await import("../test-support/fake-timer-delay.js");
  return {
    ...timers,
    setTimeout: fakeTimerDelay,
  };
});

afterEach(() => {
  vi.useRealTimers();
  vi.restoreAllMocks();
});

describe("TeamHub Execution Context store", () => {
  it("opens the epoch, reconciles and returns the Contexts with queued work", async () => {
    const calls: string[] = [];
    const client = createTeamHubRuntimeStateClientFake({
      startEpoch: async () => {
        calls.push("epoch");
        return {
          interrupted_run_ids: ["run-interrupted"],
          waiting_context_keys: [runtimeContext("suspended").context_key],
        };
      },
      reconcileContexts: async () => {
        calls.push("reconcile");
        return emptyReconciliation();
      },
    });
    const store = new TeamHubExecutionContextStore({ client });
    try {
      const startup = await store.start();
      expect(calls).toEqual(["epoch", "reconcile"]);
      expect(startup.waitingContextKeys).toEqual([
        runtimeContext("suspended").context_key,
      ]);
      expect(store.epoch).toBe(client.epoch);
      // Startup binds nothing: queued work binds through its wake.
      expect(await store.list()).toEqual([]);
    } finally {
      await store.close();
    }
  });

  it("retries temporary startup failures with a bounded budget", async () => {
    vi.useFakeTimers();
    let attempts = 0;
    const client = createTeamHubRuntimeStateClientFake({
      startEpoch: async () => {
        attempts += 1;
        if (attempts < 3)
          throw new TeamHubRuntimeStateError(503, "unavailable", undefined);
        return { interrupted_run_ids: [], waiting_context_keys: [] };
      },
      reconcileContexts: emptyReconciliation,
    });
    const store = new TeamHubExecutionContextStore({ client });
    try {
      const started = store.start();
      await vi.advanceTimersByTimeAsync(3_000);
      await started;
      expect(attempts).toBe(3);
    } finally {
      await store.close();
    }
  });

  it("does not retry a permanent startup error", async () => {
    const startEpoch = vi.fn(async () => {
      throw new TeamHubRuntimeStateError(400, "invalid", "INVALID_REQUEST");
    });
    const store = new TeamHubExecutionContextStore({
      client: createTeamHubRuntimeStateClientFake({ startEpoch }),
    });
    try {
      await expect(store.start()).rejects.toThrow("invalid");
      expect(startEpoch).toHaveBeenCalledOnce();
    } finally {
      await store.close();
    }
  });

  it("binds a Context for queued work and enumerates unheld ones without binding them", async () => {
    const context = runtimeContext("suspended");
    const getContext = vi.fn(async () => context);
    const store = await startedStore({
      getContext,
      listContexts: async () => [context],
    });
    const published: ExecutionContextRecord[] = [];
    store.subscribe((record) => published.push(record));
    try {
      expect(await store.listByAgent(roomRef.agentId)).toEqual([record()]);
      expect(await store.list()).toEqual([]);
      expect(await store.claimByKey(context.context_key)).toEqual(record());
      expect(await store.list()).toEqual([record()]);
      expect(published).toEqual([record()]);
      // A held record answers a work hint without another read.
      expect(await store.claimByKey(context.context_key)).toEqual(record());
      expect(getContext).toHaveBeenCalledOnce();
    } finally {
      await store.close();
    }
  });

  it("binds an unheld Context on a change hint only when its Room Meta Context never ran", async () => {
    let context = runtimeContext("suspended");
    const store = await startedStore({ getContext: async () => context });
    try {
      expect(store.isUnusedContext(roomRef)).toBe(false);
      expect(
        await store.claimByKey(context.context_key, true, "changed"),
      ).toEqual(record());
      expect(store.isUnusedContext(roomRef)).toBe(true);
      await store.releaseIfIdle(roomRef);
      context = {
        ...context,
        state_revision: "2",
        next_input_sequence: "4",
      };
      expect(
        await store.claimByKey(context.context_key, true, "changed"),
      ).toBeNull();
      expect(await store.list()).toEqual([]);
    } finally {
      await store.close();
    }
  });

  it("refreshes a held record only for a revision it has not seen", async () => {
    let context = runtimeContext("active");
    const getContext = vi.fn(async () => context);
    const store = await startedStore({ getContext });
    try {
      await store.claimByKey(context.context_key);
      await store.claimByKey(context.context_key, true, "changed", "1");
      expect(getContext).toHaveBeenCalledOnce();
      context = {
        ...context,
        state_revision: "2",
        target_residency: "suspended",
      };
      expect(
        (await store.claimByKey(context.context_key, true, "changed", "2"))
          ?.targetResidency,
      ).toBe("suspended");
      expect(getContext).toHaveBeenCalledTimes(2);
    } finally {
      await store.close();
    }
  });

  it("releases a suspended Context locally and notifies its unbind", async () => {
    let context = runtimeContext("active");
    const store = await startedStore({ getContext: async () => context });
    const unbound: unknown[] = [];
    store.subscribeUnbind((ref) => unbound.push(ref));
    try {
      await store.claimByKey(context.context_key);
      expect(await store.releaseIfIdle(roomRef)).toBe(false);
      context = {
        ...context,
        state_revision: "2",
        target_residency: "suspended",
      };
      await store.claimByKey(context.context_key, true);
      expect(await store.releaseIfIdle(roomRef)).toBe(true);
      expect(unbound).toEqual([roomRef]);
      expect(await store.list()).toEqual([]);
    } finally {
      await store.close();
    }
  });

  it("unbinds a held Context TeamHub rebinds to a new Room membership", async () => {
    let context: RuntimeContext = {
      ...runtimeContext("active"),
      membership_epoch_id: "membership-1",
    };
    const store = await startedStore({ getContext: async () => context });
    const events: string[] = [];
    store.subscribeUnbind(() => events.push("unbind"));
    store.subscribe(() => events.push("publish"));
    try {
      await store.claimByKey(context.context_key);
      context = {
        ...context,
        state_revision: "3",
        membership_epoch_id: "membership-2",
      };
      await store.claimByKey(context.context_key, true);
      // What was prepared stops before the rebound record applies.
      expect(events).toEqual(["publish", "unbind", "publish"]);
      expect(await store.list()).toEqual([
        { ...record(), targetResidency: "active" },
      ]);
    } finally {
      await store.close();
    }
  });

  it("publishes a terminal Context once and stops holding it", async () => {
    let context = runtimeContext("active");
    const store = await startedStore({ getContext: async () => context });
    const published: ExecutionContextRecord[] = [];
    store.subscribe((value) => published.push(value));
    try {
      await store.claimByKey(context.context_key);
      context = {
        ...context,
        state_revision: "2",
        target_residency: "suspended",
        terminal_reason: "context_deleted",
        terminated_at: "2026-11-03T00:00:00.000Z",
      };
      expect(await store.claimByKey(context.context_key, true)).toBeNull();
      expect(await store.claimByKey(context.context_key, true)).toBeNull();
      expect(published.map((value) => value.terminalReason)).toEqual([
        undefined,
        "context_deleted",
      ]);
      expect(await store.list()).toEqual([]);
    } finally {
      await store.close();
    }
  });

  it("re-reads every held Context after hints may have been lost", async () => {
    const contexts = new Map(
      ["room-a", "room-b"].map((roomId) => {
        const context = runtimeContext("active", roomId);
        return [context.context_key, context] as const;
      }),
    );
    const getContext = vi.fn(async (key: string) => contexts.get(key)!);
    const store = await startedStore({ getContext });
    try {
      for (const key of contexts.keys()) await store.claimByKey(key);
      getContext.mockClear();
      await store.refreshAvailableContexts();
      expect(getContext).toHaveBeenCalledTimes(2);
    } finally {
      await store.close();
    }
  });

  it("applies an acceptance's committed state and follows its own Run claim revision", async () => {
    const context = runtimeContext("suspended");
    const getContext = vi.fn(async () => context);
    const store = await startedStore({ getContext });
    try {
      await store.claimByKey(context.context_key);
      store.observeCommittedState(roomRef, {
        state_revision: "4",
        target_residency: "active",
        next_input_sequence: "9",
      });
      expect(store.cached(roomRef)?.targetResidency).toBe("active");
      const advanced = store.trackOwnRevisionAdvance(roomRef);
      advanced();
      // The claim's own context.changed hint at revision 5 reads nothing.
      await store.claimByKey(context.context_key, true, "changed", "5");
      expect(getContext).toHaveBeenCalledOnce();
    } finally {
      await store.close();
    }
  });

  it("carries a trusted shared Task scope and rejects one for another Context", async () => {
    const scope = {
      version: 1 as const,
      tenant_id: "tenant-acme",
      agent_id: "agent-reviewer",
      origin_room_id: "room-review",
      role: "meta" as const,
    };
    let current: RuntimeContext = {
      ...runtimeContext("active"),
      shared_task_scope: scope,
    };
    const store = await startedStore({ getContext: async () => current });
    try {
      expect(
        (await store.claimByKey(current.context_key))?.sharedTaskScope,
      ).toEqual({
        version: 1,
        tenantId: "tenant-acme",
        agentId: "agent-reviewer",
        originRoomId: "room-review",
        role: "meta",
      });
      for (const forged of [
        { ...scope, origin_room_id: "room-other" },
        { ...scope, agent_id: "agent-other" },
        { ...scope, tenant_id: "tenant-other" },
        { ...scope, role: "alter_ego" as const, task_id: "task-1" },
      ]) {
        current = {
          ...current,
          state_revision: String(Number(current.state_revision) + 1),
          shared_task_scope: forged,
        };
        await expect(
          store.claimByKey(current.context_key, true),
        ).rejects.toThrow("Shared Task scope does not match its Context");
      }
    } finally {
      await store.close();
    }
  });

  it("holds an ensured Context and keeps its existing suspended residency", async () => {
    const existing = runtimeContext("suspended");
    const ensureContext = vi.fn(async () => ({
      created: false,
      context: existing,
    }));
    const store = await startedStore({ ensureContext });
    try {
      const ensured = await store.ensure(roomRef);
      expect(ensured).toEqual({ created: false, record: record() });
      expect(ensureContext).toHaveBeenCalledWith({
        ref: {
          kind: "meta",
          agent_id: "agent-reviewer",
          room_id: "room-review",
        },
        target_residency: "active",
      });
      expect(await store.list()).toEqual([record()]);
    } finally {
      await store.close();
    }
  });

  it("holds a Context whose residency it activates", async () => {
    let context = runtimeContext("suspended");
    const setContextResidency = vi.fn(async () => {
      context = {
        ...context,
        state_revision: "2",
        target_residency: "active",
      };
      return context;
    });
    const store = await startedStore({
      getContext: async () => context,
      setContextResidency,
    });
    try {
      expect(await store.setTargetResidency(roomRef, "active")).toBe("updated");
      expect(setContextResidency).toHaveBeenCalledWith({
        context_key: context.context_key,
        expected_revision: "1",
        target_residency: "active",
      });
      expect(await store.list()).toEqual([
        { ...record(), targetResidency: "active" },
      ]);
    } finally {
      await store.close();
    }
  });
});

const startedStore = async (
  overrides: Parameters<typeof createTeamHubRuntimeStateClientFake>[0],
): Promise<TeamHubExecutionContextStore> => {
  const store = new TeamHubExecutionContextStore({
    client: createTeamHubRuntimeStateClientFake({
      reconcileContexts: emptyReconciliation,
      ...overrides,
    }),
  });
  await store.start();
  return store;
};

const emptyReconciliation = async () => ({
  examined_count: 0,
  existing_count: 0,
  created_count: 0,
  created_context_keys: [],
});

const roomRef = {
  kind: "meta" as const,
  agentId: "agent-reviewer",
  roomId: "room-review",
};

const record = (): ExecutionContextRecord => ({
  ref: roomRef,
  roomKind: "collaboration",
  targetResidency: "suspended",
});

const runtimeContext = (
  targetResidency: RuntimeContext["target_residency"],
  roomId = "room-review",
): RuntimeContext => ({
  context_key: `["meta","agent-reviewer","room","${roomId}"]`,
  ref: { kind: "meta", agent_id: "agent-reviewer", room_id: roomId },
  tenant_id: "tenant-acme",
  agent_actor_id: "actor-reviewer",
  room_kind: "collaboration",
  target_residency: targetResidency,
  state_revision: "1",
  next_input_sequence: "0",
});