Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

19.8 KB
Raw Blame
/**
 * REST tools served as MCP (rest.ts), with the gateway's real Gmail / Drive / Calendar / Figma shapes and a
 * stubbed fetch: never a real provider.
 */
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { mkdtempSync, rmSync } from 'node:fs'
import { request as httpRequest } from 'node:http'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { bridgeKey, sync, type Agent } from './agents.js'
import { createBridge } from './bridge.js'
import { tokenFrom } from './gateway.js'
import { answer, cleanRestEntry, encode, invoke, transport, type RestEntry } from './rest.js'
import { Store, type Token } from './store.js'

const GMAIL = {
  auth: { in: 'header', name: 'Authorization', format: 'Bearer {access_token}' },
  tools: [
    { name: 'gmail_identity', description: 'Who is signed in.', request: { method: 'GET', url: 'https://www.googleapis.com/oauth2/v3/userinfo' } },
    { name: 'gmail_send', description: 'Send an email.', params: { to: { type: 'string', required: true, description: 'Recipient' }, subject: { type: 'string', required: true }, body: { type: 'string', required: true } },
      request: { method: 'POST', url: 'https://gmail.googleapis.com/gmail/v1/users/me/messages/send', json: { raw: { $encode: 'rfc2822_base64url', to: '{to}', subject: '{subject}', body: '{body}' } } } },
  ],
}
const DRIVE = {
  tools: [
    { name: 'google_drive_read_file', params: { file_id: { type: 'string', required: true } }, request: { method: 'GET', url: 'https://www.googleapis.com/drive/v3/files/{file_id}', query: { alt: 'media' } } },
    { name: 'google_drive_list_files', params: { query: { type: 'string' }, page_size: { type: 'integer' } },
      request: { method: 'GET', url: 'https://www.googleapis.com/drive/v3/files', query: { q: '{query}', pageSize: '{page_size}', orderBy: 'modifiedTime desc' } } },
    { name: 'google_drive_create_file', params: { name: { type: 'string', required: true }, content: { type: 'string', required: true }, content_type: { type: 'string' } },
      request: { method: 'POST', url: 'https://www.googleapis.com/upload/drive/v3/files', query: { uploadType: 'multipart' }, multipart: { metadata: { name: '{name}' }, content: '{content}', content_type: '{content_type}' } } },
  ],
}
const FIGMA = { auth: { in: 'header', name: 'X-Figma-Token', format: '{access_token}' }, tools: [{ name: 'figma_identity', request: { url: 'https://api.figma.com/v1/me' } }] }

const entryOf = (raw: unknown): RestEntry => cleanRestEntry(raw)!
const token: Token = { access_token: 'ya29.secret', token_type: 'Bearer', source: 'gateway' }

let fetchMock: ReturnType<typeof vi.fn>
const sent = () => fetchMock.mock.calls.at(-1) as [URL, RequestInit]
function reply(status: number, body = '') { fetchMock.mockResolvedValueOnce(new Response(body || null, { status })) }

beforeEach(() => { fetchMock = vi.fn(); vi.stubGlobal('fetch', fetchMock) })
afterEach(() => { vi.unstubAllGlobals() })

