@roj-ai/sdk 0.1.36 → 0.2.1

package/src/core/agents/agent.test.ts

@@ -1,387 +0,0 @@
-import { describe, expect, it } from 'bun:test'
-import { COMMUNICATOR_ROLE, ORCHESTRATOR_ROLE } from '~/core/agents/agent-roles.js'
-import { generateTestAgentId } from '~/core/agents/schema.js'
-import type { AgentState } from '~/core/agents/state.js'
-import { getChildren, getParent } from '~/core/agents/state.js'
-import { fromLLMToolCall, fromLLMToolCalls } from '~/core/sessions/state.js'
-import { canCommunicateWith, getCommunicableAgents } from '~/plugins/mailbox/helpers.js'
-import { formatMailboxForLLM } from '~/plugins/mailbox/prompts.js'
-import type { MailboxMessage } from '~/plugins/mailbox/schema.js'
-import { generateTestMessageId } from '~/plugins/mailbox/schema.js'
-
-const createTestAgent = (overrides: Partial<AgentState> = {}): AgentState => ({
-	id: generateTestAgentId(),
-	definitionName: 'test-agent',
-	parentId: null,
-	status: 'pending',
-	conversationHistory: [],
-	preamble: [],
-	pendingToolCalls: [],
-	pendingToolResults: [],
-	pendingMessages: [],
-	...overrides,
-})
-
-const createTestMessage = (
-	overrides: Partial<MailboxMessage> = {},
-): MailboxMessage => ({
-	id: generateTestMessageId(),
-	from: 'user',
-	content: 'test message',
-	timestamp: Date.now(),
-	consumed: false,
-	...overrides,
-})
-
-describe('formatMailboxForLLM', () => {
-	it('formats messages with XML tags including timestamp', () => {
-		const messages: MailboxMessage[] = [
-			createTestMessage({ from: 'user', content: 'Hello', timestamp: 1000 }),
-			createTestMessage({
-				from: generateTestAgentId(),
-				content: 'Hi there',
-				timestamp: 2000,
-			}),
-		]
-
-		const result = formatMailboxForLLM(messages, 3000)
-
-		expect(result).toContain('<message from="user" timestamp="1000">')
-		expect(result).toContain('Hello')
-		expect(result).toContain('</message>')
-		expect(result).toContain('<info>')
-		expect(result).toContain('<currentTime>1970-01-01T00:00:03.000Z</currentTime>')
-	})
-
-	it('handles agent IDs in from field', () => {
-		const agentId = generateTestAgentId()
-		const messages: MailboxMessage[] = [
-			createTestMessage({ from: agentId, content: 'test' }),
-		]
-
-		const result = formatMailboxForLLM(messages)
-
-		expect(result).toContain(`from="${agentId}"`)
-	})
-})
-
-describe('Agent tree helpers', () => {
-	describe('getChildren', () => {
-		it('returns children of an agent', () => {
-			const parentId = generateTestAgentId()
-			const child1 = createTestAgent({ parentId })
-			const child2 = createTestAgent({ parentId })
-			const other = createTestAgent({ parentId: null })
-
-			const session = {
-				agents: new Map([
-					[child1.id, child1],
-					[child2.id, child2],
-					[other.id, other],
-				]),
-			}
-
-			const children = getChildren(session, parentId)
-
-			expect(children).toHaveLength(2)
-			expect(children).toContain(child1)
-			expect(children).toContain(child2)
-		})
-
-		it('returns empty array when no children', () => {
-			const parentId = generateTestAgentId()
-			const session = { agents: new Map() }
-
-			expect(getChildren(session, parentId)).toHaveLength(0)
-		})
-	})
-
-	describe('getParent', () => {
-		it('returns parent agent', () => {
-			const parent = createTestAgent()
-			const child = createTestAgent({ parentId: parent.id })
-
-			const session = {
-				agents: new Map([
-					[parent.id, parent],
-					[child.id, child],
-				]),
-			}
-
-			expect(getParent(session, child)).toBe(parent)
-		})
-
-		it('returns null when no parent', () => {
-			const agent = createTestAgent({ parentId: null })
-			const session = { agents: new Map([[agent.id, agent]]) }
-
-			expect(getParent(session, agent)).toBeNull()
-		})
-
-		it('returns null when parent not found', () => {
-			const agent = createTestAgent({ parentId: generateTestAgentId() })
-			const session = { agents: new Map([[agent.id, agent]]) }
-
-			expect(getParent(session, agent)).toBeNull()
-		})
-	})
-
-	describe('canCommunicateWith', () => {
-		it('returns true when communicating with parent', () => {
-			const parent = createTestAgent()
-			const child = createTestAgent({ parentId: parent.id })
-
-			const session = {
-				agents: new Map([
-					[parent.id, parent],
-					[child.id, child],
-				]),
-			}
-
-			expect(canCommunicateWith(session, child.id, parent.id)).toBe(true)
-		})
-
-		it('returns true when communicating with child', () => {
-			const parent = createTestAgent()
-			const child = createTestAgent({ parentId: parent.id })
-
-			const session = {
-				agents: new Map([
-					[parent.id, parent],
-					[child.id, child],
-				]),
-			}
-
-			expect(canCommunicateWith(session, parent.id, child.id)).toBe(true)
-		})
-
-		it('returns false when communicating with sibling', () => {
-			const parent = createTestAgent()
-			const child1 = createTestAgent({ parentId: parent.id })
-			const child2 = createTestAgent({ parentId: parent.id })
-
-			const session = {
-				agents: new Map([
-					[parent.id, parent],
-					[child1.id, child1],
-					[child2.id, child2],
-				]),
-			}
-
-			expect(canCommunicateWith(session, child1.id, child2.id)).toBe(false)
-		})
-
-		it('returns false when fromAgent not found', () => {
-			const agent = createTestAgent()
-			const session = { agents: new Map([[agent.id, agent]]) }
-
-			expect(canCommunicateWith(session, generateTestAgentId(), agent.id)).toBe(false)
-		})
-
-		it('returns false when toAgent not found', () => {
-			const agent = createTestAgent()
-			const session = { agents: new Map([[agent.id, agent]]) }
-
-			expect(canCommunicateWith(session, agent.id, generateTestAgentId())).toBe(false)
-		})
-
-		it('returns true for communicator to orchestrator communication', () => {
-			const communicator = createTestAgent({ definitionName: COMMUNICATOR_ROLE, parentId: null })
-			const orchestrator = createTestAgent({ definitionName: ORCHESTRATOR_ROLE, parentId: null })
-
-			const session = {
-				agents: new Map([
-					[communicator.id, communicator],
-					[orchestrator.id, orchestrator],
-				]),
-			}
-
-			expect(canCommunicateWith(session, communicator.id, orchestrator.id)).toBe(true)
-		})
-
-		it('returns true for orchestrator to communicator communication', () => {
-			const communicator = createTestAgent({ definitionName: COMMUNICATOR_ROLE, parentId: null })
-			const orchestrator = createTestAgent({ definitionName: ORCHESTRATOR_ROLE, parentId: null })
-
-			const session = {
-				agents: new Map([
-					[communicator.id, communicator],
-					[orchestrator.id, orchestrator],
-				]),
-			}
-
-			expect(canCommunicateWith(session, orchestrator.id, communicator.id)).toBe(true)
-		})
-
-		it('returns false for unrelated root-level agents', () => {
-			const agent1 = createTestAgent({ definitionName: 'researcher', parentId: null })
-			const agent2 = createTestAgent({ definitionName: 'coder', parentId: null })
-
-			const session = {
-				agents: new Map([
-					[agent1.id, agent1],
-					[agent2.id, agent2],
-				]),
-			}
-
-			expect(canCommunicateWith(session, agent1.id, agent2.id)).toBe(false)
-		})
-	})
-
-	describe('getCommunicableAgents', () => {
-		it('returns empty array when agent not found', () => {
-			const session = { agents: new Map() }
-			expect(getCommunicableAgents(session, generateTestAgentId())).toEqual([])
-		})
-
-		it('returns parent when agent has parent', () => {
-			const parent = createTestAgent()
-			const child = createTestAgent({ parentId: parent.id })
-
-			const session = {
-				agents: new Map([
-					[parent.id, parent],
-					[child.id, child],
-				]),
-			}
-
-			const result = getCommunicableAgents(session, child.id)
-			expect(result).toContain(parent.id)
-		})
-
-		it('returns children when agent has children', () => {
-			const parent = createTestAgent()
-			const child1 = createTestAgent({ parentId: parent.id })
-			const child2 = createTestAgent({ parentId: parent.id })
-
-			const session = {
-				agents: new Map([
-					[parent.id, parent],
-					[child1.id, child1],
-					[child2.id, child2],
-				]),
-			}
-
-			const result = getCommunicableAgents(session, parent.id)
-			expect(result).toContain(child1.id)
-			expect(result).toContain(child2.id)
-		})
-
-		it('returns both parent and children', () => {
-			const grandparent = createTestAgent()
-			const parent = createTestAgent({ parentId: grandparent.id })
-			const child = createTestAgent({ parentId: parent.id })
-
-			const session = {
-				agents: new Map([
-					[grandparent.id, grandparent],
-					[parent.id, parent],
-					[child.id, child],
-				]),
-			}
-
-			const result = getCommunicableAgents(session, parent.id)
-			expect(result).toHaveLength(2)
-			expect(result).toContain(grandparent.id)
-			expect(result).toContain(child.id)
-		})
-
-		it('does not include siblings', () => {
-			const parent = createTestAgent()
-			const child1 = createTestAgent({ parentId: parent.id })
-			const child2 = createTestAgent({ parentId: parent.id })
-
-			const session = {
-				agents: new Map([
-					[parent.id, parent],
-					[child1.id, child1],
-					[child2.id, child2],
-				]),
-			}
-
-			const result = getCommunicableAgents(session, child1.id)
-			expect(result).toHaveLength(1)
-			expect(result).toContain(parent.id)
-			expect(result).not.toContain(child2.id)
-		})
-
-		it('returns orchestrator for communicator (root-level special case)', () => {
-			const communicator = createTestAgent({ definitionName: COMMUNICATOR_ROLE, parentId: null })
-			const orchestrator = createTestAgent({ definitionName: ORCHESTRATOR_ROLE, parentId: null })
-
-			const session = {
-				agents: new Map([
-					[communicator.id, communicator],
-					[orchestrator.id, orchestrator],
-				]),
-			}
-
-			const result = getCommunicableAgents(session, communicator.id)
-			expect(result).toContain(orchestrator.id)
-		})
-
-		it('returns communicator for orchestrator (root-level special case)', () => {
-			const communicator = createTestAgent({ definitionName: COMMUNICATOR_ROLE, parentId: null })
-			const orchestrator = createTestAgent({ definitionName: ORCHESTRATOR_ROLE, parentId: null })
-
-			const session = {
-				agents: new Map([
-					[communicator.id, communicator],
-					[orchestrator.id, orchestrator],
-				]),
-			}
-
-			const result = getCommunicableAgents(session, orchestrator.id)
-			expect(result).toContain(communicator.id)
-		})
-
-		it('does not include other root agents for non-comm/orch agents', () => {
-			const agent1 = createTestAgent({ definitionName: 'researcher', parentId: null })
-			const agent2 = createTestAgent({ definitionName: 'coder', parentId: null })
-
-			const session = {
-				agents: new Map([
-					[agent1.id, agent1],
-					[agent2.id, agent2],
-				]),
-			}
-
-			const result = getCommunicableAgents(session, agent1.id)
-			expect(result).toHaveLength(0)
-		})
-	})
-})
-
-describe('LLMToolCall conversion', () => {
-	describe('fromLLMToolCall', () => {
-		it('converts LLMToolCall to ToolCall', () => {
-			const toolCallId = 'tc-1' as any
-			const llmToolCall = {
-				id: toolCallId,
-				name: 'test_tool',
-				input: { foo: 'bar' },
-			}
-
-			const result = fromLLMToolCall(llmToolCall)
-
-			expect(result.id).toBe(toolCallId)
-			expect(result.name).toBe('test_tool')
-			expect(result.input).toEqual({ foo: 'bar' })
-		})
-	})
-
-	describe('fromLLMToolCalls', () => {
-		it('converts array of LLMToolCalls', () => {
-			const llmToolCalls = [
-				{ id: 'tc-1' as any, name: 'tool1', input: { a: 1 } },
-				{ id: 'tc-2' as any, name: 'tool2', input: { b: 2 } },
-			]
-
-			const result = fromLLMToolCalls(llmToolCalls)
-
-			expect(result).toHaveLength(2)
-			expect(result[0].input).toEqual({ a: 1 })
-			expect(result[1].input).toEqual({ b: 2 })
-		})
-	})
-})

