The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
/**
* A scripted gateway for the group-chat room-engine tests.
*
* A member turn is a session-scoped RPC SEQUENCE (create/resume → attach →
* prompt.submit → poll), so nearly every room contract is only observable in
* what those RPCs saw. This models the parts of the gateway's session
* lifecycle those contracts depend on:
*
* - the STORED id is the durable identity and every `session.resume` mints a
* FRESH runtime id, which is why a turn that loses its socket mid-sequence
* has to recover through the stored id (#93602);
* - a missing session answers JSON-RPC 4007 — the real "genuinely not found"
* code that `ensureGroupChatSession`'s fail-closed branch keys on, so a
* plain failure here is NOT read as "no session, mint a new one";
* - `host.requestProfile` takes a per-request socket lease and disposes the
* socket at refcount 0, the reap that made routed members go silent.
*
* Its predecessors sliced `plugin.js` out of the bundle with string offsets
* and ran it under `vm`; this drives the real modules through the real
* `host` surface instead.
*/
import type { PluginContext } from '@hermes/plugin-sdk'
import { vi } from 'vitest'
/** One message in a scripted session transcript, in the gateway's own shape. */
export interface ScriptedMessage {
content: string
display_kind?: string
role: string
}
export interface ScriptedSession {
contracts?: { follow_profile_config: boolean; room_plumbing: boolean }
messages: ScriptedMessage[]
profile: string
runtime: string
stored: string
title: string
}
/** What the scripted member "said" this turn: one reply, or the whole tail of
* messages a real turn can append (a substantive answer plus a continuation
* nudge and its synthetic pass, #94376). */
export type TurnReply = ScriptedMessage[] | string
export interface ScriptedTurn {
/** 1-based index across every prompt.submit the gateway has seen. */
n: number
profile: string
prompt: string
session: ScriptedSession
}
export type TurnScript = (turn: ScriptedTurn) => Promise<TurnReply> | TurnReply
/** Every prompt.submit the gateway received, with the session it landed on. */
export interface PromptCall {
profile: string
prompt: string
runtime: string
stored: string
title: string
}
/** Every attachment staging RPC, and how many submits preceded it. */
export interface AttachCall {
data: string
filename: string
method: string
order: number
profile: null | string
runtime: string
}
export interface RpcCall {
method: string
params: Record<string, unknown>
/** Socket refcount after this request released its own lease. */
refcountAfter: number
spawnPriority?: 'background' | 'foreground'
timeoutMs?: number
}
export interface GatewayOptions {
/** Per profile: report inflight/running on its first N `session.resume`s. */
busyResumes?: Record<string, number>
/** Per profile: carry `pending_approval` on its first `until` resumes. */
approvalUntil?: Record<string, { payload: Record<string, unknown>; until: number }>
/** Per profile: carry open server requests on its first `until` resumes. */
/** `payload` is an open-request frame `{ id, method: 'clarify', params }`. */
clarifyUntil?: Record<string, { payload: Record<string, unknown>; until: number }>
/** Land a competing writer's `ui_meta` under `key` during the FIRST
* `profiles.configure`, then reject it as a CAS conflict — the race the
* sync worker's pull-merge-retry exists for. */
conflictOnce?: { key: string; value: unknown }
/** Reject attach RPCs whose method is in this map — after recording the call
* so tests can see the staging attempt even when it throws. */
failAttach?: Record<string, unknown>
/** Reject every prompt.submit with this — a fatal, non-recoverable failure. */
failEverySubmitWith?: unknown
/** Reject only the FIRST prompt.submit — the 4001 reap the retry recovers. */
failFirstSubmitWith?: unknown
/** Fired on each post-submit poll, so a test can land a stop mid-turn. */
onResumePoll?: (polls: number) => void
/** Report the member inflight for the first N post-submit polls. */
pollsBusy?: number
/** After a submit, every resume replays the gateway's RETAINED failed turn
* (`inflight: { status: 'error', error }`, `running: false`) instead of a
* reply — the snapshot `_fail_inflight_turn` leaves for reconnecting clients. */
retainedErrorAfterSubmit?: string
turn?: TurnScript
}
/** A gateway-shaped rejection: `.code` is what the engine branches on. */
function gatewayError(message: string, code: number) {
return Object.assign(new Error(message), { code })
}
export interface ScriptedGateway {
/** Attachment staging RPCs, in order. */
attaches: AttachCall[]
/** prompt.submit calls, in order. */
calls: PromptCall[]
/** Times the socket refcount fell to zero — each one reaps a runtime session. */
disposals: () => number
/** The mock `host` the `@hermes/plugin-sdk` mock should expose. */
host: Record<string, unknown>
/** Every RPC, for methods the typed recorders above don't cover. */
rpc: RpcCall[]
/** Filter `rpc` by method. */
rpcFor: (method: string) => RpcCall[]
/** Route retentions acquired for explicit multi-RPC member turns. */
retains: Array<{ spawnPriority?: 'background' | 'foreground' }>
/** Live socket refcount — zero between turns, never zero during one. */
refcount: () => number
/** Sessions by stored id, so a test can pre-seed a finished transcript. */
sessions: Map<string, ScriptedSession>
/** Plugin storage writes, by key. */
storage: Map<string, unknown>
/** `retain`/`release`/method names in call order — the lease lifetime. */
timeline: string[]
/** The default profile's `ui_meta`, as `profiles.list` reports it. */
uiMeta: Record<string, unknown>
/** CAS revisions for `uiMeta`, advanced by every applied configure. */
uiMetaRevisions: Record<string, number>
}
export function createGroupGateway(options: GatewayOptions = {}): ScriptedGateway {
const { turn = () => '(pass)' } = options
const sessions = new Map<string, ScriptedSession>()
const runtimeToStored = new Map<string, string>()
const titleToStored = new Map<string, string>()
const resumesByProfile = new Map<string, number>()
const calls: PromptCall[] = []
const attaches: AttachCall[] = []
const rpc: RpcCall[] = []
const retains: Array<{ spawnPriority?: 'background' | 'foreground' }> = []
const timeline: string[] = []
const storage = new Map<string, unknown>()
const uiMeta: Record<string, unknown> = {}
const uiMetaRevisions: Record<string, number> = {}
let sequence = 0
let submits = 0
let polls = 0
let refcount = 0
let disposals = 0
let conflicted = false
const resolveSession = (profile: unknown, target: unknown) => {
const key = String(target ?? '')
const stored =
runtimeToStored.get(key) || (sessions.has(key) ? key : titleToStored.get(`${String(profile)}::${key}`))
return stored ? sessions.get(stored) || null : null
}
// `profiles.configure`: CAS-checked ui_meta writes, with an optional one-shot conflict.
const configureProfiles = (params: Record<string, unknown>) => {
if (options.conflictOnce && !conflicted) {
conflicted = true
const { key, value } = options.conflictOnce
uiMeta[key] = value
uiMetaRevisions[key] = (uiMetaRevisions[key] || 0) + 1
return {
applied: {
ui_meta: false,
ui_meta_conflicts: { [key]: { actual: uiMetaRevisions[key], expected: uiMetaRevisions[key] - 1 } },
ui_meta_revisions: { ...uiMetaRevisions }
}
}
}
const expected = params.ui_meta_expected_revisions as Record<string, number> | undefined
const incoming = (params.ui_meta || {}) as Record<string, unknown>
if (expected) {
for (const key of Object.keys(incoming)) {
if ((uiMetaRevisions[key] || 0) !== expected[key]) {
return {
applied: {
ui_meta: false,
ui_meta_conflicts: { [key]: { actual: uiMetaRevisions[key] || 0, expected: expected[key] } }
}
}
}
}
}
for (const [key, value] of Object.entries(incoming)) {
if (value === null) {
delete uiMeta[key]
} else {
uiMeta[key] = value
}
uiMetaRevisions[key] = (uiMetaRevisions[key] || 0) + 1
}
return { applied: { ui_meta: true, ui_meta_revisions: { ...uiMetaRevisions } } }
}
const handle = async (method: string, params: Record<string, unknown>): Promise<unknown> => {
// A legacy Desktop room: no hosted-room driver, nonpersistent owner.
if (method === 'groups.capabilities') {
return { driver: false, persistent_process: false }
}
if (method === 'profiles.list') {
return {
profiles: [{ name: 'default', ui_meta: { ...uiMeta }, ui_meta_revisions: { ...uiMetaRevisions } }]
}
}
if (method === 'profiles.configure') {
return configureProfiles(params)
}
if (method === 'session.create') {
sequence += 1
const profile = String(params.profile ?? '')
const title = String(params.title ?? '')
const session: ScriptedSession = {
contracts: {
follow_profile_config: params.follow_profile_config === true,
room_plumbing: params.room_plumbing === true
},
messages: [],
profile,
runtime: `rt-${profile}-${sequence}`,
stored: `sid-${profile}-${sequence}`,
title
}
sessions.set(session.stored, session)
runtimeToStored.set(session.runtime, session.stored)
titleToStored.set(`${profile}::${title}`, session.stored)
return { message_count: 0, messages: [], session_id: session.runtime, stored_session_id: session.stored }
}
if (method === 'session.resume') {
const session = resolveSession(params.profile, params.session_id)
if (!session) {
throw gatewayError(`session not found: ${String(params.session_id)}`, 4007)
}
// Every resume mints a fresh runtime id; the stored id is the durable
// identity. Old runtime ids stay resolvable so an in-flight turn that
// still holds one is not spuriously reaped by the harness itself.
sequence += 1
session.runtime = `rt-${session.profile}-${sequence}`
runtimeToStored.set(session.runtime, session.stored)
const seen = (resumesByProfile.get(session.profile) || 0) + 1
resumesByProfile.set(session.profile, seen)
let busy = Boolean(options.busyResumes?.[session.profile] && seen <= options.busyResumes[session.profile])
if (session.messages.length > 0) {
polls += 1
busy = busy || Boolean(options.pollsBusy && polls <= options.pollsBusy)
options.onResumePoll?.(polls)
}
const clarify = options.clarifyUntil?.[session.profile]
const approval = options.approvalUntil?.[session.profile]
const retained =
options.retainedErrorAfterSubmit && session.messages.at(-1)?.role === 'user'
? { error: options.retainedErrorAfterSubmit, status: 'error', streaming: false }
: null
return {
inflight: retained ?? busy,
message_count: busy ? 0 : session.messages.length,
messages: busy || params.omit_messages ? [] : [...session.messages],
running: false,
session_id: session.runtime,
session_key: session.stored,
...(clarify && seen <= clarify.until ? { open_requests: [clarify.payload] } : {}),
...(approval && seen <= approval.until ? { pending_approval: approval.payload } : {})
}
}
if (method === 'image.attach_bytes' || method === 'pdf.attach' || method === 'file.attach') {
const session = resolveSession(null, params.session_id)
if (!session) {
throw gatewayError(`session-scoped RPC rejected: ${String(params.session_id)} not in memory`, 4001)
}
attaches.push({
data: String(params.content_base64 ?? params.data_url ?? ''),
filename: String(params.filename ?? params.name ?? ''),
method,
order: calls.length,
profile: session.profile,
runtime: String(params.session_id ?? '')
})
if (Object.hasOwn(options.failAttach ?? {}, method)) {
throw options.failAttach![method]
}
return method === 'file.attach'
? { attached: true, ref_text: `@file:attachments/${String(params.name ?? 'attachment')}` }
: { attached: true }
}
if (method === 'prompt.submit') {
submits += 1
if (options.failEverySubmitWith) {
throw options.failEverySubmitWith
}
if (submits === 1 && options.failFirstSubmitWith) {
throw options.failFirstSubmitWith
}
const session = resolveSession(null, params.session_id)
if (!session) {
throw gatewayError(`session-scoped RPC rejected: ${String(params.session_id)} not in memory`, 4001)
}
const prompt = String(params.text ?? '')
session.messages.push({ content: prompt, role: 'user' })
calls.push({
profile: session.profile,
prompt,
runtime: session.runtime,
stored: session.stored,
title: session.title
})
const reply = await turn({ n: calls.length, profile: session.profile, prompt, session })
for (const message of typeof reply === 'string' ? [{ content: reply, role: 'assistant' }] : reply) {
session.messages.push(message)
}
return {}
}
return {}
}
const record = async (method: string, params: Record<string, unknown>) => {
try {
return await handle(method, params)
} finally {
rpc.push({ method, params, refcountAfter: refcount })
}
}
const host: Record<string, unknown> = {
activeConnectionId: () => 'local',
notify: vi.fn(),
notifyError: vi.fn(),
request: async (method: string, params: Record<string, unknown> = {}) => record(method, params),
requestProfile: async (
_route: unknown,
method: string,
params: Record<string, unknown> = {},
timeoutMs?: number,
options?: { spawnPriority?: 'background' | 'foreground' }
) => {
refcount += 1
try {
return await handle(method, params)
} finally {
refcount -= 1
if (refcount === 0) {
disposals += 1
}
rpc.push({ method, params, refcountAfter: refcount, spawnPriority: options?.spawnPriority, timeoutMs })
timeline.push(method)
}
},
retainProfile: async (_route: unknown, options?: { spawnPriority?: 'background' | 'foreground' }) => {
retains.push({ spawnPriority: options?.spawnPriority })
timeline.push('retain')
refcount += 1
let released = false
return () => {
if (released) {
return
}
released = true
timeline.push('release')
refcount -= 1
if (refcount === 0) {
disposals += 1
}
}
},
setWorkspaceScope: vi.fn(),
state: {
connectionId: { get: () => 'local', listen: () => () => undefined },
gateway: { get: () => 'open', listen: () => () => undefined },
profile: { get: () => 'default', listen: () => () => undefined }
}
}
return {
attaches,
calls,
disposals: () => disposals,
host,
refcount: () => refcount,
rpc,
rpcFor: (method: string) => rpc.filter(entry => entry.method === method),
retains,
sessions,
storage,
timeline,
uiMeta,
uiMetaRevisions
}
}
/** The `@hermes/plugin-sdk` surface the group modules actually reach for.
* `atom` must be the real nanostores one — the room store IS its atoms — and
* it has to come from the CURRENT module generation, so this is built inside
* the `vi.mock` factory rather than hoisted alongside it. */
export async function pluginSdkMock(host: Record<string, unknown>) {
const nanostores = await import('nanostores')
const { Textarea } = await import('@/components/ui/textarea')
const { cn } = await import('@/lib/utils')
const { randomUuid } = await import('@hermes/shared')
// The gateway Group Chat row's right-click menu (#143571) renders the real one.
const { ContextMenu, ContextMenuContent, ContextMenuItem, ContextMenuSeparator, ContextMenuTrigger } =
await import('@/components/ui/context-menu')
return {
Textarea,
ContextMenu,
ContextMenuContent,
ContextMenuItem,
ContextMenuSeparator,
ContextMenuTrigger,
cn,
// Real value: approval.respond forwards it as its client deadline (#60654).
APPROVAL_RESPOND_TIMEOUT_MS: 300_000,
atom: nanostores.atom,
// Feature-detected SDK members: the modules read them off the namespace
// and fall back when absent, but vitest rejects a namespace access with
// no matching export at all — so they have to be present and undefined.
BOT_CHAT_SESSION_HYDRATION_TIMEOUT_MS: undefined,
blobatarSvg: undefined,
computed: nanostores.computed,
createBudgetedLoop: undefined,
gatewayActivationEpoch: () => 0,
GlyphSpinner: () => null,
useGatewayActivationEpoch: () => 0,
host,
randomUuid,
CapabilitiesView: undefined,
MessageTextContent: undefined,
Streamdown: undefined,
queryClient: { invalidateQueries: () => undefined },
useQuery: () => ({ data: [], isLoading: false }),
useValue: <T>(store: { get: () => T }) => store.get()
}
}
/** Plugin storage backed by a plain map, for `setPluginCtx`. */
export function scriptedStorage(storage: Map<string, unknown>): PluginContext {
return {
storage: {
get: async (key: string) => storage.get(key) ?? null,
set: async (key: string, value: unknown) => {
storage.set(key, structuredClone(value))
}
}
// The modules under test only ever reach for ctx.storage; the rest of the
// host-supplied context has no bearing on room state.
} as unknown as PluginContext
}
/** Run the room engine's timers inline.
*
* The turn poll sleeps `GROUP_TURN_POLL_MS` between resumes and the sync
* mirror debounces by 350ms; both are wall-clock waits a test must not
* actually serve. Resolving immediately keeps the awaits (and therefore the
* interleaving the race contracts depend on) while removing the delay. */
export function runTimersInline() {
vi.stubGlobal('setTimeout', (fn: () => void) => {
fn()
return 0
})
vi.stubGlobal('clearTimeout', () => undefined)
}
/** Run the engine's timers on the next macrotask instead of inline.
*
* The sync worker's retry path stores its own timer handle AFTER scheduling
* it (`retryTimers.set(id, setTimeout(...))`), so an inline timer deletes the
* handle before it is written and the entry never clears. Deferring keeps
* that ordering intact while still ignoring the backoff delay. */
export function deferTimers() {
vi.stubGlobal('setTimeout', (fn: () => void) => {
setImmediate(fn)
return 1
})
vi.stubGlobal('clearTimeout', () => undefined)
}
/** Let the room engine's async loop run to completion. */
export async function drain(isRunning: () => boolean, limit = 400) {
for (let i = 0; i < limit && isRunning(); i++) {
await new Promise(resolve => setImmediate(resolve))
}
// One more flush so the `finally` bookkeeping after the last await lands.
await new Promise(resolve => setImmediate(resolve))
}