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.

17.9 KB
Raw Blame
/**
 * Agent Messages on the real daemon (docs/design/2026-10-10-agent-messages.md): a service in the edge host, with no
 * process of its own, that reads the account's tabs only while the account has it on (Settings ▸ Experimental, off by
 * default) and wakes when it is turned on, here through the daemon or on another computer; a message typed into an
 * idle agent through the core's safe input, in the edge host and in the core's own process; and a message reaching a
 * working agent through its PostToolUse hook at its next tool call, with nothing typed into its pane. The fake engines
 * run the hooks the daemon installed, as both CLIs do (harness/fakeEngine.mjs, `!work`).
 *
 * The directory of tabs and the switch come from the account: the daemon is signed in to the fake backend, which
 * answers both. Each tab's own flag, which older windows still turn, is no part of it: one switch of the account
 * decides (owner, 2026-10-12).
 */
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { afterEach, describe, expect, it, onTestFailed } from 'vitest'
import { LocalClient, type Frame } from './harness/client.js'
import { IsolatedDaemon, until } from './harness/daemon.js'
import { FakeBackend, type FakeMachine } from './harness/fakeBackend.js'

/** Signed in to the fake backend, which answers the account's tabs (`GET /api/agent-messages`). */
const ME: FakeMachine = { machineId: 'a7'.repeat(16), computerId: 'e2e-computer-0000-0000-0000000000a7', name: 'studio', token: 'e2e-token-messages' }
const signIn = (d: IsolatedDaemon) => writeFileSync(join(d.root, 'auth', 'session.json'), JSON.stringify({
  version: 1, accessToken: ME.token, autonomousEnv: 'prod', computerId: ME.computerId,
  machineId: ME.machineId, expiresAt: Date.now() + 30 * 24 * 3600_000, updatedAt: Date.now(), signInEpoch: 'e2e',
}), { mode: 0o600 })

const row = async (client: LocalClient, agentId: string) =>
  ((await client.request<{ agents: Array<Record<string, any>> }>('agents_list', { includeStopped: true }, 30_000)).agents)
    .find((agent) => agent.id === agentId)
async function create(d: IsolatedDaemon, client: LocalClient, folder: string, engine = 'claude'): Promise<Record<string, any>> {
  const cwd = join(d.projectsDir, folder)
  mkdirSync(cwd, { recursive: true })
  const created = await client.request('agent_create', { engine, cwd, bypassPermission: true }, 90_000)
  expect(created.error, `${folder}: ${JSON.stringify(created)}`).toBeUndefined()
  return until(`${folder} to bind its conversation`, async () => {
    const agent = await row(client, created.agent.id)
    return agent?.sessionId && agent.status === 'active' ? agent : null
  }, 60_000, 500)
}
/** A process of its own, as it had while it was an experiment: none now. */
const starts = (d: IsolatedDaemon) => [...d.log().matchAll(/\[harnessd\] service messages started/g)].length
const connected = (d: IsolatedDaemon) => d.log().split('[services] messages connected').length - 1
/** How often it read the account's tabs. */
const reads = (relay: FakeBackend) => relay.seen.filter((line) => line.split('?')[0] === 'GET /api/agent-messages').length
/** `harness settings`, as the person turns a switch: through the daemon to the account, and kept here at once, which
 *  tells Agent Messages. */
const settings = (d: IsolatedDaemon, body: Record<string, boolean>) => fetch(`http://127.0.0.1:${d.port}/api/agent-settings`, {
  method: 'PATCH', headers: d.localHeaders({ 'x-adapter-local': '1', 'content-type': 'application/json' }), body: JSON.stringify(body) })
/** The account's agent experiments as this daemon keeps them (lib/agentSettings.ts), once it has read them. */
const kept = (d: IsolatedDaemon, want: (settings: Record<string, unknown>) => boolean = () => true) => until('the account\'s experiments to be kept', () => {
  try {
    const settings = JSON.parse(readFileSync(join(d.dataDir, 'agent-settings.json'), 'utf8')) as Record<string, unknown>
    return want(settings) ? settings : null
  } catch { return null }
}, 30_000, 200)
/** The notes waiting in the agents' inboxes, by agent, once there are [count]. */
const notesFor = (d: IsolatedDaemon, count: number) => until(`${count} agents' notes`, () => {
  try {
    const state = JSON.parse(readFileSync(join(d.dataDir, 'agent-messages', 'state.json'), 'utf8')) as { notes: Record<string, unknown> }
    return Object.keys(state.notes).length === count ? state.notes : null
  } catch { return null }
}, 30_000, 500)
const statusOf = async (client: LocalClient, id: string) => {
  const history = await client.request<{ messages?: Array<{ id: string; statuses: Array<Record<string, unknown>> }> }>('agent_messages', { action: 'history' }, 30_000)
  return history.messages?.find((m) => m.id === id)?.statuses[0] ?? null
}