describe('reading a rest_entry', () => {
  it('keeps the usable tools and fills the defaults', () => {
    const entry = entryOf({ tools: [...DRIVE.tools, { name: 'downgraded', request: { url: 'http://www.googleapis.com/x' } }, { name: 'bad name!', request: { url: 'https://x.example' } },
      { name: 'no_url', request: {} }, { name: 'unparsable', request: { url: 'https://' } }, { name: 'with_user', request: { url: 'https://me:[email protected]' } }, 'junk', { name: 'odd', params: { x: 'junk' }, request: { url: 'https://x.example', query: { n: 1 }, multipart: [] } }] })
    expect(entry.auth).toEqual({ in: 'header', name: 'Authorization', format: 'Bearer {access_token}' })
    expect(entry.tools.map(tool => tool.name)).toEqual(['google_drive_read_file', 'google_drive_list_files', 'google_drive_create_file', 'odd'])
    expect(entry.tools[3]).toEqual({ name: 'odd', params: { x: { type: 'string' } }, request: { method: 'GET', url: 'https://x.example' } })
    expect(entry.tools[0].request).toEqual({ method: 'GET', url: 'https://www.googleapis.com/drive/v3/files/{file_id}', query: { alt: 'media' } })
  })

  it('is no entry without a usable tool', () => {
    for (const raw of [undefined, null, [], {}, { tools: {} }, { tools: [{ name: 'x', request: { url: 'http://x.example' } }] }]) expect(cleanRestEntry(raw)).toBeNull()
  })

  it('arrives from the gateway and survives the store, the token never filled in', () => {
    const vault = new Store(mkdtempSync(join(tmpdir(), 'rest-store-')))
    try {
      const got = tokenFrom({ access_token: 'ya29.secret', refresh: true, rest_entry: GMAIL, transport: 'rest', mcp_entry: null })
      expect(got).toMatchObject({ transport: 'rest', rest_entry: { auth: GMAIL.auth } })
      expect(JSON.stringify(got.rest_entry)).not.toContain('ya29')
      vault.save('gmail', got)
      expect(vault.token('gmail')!.rest_entry!.tools.map(tool => tool.name)).toEqual(['gmail_identity', 'gmail_send'])
      expect(vault.status('gmail', 'Gmail', vault.token('gmail')).tools).toBe(true)
      expect(tokenFrom({ access_token: 'a', transport: 'sideways', rest_entry: 'x' })).not.toHaveProperty('transport')
      vault.save('plain', { access_token: 'a', transport: 'none' })
      expect(vault.token('plain')).toMatchObject({ transport: 'none' })
      expect(vault.status('plain', 'Plain', vault.token('plain')).tools).toBe(false)
    } finally { rmSync(vault.root, { recursive: true, force: true }) }
  })
})

describe('which way agents reach a connection', () => {
  const mcp = { url: 'https://mcp.example/mcp', headers: {} }
  const rest = entryOf(GMAIL)
  it('follows the gateway when what it names came with it, and infers otherwise', () => {
    expect(transport({ transport: 'none', mcp_entry: mcp })).toBe('none')
    expect(transport({ transport: 'rest', mcp_entry: mcp, rest_entry: rest })).toBe('rest')
    expect(transport({ transport: 'rest', mcp_entry: mcp })).toBe('mcp')
    expect(transport({ mcp_entry: mcp, rest_entry: rest })).toBe('mcp')
    expect(transport({ transport: 'mcp', rest_entry: rest })).toBe('rest')
    expect(transport({ access_token: 'a' })).toBe('none')
  })
})

describe('encoders', () => {
  it('writes an RFC 2822 message Gmail accepts, safe from header injection, Vietnamese intact', () => {
    const raw = encode('rfc2822_base64url', { to: '[email protected]\r\nBcc: [email protected]', cc: '[email protected]', subject: 'Chào bạn', body: 'Xin chào'.repeat(20) })
    expect(raw).not.toMatch(/[+/=]/)
    const message = Buffer.from(raw, 'base64url').toString('utf8')
    const [head, body] = message.split('\r\n\r\n')
    expect(head.split('\r\n')).toEqual(['To: [email protected]  Bcc: [email protected]', 'Cc: [email protected]', `Subject: =?UTF-8?B?${Buffer.from('Chào bạn').toString('base64')}?=`,
      'MIME-Version: 1.0', 'Content-Type: text/plain; charset="UTF-8"', 'Content-Transfer-Encoding: base64'])
    expect(body.split('\r\n').every(line => line.length <= 76)).toBe(true)
    expect(Buffer.from(body.replace(/\r\n/g, ''), 'base64').toString('utf8')).toBe('Xin chào'.repeat(20))
    expect(Buffer.from(encode('rfc2822_base64url', { to: 5 }), 'base64url').toString()).toContain('To: \r\nSubject: \r\n')
  })

  it('base64url, and refuses one it does not know', () => {
    expect(encode('base64url', { value: 'hi?>' })).toBe(Buffer.from('hi?>').toString('base64url'))
    expect(encode('base64url', {})).toBe('')
    expect(() => encode('rot13', {})).toThrow('does not know ("rot13")')
  })
})

