Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

14.9 KB
Raw Blame
import { EventType } from '../../src/agent-session/schemas/events';
import { CancellationReason } from '../../src/agent-session/schemas/turn';
import { Sessions } from '../../src/agent-session/Sessions';
import { InMemorySessionStore } from '../../src/agent-session/store/InMemorySessionStore';
import { TurnNotFoundError } from '../../src/agent-session/store/SessionStoreErrors';
import { TurnHandle } from '../../src/agent-session/TurnHandle';
import { makeAgentSpec, makeTestResolver, mintTestTurnId, TEST_ACTIVE_EXECUTOR_ID } from './testHelpers';

describe('Sessions / SessionHandle / TurnHandle (storage + createTurn)', () => {
  const tenant = 'tenant-1';

  it('create/get persists metadata', async () => {
    const store = new InMemorySessionStore();
    const sessions = new Sessions({ sessionStore: store });
    const created = await sessions.create({
      tenant_id: tenant,
      session_id: 's-meta',
      created_by_subject: { subject_id: 'user-1', subject_type: 'user', subject_display_name: 'user-1' },
      agent: { type: 'inline', spec: makeAgentSpec({ instructions: 'meta' }) },
      metadata: { env: 'test' },
      external_id: null,
    });
    expect(created.metadata).toEqual({ env: 'test' });

    await store.updateSession({
      tenant_id: tenant,
      session_id: 's-meta',
      agent: undefined,
      title: undefined,
      metadata: { env: 'prod' },
      shared: undefined,
    });
    const afterReplace = await sessions.get({ tenant_id: tenant, session_id: 's-meta' });
    expect(afterReplace?.metadata).toEqual({ env: 'prod' });

    await store.updateSession({
      tenant_id: tenant,
      session_id: 's-meta',
      agent: undefined,
      title: 't',
      metadata: undefined,
      shared: undefined,
    });
    const afterOmit = await sessions.get({ tenant_id: tenant, session_id: 's-meta' });
    expect(afterOmit?.record.title).toBe('t');
    expect(afterOmit?.metadata).toEqual({ env: 'prod' });
  });

  it('create/get persists an inline value-agent session', async () => {
    const store = new InMemorySessionStore<{ tag: string }>();
    const sessions = new Sessions<{ tag: string }>({ sessionStore: store });
    const created = await sessions.create({
      tenant_id: tenant,
      session_id: 's1',
      created_by_subject: { subject_id: 'user-1', subject_type: 'user', subject_display_name: 'user-1' },
      agent: { type: 'inline', spec: makeAgentSpec({ instructions: 'hydrate-me' }) },
      custom: { tag: 'a' },
      external_id: null,
    });
    expect(created.agent).toEqual({
      type: 'inline',
      spec: expect.objectContaining({ instructions: 'hydrate-me' }),
    });
    expect(created.custom).toEqual({ tag: 'a' });
    expect(created.metadata).toEqual({});

    const loaded = await sessions.get({ tenant_id: tenant, session_id: 's1' });
    expect(loaded?.agent).toEqual({
      type: 'inline',
      spec: expect.objectContaining({ instructions: 'hydrate-me' }),
    });
    expect(loaded?.session_id).toBe('s1');
  });

  it('getOrCreateByExternalId creates once and returns the existing row on retry', async () => {
    const store = new InMemorySessionStore();
    const sessions = new Sessions({ sessionStore: store });
    const agent = { type: 'inline' as const, spec: makeAgentSpec({ instructions: 'first' }) };

    const first = await sessions.getOrCreateByExternalId({
      tenant_id: tenant,
      created_by_subject: { subject_id: 'user-1', subject_type: 'user', subject_display_name: 'user-1' },
      agent,
      external_id: 'run-1',
    });
    expect(first.created).toBe(true);
    expect(first.session.record.external_id).toBe('run-1');

    const again = await sessions.getOrCreateByExternalId({
      tenant_id: tenant,
      created_by_subject: { subject_id: 'other', subject_type: 'user', subject_display_name: 'other' },
      agent: { type: 'inline', spec: makeAgentSpec({ instructions: 'ignored' }) },
      external_id: 'run-1',
    });
    expect(again.created).toBe(false);
    expect(again.session.session_id).toBe(first.session.session_id);
    expect(again.session.record.created_by_subject.subject_id).toBe('user-1');
    expect(again.session.agent).toEqual({
      type: 'inline',
      spec: expect.objectContaining({ instructions: 'first' }),
    });
  });

  it('getOrCreateByExternalId returns the winner when create loses the unique race', async () => {
    const store = new InMemorySessionStore();
    const sessions = new Sessions({ sessionStore: store });
    const agent = { type: 'inline' as const, spec: makeAgentSpec() };

    await sessions.create({
      tenant_id: tenant,
      session_id: 'winner',
      created_by_subject: { subject_id: 'user-1', subject_type: 'user', subject_display_name: 'user-1' },
      agent,
      external_id: 'run-1',
    });

    const getByExternalId = jest.spyOn(sessions, 'getByExternalId');
    getByExternalId.mockResolvedValueOnce(undefined);

    const { session, created } = await sessions.getOrCreateByExternalId({
      tenant_id: tenant,
      created_by_subject: { subject_id: 'user-2', subject_type: 'user', subject_display_name: 'user-2' },
      agent,
      external_id: 'run-1',
    });
    expect(created).toBe(false);
    expect(session.session_id).toBe('winner');
  });

  it('run() happy path commits a running turn without executing', async () => {
    const store = new InMemorySessionStore();
    const sessions = new Sessions({ sessionStore: store });
    const session = await sessions.create({
      tenant_id: tenant,
      session_id: 's1',
      created_by_subject: { subject_id: 'user-1', subject_type: 'user', subject_display_name: 'user-1' },
      agent: { type: 'inline', spec: makeAgentSpec() },
      external_id: null,
    });
    const turn = await session.createTurn({
      turn_id: mintTestTurnId(),
      active_executor_id: TEST_ACTIVE_EXECUTOR_ID,
      input: [{ type: EventType.USER_MESSAGE, content: 'hello' }],
      previous_turn_id: 'none',
      signal: new AbortController().signal,
      resolver: makeTestResolver(),
      update_session_title_if_not_exist: 'From first message',
    });
    expect(turn.state.status).toBe('running');
    expect(turn.input).toHaveLength(1);

    const stored = await store.getTurn({
      session_id: 's1',
      turn_id: turn.id,
    });
    expect(stored?.state.status).toBe('running');
    const sessionRecord = await store.getSession({ tenant_id: tenant, session_id: 's1' });
    expect(sessionRecord?.title).toBe('From first message');
    expect(sessionRecord?.last_turn_id).toBe(turn.id);
  });

  it('loads turn handles without reading the session', async () => {
    const store = new InMemorySessionStore();
    const sessions = new Sessions({ sessionStore: store });
    const session = await sessions.create({
      tenant_id: tenant,
      session_id: 's1',
      created_by_subject: { subject_id: 'user-1', subject_type: 'user', subject_display_name: 'user-1' },
      agent: { type: 'inline', spec: makeAgentSpec() },
      external_id: null,
    });
    const created = await session.createTurn({
      turn_id: mintTestTurnId(),
      active_executor_id: TEST_ACTIVE_EXECUTOR_ID,
      previous_turn_id: 'none',
      signal: new AbortController().signal,
      resolver: makeTestResolver(),
    });
    const getSession = jest.spyOn(store, 'getSession');

    const direct = await TurnHandle.get({
      store,
      session_id: 's1',
      turn_id: created.id,
    });
    const throughSession = await session.getTurn(created.id);
    const missingDirect = await TurnHandle.get({
      store,
      session_id: 's1',
      turn_id: 'missing-turn',
    });
    const missingThroughSession = await session.getTurn('missing-turn');

    expect(direct?.id).toBe(created.id);
    expect(throughSession?.id).toBe(created.id);
    expect(missingDirect).toBeUndefined();
    expect(missingThroughSession).toBeUndefined();
    expect(getSession).not.toHaveBeenCalled();
  });

  it('freezeTurn cancels a running turn with the given reason', async () => {
    const store = new InMemorySessionStore();
    const sessions = new Sessions({ sessionStore: store });
    const session = await sessions.create({
      tenant_id: tenant,
      session_id: 's1',
      created_by_subject: { subject_id: 'user-1', subject_type: 'user', subject_display_name: 'user-1' },
      agent: { type: 'inline', spec: makeAgentSpec() },
      external_id: null,
    });
    const turn = await session.createTurn({
      turn_id: mintTestTurnId(),
      active_executor_id: TEST_ACTIVE_EXECUTOR_ID,
      previous_turn_id: 'none',
      signal: new AbortController().signal,
      resolver: makeTestResolver(),
    });
    const frozen = await session.freezeTurn({
      turn_id: turn.id,
      reason: CancellationReason.ClientCancelled,
    });
    expect(frozen.state).toMatchObject({
      status: 'cancelled',
      reason: CancellationReason.ClientCancelled,
    });
    await expect(
      session.freezeTurn({ turn_id: 'missing-turn', reason: CancellationReason.ClientCancelled }),
    ).rejects.toBeInstanceOf(TurnNotFoundError);
  });

  it('custom value vs merge-fn', async () => {
    const store = new InMemorySessionStore<{ tag: string }, { n: number }>();
    const sessions = new Sessions({ sessionStore: store });
    const session = await sessions.create({
      tenant_id: tenant,
      session_id: 's1',
      created_by_subject: { subject_id: 'user-1', subject_type: 'user', subject_display_name: 'user-1' },
      agent: { type: 'inline', spec: makeAgentSpec() },
      external_id: null,
    });
    const t1 = await session.createTurn({
      turn_id: mintTestTurnId(),
      active_executor_id: TEST_ACTIVE_EXECUTOR_ID,
      input: [{ type: EventType.USER_MESSAGE, content: 'one' }],
      previous_turn_id: 'none',
      signal: new AbortController().signal,
      resolver: makeTestResolver<{ n: number }>(),
      custom: { n: 1 },
    });
    expect(t1.custom).toEqual({ n: 1 });

    const t2 = await session.createTurn({
      turn_id: mintTestTurnId(),
      active_executor_id: TEST_ACTIVE_EXECUTOR_ID,
      input: [{ type: EventType.USER_MESSAGE, content: 'two' }],
      previous_turn_id: 'auto',
      signal: new AbortController().signal,
      resolver: makeTestResolver<{ n: number }>(),
      custom: prev => ({ n: (prev?.n ?? 0) + 10 }),
    });
    expect(t2.custom).toEqual({ n: 11 });
  });

  it('previous_turn_id none creates a new root on a non-empty session', async () => {
    const store = new InMemorySessionStore();
    const sessions = new Sessions({ sessionStore: store });
    const session = await sessions.create({
      tenant_id: tenant,
      session_id: 's1',
      created_by_subject: { subject_id: 'user-1', subject_type: 'user', subject_display_name: 'user-1' },
      agent: { type: 'inline', spec: makeAgentSpec() },
      external_id: null,
    });
    const first = await session.createTurn({
      turn_id: mintTestTurnId(),
      active_executor_id: TEST_ACTIVE_EXECUTOR_ID,
      input: [{ type: EventType.USER_MESSAGE, content: 'one' }],
      previous_turn_id: 'none',
      signal: new AbortController().signal,
      resolver: makeTestResolver(),
    });
    for await (const event of first.stream()) {
      void event;
      // drain
    }
    const root2 = await session.createTurn({
      turn_id: mintTestTurnId(),
      active_executor_id: TEST_ACTIVE_EXECUTOR_ID,
      input: [{ type: EventType.USER_MESSAGE, content: 'fresh root' }],
      previous_turn_id: 'none',
      signal: new AbortController().signal,
      resolver: makeTestResolver(),
    });
    expect(root2.previous_turn_id).toBeNull();
    const sessionRecord = await store.getSession({ tenant_id: tenant, session_id: 's1' });
    expect(sessionRecord?.last_turn_id).toBe(root2.id);
  });

  it('send/validation failure in run() persists no turn', async () => {
    const store = new InMemorySessionStore();
    const sessions = new Sessions({ sessionStore: store });
    const session = await sessions.create({
      tenant_id: tenant,
      session_id: 's1',
      created_by_subject: { subject_id: 'user-1', subject_type: 'user', subject_display_name: 'user-1' },
      agent: { type: 'inline', spec: makeAgentSpec() },
      external_id: null,
    });
    await expect(
      session.createTurn({
        turn_id: mintTestTurnId(),
        active_executor_id: TEST_ACTIVE_EXECUTOR_ID,
        // Mixed batch — rejected by SessionHandle.toSendBatch / orchestrator validation path.
        input: [
          { type: EventType.USER_MESSAGE, content: 'hi' },
          {
            type: EventType.USER_TOOL_APPROVAL,
            thread_id: 'main',
            tool_call_id: 'tc1',
            approval: { status: 'allow' },
          },
        ],
        previous_turn_id: 'none',
        signal: new AbortController().signal,
        resolver: makeTestResolver(),
      }),
    ).rejects.toThrow();
    const turns = await store.listTurns({
      session_id: 's1',
      limit: 10,
      page_token: undefined,
    });
    expect(turns.data).toHaveLength(0);
    const sessionRecord = await store.getSession({ tenant_id: tenant, session_id: 's1' });
    expect(sessionRecord?.last_turn_id).toBeNull();
  });

  it('run() failure closes the resolver; success defers close() to stream()', async () => {
    const store = new InMemorySessionStore();
    const sessions = new Sessions({ sessionStore: store });
    const session = await sessions.create({
      tenant_id: tenant,
      session_id: 's1',
      created_by_subject: { subject_id: 'user-1', subject_type: 'user', subject_display_name: 'user-1' },
      agent: { type: 'inline', spec: makeAgentSpec() },
      external_id: null,
    });

    // Failure path: resources acquired before the throw must be released.
    const closeOnFailure = jest.fn().mockResolvedValue(undefined);
    await expect(
      session.createTurn({
        turn_id: mintTestTurnId(),
        active_executor_id: TEST_ACTIVE_EXECUTOR_ID,
        // Mixed batch — rejected after sandbox/thread resolution.
        input: [
          { type: EventType.USER_MESSAGE, content: 'hi' },
          {
            type: EventType.USER_TOOL_APPROVAL,
            thread_id: 'main',
            tool_call_id: 'tc1',
            approval: { status: 'allow' },
          },
        ],
        previous_turn_id: 'none',
        signal: new AbortController().signal,
        resolver: makeTestResolver({ close: closeOnFailure }),
      }),
    ).rejects.toThrow();
    expect(closeOnFailure).toHaveBeenCalledTimes(1);

    // Success path: run() must NOT close — TurnHandle.stream()'s finally owns it.
    const closeOnSuccess = jest.fn().mockResolvedValue(undefined);
    const turn = await session.createTurn({
      turn_id: mintTestTurnId(),
      active_executor_id: TEST_ACTIVE_EXECUTOR_ID,
      input: [{ type: EventType.USER_MESSAGE, content: 'hello' }],
      previous_turn_id: 'none',
      signal: new AbortController().signal,
      resolver: makeTestResolver({ close: closeOnSuccess }),
    });
    expect(closeOnSuccess).not.toHaveBeenCalled();
    for await (const event of turn.stream()) {
      void event;
      // drain
    }
    expect(closeOnSuccess).toHaveBeenCalledTimes(1);
  });
});