Skip to content

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

15.2 KB
Raw Blame
import assert from 'node:assert/strict';
import { describe, it } from 'vitest';

import {
  createHarnessChatServer,
  toHarnessAgentSpec,
  toUiAgentSpec,
  type HarnessAgentSpec,
} from '@/plugins/trueforge-agent-server-adapter/chatServer.js';

const session = {
  id: 'ses_1',
  agent: {
    type: 'inline',
    spec: {
      model: { name: 'test/model' },
      mcp_servers: [{ name: 'github', enable_tools: ['@all'] }],
      skills: [{ name: 'review' }],
    },
  },
  title: null,
  created_by: 'trueforge-default',
  created_at: '2026-08-03T00:00:00.000Z',
  updated_at: '2026-08-03T00:00:00.000Z',
  metrics: {
    total_turns: 1,
    total_duration_ms: 12_000,
    total_cost_in_usd: 0.42,
  },
};

const turnRequests: unknown[] = [];
const sessionRequests: unknown[] = [];
const deletedSessions: string[] = [];
const subscribeRequests: (string | null)[] = [];

const fetchMock: typeof fetch = async (input, init) => {
  const url = input instanceof Request ? input.url : String(input);
  const method = init?.method ?? 'GET';
  if (url.endsWith('/api/v1/sessions/ses_1/turns') && typeof init?.body === 'string') {
    const body: unknown = JSON.parse(init.body);
    turnRequests.push(body);
  }
  if (url.endsWith('/api/v1/sessions') && method === 'POST') {
    if (typeof init?.body === 'string') {
      sessionRequests.push(JSON.parse(init.body));
    }
    return Response.json({ data: session });
  }
  if (url.endsWith('/api/v1/sessions/ses_1') && method === 'PATCH') {
    const body: unknown = typeof init?.body === 'string' ? JSON.parse(init.body) : undefined;
    sessionRequests.push(body);
    const title =
      body !== null && typeof body === 'object' && 'title' in body && typeof body.title === 'string'
        ? body.title
        : session.title;
    return Response.json({ data: { ...session, title } });
  }
  if (url.endsWith('/api/v1/sessions/ses_1') && method === 'DELETE') {
    deletedSessions.push('ses_1');
    return new Response(null, { status: 204 });
  }
  if (url.includes('/api/v1/sessions?') || url.endsWith('/api/v1/sessions')) {
    return Response.json({ data: [session], pagination: { limit: 20, next_page_token: 'tok_2' } });
  }
  if (url.endsWith('/api/v1/agents')) {
    return Response.json({ data: [] });
  }
  if (url.endsWith('/api/v1/sessions/ses_1/turns')) {
    return new Response(
      'id: 7\ndata: {"type":"model.message.delta","id":"evt_1","thread_id":"main","content":"hello"}\n\n',
      { headers: { 'content-type': 'text/event-stream' } },
    );
  }
  if (url.includes('/api/v1/sessions/ses_1/turns/trn_1/subscribe')) {
    // SDK join can yield a relative path; base is only for URL parsing.
    const after = new URL(url, 'http://test.local').searchParams.get('after_sequence_number');
    subscribeRequests.push(after);
    return new Response(
      'id: 8\ndata: {"type":"model.message.delta","id":"evt_2","thread_id":"main","content":"world"}\n\n',
      { headers: { 'content-type': 'text/event-stream' } },
    );
  }
  return new Response(`Unexpected request: ${method} ${url}`, { status: 500 });
};