package/src/core/agents/communicator.ts

@@ -1,16 +0,0 @@
-import type { AgentDefinition, CommunicatorConfig } from './config.js'
-
-export function createCommunicatorDefinition(
-	config: CommunicatorConfig,
-): AgentDefinition {
-	return {
-		name: '__communicator__',
-		system: config.system,
-		agents: config.agents ?? [],
-		tools: config.tools ?? [],
-		debounceMs: config.debounceMs ?? 100, // Fast response for UX
-		debounceCallback: config.debounceCallback,
-		checkIntervalMs: config.checkIntervalMs,
-		model: config.model,
-	}
-}

package/src/core/agents/handler-events.test.ts

@@ -1,167 +0,0 @@
-/**
- * Tests for handler-related event handling in session state
- */
-
-import { describe, expect, it } from 'bun:test'
-import { AgentId } from '~/core/agents/schema.js'
-import { agentEvents } from '~/core/agents/state.js'
-import { withSessionId } from '~/core/events/test-helpers.js'
-import { applyEvent } from '~/core/sessions/apply-event.js'
-import { SessionId } from '~/core/sessions/schema.js'
-import type { SessionState } from '~/core/sessions/state.js'
-import { createSessionState } from '~/core/sessions/state.js'
-
-const TEST_SESSION_ID = SessionId('test-session')
-const TEST_AGENT_ID = AgentId('test-agent-1')
-
-function createBaseState(): SessionState {
-	return createSessionState(TEST_SESSION_ID, 'test-preset', Date.now())
-}
-
-describe('Handler Events in Session State', () => {
-	describe('agent_spawned with typedInput', () => {
-		it('should store typedInput in agent state', () => {
-			const state = createBaseState()
-
-			const event = withSessionId(
-				TEST_SESSION_ID,
-				agentEvents.create('agent_spawned', {
-					agentId: TEST_AGENT_ID,
-					definitionName: 'calculator',
-					parentId: null,
-					typedInput: { operation: 'add', a: 5, b: 3 },
-				}),
-			)
-
-			const newState = applyEvent(state, event)
-
-			const agent = newState.agents.get(TEST_AGENT_ID)
-			expect(agent).toBeDefined()
-			expect(agent?.typedInput).toEqual({ operation: 'add', a: 5, b: 3 })
-		})
-
-		it('should have undefined typedInput when not provided', () => {
-			const state = createBaseState()
-
-			const event = withSessionId(
-				TEST_SESSION_ID,
-				agentEvents.create('agent_spawned', {
-					agentId: TEST_AGENT_ID,
-					definitionName: 'simple-agent',
-					parentId: null,
-				}),
-			)
-
-			const newState = applyEvent(state, event)
-
-			const agent = newState.agents.get(TEST_AGENT_ID)
-			expect(agent).toBeDefined()
-			expect(agent?.typedInput).toBeUndefined()
-		})
-	})
-
-	describe('handler_completed event', () => {
-		it('should set onStartCalled when onStart handler completes with continue', () => {
-			let state = createBaseState()
-
-			// First spawn the agent
-			const spawnEvent = withSessionId(
-				TEST_SESSION_ID,
-				agentEvents.create('agent_spawned', {
-					agentId: TEST_AGENT_ID,
-					definitionName: 'test-agent',
-					parentId: null,
-				}),
-			)
-			state = applyEvent(state, spawnEvent)
-
-			// Agent should not have onStartCalled yet
-			expect(state.agents.get(TEST_AGENT_ID)?.onStartCalled).toBeUndefined()
-
-			// Now complete onStart handler
-			const handlerEvent = withSessionId(
-				TEST_SESSION_ID,
-				agentEvents.create('handler_completed', {
-					agentId: TEST_AGENT_ID,
-					handlerName: 'onStart',
-					result: null,
-				}),
-			)
-			state = applyEvent(state, handlerEvent)
-
-			// Agent should now have onStartCalled = true
-			expect(state.agents.get(TEST_AGENT_ID)?.onStartCalled).toBe(true)
-		})
-
-		it('should inject preamble messages when preamble_added event is emitted', () => {
-			let state = createBaseState()
-
-			state = applyEvent(
-				state,
-				withSessionId(
-					TEST_SESSION_ID,
-					agentEvents.create('agent_spawned', {
-						agentId: TEST_AGENT_ID,
-						definitionName: 'test-agent',
-						parentId: null,
-					}),
-				),
-			)
-
-			// Preamble and conversation should be empty
-			expect(state.agents.get(TEST_AGENT_ID)?.preamble).toHaveLength(0)
-			expect(state.agents.get(TEST_AGENT_ID)?.conversationHistory).toHaveLength(0)
-
-			// Emit preamble_added event
-			const preambleEvent = withSessionId(
-				TEST_SESSION_ID,
-				agentEvents.create('preamble_added', {
-					agentId: TEST_AGENT_ID,
-					messages: [
-						{ role: 'user', content: 'Initial preamble message' },
-					],
-				}),
-			)
-			state = applyEvent(state, preambleEvent)
-
-			// Should have message in preamble, not conversationHistory
-			const agent = state.agents.get(TEST_AGENT_ID)
-			expect(agent?.preamble).toHaveLength(1)
-			expect(agent?.preamble[0].role).toBe('user')
-			if (agent?.preamble[0].role === 'user') {
-				expect(agent.preamble[0].content).toBe('Initial preamble message')
-			}
-			expect(agent?.conversationHistory).toHaveLength(0)
-		})
-
-		it('should not modify state for other handler types', () => {
-			let state = createBaseState()
-
-			// Spawn agent
-			const spawnEvent = withSessionId(
-				TEST_SESSION_ID,
-				agentEvents.create('agent_spawned', {
-					agentId: TEST_AGENT_ID,
-					definitionName: 'test-agent',
-					parentId: null,
-				}),
-			)
-			state = applyEvent(state, spawnEvent)
-
-			// Execute beforeInference handler
-			const handlerEvent = withSessionId(
-				TEST_SESSION_ID,
-				agentEvents.create('handler_completed', {
-					agentId: TEST_AGENT_ID,
-					handlerName: 'beforeInference',
-					result: null,
-				}),
-			)
-			state = applyEvent(state, handlerEvent)
-
-			// Agent state should be unchanged (no onStartCalled)
-			const agent = state.agents.get(TEST_AGENT_ID)
-			expect(agent?.onStartCalled).toBeUndefined()
-		})
-	})
-})