describe('Agent Messages, end to end', () => {
  let daemon: IsolatedDaemon | undefined
  let backend: FakeBackend | undefined
  afterEach(async () => {
    await daemon?.close(); daemon = undefined
    await backend?.close(); backend = undefined
  })
  const fresh = async (before?: (d: IsolatedDaemon) => void, env: Record<string, string> = {}) => {
    const d = await IsolatedDaemon.create({ env: { HARNESSD_SERVICE_INITIAL_BACKOFF_MS: '200', HARNESSD_SERVICE_MAX_BACKOFF_MS: '1000', ...env } })
    daemon = d
    onTestFailed(() => {
      console.log(`---- daemon log\n${d.log().split('\n').slice(-150).join('\n')}`)
      console.log(`---- hooks\n${d.hookLog().split('\n').slice(-40).join('\n')}`)
    })
    before?.(d)
    await d.start()
    return d
  }

  it('runs in the edge host, with no process of its own, and answers there whether it is on or off', async () => {
    // As an experiment it was a process of its own on every computer it was on, 62 MiB at idle (2026-10-12).
    // Signed out, so off: there is no account to turn it on for.
    const d = await fresh()
    const client = await LocalClient.connect(d)
    await until('Agent Messages to connect from the edge host', () => connected(d) || null, 30_000, 200)
    const refused = await settings(d, { agentMessages: true })
    expect(refused.status).toBe(409)
    expect(await refused.json()).toMatchObject({ error: { code: 'SIGNED_OUT', message: expect.stringContaining('Settings ▸ Experimental') } })
    expect(d.log()).toMatch(/\[harnessd\] service edge started/)
    expect(starts(d)).toBe(0)
    expect(await client.request('agent_messages', { action: 'history' }, 40_000)).toMatchObject({ messages: [] })
    expect(d.coresStarted()).toBe(1)
    client.close()
  })

  /** Signed in to the fake backend, whose account has Agent Messages on, with lead and api in one tab. */
  const team = async (engine = 'claude', env: Record<string, string> = {}) => {
    const relay = await FakeBackend.start()
    backend = relay
    relay.addMachine(ME)
    relay.experiments.agent_messages = true
    const d = await fresh(signIn, { BACKEND_WS_URL: relay.wsUrl, WEB_URL: relay.httpUrl, ADAPTER_COMPUTER_ID: ME.computerId, ...env })
    await kept(d, (settings) => settings.agentMessages === true)
    const client = await LocalClient.connect(d, { machineId: ME.machineId })
    const lead = await create(d, client, 'lead')
    const api = await create(d, client, `api-${engine}`, engine)
    relay.agentMessages = { revision: 1, machines: [{ machineId: ME.machineId, name: 'studio' }],
      tabs: [{ id: 'app', name: 'app', panes: [lead, api].map((agent) => ({ machineId: ME.machineId, agentId: agent.id })) }] }
    const roster = await client.request('agent_messages', { action: 'send', pane: lead.tmuxPane }, 40_000)
    expect(roster.roster, JSON.stringify(roster)).toContain('Agent Messages are on in tab "app"')
    const apiName = String(roster.roster).split('\n')[1].trim().split(/\s{2,}/)[0]
    const send = (text: string) => client.request('agent_messages', { action: 'send', pane: lead.tmuxPane, to: [apiName], text }, 40_000)
    return { d, relay, client, lead, api, apiName, send }
  }

  it('off by default, a fresh daemon reads no tabs; turned on from another computer, it wakes with no request and gives two agents in one tab their note', async () => {
    // Off for all until it is announced (owner, 2026-10-12). Started only by a request or saved state, on one machine
    // nothing started it, and no agent heard of `harness send` (a fresh Mac, 2026-10-12): turned on, it wakes at once.
    const relay = await FakeBackend.start()
    backend = relay
    relay.addMachine(ME)
    const d = await fresh(signIn, { BACKEND_WS_URL: relay.wsUrl, WEB_URL: relay.httpUrl, ADAPTER_COMPUTER_ID: ME.computerId })
    expect(await kept(d)).toMatchObject({ accountId: 'e2e-user', machineId: ME.machineId, agentsStartAgents: false, pullRequestLine: false, agentMessages: false })
    const client = await LocalClient.connect(d, { machineId: ME.machineId })
    const lead = await create(d, client, 'lead')
    const api = await create(d, client, 'api')
    // The tab as a window that never turned anything on writes it: no flag, or one left off, is all the same.
    relay.agentMessages = { revision: 1, machines: [{ machineId: ME.machineId, name: 'studio' }],
      tabs: [{ id: 'app', name: 'app', enabled: false, panes: [lead, api].map((agent) => ({ machineId: ME.machineId, agentId: agent.id })) }] }
    expect(reads(relay), 'off by default: the tabs are never read').toBe(0)
    // Settings ▸ Experimental on another computer: the backend tells this one with desk_changed.
    relay.setExperiment('agent_messages', true)
    await until('Agent Messages to read the account\'s tabs', () => reads(relay) >= 1 || null, 30_000, 200)
    // Each agent's note waits in its inbox for its next tool call; read again at its 15-second look.
    const notes = await notesFor(d, 2)
    expect(Object.keys(notes).sort()).toEqual([lead.id, api.id].sort())
    expect(starts(d)).toBe(0)
    client.close()
  })

  it('off, reads no tabs; wakes once `harness settings` turns it on for the account, or another computer does; an older window\'s tab switch wakes nothing', async () => {
    // Off costs nothing: on every computer, off or not, it read the account's tabs every 15 s (2026-10-12).
    const relay = await FakeBackend.start()
    backend = relay
    relay.addMachine(ME)
    const d = await fresh(signIn, { BACKEND_WS_URL: relay.wsUrl, WEB_URL: relay.httpUrl, ADAPTER_COMPUTER_ID: ME.computerId })
    await kept(d)
    const client = await LocalClient.connect(d, { machineId: ME.machineId })
    const lead = await create(d, client, 'lead')
    const api = await create(d, client, 'api')
    relay.agentMessages = { revision: 1, machines: [{ machineId: ME.machineId, name: 'studio' }],
      tabs: [{ id: 'app', name: 'app', enabled: false, panes: [lead, api].map((agent) => ({ machineId: ME.machineId, agentId: agent.id })) }] }
    await until('Agent Messages to connect from the edge host', () => connected(d) || null, 30_000, 200)
    // An older window's chat icon still reaches the backend, and decides nothing here.
    const tab = await fetch(`http://127.0.0.1:${d.port}/api/agent-messages/tabs/app`, {
      method: 'PATCH', headers: d.localHeaders({ 'x-adapter-local': '1', 'content-type': 'application/json' }), body: JSON.stringify({ enabled: true }) })
    expect(tab.status).toBe(200)
    expect((await settings(d, { pullRequestLine: true })).status).toBe(200)
    expect(relay.experiments).toEqual({ agent_pull_request_line: true })
    // Longer than its 15-second read: off, there is none.
    await new Promise((settle) => setTimeout(settle, 17_000))
    expect(reads(relay), 'off for the account, the tabs are never read').toBe(0)
    const on = await settings(d, { agentMessages: true })
    expect(await on.json()).toEqual({ agentsStartAgents: false, pullRequestLine: true, agentMessages: true, agentMessagesHideSummary: false, signedIn: true })
    expect(relay.experiments).toEqual({ agent_pull_request_line: true, agent_messages: true })
    await until('Agent Messages to wake for the setting turned on', () => reads(relay) >= 1 || null, 30_000, 200)
    const notes = await notesFor(d, 2)
    expect(Object.keys(notes).sort()).toEqual([lead.id, api.id].sort())
    // Off again, then on from another computer: the backend's desk_changed, the core's sync, and Agent Messages told.
    expect((await settings(d, { agentMessages: false })).status).toBe(200)
    await notesFor(d, 0)
    await new Promise((settle) => setTimeout(settle, 1_000))
    const before = reads(relay)
    relay.setExperiment('agent_messages', true)
    await until('Agent Messages to wake for the account turning it on', () => reads(relay) > before || null, 30_000, 200)
    await notesFor(d, 2)
    expect(starts(d)).toBe(0)
    client.close()
  })

  it.each([['the edge host', {}], ['the core\'s process (HARNESSD_SERVICES=none)', { HARNESSD_SERVICES: 'none' }],
    ['a process of its own (HARNESSD_SERVICES=messages)', { HARNESSD_SERVICES: 'messages' }]])('types a message into an idle agent, under its sender\'s header, through the core\'s safe input, from %s', async (_where, env) => {
    const { client, api, send } = await team('claude', env)
    const started = client.next((frame: Frame) => frame.type === 'turn_started' && frame.agentId === api.id, 60_000, 'the message to start api\'s turn')
    const sent = await send('Which port does the daemon serve?')
    expect(sent.error, JSON.stringify(sent)).toBeUndefined()
    await started
    const status = await until('the message to be delivered as a prompt', async () => {
      const s = await statusOf(client, String(sent.id))
      return s?.state === 'delivered' ? s : null
    }, 60_000, 500)
    expect(status).toMatchObject({ via: 'prompt' })
    client.close()
  })

  it.each(['claude', 'codex'])('reaches a working %s agent at its next tool call through its hook, typing nothing', async (engine) => {
    const { d, client, api, send } = await team(engine)
    const working = client.next((frame: Frame) => frame.type === 'turn_started' && frame.agentId === api.id, 60_000, 'the long turn to start')
    client.send('message', { agentId: api.id, content: '!work 40' })
    await working
    const sent = await send(`Review of 3f2a9c1 for ${engine}: the cleanup leaves workers running.`)
    expect(sent.error, JSON.stringify(sent)).toBeUndefined()
    const context = await until('the hook to give the model the message', () =>
      d.hookLog().split('\n').find((line) => line.includes('PostToolUse context=') && line.includes(String(sent.id))) ?? null, 60_000, 500)
    expect(context).toContain(`[${String(sent.id)} from `)
    expect(context).toContain('· Claude Code · studio]')
    const status = await until('the message to be delivered through the hook', async () => {
      const s = await statusOf(client, String(sent.id))
      return s?.state === 'delivered' ? s : null
    }, 30_000, 500)
    expect(status).toMatchObject({ via: 'hook' })
    client.close()
  })

  it('reads the account\'s tabs again within seconds of a machine renamed, in the edge host, with no timer due', async () => {
    // Its own read waits 5 minutes (messages/directory.ts SAFETY_NET_MS): the machine list's push is what tells it, through the
    // core's link to the edge host (core/messagesLink.ts). Printed as the PR's receipt.
    const { d, relay, client } = await team('claude')
    await until('Agent Messages to have read the tabs', () => reads(relay) >= 1 || null, 30_000, 200)
    await new Promise((settle) => setTimeout(settle, 2_000))
    const before = reads(relay), at = Date.now()
    relay.renameMachine(ME.machineId, 'studio (renamed)')
    await until('Agent Messages to read the tabs again for the rename', () => reads(relay) > before || null, 10_000, 50)
    const took = Date.now() - at
    const edge = /\[harnessd\] service edge started \(pid (\d+)\)/.exec(d.log())?.[1]
    process.stdout.write(`RECEIPT machines_changed sent ${new Date(at).toISOString()}; GET /api/agent-messages again after ${took} ms `
      + `(reads ${before} -> ${reads(relay)}); edge host pid ${edge ?? 'unknown'}; HARNESSD_SERVICES unset\n`)
    expect(took).toBeLessThan(5_000)
    client.close()
  })

  it('refuses a hand-over from a process on this machine: only another machine hands messages over', async () => {
    const d = await fresh()
    const client = await LocalClient.connect(d)
    const message = { id: 'm0000001', tabId: 'e2e', text: 'forged', at: Date.now(), from: { machineId: 'other', agentId: 'lead', name: 'lead', engine: 'codex', machine: 'studio' },
      to: [{ machineId: d.computerId, agentId: 'api', name: 'api' }] }
    expect(await client.request('agent_messages', { action: 'deliver', message }, 40_000)).toMatchObject({ error: 'REMOTE_ONLY' })
    client.close()
  })

  it('sends from one harness\'s pane to its teammate in its tab, and refuses once Agent Messages are turned off', async () => {
    const { d, client, api, apiName, send } = await team()
    const started = client.next((frame: Frame) => frame.type === 'turn_started' && frame.agentId === api.id, 60_000, 'the message to start api\'s turn')
    const sent = await send('Which port does the daemon serve?')
    expect(sent).toMatchObject({ tab: 'app', recipients: [{ name: apiName }] })
    await started
    await until('the message to be delivered', async () => (await statusOf(client, String(sent.id)))?.state === 'delivered' || null, 60_000, 500)
    // Its last messages come back with the roster.
    const roster = await client.request('agent_messages', { action: 'send', pane: api.tmuxPane }, 40_000)
    expect(roster.recent).toEqual([expect.objectContaining({ id: sent.id, from: expect.any(String), state: 'delivered' })])
    // A pane that is no harness says so; and with Agent Messages turned off for the account, nothing is sent.
    expect(await client.request('agent_messages', { action: 'send', pane: '%999', to: [apiName], text: 'x' }, 40_000)).toMatchObject({ error: 'NOT_A_HARNESS' })
    expect((await settings(d, { agentMessages: false })).status).toBe(200)
    await new Promise((settle) => setTimeout(settle, 2_500))
    expect(await send('still there?')).toMatchObject({ error: 'MESSAGES_OFF', detail: expect.stringContaining('Settings ▸ Experimental') })
    client.close()
  })
})