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.

6.5 KB
Raw Blame
import { assignAgentDisplayNames, freeAgentName, isEngineName, isRoleName } from './agentNames.js'
import { fail, type Actor, type Agent, type SuperTabState } from './model.js'
import { nameRefusal } from './personNames.js'
import { printable } from './profile.js'
import { agentNamesSeenBy, nameKey, swarmUsernames } from './usernames.js'

/** Characters, not UTF-16 units, as a person's name counts (personNames.ts). */
const AGENT_NAME_LENGTH = 60
/** What hides a name: the default-ignorables, and the Braille blank U+2800, which no category marks. */
const HIDDEN = /[\p{Default_Ignorable_Code_Point}\u2800]/u

/**
 * `agent.rename`: the name a person gave their agent with Rename Harness, which every reader's list shows. Only the agent's
 * contributor or its machine's owner, as a person, may (security review 2 of #3015). The name passes what a person's does
 * (personNames.ts `nameRefusal`: no web address, no role's or the Swarm's own name) and is not a name or username or email
 * of anyone here, nor another agent's that [actor] can read: a name nobody can take to pass as someone else, and a refusal
 * that never tells them an agent they cannot read exists.
 */
type Checked = { name: string } | { code: 'INVALID_AGENT_NAME' | 'AGENT_NAME_ROLE' | 'AGENT_NAME_TAKEN'; message: string; status: 400 | 409 }

/** [input] as the name of [exceptId]'s agent (or a new one), for what [actor] reads, or why it is refused. */
function checkedAgentName(state: SuperTabState, actor: Actor, exceptId: string | null, input: string): Checked {
  const name = input.normalize('NFKC').replace(/\s+/g, ' ').trim()
  if (!name || [...name].length > AGENT_NAME_LENGTH || !printable(name) || HIDDEN.test(name)) {
    return { code: 'INVALID_AGENT_NAME', message: `Use 1 to ${AGENT_NAME_LENGTH} characters, with no hidden ones.`, status: 400 }
  }
  // An engine's name reads as no name: every such agent is shown a member name (agentNames.ts, task #4568).
  if (isEngineName(name)) return { code: 'AGENT_NAME_ROLE', message: `${name} is an engine's name. Choose another.`, status: 400 }
  const refused = nameRefusal(name)
  if (refused) return { code: refused.code === 'NAME_RESERVED' ? 'AGENT_NAME_ROLE' : 'INVALID_AGENT_NAME', message: refused.message, status: 400 }
  const key = nameKey(name)
  const usernames = swarmUsernames(state)
  const others = state.people.flatMap(p => [p.name, usernames.get(p.id), p.email])
  const agents = agentNamesSeenBy({ ...state, agents: state.agents.filter(a => a.id !== exceptId) }, actor)
  // The person's own agents still starting, and their own agent chats, are theirs to read: two quick starts never share a name.
  const own = actor.kind === 'person' ? [...(state.starts ?? []).filter(s => !s.harnessId && !s.error && s.contributorId === actor.userId).map(s => s.request.name),
    ...state.conversations.filter(c => c.kind === 'agent-chat' && !(exceptId && c.agentIds.includes(exceptId)) && c.audience?.people.some(p => p.id === actor.userId)).map(c => c.title)] : []
  if ([...others, ...agents, ...own].some(other => other && nameKey(other) === key)) {
    return { code: 'AGENT_NAME_TAKEN', message: `${name} is taken in this Swarm. Choose another.`, status: 409 }
  }
  return { name }
}

/**
 * `agent.rename`: the name a person gave their agent with Rename Harness, which every reader's list shows. Only the agent's
 * contributor or its machine's owner, as a person, may (security review 2 of #3015). The name passes what a person's does
 * (personNames.ts `nameRefusal`: no web address, no role's or the Swarm's own name) and is not a name or username or email
 * of anyone here, nor another agent's that [actor] can read: a name nobody can take to pass as someone else, and a refusal
 * that never tells them an agent they cannot read exists.
 */
export function renameAgentTo(state: SuperTabState, actor: Actor, target: Agent, input: string): void {
  if (actor.kind !== 'person' || (actor.userId !== target.contributorId && actor.userId !== target.machineOwnerId)) {
    fail('FORBIDDEN', 'Only the person who runs this agent, or its machine\'s owner, can rename it.', 403)
  }
  const checked = checkedAgentName(state, actor, target.id, input)
  if ('code' in checked) fail(checked.code, checked.message, checked.status)
  target.displayName = checked.name
}

/**
 * The name `agent.add` gives a session a person shares, which Desktop takes from the harness's own name: the same rules, but
 * a name that fails them never stops the add. It is left for a member name (a role's name already is: agentNames.ts), so a
 * harness called "System" or "Quinn" joins as someone else's name never would.
 */
export function addedAgentName(state: SuperTabState, actor: Actor, input: string): string {
  const checked = checkedAgentName(state, actor, null, input)
  // A role's name stays as it always did: the agent is given a member name for it (agentNames.ts).
  if (isRoleName(input.normalize('NFKC'))) return input
  return 'name' in checked ? checked.name : 'Agent'
}

/**
 * The name `agent.new` gives a person's new agent (task #4568, anh Dee: every agent has a real name): the one they chose, with
 * the rename checks, or a free one from the agent names when they chose none, or only its engine's or a role's (Desktop's
 * Cmd-N names every Member "Claude Code"). A free name is free across the whole Swarm, people, every agent, the starts still
 * waiting and the names chosen in Buddy chats, so it never repeats one the person cannot read either. [seed] fixes the pick.
 */
export function newAgentName(state: SuperTabState, actor: Actor, input: string | undefined, seed: string): string {
  const given = input?.normalize('NFKC').trim()
  if (given && !isEngineName(given) && !isRoleName(given)) {
    const checked = checkedAgentName(state, actor, null, given)
    if ('code' in checked) fail(checked.code, checked.message, checked.status)
    return checked.name
  }
  const shown = state.agents.map(a => ({ id: a.id, name: a.name, ...(a.displayName ? { displayName: a.displayName } : {}) }))
  assignAgentDisplayNames(shown)
  const usernames = swarmUsernames(state)
  const taken = new Set([...state.people.flatMap(p => [p.name, usernames.get(p.id), p.email, p.email.split('@')[0]]),
    ...shown.map(a => a.displayName), ...(state.starts ?? []).filter(s => !s.harnessId && !s.error).map(s => s.request.name),
    ...state.conversations.map(c => c.buddyName), ...state.conversations.filter(c => c.kind === 'agent-chat').map(c => c.title)]
    .filter((name): name is string => !!name).map(nameKey))
  return freeAgentName(name => taken.has(nameKey(name)), seed)
}