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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
import { describe, expect, it } from 'vitest'
import { applyCommand, type Command, type CommandContext } from './commands.js'
import { createSuperTab, visibleState, type Actor } from './model.js'
import { split } from './parts/shape.js'
import { touchesFor } from './parts/touches.js'
import { readerView } from './read/views.js'
import { authorForAgent, lazyUsernames, MAX_NAME_LENGTH, namesPerson, rowForAgent, shownNameOf, writtenNameOf } from './personNames.js'
import { swarmUsernames, usernameOf } from './usernames.js'
const owner: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'owner', email: '[email protected]' }
const NOW = Date.parse('2026-11-03T10:00:00.000Z')
const configuration = { engine: 'claude', model: null, effort: null, contextWindow: null, engineVersion: null }
const person = (id: string, email: string) => ({ kind: 'person', userId: id, email }) as Extract<Actor, { kind: 'person' }>
const relay = person('relay', '[email protected]')
const peer = person('peer', '[email protected]')
function fixture() {
let state = createSuperTab('tab', 'Pilot', { id: 'owner', email: owner.email }, 'prod')
let sequence = 0
const run = (command: Command, actor: Actor = owner, context: Partial<CommandContext> = {}) => {
const effects = applyCommand(state, actor, command, { now: NOW, operationId: `op-${++sequence}`, ...context })
state = effects.state
return effects
}
const join = (who: Extract<Actor, { kind: 'person' }>, role: 'viewer' | 'collaborator' = 'collaborator') => {
const invited = run({ type: 'invite.create', email: who.email, role, conversationId: 'lead' })
run({ type: 'invite.accept', inviteId: invited.result.inviteId as string }, who)
}
join(relay)
join(peer)
const name = (id: string) => state.people.find(p => p.id === id)!.name
const shown = (id: string) => shownNameOf(state, id)
const setName = (value: string | null, actor: Actor = relay) => run({ type: 'member.name', name: value }, actor)
return { run, join, name, shown, setName, get state() { return state } }
}
describe('member.name', () => {
it('shows the username until a person sets a name, and again once they clear it', () => {
const f = fixture()
expect(f.shown('relay')).toBe('wkpnjjhbnm')
f.setName('Minh Nguyen')
expect(f.name('relay')).toBe('Minh Nguyen')
expect(f.shown('relay')).toBe('Minh Nguyen')
f.setName(null)
expect(f.name('relay')).toBeUndefined()
expect(f.shown('relay')).toBe('wkpnjjhbnm')
})
it('trims the name and keeps one space between its words', () => {
const f = fixture()
f.setName(' Minh \t Nguyen ')
expect(f.name('relay')).toBe('Minh Nguyen')
})
it(`refuses an empty name, one over ${MAX_NAME_LENGTH} characters, and hidden characters`, () => {
const f = fixture()
for (const name of ['', ' ', 'a'.repeat(MAX_NAME_LENGTH + 1), 'MinhNguyen', 'Minh', 'Minh\nNguyen', 'Minh
Nguyen']) {
expect(() => f.setName(name), JSON.stringify(name)).toThrow(expect.objectContaining({ code: 'INVALID_NAME', status: 400 }))
}
// Characters, not UTF-16 units: forty letters with accents or an emoji still fit.
f.setName('é'.repeat(MAX_NAME_LENGTH - 1) + '🦊')
expect([...f.name('relay')!]).toHaveLength(MAX_NAME_LENGTH)
})
it('refuses another member’s name, username or email, whatever its case, width, spacing or @', () => {
const f = fixture()
f.setName('Dee Tran', peer)
for (const name of ['dee tran', 'DEETRAN', 'Dee Tran', 'dee', '@Dee', 'D E E', '[email protected]', '[email protected]', 'ken15', '@ken15']) {
expect(() => f.setName(name), name).toThrow(expect.objectContaining({ code: 'NAME_TAKEN', status: 409 }))
}
expect(f.name('relay')).toBeUndefined()
})
it('allows one’s own username or email, and a name close to but not another’s', () => {
const f = fixture()
f.setName('WKPNJJHBNM')
expect(f.name('relay')).toBe('WKPNJJHBNM')
f.setName('Dee’s friend')
expect(f.name('relay')).toBe('Dee’s friend')
})
it('refuses an agent’s name the person can see', () => {
const f = fixture()
f.run({ type: 'agent.add', conversationId: 'lead', harnessId: 'pm', machineId: 'machine', name: 'River', configuration, lead: true },
owner, { contribution: { machineOwnerId: 'owner', contributorId: 'owner' } })
expect(() => f.setName('river')).toThrow(expect.objectContaining({ code: 'NAME_TAKEN' }))
})
it('changes only the person’s own name: an agent, or someone outside the Swarm, is refused', () => {
const f = fixture()
const lead = f.run({ type: 'agent.add', conversationId: 'lead', harnessId: 'pm', machineId: 'machine', name: 'River', configuration, lead: true },
owner, { contribution: { machineOwnerId: 'owner', contributorId: 'owner' } }).result.agentId as string
expect(() => f.setName('Bot', { kind: 'agent', agentId: lead, machineOwnerId: 'owner' })).toThrow(expect.objectContaining({ code: 'HUMAN_REQUIRED' }))
expect(() => f.setName('Stranger', person('stranger', '[email protected]'))).toThrow()
// The command names no one: it sets the actor's own, and nobody else's.
expect(() => f.run({ type: 'member.name', name: 'Minh', userId: 'relay' } as unknown as Command, owner)).toThrow()
f.setName('Owner name', owner)
expect([f.name('owner'), f.name('relay'), f.name('peer')]).toEqual(['Owner name', undefined, undefined])
})
it('lets a viewer set their own name, though they write nothing else', () => {
const f = fixture()
const viewer = person('viewer', '[email protected]')
f.join(viewer, 'viewer')
f.setName('Watcher', viewer)
expect(f.name('viewer')).toBe('Watcher')
expect(() => f.run({ type: 'member.status', status: { text: 'Hi' } }, viewer)).toThrow(expect.objectContaining({ code: 'READ_ONLY' }))
})
it('refuses a username equal to another member’s name', () => {
const f = fixture()
f.setName('Minh')
expect(() => f.run({ type: 'member.username', username: 'minh' }, peer)).toThrow(expect.objectContaining({ code: 'USERNAME_TAKEN' }))
// One's own name is no conflict.
f.run({ type: 'member.username', username: 'minh' }, relay)
expect(f.state.people.find(p => p.id === 'relay')!.username).toBe('minh')
})
it('reaches members with the rest of the person, and only members', () => {
const f = fixture()
f.setName('Minh Nguyen')
const view = readerView(split(f.state, { tabId: 'tab', version: 1, now: NOW }), peer, NOW, { teamMachines: [] })
expect(view.parts.members.find(m => m.key === 'relay')!.data.name).toBe('Minh Nguyen')
expect(visibleState(f.state, peer, NOW).people.find(p => p.id === 'relay')!.name).toBe('Minh Nguyen')
expect(() => visibleState(f.state, person('stranger', '[email protected]'), NOW)).toThrow()
})
it('touches every person and the head, so two people choosing one name at once retry', () => {
const f = fixture()
const before = f.state
const command: Command = { type: 'member.name', name: 'Pilot' }
const effects = applyCommand(before, relay, command, { now: NOW, operationId: 'op-touch' })
expect(touchesFor(command, relay, before, effects)).toEqual(expect.arrayContaining([
{ kind: 'member', key: 'owner' }, { kind: 'member', key: 'relay' }, { kind: 'member', key: 'peer' }, { kind: 'head', key: 'head' },
]))
})
it('refuses a role’s or the Swarm’s own name, numbered too (review 1 of #2794)', () => {
const f = fixture()
for (const name of ['Product Manager', 'PM', 'pm 2', 'Lead', 'Engineer', 'Reviewer', 'Tester', 'Harness', 'System', 'Admin',
'Everyone', 'Swarm', 'You', 'Someone']) {
expect(() => f.setName(name), name).toThrow(expect.objectContaining({ code: 'NAME_RESERVED', status: 400 }))
}
// Width variants too, as every name compare reads them (review 2 of #2794).
for (const name of ['PM', 'Lead', 'system']) {
expect(() => f.setName(name), name).toThrow(expect.objectContaining({ code: 'NAME_RESERVED' }))
}
f.setName('Leading Light')
expect(f.name('relay')).toBe('Leading Light')
})
it('numbers a later joiner’s default around a name someone set, never the person’s own (review 1 of #2794)', () => {
const f = fixture()
f.setName('Bob')
f.join(person('bob', '[email protected]'))
expect(usernameOf(f.state, 'bob')).toBe('bob2')
// One's own name never moves one's own default.
f.setName('WKPNJJHBNM')
expect(usernameOf(f.state, 'relay')).toBe('wkpnjjhbnm')
})
it('refuses a web address as a name, which server lines would show as a link (review 2 of #2794)', () => {
const f = fixture()
for (const name of ['https://ev.il/x', 'ev.il://x', 'www.ev.il', 'WWW.EV.IL', '//ev.il', '[Ken](//ev.il)']) {
expect(() => f.setName(name), name).toThrow(expect.objectContaining({ code: 'INVALID_NAME' }))
}
})
it('writes a name into server-written text as plain words, never Markdown (review 1 of #2794)', () => {
const f = fixture()
f.setName('[Ken](ev.il/x) *x*')
expect(writtenNameOf(f.state, 'relay')).toBe('\\[Ken\\]\\(ev.il/x\\) \\*x\\*')
f.setName('1. Minh')
expect(writtenNameOf(f.state, 'relay')).toBe('1\\. Minh')
// A username is written as it is today.
expect(writtenNameOf(f.state, 'peer')).toBe('dee')
})
})
// Task #2954 (Ken, 11-04): a person's message is stored with their email as its author's name, and agents copied it into
// commands and pull request bodies until a machine's privacy hook stopped their sessions. An agent reads names instead.
describe('a person author as an agent reads it', () => {
const stored = (id: string, email: string) => ({ kind: 'person' as const, id, name: email, membershipGeneration: 'g' })
it('names them by username and the name they show, never by email', () => {
const f = fixture()
f.setName('Minh Nguyen')
const names = swarmUsernames(f.state)
expect(authorForAgent(f.state, stored('relay', relay.email), names))
.toEqual({ kind: 'person', id: 'relay', name: 'wkpnjjhbnm', displayName: 'Minh Nguyen', membershipGeneration: 'g' })
expect(authorForAgent(f.state, stored('peer', peer.email), names))
.toEqual({ kind: 'person', id: 'peer', name: 'dee', displayName: 'dee', membershipGeneration: 'g' })
})
// A person may take their own email as their name (member.name): an agent still never reads it.
it('names a person whose name is their own email by username', () => {
const f = fixture()
f.setName(relay.email)
expect(authorForAgent(f.state, stored('relay', relay.email), swarmUsernames(f.state)))
.toEqual({ kind: 'person', id: 'relay', name: 'wkpnjjhbnm', displayName: 'wkpnjjhbnm', membershipGeneration: 'g' })
// Or holds it among other words (review of #2954).
f.setName(`Minh ${relay.email}`)
expect(authorForAgent(f.state, stored('relay', relay.email), swarmUsernames(f.state))).toMatchObject({ displayName: 'wkpnjjhbnm' })
})
it('reads every username as swarmUsernames gives it, working them out only for one not stored', () => {
const f = fixture()
f.run({ type: 'member.username', username: 'minh' }, relay)
const lazy = lazyUsernames(f.state), all = swarmUsernames(f.state)
for (const p of f.state.people) expect(lazy.get(p.id), p.id).toBe(all.get(p.id))
expect(lazy.get('gone')).toBeUndefined()
})
it('names someone who left as a person, and leaves an agent author as it is', () => {
const f = fixture()
const names = swarmUsernames(f.state)
const gone = authorForAgent(f.state, stored('gone', '[email protected]'), names)
expect(gone).toEqual({ kind: 'person', id: 'gone', name: 'a person', displayName: 'a person', membershipGeneration: 'g' })
expect(JSON.stringify(gone)).not.toContain('@')
const agent = { kind: 'agent' as const, id: 'a1', name: 'Lead', displayName: 'River', membershipGeneration: 'g' }
expect(authorForAgent(f.state, agent, names)).toBe(agent)
})
it('names the person who typed into an agent\'s terminal by name too, in a row an agent reads', () => {
const f = fixture()
const names = swarmUsernames(f.state)
const agent = { kind: 'agent' as const, id: 'a1', name: 'Builder', displayName: 'Robin', membershipGeneration: 'g' }
const native = { id: 'm1', author: agent, text: 'npm test', source: { kind: 'native', phase: 'input', operator: stored('peer', peer.email) } }
expect(namesPerson(native)).toBe(true)
const read = rowForAgent(f.state, names, native)
expect(read).toEqual({ ...native, source: { kind: 'native', phase: 'input', operator: { kind: 'person', id: 'peer', name: 'dee', displayName: 'dee', membershipGeneration: 'g' } } })
expect(JSON.stringify(read)).not.toContain('@')
const plain = { id: 'm2', author: agent, text: 'Done.', source: null }
expect(namesPerson(plain)).toBe(false)
expect(rowForAgent(f.state, names, plain)).toEqual(plain)
})
})