@roj-ai/sdk 0.0.2

package/src/plugins/agents/index.ts

@@ -0,0 +1,2 @@
+export { agentsPlugin } from './plugin.js'
+export type { AgentsPluginConfig, SpawnableAgentInfo } from './plugin.js'

package/src/plugins/agents/plugin.ts

@@ -0,0 +1,242 @@
+/**
+ * Agents Plugin - Spawn tools for child agent creation + agent management methods
+ *
+ * Generates `start_<agent_name>` tools for each spawnable agent defined in the agent config.
+ * Tool executors delegate to the plugin's own `spawn` method via ctx.self.spawn().
+ *
+ * Also provides session-level methods for agent management:
+ * - agents.spawn — spawn agent manually
+ * - agents.resume — resume paused agent
+ * - agents.pause — pause agent
+ */
+
+import z from 'zod/v4'
+import { AgentId, agentIdSchema, generateAgentId } from '~/core/agents/schema.js'
+import { agentEvents } from '~/core/agents/state.js'
+import { AgentErrors, ValidationErrors } from '~/core/errors.js'
+import { definePlugin } from '~/core/plugins/index.js'
+import { getNextAgentSeq } from '~/core/sessions/state.js'
+import { createTool } from '~/core/tools/definition.js'
+import { Err, Ok } from '~/lib/utils/result.js'
+import { mailboxPlugin } from '~/plugins/mailbox/plugin.js'
+
+/**
+ * Information about a spawnable agent, used to generate typed start_<name> tools.
+ */
+export interface SpawnableAgentInfo {
+	name: string
+	description?: string
+	inputSchema?: z.ZodType<unknown>
+}
+
+/**
+ * Session-wide agents plugin configuration.
+ * Maps agent name to its spawn info (description, input schema).
+ */
+export interface AgentsPluginConfig {
+	/** Map of agent name → spawn info for generating typed tools */
+	agentDefinitions: Map<string, SpawnableAgentInfo>
+}
+
+/**
+ * Creates the Zod schema for a start_<agent_name> tool.
+ * If the agent has an inputSchema, includes a typed `input` field.
+ */
+function createStartAgentSchema(agent: SpawnableAgentInfo) {
+	if (agent.inputSchema) {
+		return z.object({
+			message: z.string().describe('Task description for the agent'),
+			input: agent.inputSchema.describe('Typed input for the agent'),
+		})
+	}
+	return z.object({
+		message: z.string().describe('Task description for the agent'),
+	})
+}
+
+export const agentsPlugin = definePlugin('agents')
+	.pluginConfig<AgentsPluginConfig>()
+	.dependencies([mailboxPlugin])
+	.isEnabled((ctx) => {
+		return ctx.agentConfig.spawnableAgents.length > 0
+	})
+	.method('spawn', {
+		input: z.object({
+			definitionName: z.string(),
+			parentId: agentIdSchema,
+			message: z.string().optional(),
+			typedInput: z.unknown().optional(),
+		}),
+		output: z.object({
+			agentId: agentIdSchema,
+		}),
+		handler: async (ctx, input) => {
+			const parentId = AgentId(input.parentId)
+
+			// Validate parent exists
+			if (!ctx.sessionState.agents.has(parentId)) {
+				return Err(AgentErrors.notFound(String(parentId)))
+			}
+
+			// Validate definition exists
+			if (!ctx.pluginConfig.agentDefinitions.has(input.definitionName)) {
+				return Err(ValidationErrors.invalid(`Agent definition not found: ${input.definitionName}`))
+			}
+
+			// Generate agent ID and emit spawn event
+			const agentId = generateAgentId(input.definitionName, getNextAgentSeq(ctx.sessionState, input.definitionName))
+			await ctx.emitEvent(agentEvents.create('agent_spawned', {
+				agentId,
+				definitionName: input.definitionName,
+				parentId,
+				...(input.typedInput !== undefined && { typedInput: input.typedInput }),
+			}))
+
+			// Optionally send initial message via mailbox plugin
+			if (input.message) {
+				const sendResult = await ctx.deps.mailbox.send({
+					fromAgentId: parentId,
+					toAgentId: agentId,
+					content: input.message,
+				})
+				if (!sendResult.ok) return sendResult
+			}
+
+			ctx.logger.info('Agent spawned via agents.spawn', {
+				agentId,
+				definitionName: input.definitionName,
+				parentId: input.parentId,
+			})
+
+			return Ok({ agentId })
+		},
+	})
+	.method('resume', {
+		input: z.object({
+			agentId: agentIdSchema,
+		}),
+		output: z.object({}),
+		handler: async (ctx, input) => {
+			const agentId = AgentId(input.agentId)
+
+			// Validate agent exists and is paused or errored
+			const agentState = ctx.sessionState.agents.get(agentId)
+			if (!agentState) {
+				return Err(AgentErrors.notFound(String(agentId)))
+			}
+			if (agentState.status !== 'paused' && agentState.status !== 'errored') {
+				return Err(ValidationErrors.invalid('Agent is not paused or errored'))
+			}
+
+			await ctx.emitEvent(agentEvents.create('agent_resumed', { agentId }))
+			ctx.scheduleAgent(agentId)
+
+			ctx.logger.info('Agent resumed via agents.resume', { agentId: input.agentId })
+
+			return Ok({})
+		},
+	})
+	.method('pause', {
+		input: z.object({
+			agentId: agentIdSchema,
+			message: z.string().optional(),
+		}),
+		output: z.object({}),
+		handler: async (ctx, input) => {
+			const agentId = AgentId(input.agentId)
+
+			// Validate agent exists and is not already paused
+			const agentState = ctx.sessionState.agents.get(agentId)
+			if (!agentState) {
+				return Err(AgentErrors.notFound(String(agentId)))
+			}
+			if (agentState.status === 'paused') {
+				return Err(ValidationErrors.invalid('Agent is already paused'))
+			}
+
+			await ctx.emitEvent(agentEvents.create('agent_paused', {
+				agentId,
+				reason: 'manual',
+				message: input.message,
+			}))
+
+			ctx.logger.info('Agent paused via agents.pause', { agentId: input.agentId })
+
+			return Ok({})
+		},
+	})
+	.method('rewind', {
+		input: z.object({
+			agentId: agentIdSchema,
+			messageIndex: z.number().int().min(0),
+		}),
+		output: z.object({}),
+		handler: async (ctx, input) => {
+			const agentId = AgentId(input.agentId)
+			const agentState = ctx.sessionState.agents.get(agentId)
+			if (!agentState) {
+				return Err(AgentErrors.notFound(String(agentId)))
+			}
+
+			if (input.messageIndex >= agentState.conversationHistory.length) {
+				return Err(ValidationErrors.invalid('messageIndex out of range'))
+			}
+
+			const deleteCount = agentState.conversationHistory.length - input.messageIndex
+
+			await ctx.emitEvent(agentEvents.create('agent_conversation_spliced', {
+				agentId,
+				start: input.messageIndex,
+				deleteCount,
+			}))
+			ctx.scheduleAgent(agentId)
+
+			ctx.logger.info('Agent rewound via agents.rewind', { agentId: input.agentId, messageIndex: input.messageIndex })
+
+			return Ok({})
+		},
+	})
+	.systemPrompt(() => {
+		return `## Working with Child Agents
+
+- **New task** → spawn a new agent using \`start_<agent_name>\`. You will receive the agent's ID in the result — use it with \`send_message\` for follow-up communication.
+- **Follow-up on an existing task** → send a message to the existing agent via \`send_message\` with the agent's ID. Do NOT spawn a new agent for feedback, corrections, or additional instructions on a task already assigned.
+- Spawned agents communicate back to you via \`send_message\`. Check your incoming messages for their results and progress updates.`
+	})
+	.tools((ctx) => {
+		const spawnableAgents = ctx.agentConfig.spawnableAgents
+		const agentDefs = ctx.pluginConfig.agentDefinitions
+
+		return spawnableAgents.map((agentName) => {
+			const agentInfo = agentDefs.get(agentName) ?? { name: agentName }
+			const toolName = `start_${agentInfo.name}`
+			const description = agentInfo.description
+				? `Start a new ${agentInfo.name} agent. ${agentInfo.description} Use send_message with the returned agent ID for follow-up communication. Only spawn for NEW tasks — for follow-ups on existing tasks, use send_message to the existing agent.`
+				: `Start a new ${agentInfo.name} agent to handle a specific task. Use send_message with the returned agent ID for follow-up communication. Only spawn for NEW tasks — for follow-ups on existing tasks, use send_message to the existing agent.`
+
+			return createTool({
+				name: toolName,
+				description,
+				input: createStartAgentSchema(agentInfo),
+				execute: async (input) => {
+					const typedInput = 'input' in input ? input.input : undefined
+					const messageContent = typedInput !== undefined ? JSON.stringify(typedInput) : input.message
+
+					const result = await ctx.self.spawn({
+						definitionName: agentInfo.name,
+						parentId: ctx.agentId,
+						message: messageContent,
+						...(typedInput !== undefined && { typedInput }),
+					})
+
+					if (!result.ok) {
+						return Err({ message: result.error.message, recoverable: false })
+					}
+
+					const spawnedId = result.value.agentId
+					return Ok(`Agent "${agentInfo.name}" spawned with ID ${spawnedId}. Use send_message with to: "${spawnedId}" to communicate with it.`)
+				},
+			})
+		})
+	})
+	.build()

