The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
/**
* Bot metadata: the write path (`saveBotMeta`), the disk-load path
* (`migrateBotMeta`), and the server-reconciliation overlay
* (`mergeServerMeta`).
*
* Every case below is a shipped regression:
* - a save must report a REAL remote failure differently from the documented
* older-gateway fallback, or the editor toasts "remote persistence failed"
* on every save forever;
* - `profiles.set_asset` must fire only when the avatar actually changed — a
* no-op `clear` from one machine raced another machine's just-pushed avatar
* and wiped it server-side;
* - a slow disk load must not wipe metadata written earlier in the session;
* - the server overlay is authoritative for the fields it carries (a dropped
* `chat` pointer, a disbanded group) but must NOT resurrect state a local
* write already removed — the disband-resurrection fence.
*/
import { beforeEach, describe, expect, it, vi } from 'vitest'
import { $botMeta, $lastRoster, botMentionTag, botMetaWriteAt, mergeMultiSourceRoster, saveBotMeta } from './data'
import { editedLook } from './edit-profile-look'
import { groupSpeakerLabel } from './group-chat'
import { buildGroupChatTurnPrompt } from './group-round-prompt'
import { displayName } from './labels'
import { mergeServerMeta } from './profile-ops'
import { botRosterMeta } from './routing'
import type { RosterRow } from './types'
const { hostMock, storageMock } = vi.hoisted(() => ({
hostMock: {
agents: undefined as unknown,
profileRoutes: undefined as unknown,
request: vi.fn(),
requestProfile: vi.fn(),
state: { connectionId: { get: () => 'local' }, profile: { get: () => 'default' } }
},
storageMock: { get: vi.fn(), remove: vi.fn(), set: vi.fn() }
}))
vi.mock('@hermes/plugin-sdk', async () => {
const { atom } = await import('nanostores')
return {
atom,
forgetSessionUnread: vi.fn(),
host: hostMock,
queryClient: { invalidateQueries: vi.fn() },
useQuery: vi.fn(),
useValue: vi.fn()
}
})
vi.mock('./shared', () => ({ getPluginCtx: () => ({ storage: storageMock }), ID: 'hermes-bots' }))
// profile-ops pulls in the roster surfaces for delete/duplicate; the overlay
// under test needs none of them.
vi.mock('./avatar-image', () => ({ isBackfilledFacePng: () => false }))
vi.mock('./canonical-chat', () => ({ ensureBotMetadata: vi.fn() }))
/** The backend's profile listing: a save reads the bot's server namespace
* before it writes, so every profile a case saves has to exist there. */
const SERVED_PROFILES = {
profiles: ['beta', 'ops', 'researcher', 'source', 'source-2'].map(name => ({ name, ui_meta_revisions: {} }))
}
/** Every `host.request` recorded, with the params frozen at call time. */
function recordRequests(reply: (method: string) => unknown = () => ({})) {
const calls: Array<{ method: string; params: Record<string, unknown> }> = []
hostMock.request.mockImplementation(async (method: string, params: Record<string, unknown>) => {
calls.push({ method, params: structuredClone(params ?? {}) })
return method === 'profiles.list' ? SERVED_PROFILES : reply(method)
})
return calls
}
beforeEach(() => {
vi.clearAllMocks()
$botMeta.set({})
botMetaWriteAt.clear()
storageMock.get.mockResolvedValue(null)
storageMock.set.mockResolvedValue(undefined)
storageMock.remove.mockResolvedValue(undefined)
recordRequests()
})
describe('a save reports what the SERVER did, not just what the screen shows', () => {
it('keeps the look locally and reports the remote failure', async () => {
recordRequests(method => (method === 'profiles.configure' ? { applied: { ui_meta: false } } : {}))
const result = await saveBotMeta('researcher', { color: '#38bdf8', custom: true, shape: 'cloud' })
expect($botMeta.get().researcher).toMatchObject({ color: '#38bdf8', shape: 'cloud' })
expect(result).toEqual({ serverOutcome: 'failed', serverPersisted: false })
})
it('reports success once ui_meta is applied', async () => {
recordRequests(method => (method === 'profiles.configure' ? { applied: { ui_meta: true } } : {}))
await expect(saveBotMeta('researcher', { color: '#8b5cf6', custom: true, shape: 'hexagon' })).resolves.toEqual({
serverOutcome: 'persisted',
serverPersisted: true
})
})
it('treats an older gateway with no `applied` contract as unsupported, not failed', async () => {
// An error toast on this path would fire on EVERY save forever.
recordRequests(() => ({}))
await expect(saveBotMeta('researcher', { custom: true, shape: 'circle' })).resolves.toEqual({
serverOutcome: 'unsupported',
serverPersisted: false
})
})
it('treats a rejected configure the same way', async () => {
hostMock.request.mockRejectedValue(new Error('param shape rejected'))
await expect(saveBotMeta('researcher', { custom: true, shape: 'circle' })).resolves.toMatchObject({
serverOutcome: 'unsupported'
})
})
})
describe('a save for a bot on the pooled local backend', () => {
it('is admitted while warm bot backends hold every background slot', async () => {
// Main's pool admission, reduced: cap 3 with one slot reserved for
// foreground dials. Two warm bots hold both background slots and beta's
// backend is cold, so a dial without an explicit priority (background,
// main's default) waits out its slot deadline and fails.
hostMock.requestProfile.mockImplementation(
async (
_route: unknown,
method: string,
_params: unknown,
_timeoutMs?: number,
options?: { spawnPriority?: 'background' | 'foreground' }
) => {
if ((options?.spawnPriority ?? 'background') === 'background') {
throw new Error('Local backend start for "beta" timed out while waiting for a free slot. (background)')
}
return method === 'profiles.configure'
? { applied: { ui_meta: true } }
: method === 'profiles.list'
? SERVED_PROFILES
: {}
}
)
const beta = { connectionId: 'local', connectionKind: 'local', name: 'beta', sourceScoped: true } as RosterRow
await expect(saveBotMeta(beta, { sectionId: 'sec-1', sectionName: 'Clients' })).resolves.toEqual({
serverOutcome: 'persisted',
serverPersisted: true
})
})
})
describe('avatar asset sync fires only on a real change', () => {
// Edit Profile always sends the image key, changed or not. Firing
// set_asset for every patch re-uploaded the full data URL — and a no-op
// `clear` from one machine could race another machine's just-pushed
// avatar and wipe it server-side.
it('pushes once, skips the re-save, clears on removal, ignores an absent key', async () => {
const calls = recordRequests()
const png = 'data:image/png;base64,AAAA'
await saveBotMeta('ops', { image: png, title: 'One' })
await saveBotMeta('ops', { image: png, title: 'Two' })
await saveBotMeta('ops', { image: null, title: 'Three' })
await saveBotMeta('ops', { title: 'Four' })
expect(calls.filter(call => call.method === 'profiles.set_asset').map(call => call.params)).toEqual([
{ asset: 'avatar', data: png, name: 'ops' },
{ asset: 'avatar', clear: true, name: 'ops' }
])
// Meta still merges per patch, and ui_meta sync is unaffected.
expect($botMeta.get().ops.title).toBe('Four')
expect(calls.filter(call => call.method === 'profiles.configure')).toHaveLength(4)
})
it('still pushes the copied avatar when a bot is duplicated', async () => {
const calls = recordRequests()
const png = 'data:image/png;base64,BBBB'
await saveBotMeta('source', { image: png, title: 'Original' })
await saveBotMeta('source-2', { image: png, title: 'Original (copy)' })
// The fresh profile's image differs from its (empty) meta, so it pushes.
expect(calls.filter(call => call.method === 'profiles.set_asset').map(call => call.params)).toEqual([
{ asset: 'avatar', data: png, name: 'source' },
{ asset: 'avatar', data: png, name: 'source-2' }
])
})
it('never ships the image or the pet icon inside ui_meta', async () => {
// ui_meta rides every profiles.list and is capped at 64KB; the image goes
// to the uncapped profile asset store instead.
const calls = recordRequests()
await saveBotMeta('ops', { image: 'data:image/png;base64,CCCC', pet: 'pet-cat', title: 'Ops' })
const configure = calls.find(call => call.method === 'profiles.configure')
const uiMeta = (configure?.params.ui_meta as Record<string, Record<string, unknown>>)['hermes-bots']
expect(uiMeta).toEqual({ title: 'Ops' })
})
})
describe('the disk load never clobbers a write from this session', () => {
async function loadWithStorage(value: unknown) {
vi.resetModules()
const data = await import('./data')
storageMock.get.mockImplementation(async (key: string) => (key === 'bot-meta' ? await value : null))
return data
}
it('keeps a value written while the load was still in flight', async () => {
let resolveStorage!: (value: unknown) => void
const pending = new Promise(resolve => {
resolveStorage = resolve
})
const data = await loadWithStorage(pending)
void data.saveBotMeta('researcher', { pinned: true, title: 'Research' })
expect(data.$botMeta.get().researcher.pinned).toBe(true)
const migration = data.migrateBotMeta(storageMock)
resolveStorage({ researcher: { title: 'Research' } })
await migration
expect(data.$botMeta.get().researcher).toMatchObject({ pinned: true, title: 'Research' })
})
it('still merges looks from disk under the fresher in-session write', async () => {
const data = await loadWithStorage({ researcher: { color: '#38bdf8', shape: 'cloud', title: 'Research' } })
void data.saveBotMeta('researcher', { pinned: true })
await data.migrateBotMeta(storageMock)
expect(data.$botMeta.get().researcher).toMatchObject({
color: '#38bdf8',
pinned: true,
shape: 'cloud',
title: 'Research'
})
})
it('fills in bots this session has not touched', async () => {
const data = await loadWithStorage({
researcher: { pinned: true, title: 'Research' },
writer: { title: 'Writer' }
})
await data.migrateBotMeta(storageMock)
expect(data.$botMeta.get().researcher.pinned).toBe(true)
expect(data.$botMeta.get().writer.title).toBe('Writer')
})
})
describe('server metadata reconciliation', () => {
const serverRow = (name: string, meta: Record<string, unknown>) =>
({ name, ui_meta: { 'hermes-bots': meta } }) as unknown as RosterRow
it('removes a stale local canonical-chat pointer on sight', () => {
// Identity is the profile's "Bot Chat" registry row, resolved by name.
// Old `meta.chat` pointers must never look meaningful again.
$botMeta.set({
default: { chat: '4f6f6798ad6f', image: 'data:image/png;base64,avatar', pet: 'pet-cat', shape: 'cloud' }
})
mergeServerMeta([serverRow('default', { color: '#8b5cf6', shape: 'cloud', title: 'Hermana' })])
const current = $botMeta.get().default
expect(Object.hasOwn(current, 'chat')).toBe(false)
// Local-only fields the server copy never carries survive the overlay.
expect(current.image).toBe('data:image/png;base64,avatar')
expect(current.pet).toBe('pet-cat')
const [key, value] = storageMock.set.mock.calls.at(-1) as [string, Record<string, Record<string, unknown>>]
expect(key).toBe('bot-meta')
expect(Object.hasOwn(value.default, 'chat')).toBe(false)
})
it('drops the legacy scalar when authoritative groups say the membership is gone', () => {
// A server-side `group: null` is represented by OMISSION, so retaining
// the local scalar resurrects a membership another desktop just removed.
$botMeta.set({ researcher: { group: 'Old', groups: ['Old'], title: 'Researcher' } })
mergeServerMeta([serverRow('researcher', { groups: [], title: 'Researcher' })])
const current = $botMeta.get().researcher
expect(current.groups).toEqual([])
expect(Object.hasOwn(current, 'group')).toBe(false)
})
it('leaves local metadata alone when the gateway has none', () => {
$botMeta.set({ default: { chat: 'local-chat', shape: 'cloud' } })
mergeServerMeta([{ name: 'default' } as RosterRow])
expect($botMeta.get().default.chat).toBe('local-chat')
expect(storageMock.set).not.toHaveBeenCalled()
})
it('cannot resurrect a membership a later local write removed (disband-resurrection)', async () => {
$botMeta.set({ builder: { group: 'Team', groups: ['Team'], title: 'Builder' } })
// Snapshot fetched now — its ui_meta still names the group.
const staleFetchedAt = Date.now()
const staleRow = serverRow('builder', { group: 'Team', groups: ['Team'], title: 'Builder' })
// Disband path: the local write lands AFTER that fetch.
await new Promise(resolve => setTimeout(resolve, 5))
await saveBotMeta('builder', { group: null, groups: [] })
expect($botMeta.get().builder.groups).toEqual([])
mergeServerMeta([staleRow], staleFetchedAt)
expect($botMeta.get().builder.groups).toEqual([])
// A FRESH snapshot still gets the last word — server truth wins once it
// actually post-dates the local change.
mergeServerMeta([staleRow], Date.now() + 5)
expect($botMeta.get().builder.groups).toEqual(['Team'])
})
it('overlays without a fence when the caller has no fetch time (older callers)', async () => {
await saveBotMeta('builder', { group: null, groups: [] })
mergeServerMeta([serverRow('builder', { groups: ['Team'] })])
expect($botMeta.get().builder.groups).toEqual(['Team'])
})
it('forgets write stamps far too old to fence any snapshot', async () => {
vi.useFakeTimers()
try {
await saveBotMeta('builder', { title: 'Builder' })
expect([...botMetaWriteAt.keys()]).toEqual(['builder'])
// The renderer stays up for days. Once no snapshot can still be in
// flight from before a stamp, keeping it just costs a row per bot.
vi.advanceTimersByTime(120_000)
await saveBotMeta('researcher', { title: 'Research' })
expect([...botMetaWriteAt.keys()]).toEqual(['researcher'])
} finally {
vi.useRealTimers()
}
})
})
// Two machines, both with a profile literally named `default`: the VPS bot is
// "Agent A" on its own backend; this Desktop's local agent is "Agent B", whose
// title still sits under the bare legacy key from its single-source days.
describe("a bot is named by its own backend, never by another bot's cached record", () => {
const vps = {
connectionId: 'vps',
display_name: 'Agent A',
name: 'default',
remoteSource: true,
sourceScoped: true
} as RosterRow
it('a save writes its own patch onto the server namespace, and re-reads after losing a CAS race', async () => {
$botMeta.set({ 'vps::default': { color: '#ff0000', title: 'Agent B' } })
let revision = 3
const configures: Array<Record<string, unknown>> = []
hostMock.requestProfile.mockImplementation(
async (_route: unknown, method: string, params: Record<string, unknown>) => {
if (method === 'profiles.list') {
return {
profiles: [
{
name: 'default',
ui_meta: { 'hermes-bots': { color: '#0000ff', groups: [] } },
ui_meta_revisions: { 'hermes-bots': revision }
}
]
}
}
if (method === 'profiles.configure') {
configures.push(structuredClone(params))
// Another writer lands between this save's read and its write, once.
if (configures.length === 1) {
revision = 4
return { applied: { ui_meta: false, ui_meta_conflicts: { 'hermes-bots': { actual: 4, expected: 3 } } } }
}
return { applied: { ui_meta: true } }
}
return {}
}
)
await expect(saveBotMeta(vps, { groups: ['room'] })).resolves.toMatchObject({ serverOutcome: 'persisted' })
expect(configures.map(params => params.ui_meta_expected_revisions)).toEqual([
{ 'hermes-bots': 3 },
{ 'hermes-bots': 4 }
])
// The local cache's stale title and color never travel: only the patch rides the server's copy.
expect(configures.at(-1)?.ui_meta).toEqual({ 'hermes-bots': { color: '#0000ff', groups: ['room'] } })
})
it('names, tags, and prompts the bot with what its backend reports', () => {
$botMeta.set({ default: { title: 'Agent B' }, 'vps::default': { title: 'Agent B' } })
// `/api/profiles` reports no Bot Mode title for the VPS bot.
const thin = { ...vps, title: '' } as RosterRow
mergeServerMeta([thin])
expect(displayName(thin, botRosterMeta(thin, $botMeta.get()))).toBe('Agent A')
expect(botMentionTag(thin)).toBe('agent-a')
// Window switched to the VPS: its rows are the active source's (scoped, not remote).
const active = { ...vps, remoteSource: false, ui_meta_revisions: {} } as RosterRow
expect(buildGroupChatTurnPrompt({ deltaLines: [], groupName: 'g', members: [active], viewer: active })).toContain(
'You are @agent-a,'
)
// A keyed speaker with no live roster row (Bots pane not mounted).
$lastRoster.set([])
expect(groupSpeakerLabel('vps::default')).not.toBe('Agent B')
})
it('the row shows the name its @handle uses when the backend title and display_name differ', () => {
$botMeta.set({})
const thin = {
...vps,
connectionLabel: 'VPS',
display_name: 'Remote Human Name',
title: 'Remote Bot Title'
} as RosterRow
mergeServerMeta([thin])
expect(displayName(thin, botRosterMeta(thin, $botMeta.get()))).toBe('Remote Bot Title')
expect(botMentionTag(thin)).toBe('remote-bot-title')
// No display_name: the backend's title, never the Desktop-side connection label.
const titleOnly = { ...thin, display_name: '' } as RosterRow
expect(displayName(titleOnly, botRosterMeta(titleOnly, $botMeta.get()))).toBe('Remote Bot Title')
})
it("only a fresh answer from the bot's backend corrects its record, and a title alone never mints one", () => {
$botMeta.set({ 'vps::default': { color: '#00ff00', title: 'New title' } })
// The VPS stops answering; the pane keeps its last-painted row, which predates the rename.
const painted = { ...vps, title: 'Old title' } as RosterRow
const kept = mergeMultiSourceRoster(
{ profiles: [] },
{ agents: [], sources: [{ connectionId: 'vps', reachable: false }] },
'local',
[painted]
)
mergeServerMeta(kept.profiles as RosterRow[], Date.now())
expect($botMeta.get()['vps::default']).toEqual({ color: '#00ff00', title: 'New title' })
// No record yet (a configured alias may own this bot's look): the backend's
// title rides the row, and no empty record appears to shadow the alias.
$botMeta.set({})
mergeServerMeta([{ ...vps, title: 'Agent A' } as RosterRow])
expect($botMeta.get()).toEqual({})
})
it('Edit Profile sends only what the user changed since it opened', () => {
const opened = { color: '#ff0000', image: null, shape: 'circle' as const, title: 'Old title' }
// Renamed elsewhere meanwhile; this dialog only changes the color.
expect(editedLook(opened, { ...opened, color: '#0000ff' })).toEqual({ color: '#0000ff', custom: true })
expect(editedLook(opened, { ...opened, title: ' Old title ' })).toBeNull()
})
})