describe('createHarnessChatServer', () => {
  it('forwards gateway-shaped mounts without synthesizing ids', async () => {
    const server = createHarnessChatServer({ fetch: fetchMock });
    const spec: HarnessAgentSpec = { model: { name: 'test/model' } };

    const created = await server.createSession({ agentSpec: spec });

    assert.equal(created.isMutable, true);
    assert.equal(created.title, undefined);
    assert.deepEqual(created.agentSpec?.mcpServers?.[0], { name: 'github', enableTools: ['@all'] });
    assert.deepEqual(created.agentSpec?.skills?.[0], { name: 'review', preload: false });
  });

  it('sends skill name refs and strips UI-only mount ids before admission', async () => {
    const server = createHarnessChatServer({ fetch: fetchMock });
    const skillName = 'agent-skill:acme/team-a/echo:3';

    await server.createSession({
      agentSpec: {
        model: { name: 'test/model' },
        skills: [{ id: skillName, name: 'echo', preload: true }],
        mcpServers: [{ name: 'github', enableTools: ['@all'] }],
      },
    });

    const sent = sessionRequests.at(-1);
    assert.ok(sent !== null && typeof sent === 'object' && 'agent' in sent);
    assert.deepEqual(sent.agent, {
      spec: {
        model: { name: 'test/model' },
        mcp_servers: [{ name: 'github', enable_tools: ['@all'] }],
        skills: [{ name: skillName, preload: true }],
      },
    });
  });

  it('defaults skill preload to false when omitted', () => {
    const ui = toUiAgentSpec({
      model: { name: 'test/model' },
      skills: [{ name: 'agent-skill:acme/team-a/echo:3' }],
    });
    assert.deepEqual(ui.skills?.[0], { name: 'agent-skill:acme/team-a/echo:3', preload: false });
    assert.deepEqual(toHarnessAgentSpec({ model: { name: 'test/model' }, skills: [{ name: 'echo' }] }).skills?.[0], {
      name: 'echo',
      preload: false,
    });
  });

  it('preserves sandbox environmentName on UI and harness agent specs', () => {
    const ui = toUiAgentSpec({
      model: { name: 'test/model' },
      config: {
        sandbox: { enabled: true, environmentName: 'python-dev', fileDownloads: true },
        webSearch: { enabled: true },
      },
    });
    assert.deepEqual(ui.config?.sandbox, {
      enabled: true,
      environmentName: 'python-dev',
      fileDownloads: true,
    });
    assert.deepEqual(
      toHarnessAgentSpec({
        model: { name: 'test/model' },
        config: {
          sandbox: { enabled: true, environmentName: 'python-dev', fileDownloads: true },
          webSearch: { enabled: true },
        },
      }).config?.sandbox,
      {
        enabled: true,
        environmentName: 'python-dev',
        fileDownloads: true,
      },
    );
  });

  it('reports pages under the ListResult pagination contract', async () => {
    const server = createHarnessChatServer({ fetch: fetchMock });

    const page = await server.listSessions({ limit: 20 });

    assert.equal(page.data[0]?.id, 'ses_1');
    assert.equal(page.nextPageToken, 'tok_2');
  });

  it('preserves SSE sequence numbers and roots chains Harness-style', async () => {
    const server = createHarnessChatServer({ fetch: fetchMock });

    const events = [];
    for await (const event of server.createTurn({
      sessionId: 'ses_1',
      input: [{ type: 'user.message', content: 'hello' }],
      previousTurnId: 'none',
    })) {
      events.push(event);
    }

    const sent = turnRequests.at(-1);
    assert.ok(sent !== null && typeof sent === 'object' && 'previous_turn_id' in sent && 'stream' in sent);
    assert.equal(sent.previous_turn_id, 'none');
    assert.equal(sent.stream, true);

    assert.deepEqual(events, [
      {
        sequenceNumber: 7,
        event: {
          type: 'model.message.delta',
          id: 'evt_1',
          threadId: 'main',
          content: 'hello',
        },
      },
    ]);
  });

  it('creates a named session from agentName and reports it immutable', async () => {
    const requests: { url: string; body?: unknown }[] = [];
    const fetchNamed: typeof fetch = async (input, init) => {
      const url = input instanceof Request ? input.url : String(input);
      if (url.endsWith('/api/v1/sessions') && init?.method === 'POST' && typeof init.body === 'string') {
        requests.push({ url, body: JSON.parse(init.body) });
        return Response.json({ data: { ...session, agent: { type: 'reference', id: 'agt_1', name: 'reviewer' } } });
      }
      return new Response(`Unexpected request: ${url}`, { status: 500 });
    };

    const server = createHarnessChatServer({ fetch: fetchNamed });
    const created = await server.createSession({ agentName: 'reviewer' });

    assert.deepEqual(requests.at(-1)?.body, { agent: { name: 'reviewer' } });
    assert.equal(created.isMutable, false);
    assert.equal(created.agentName, 'reviewer');
    assert.equal(created.agentSpec, undefined);
  });

  it('filters listSessions by registry agentId and stamps the wire name on ref rows', async () => {
    let listUrl: string | undefined;
    let listedAgents = false;
    const fetchNamed: typeof fetch = async input => {
      const url = input instanceof Request ? input.url : String(input);
      if (url.endsWith('/api/v1/agents')) {
        listedAgents = true;
        return Response.json({ data: [] });
      }
      if (url.includes('/api/v1/sessions?')) {
        listUrl = url;
        return Response.json({
          data: [{ ...session, agent: { type: 'reference', id: 'agt_1', name: 'reviewer' } }],
          pagination: { limit: 20 },
        });
      }
      return new Response(`Unexpected request: ${url}`, { status: 500 });
    };

    const server = createHarnessChatServer({ fetch: fetchNamed });
    const page = await server.listSessions({ agentId: 'agt_1' });

    assert.equal(listedAgents, false);
    assert.ok(listUrl !== undefined);
    assert.equal(new URL(listUrl, 'http://test.local').searchParams.get('agent_id'), 'agt_1');
    assert.equal(page.data[0]?.agentName, 'reviewer');
    assert.equal(page.data[0]?.isMutable, false);
  });

  it('forwards createdByMe to listSessions as created_by_me', async () => {
    let listUrl: string | undefined;
    const fetchNamed: typeof fetch = async input => {
      const url = input instanceof Request ? input.url : String(input);
      if (url.includes('/api/v1/sessions?')) {
        listUrl = url;
        return Response.json({ data: [], pagination: { limit: 20 } });
      }
      return new Response(`Unexpected request: ${url}`, { status: 500 });
    };

    const server = createHarnessChatServer({ fetch: fetchNamed });
    await server.listSessions({ createdByMe: true, limit: 10 });

    assert.ok(listUrl !== undefined);
    assert.equal(new URL(listUrl, 'http://test.local').searchParams.get('created_by_me'), 'true');
  });

  it('PATCHes session title and returns the updated UI session', async () => {
    sessionRequests.length = 0;
    const server = createHarnessChatServer({ fetch: fetchMock });
    assert.equal(typeof server.renameSession, 'function');
    await server.renameSession?.({ sessionId: 'ses_1', title: 'Acme onboarding' });
    assert.deepEqual(sessionRequests.at(-1), { title: 'Acme onboarding' });

    const updated = await server.updateSession({ sessionId: 'ses_1', title: 'Acme onboarding' });
    assert.deepEqual(sessionRequests.at(-1), { title: 'Acme onboarding' });
    assert.equal(updated.title, 'Acme onboarding');
  });

  it('listSessions forwards an unknown agentId to the API (empty page from the server)', async () => {
    let listUrl: string | undefined;
    const fetchNamed: typeof fetch = async input => {
      const url = input instanceof Request ? input.url : String(input);
      if (url.includes('/api/v1/sessions?')) {
        listUrl = url;
        return Response.json({ data: [], pagination: { limit: 10 } });
      }
      return new Response(`Unexpected request: ${url}`, { status: 500 });
    };

    const server = createHarnessChatServer({ fetch: fetchNamed });
    const page = await server.listSessions({ agentId: 'ghost', limit: 10 });

    assert.ok(listUrl !== undefined);
    assert.equal(new URL(listUrl, 'http://test.local').searchParams.get('agent_id'), 'ghost');
    assert.deepEqual(page.data, []);
    assert.equal(page.nextPageToken, undefined);
  });

  it('getSession takes the agentName of a ref session from the wire, without a registry lookup', async () => {
    let listedAgents = false;
    const fetchNamed: typeof fetch = async input => {
      const url = input instanceof Request ? input.url : String(input);
      if (url.endsWith('/api/v1/agents')) {
        listedAgents = true;
        return Response.json({ data: [] });
      }
      if (url.endsWith('/api/v1/sessions/ses_1')) {
        return Response.json({ data: { ...session, agent: { type: 'reference', id: 'agt_1', name: 'reviewer' } } });
      }
      return new Response(`Unexpected request: ${url}`, { status: 500 });
    };

    const server = createHarnessChatServer({ fetch: fetchNamed });
    const found = await server.getSession({ sessionId: 'ses_1' });

    assert.equal(listedAgents, false);
    assert.equal(found.agentName, 'reviewer');
    assert.equal(found.isMutable, false);
    assert.deepEqual(found.metrics, {
      totalTurns: 1,
      totalDurationMs: 12_000,
      totalCostInUsd: 0.42,
    });
  });

  it('getSession leaves a ref session unlabelled when it carries no name snapshot', async () => {
    const fetchNamed: typeof fetch = async input => {
      const url = input instanceof Request ? input.url : String(input);
      if (url.endsWith('/api/v1/sessions/ses_1')) {
        return Response.json({ data: { ...session, agent: { type: 'reference', id: 'agt_deleted', name: null } } });
      }
      return new Response(`Unexpected request: ${url}`, { status: 500 });
    };

    const server = createHarnessChatServer({ fetch: fetchNamed });
    const found = await server.getSession({ sessionId: 'ses_1' });

    assert.equal(found.isMutable, false);
    assert.equal(found.agentName, undefined);
  });

  it('deletes sessions through the Harness SDK client', async () => {
    deletedSessions.length = 0;
    const server = createHarnessChatServer({ fetch: fetchMock });
    if (server.deleteSession === undefined) {
      throw new Error('Expected deleteSession to be implemented');
    }

    await server.deleteSession({ sessionId: 'ses_1' });

    assert.deepEqual(deletedSessions, ['ses_1']);
  });

  it('subscribes to a turn and forwards afterSequenceNumber', async () => {
    const server = createHarnessChatServer({ fetch: fetchMock });
    assert.ok(server.subscribeToTurn);

    const events = [];
    for await (const event of server.subscribeToTurn({
      sessionId: 'ses_1',
      turnId: 'trn_1',
      afterSequenceNumber: 7,
    })) {
      events.push(event);
    }

    assert.equal(subscribeRequests.at(-1), '7');
    assert.deepEqual(events, [
      {
        sequenceNumber: 8,
        event: {
          type: 'model.message.delta',
          id: 'evt_2',
          threadId: 'main',
          content: 'world',
        },
      },
    ]);
  });

  it('fills missing turn.done metrics fields for the runtime contract', async () => {
    const fetchGetTurn: typeof fetch = async (input, init) => {
      const url = input instanceof Request ? input.url : String(input);
      const method = init?.method ?? 'GET';
      if (url.endsWith('/api/v1/sessions/ses_1/turns/trn_1') && method === 'GET') {
        return Response.json({
          data: {
            id: 'trn_1',
            session_id: 'ses_1',
            previous_turn_id: null,
            created_at: '2026-08-03T00:00:00.000Z',
            state: {
              status: 'done',
              completed_at: '2026-08-03T00:00:01.000Z',
              output: null,
              required_actions: [],
              metrics: { total_input_tokens: 12 },
            },
          },
        });
      }
      return fetchMock(input, init);
    };

    const server = createHarnessChatServer({ fetch: fetchGetTurn });
    const turn = await server.getTurn({ sessionId: 'ses_1', turnId: 'trn_1' });

    assert.equal(turn.state.status, 'done');
    if (turn.state.status !== 'done') throw new Error('expected done');
    assert.deepEqual(turn.state.metrics, {
      totalInputTokens: 12,
      totalOutputTokens: 0,
      totalTokens: 0,
      totalCacheReadTokens: 0,
      totalCacheWriteTokens: 0,
      totalReasoningTokens: 0,
    });
  });
});