package/src/plugins/context-compact/context-compact.integration.test.ts

@@ -0,0 +1,207 @@
+import { describe, expect, it } from 'bun:test'
+import { contextEvents } from '~/core/context/state.js'
+import { MockLLMProvider } from '~/core/llm/mock.js'
+import { ModelId } from '~/core/llm/schema.js'
+import { createTestPreset, TestHarness } from '~/testing/index.js'
+import { contextCompactPlugin } from './index.js'
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function createCompactPreset(maxTokens: number, overrides?: Parameters<typeof createTestPreset>[0]) {
+	return createTestPreset({
+		...overrides,
+		plugins: [
+			contextCompactPlugin.configure({
+				compaction: {
+					model: ModelId('mock'),
+					maxTokens,
+					keepRecentMessages: 2,
+				},
+			}),
+			...(overrides?.plugins ?? []),
+		],
+	})
+}
+
+function createCompactHarness(options: Omit<ConstructorParameters<typeof TestHarness>[0], 'systemPlugins'>) {
+	return new TestHarness({ ...options, systemPlugins: [contextCompactPlugin] })
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe('context-compact plugin', () => {
+	// =========================================================================
+	// Compaction triggering
+	// =========================================================================
+
+	describe('compaction triggering', () => {
+		it('conversation exceeding maxTokens → context_compacted event emitted', async () => {
+			// Use very low maxTokens to trigger compaction.
+			// conversationHistory is populated by inference_completed events:
+			//   After 1st round: [user1, assist1] (2 messages)
+			//   After 2nd round: [user1, assist1, user2, assist2] (4 messages)
+			// With keepRecentMessages=2, the 3rd beforeInference sees 4 messages,
+			// compacts the first 2, and calls LLM for summarization.
+			const harness = createCompactHarness({
+				presets: [createCompactPreset(10)],
+				mockHandler: (request) => {
+					// Compaction requests use CONTEXT_SUMMARY_PROMPT which contains "summarizer".
+					if (request.systemPrompt.includes('summary') || request.systemPrompt.includes('Summarize')) {
+						return {
+							content: 'Summary of conversation so far.',
+							toolCalls: [],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+
+					// Regular agent inference
+					return {
+						content: 'Agent response with some content to increase token count.',
+						toolCalls: [],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				},
+			})
+
+			const session = await harness.createSession('test')
+
+			// Build up conversation history across multiple rounds
+			await session.sendAndWaitForIdle('First message')
+			await session.sendAndWaitForIdle('Second message')
+			// Third message — beforeInference sees 4+ messages, compacts older ones
+			await session.sendAndWaitForIdle('Third message to trigger actual compaction')
+
+			const compactedEvents = await session.getEventsByType(contextEvents, 'context_compacted')
+			const actualCompaction = compactedEvents.find((e) => e.messagesRemoved > 0)
+			expect(actualCompaction).toBeDefined()
+			expect(actualCompaction!.compactedContent).toBe('Summary of conversation so far.')
+			expect(actualCompaction!.messagesRemoved).toBeGreaterThan(0)
+
+			await harness.shutdown()
+		})
+
+		it('short conversation under limit → no compaction', async () => {
+			// Use a very high maxTokens so compaction is never triggered
+			const harness = createCompactHarness({
+				presets: [createCompactPreset(100000)],
+				llmProvider: MockLLMProvider.withFixedResponse({ content: 'Short reply', toolCalls: [] }),
+			})
+
+			const session = await harness.createSession('test')
+			await session.sendAndWaitForIdle('Short message')
+			await session.sendAndWaitForIdle('Another short message')
+
+			const compactedEvents = await session.getEventsByType(contextEvents, 'context_compacted')
+			expect(compactedEvents).toHaveLength(0)
+
+			await harness.shutdown()
+		})
+	})
+
+	// =========================================================================
+	// Compaction behavior
+	// =========================================================================
+
+	describe('compaction behavior', () => {
+		it('after compaction, subsequent inference sees fewer messages', async () => {
+			let inferenceCallCount = 0
+			let messagesInThirdCall = 0
+
+			const harness = createCompactHarness({
+				presets: [createCompactPreset(10)],
+				mockHandler: (request) => {
+					inferenceCallCount++
+
+					// Summarization requests (from context-compact plugin)
+					if (request.systemPrompt.includes('summary') || request.systemPrompt.includes('Summarize')) {
+						return {
+							content: 'Conversation summary.',
+							toolCalls: [],
+							finishReason: 'stop',
+							metrics: MockLLMProvider.defaultMetrics(),
+						}
+					}
+
+					// Track messages in later calls
+					if (inferenceCallCount >= 3) {
+						messagesInThirdCall = request.messages.length
+					}
+
+					return {
+						content: 'Response with enough content to push tokens over the limit for compaction.',
+						toolCalls: [],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				},
+			})
+
+			const session = await harness.createSession('test')
+
+			// First message — builds history
+			await session.sendAndWaitForIdle('First long message with plenty of content')
+			// Second message — triggers compaction, then inference with compacted history
+			await session.sendAndWaitForIdle('Second long message to trigger compaction')
+
+			// After compaction, the conversation history should be shorter
+			const compactedEvents = await session.getEventsByType(contextEvents, 'context_compacted')
+			expect(compactedEvents.length).toBeGreaterThanOrEqual(1)
+
+			await harness.shutdown()
+		})
+	})
+
+	// =========================================================================
+	// Compaction failure
+	// =========================================================================
+
+	describe('compaction failure', () => {
+		it('LLM fails during summarization → compaction skipped, no crash', async () => {
+			let regularCallCount = 0
+
+			const harness = createCompactHarness({
+				presets: [createCompactPreset(10)],
+				mockHandler: (request) => {
+					// Summarization requests — throw to simulate LLM failure.
+					// MockLLMProvider only returns Err() when the handler throws.
+					if (request.systemPrompt.includes('summary') || request.systemPrompt.includes('Summarize')) {
+						throw { type: 'server_error', message: 'LLM summarization failed' }
+					}
+
+					// Regular inference
+					regularCallCount++
+					return {
+						content: 'Agent response despite compaction failure. Content to push tokens.',
+						toolCalls: [],
+						finishReason: 'stop',
+						metrics: MockLLMProvider.defaultMetrics(),
+					}
+				},
+			})
+
+			const session = await harness.createSession('test')
+
+			// Build up conversation history so actual compaction is attempted
+			await session.sendAndWaitForIdle('First message')
+			await session.sendAndWaitForIdle('Second message')
+			// Third message — compaction attempt on 4+ messages will call LLM and fail
+			await session.sendAndWaitForIdle('Third message triggers failed compaction')
+
+			// No compaction event with actual messages removed (LLM summarization failed)
+			const compactedEvents = await session.getEventsByType(contextEvents, 'context_compacted')
+			const actualCompactions = compactedEvents.filter((e) => e.messagesRemoved > 0)
+			expect(actualCompactions).toHaveLength(0)
+
+			// But the agent should still have responded (graceful degradation)
+			expect(regularCallCount).toBeGreaterThanOrEqual(3)
+
+			await harness.shutdown()
+		})
+	})
+})