describe('calling a tool', () => {
  const gmail = entryOf(GMAIL)
  const drive = entryOf({ ...DRIVE, auth: GMAIL.auth })
  const tool = (entry: RestEntry, name: string) => entry.tools.find(item => item.name === name)!

  it('sends Gmail a message with the token in the entry\'s header', async () => {
    reply(200, '{"id":"m1"}')
    const result = await invoke(gmail, tool(gmail, 'gmail_send'), token, { to: '[email protected]', subject: 'Hi', body: 'Hello' })
    expect(result).toEqual({ ok: true, text: '{"id":"m1"}' })
    const [url, init] = sent()
    expect(String(url)).toBe('https://gmail.googleapis.com/gmail/v1/users/me/messages/send')
    expect(init).toMatchObject({ method: 'POST', redirect: 'error', headers: { Authorization: 'Bearer ya29.secret', 'Content-Type': 'application/json' } })
    const raw = JSON.parse(init.body as string).raw
    expect(Buffer.from(raw, 'base64url').toString()).toContain('To: [email protected]\r\nSubject: Hi\r\n')
  })

  it('checks required arguments before anything is sent', async () => {
    expect(await invoke(gmail, tool(gmail, 'gmail_send'), token, { to: ' ', subject: null })).toEqual({ ok: false, text: 'Missing required arguments: to, subject, body.' })
    expect((await invoke(drive, tool(drive, 'google_drive_read_file'), token, {})).text).toBe('Missing required argument: file_id.')
    expect(fetchMock).not.toHaveBeenCalled()
  })

  it('encodes path values, leaves out empty query values, and fills other auth formats', async () => {
    reply(200)
    expect(await invoke(drive, tool(drive, 'google_drive_read_file'), token, { file_id: '../../about?x=1' })).toEqual({ ok: true, text: '{}' })
    expect(String(sent()[0])).toBe('https://www.googleapis.com/drive/v3/files/..%2F..%2Fabout%3Fx%3D1?alt=media')
    reply(200, '[]')
    await invoke(drive, tool(drive, 'google_drive_list_files'), token, { page_size: 5 })
    expect(String(sent()[0])).toBe('https://www.googleapis.com/drive/v3/files?pageSize=5&orderBy=modifiedTime+desc')
    const figma = entryOf(FIGMA)
    reply(200, '{}')
    await invoke(figma, figma.tools[0], { access_token: 'figd' }, {})
    expect(sent()[1]).toMatchObject({ method: 'GET', headers: { 'X-Figma-Token': 'figd' } })
    expect(sent()[1].body).toBeUndefined()
  })

  it('uploads to Drive as multipart/related', async () => {
    reply(200, '{"id":"f1"}')
    await invoke(drive, tool(drive, 'google_drive_create_file'), token, { name: 'notes.txt', content: 'hello', content_type: 'text/markdown' })
    const [url, init] = sent()
    expect(String(url)).toBe('https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart')
    const boundary = /boundary=(.+)$/.exec((init.headers as Record<string, string>)['Content-Type'])![1]
    expect(init.body).toBe(`--${boundary}\r\nContent-Type: application/json; charset=UTF-8\r\n\r\n{"name":"notes.txt"}\r\n--${boundary}\r\nContent-Type: text/markdown\r\n\r\nhello\r\n--${boundary}--`)
    const bare = entryOf({ tools: [{ name: 'up', params: {}, request: { method: 'post', url: 'https://x.example/u', multipart: { content: 7 } } }] })
    reply(200)
    await invoke(bare, bare.tools[0], { access_token: 'a' }, {})
    expect(sent()[1].method).toBe('POST')
    expect(sent()[1].body).toMatch(/\r\n\r\n\{\}\r\n--[^\r]+\r\nContent-Type: text\/plain\r\n\r\n\r\n/)
  })

  it('says what went wrong in words a person can act on', async () => {
    const identity = tool(gmail, 'gmail_identity')
    const cases: [number, string, string][] = [
      [401, '{"error":{"message":"Invalid Credentials"}}', 'The connection needs signing in again: Invalid Credentials'],
      [403, '{"message":"Insufficient scope"}', "This account doesn't have permission for that. Reconnect it in harness connections and grant the extra access: Insufficient scope"],
      [404, '{"detail":"No file"}', 'Not found — check the id or key that was used: No file'],
      [429, '<html>slow down</html>', 'The service is rate-limiting this account. Try again shortly.'],
      [503, '{"error":"down"}', 'The service had an error (503).'],
      [418, '[]', 'The service refused the request (418).'],
    ]
    for (const [status, body, text] of cases) {
      reply(status, body)
      expect(await invoke(gmail, identity, token, {})).toEqual({ ok: false, text })
    }
    fetchMock.mockRejectedValueOnce(Object.assign(new Error('getaddrinfo https://www.googleapis.com/?key=x'), { name: 'TypeError' }))
    expect(await invoke(gmail, identity, token, {})).toEqual({ ok: false, text: "Couldn't reach the service (TypeError)." })
  })

  it('refuses rather than guesses', async () => {
    const query = entryOf({ ...GMAIL, auth: { in: 'query' } })
    expect((await invoke(query, query.tools[0], token, {})).text).toContain('("query")')
    const odd = entryOf({ tools: [{ name: 'x', request: { method: 'POST', url: 'https://x.example', json: { a: { $encode: 'rot13' } } } }] })
    expect((await invoke(odd, odd.tools[0], token, {})).text).toContain('does not know ("rot13")')
    const broken = entryOf({ tools: [{ name: 'y', params: { host: {} }, request: { url: 'https://{host}' } }] })
    expect((await invoke(broken, broken.tools[0], token, {})).text).toMatch(/^Couldn't build the request: /)
    expect(fetchMock).not.toHaveBeenCalled()
  })

  it('fills nested bodies: lists, numbers and objects as given', async () => {
    const cal = entryOf({ tools: [{ name: 'c', params: {}, request: { method: 'POST', url: 'https://x.example', json: { summary: '{s}', start: { dateTime: '{t}' }, tags: ['{s}', 3], n: 1, none: null } } }] })
    reply(200, '{}')
    await invoke(cal, cal.tools[0], {}, { s: 'Họp', t: { at: 1 } })
    expect(JSON.parse(sent()[1].body as string)).toEqual({ summary: 'Họp', start: { dateTime: '{"at":1}' }, tags: ['Họp', 3], n: 1, none: null })
    expect(sent()[1].headers).toMatchObject({ Authorization: 'Bearer ' })
  })
})

describe('answering MCP', () => {
  const entry = entryOf(GMAIL)
  const ask = (message: unknown, fresh: () => Promise<Token> = async () => token, current: RestEntry | null = entry) => answer(message, () => current, fresh)

  it('introduces itself and lists the tools', async () => {
    expect(await ask({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18' } })).toEqual({ jsonrpc: '2.0', id: 1,
      result: { protocolVersion: '2025-06-18', capabilities: { tools: {} }, serverInfo: { name: 'harness-connector-bridge', version: '1' } } })
    expect((await ask({ id: 2, method: 'initialize' }))!.result).toMatchObject({ protocolVersion: '2025-03-26' })
    expect(await ask({ id: 3, method: 'ping' })).toEqual({ jsonrpc: '2.0', id: 3, result: {} })
    const listed = (await ask({ id: 4, method: 'tools/list' }))!.result as { tools: Record<string, unknown>[] }
    expect(listed.tools[0]).toEqual({ name: 'gmail_identity', description: 'Who is signed in.', inputSchema: { type: 'object', properties: {}, required: [] } })
    expect(listed.tools[1].inputSchema).toEqual({ type: 'object', properties: { to: { type: 'string', description: 'Recipient' }, subject: { type: 'string' }, body: { type: 'string' } }, required: ['to', 'subject', 'body'] })
    expect(await ask({ id: 5, method: 'tools/list' }, undefined, null)).toEqual({ jsonrpc: '2.0', id: 5, result: { tools: [] } })
    expect(((await ask({ id: 6, method: 'tools/list' }, undefined, entryOf({ tools: [{ name: 'n', request: { url: 'https://x.example' } }] })))!.result as { tools: unknown[] }).tools[0]).toMatchObject({ description: '' })
  })

  it('calls a tool with the fresh token; a failure is a result the model reads', async () => {
    reply(200, '{"sub":"1"}')
    expect(await ask({ id: 7, method: 'tools/call', params: { name: 'gmail_identity', arguments: {} } }, async () => ({ access_token: 'renewed' })))
      .toEqual({ jsonrpc: '2.0', id: 7, result: { content: [{ type: 'text', text: '{"sub":"1"}' }], isError: false } })
    expect(sent()[1].headers).toMatchObject({ Authorization: 'Bearer renewed' })
    expect((await ask({ id: 8, method: 'tools/call', params: { name: 'gmail_send' } }))!.result).toEqual({ content: [{ type: 'text', text: 'Missing required arguments: to, subject, body.' }], isError: true })
    expect((await ask({ id: 9, method: 'tools/call', params: { name: 'gmail_read' } }))!.result).toMatchObject({ content: [{ text: 'This connection has no tool called "gmail_read".' }], isError: true })
    expect((await ask({ id: 10, method: 'tools/call', params: { name: 'gmail_identity' } }, async () => { throw new Error('Reconnect it.') }))!.result)
      .toMatchObject({ content: [{ text: 'Reconnect it.' }], isError: true })
  })

  it('takes no notification as a request and refuses what is not one', async () => {
    expect(await ask({ jsonrpc: '2.0', method: 'notifications/initialized' })).toBeNull()
    expect(await ask({ id: null, method: 'ping' })).toBeNull()
    expect(await ask([1])).toEqual({ jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Invalid request' } })
    expect(await ask({ id: 'x', method: 'resources/list' })).toEqual({ jsonrpc: '2.0', id: 'x', error: { code: -32601, message: 'Method not found: resources/list' } })
  })
})

describe('through the bridge', () => {
  let home: string
  let vault: Store
  let port: number
  let key: string
  const closers: (() => void)[] = []

  beforeEach(async () => {
    home = mkdtempSync(join(tmpdir(), 'rest-bridge-'))
    vault = new Store(join(home, 'connections'))
    vault.save('gmail', tokenFrom({ access_token: 'ya29.secret', rest_entry: GMAIL, transport: 'rest' }))
    key = bridgeKey(vault)
    const bridge = createBridge(vault, { key: () => String(vault.file('bridge.json').key) })
    await new Promise<void>(resolve => bridge.listen(0, '127.0.0.1', resolve))
    port = (bridge.address() as { port: number }).port
    closers.push(() => { bridge.close(); bridge.closeAllConnections() })
  })
  afterEach(() => { while (closers.length) closers.pop()!(); rmSync(home, { recursive: true, force: true }) })

  function send(method: string, body = ''): Promise<{ status: number, headers: Record<string, unknown>, body: string }> {
    return new Promise((resolve, reject) => {
      const request = httpRequest({ host: '127.0.0.1', port, path: `/${key}/gmail/mcp`, method, headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(body) } }, response => {
        const chunks: Buffer[] = []
        response.on('data', chunk => chunks.push(chunk)).on('end', () => resolve({ status: response.statusCode!, headers: response.headers, body: Buffer.concat(chunks).toString() }))
      })
      request.on('error', reject).end(body)
    })
  }

  it('is the MCP server for a REST-backed connection', async () => {
    const listed = await send('POST', '{"jsonrpc":"2.0","id":1,"method":"tools/list"}')
    expect(listed.status).toBe(200)
    expect(listed.headers['content-type']).toBe('application/json')
    expect(JSON.parse(listed.body).result.tools.map((tool: { name: string }) => tool.name)).toEqual(['gmail_identity', 'gmail_send'])
    reply(200, '{"email":"[email protected]"}')
    const called = JSON.parse((await send('POST', '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"gmail_identity"}}')).body)
    expect(called.result).toEqual({ content: [{ type: 'text', text: '{"email":"[email protected]"}' }], isError: false })
    expect(sent()[1].headers).toMatchObject({ Authorization: 'Bearer ya29.secret' })
    expect((await send('POST', '{"jsonrpc":"2.0","method":"notifications/initialized"}')).status).toBe(202)
    expect(JSON.parse((await send('POST', '{oops')).body).error.code).toBe(-32700)
    expect(JSON.parse((await send('POST')).body).error.code).toBe(-32700)
    const stream = await send('GET')
    expect([stream.status, stream.headers.allow]).toEqual([405, 'POST'])
  })

  it('says so when the connection went away mid-session', async () => {
    const renewing = vi.spyOn(vault, 'token')
    renewing.mockImplementation(code => code === 'gmail' && renewing.mock.calls.length > 2 ? undefined : Store.prototype.token.call(vault, code))
    const called = JSON.parse((await send('POST', '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"gmail_identity"}}')).body)
    expect(called.result).toMatchObject({ isError: true, content: [{ text: expect.stringContaining('no longer connected') }] })
  })

  it('gives agents the connection like any MCP one', () => {
    const applied: Record<string, string>[] = []
    const agent = { name: 'fake', installed: () => true, apply: (wanted: Record<string, string>) => { applied.push(wanted); return Object.keys(wanted) } } as unknown as Agent
    sync(vault, { HOME: home }, [agent])
    expect(Object.keys(applied[0])).toEqual(['gmail'])
  })
})