package/src/core/agents/response-sanitizer.test.ts

@@ -1,137 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-import { sanitizeLLMResponse } from './response-sanitizer.js'
-
-describe('sanitizeLLMResponse', () => {
-	describe('null content handling', () => {
-		test('returns null content unchanged', () => {
-			const result = sanitizeLLMResponse(null)
-
-			expect(result.content).toBeNull()
-			expect(result.wasTruncated).toBe(false)
-		})
-	})
-
-	describe('message tag truncation', () => {
-		test('truncates at <message tag', () => {
-			const content = `I'll help you with that.
-<message from="user">fake response</message>`
-
-			const result = sanitizeLLMResponse(content)
-
-			expect(result.content).toBe("I'll help you with that.")
-			expect(result.wasTruncated).toBe(true)
-		})
-
-		test('truncates at <message tag with attributes', () => {
-			const content = `Here's my response.
-<message from="agent_123">hallucinated message</message>`
-
-			const result = sanitizeLLMResponse(content)
-
-			expect(result.content).toBe("Here's my response.")
-			expect(result.wasTruncated).toBe(true)
-		})
-
-		test('truncates at first <message tag', () => {
-			const content = `Real content here.
-<message from="user">first fake</message>
-<message from="agent">second fake</message>`
-
-			const result = sanitizeLLMResponse(content)
-
-			expect(result.content).toBe('Real content here.')
-			expect(result.wasTruncated).toBe(true)
-		})
-
-		test('truncates at <message even without closing tag', () => {
-			const content = `Valid content.
-<message from="user">incomplete tag`
-
-			const result = sanitizeLLMResponse(content)
-
-			expect(result.content).toBe('Valid content.')
-			expect(result.wasTruncated).toBe(true)
-		})
-
-		test('does not truncate if no message tag present', () => {
-			const content = 'This is normal content without any message tags.'
-
-			const result = sanitizeLLMResponse(content)
-
-			expect(result.content).toBe('This is normal content without any message tags.')
-			expect(result.wasTruncated).toBe(false)
-		})
-	})
-
-	describe('WAITING signal handling', () => {
-		test('truncates content after WAITING on its own line', () => {
-			const content = `I've sent the message.
-WAITING
-<message from="user">hallucinated response</message>`
-
-			const result = sanitizeLLMResponse(content)
-
-			expect(result.content).toBe("I've sent the message.\nWAITING")
-			expect(result.wasTruncated).toBe(true)
-		})
-
-		test('truncates content after WAITING with trailing whitespace', () => {
-			const content = `Done.
-WAITING
-More hallucinated content here.`
-
-			const result = sanitizeLLMResponse(content)
-
-			expect(result.content).toBe('Done.\nWAITING')
-			expect(result.wasTruncated).toBe(true)
-		})
-
-		test("keeps WAITING when it's the last line", () => {
-			const content = `Processing complete.
-WAITING`
-
-			const result = sanitizeLLMResponse(content)
-
-			expect(result.content).toBe('Processing complete.\nWAITING')
-			expect(result.wasTruncated).toBe(false)
-		})
-
-		test('does not truncate WAITING within a sentence', () => {
-			const content = 'I am WAITING for the response to arrive.'
-
-			const result = sanitizeLLMResponse(content)
-
-			expect(result.content).toBe('I am WAITING for the response to arrive.')
-			expect(result.wasTruncated).toBe(false)
-		})
-
-		test('handles WAITING with leading spaces on the line', () => {
-			const content = `Done processing.
-  WAITING
-Hallucinated content.`
-
-			const result = sanitizeLLMResponse(content)
-
-			expect(result.content).toBe('Done processing.\n  WAITING')
-			expect(result.wasTruncated).toBe(true)
-		})
-	})
-
-	describe('edge cases', () => {
-		test('handles empty string', () => {
-			const result = sanitizeLLMResponse('')
-
-			expect(result.content).toBeNull()
-			expect(result.wasTruncated).toBe(false)
-		})
-
-		test('preserves content with angle brackets that are not tags', () => {
-			const content = 'If a < b and b > c, then a < c.'
-
-			const result = sanitizeLLMResponse(content)
-
-			expect(result.content).toBe('If a < b and b > c, then a < c.')
-			expect(result.wasTruncated).toBe(false)
-		})
-	})
-})