@roj-ai/sdk 0.0.2

package/src/plugins/limits-guard/plugin.ts

@@ -0,0 +1,306 @@
+import type { AgentId } from '~/core/agents/schema.js'
+import { agentEvents } from '~/core/agents/state.js'
+import { llmEvents } from '~/core/llm/state.js'
+import { definePlugin } from '~/core/plugins/plugin-builder.js'
+import { selectPluginState } from '~/core/sessions/reducer.js'
+import type { SessionState } from '~/core/sessions/state.js'
+import { toolEvents } from '~/core/tools/state.js'
+import { responseFingerprint, toolCallFingerprint } from '~/lib/utils/hash.js'
+import { mailboxEvents } from '~/plugins/mailbox/state.js'
+import type { AgentLimits } from './config.js'
+import { checkLimits, countConsecutiveTailDuplicates, resolveAgentLimits } from './limit-guard.js'
+
+// ============================================================================
+// Agent counters (state)
+// ============================================================================
+
+export interface AgentCounters {
+	inferenceCount: number
+	toolCallCount: number
+	spawnedAgentCount: number
+	messagesSentCount: number
+	/** Tool name → consecutive failure count + last error message. Reset on success. */
+	consecutiveToolFailures: Record<string, { count: number; lastError: string }>
+	/** Ring buffer of last 20 tool call fingerprints ("toolName:inputHash") */
+	recentToolCallHashes: string[]
+	/** Ring buffer of last 10 response content hashes (text-only responses without tool calls) */
+	recentResponseHashes: string[]
+}
+
+export const createAgentCounters = (): AgentCounters => ({
+	inferenceCount: 0,
+	toolCallCount: 0,
+	spawnedAgentCount: 0,
+	messagesSentCount: 0,
+	consecutiveToolFailures: {},
+	recentToolCallHashes: [],
+	recentResponseHashes: [],
+})
+
+/**
+ * Extract agent counters from session state (for external consumers).
+ */
+export function selectAgentCounters(sessionState: SessionState, agentId: AgentId): AgentCounters {
+	return selectPluginState<Map<AgentId, AgentCounters>>(sessionState, 'agentLimits')?.get(agentId) ?? createAgentCounters()
+}
+
+// ============================================================================
+// Limit warning event
+// ============================================================================
+
+import z from 'zod/v4'
+import { agentIdSchema } from '~/core/agents/schema.js'
+import { createEventsFactory } from '~/core/events/types.js'
+
+export const limitsEvents = createEventsFactory({
+	events: {
+		limit_warning: z.object({
+			agentId: agentIdSchema,
+			limitName: z.string(),
+			currentValue: z.number(),
+			hardLimit: z.number(),
+			message: z.string(),
+		}),
+	},
+})
+
+export type LimitWarningEvent = (typeof limitsEvents)['Events']['limit_warning']
+
+// ============================================================================
+// Helper
+// ============================================================================
+
+/**
+ * Resolve tool name from agent state for tool_completed/tool_failed events.
+ * Must run BEFORE core reducer (which clears executingToolCall).
+ */
+function resolveToolName(
+	sessionState: { agents: Map<AgentId, { executingToolCall?: { toolName: string }; pendingToolCalls: Array<{ id: string; name: string }> }> },
+	agentId: AgentId,
+	toolCallId: string,
+): string {
+	const agent = sessionState.agents.get(agentId)
+	if (!agent) return 'unknown'
+	return agent.executingToolCall?.toolName
+		?? agent.pendingToolCalls.find((tc) => tc.id === toolCallId)?.name
+		?? 'unknown'
+}
+
+// ============================================================================
+// Plugin
+// ============================================================================
+
+export interface LimitsAgentConfig {
+	limits?: AgentLimits
+}
+
+export const limitsGuardPlugin = definePlugin('limits-guard')
+	.events([agentEvents, llmEvents, toolEvents, mailboxEvents])
+	.state({
+		key: 'agentLimits',
+		initial: (): Map<AgentId, AgentCounters> => new Map(),
+		reduce: (limits, event, sessionState) => {
+			switch (event.type) {
+				case 'agent_spawned': {
+					const newLimits = new Map(limits)
+					newLimits.set(event.agentId, createAgentCounters())
+
+					// Increment parent's spawnedAgentCount
+					if (event.parentId) {
+						const parentCounters = newLimits.get(event.parentId)
+						if (parentCounters) {
+							newLimits.set(event.parentId, {
+								...parentCounters,
+								spawnedAgentCount: parentCounters.spawnedAgentCount + 1,
+							})
+						}
+					}
+
+					return newLimits
+				}
+
+				case 'mailbox_message': {
+					// Increment sender's messagesSentCount if sender is an agent
+					const senderAgentId = typeof event.message.from === 'string' && event.message.from !== 'user'
+						? event.message.from
+						: null
+					if (!senderAgentId) return limits
+
+					const senderCounters = limits.get(senderAgentId as AgentId)
+					if (!senderCounters) return limits
+
+					const newLimits = new Map(limits)
+					newLimits.set(senderAgentId as AgentId, {
+						...senderCounters,
+						messagesSentCount: senderCounters.messagesSentCount + 1,
+					})
+					return newLimits
+				}
+
+				case 'inference_completed': {
+					const counters = limits.get(event.agentId)
+					if (!counters) return limits
+
+					const hasToolCalls = event.response.toolCalls.length > 0
+					let newRecentResponseHashes = counters.recentResponseHashes
+
+					if (!hasToolCalls) {
+						const isWaiting = /^\s*WAITING\s*$/.test(event.response.content ?? '')
+						if (!isWaiting) {
+							const hash = responseFingerprint(event.response.content)
+							newRecentResponseHashes = [...newRecentResponseHashes, hash].slice(-10)
+						}
+					}
+
+					const newLimits = new Map(limits)
+					newLimits.set(event.agentId, {
+						...counters,
+						inferenceCount: counters.inferenceCount + 1,
+						recentResponseHashes: newRecentResponseHashes,
+					})
+					return newLimits
+				}
+
+				case 'tool_started': {
+					const counters = limits.get(event.agentId)
+					if (!counters) return limits
+
+					const fingerprint = toolCallFingerprint(event.toolName, event.input)
+					const newLimits = new Map(limits)
+					newLimits.set(event.agentId, {
+						...counters,
+						toolCallCount: counters.toolCallCount + 1,
+						recentToolCallHashes: [...counters.recentToolCallHashes, fingerprint].slice(-20),
+					})
+					return newLimits
+				}
+
+				case 'tool_completed': {
+					const counters = limits.get(event.agentId)
+					if (!counters) return limits
+
+					// Resolve tool name from agent state (must run before core clears executingToolCall)
+					const toolName = resolveToolName(sessionState, event.agentId, event.toolCallId)
+					const { [toolName]: _, ...restFailures } = counters.consecutiveToolFailures
+
+					const newLimits = new Map(limits)
+					newLimits.set(event.agentId, {
+						...counters,
+						consecutiveToolFailures: restFailures,
+					})
+					return newLimits
+				}
+
+				case 'tool_failed': {
+					const counters = limits.get(event.agentId)
+					if (!counters) return limits
+
+					// Resolve tool name from agent state (must run before core clears executingToolCall)
+					const toolName = resolveToolName(sessionState, event.agentId, event.toolCallId)
+					const currentEntry = counters.consecutiveToolFailures[toolName]
+
+					const newLimits = new Map(limits)
+					newLimits.set(event.agentId, {
+						...counters,
+						consecutiveToolFailures: {
+							...counters.consecutiveToolFailures,
+							[toolName]: { count: (currentEntry?.count ?? 0) + 1, lastError: event.error },
+						},
+					})
+					return newLimits
+				}
+
+				case 'agent_resumed': {
+					const counters = limits.get(event.agentId)
+					if (!counters) return limits
+
+					const newLimits = new Map(limits)
+					newLimits.set(event.agentId, {
+						...counters,
+						inferenceCount: 0,
+						toolCallCount: 0,
+						spawnedAgentCount: 0,
+						messagesSentCount: 0,
+						consecutiveToolFailures: {},
+						recentToolCallHashes: [],
+						recentResponseHashes: [],
+					})
+					return newLimits
+				}
+
+				default:
+					return limits
+			}
+		},
+	})
+	.agentConfig<LimitsAgentConfig>()
+	.hook('afterInference', async (ctx) => {
+		const resolvedLimits = resolveAgentLimits(ctx.pluginAgentConfig?.limits)
+		const counters = ctx.pluginState.get(ctx.agentId)
+		if (!counters) return null
+
+		// The inference_completed event hasn't been emitted yet, so project
+		// what the counters will be after it's processed by the reducer.
+		const hasToolCalls = ctx.response.toolCalls.length > 0
+		const projected: AgentCounters = {
+			...counters,
+			inferenceCount: counters.inferenceCount + 1,
+			recentResponseHashes: hasToolCalls
+				? counters.recentResponseHashes
+				: [...counters.recentResponseHashes, responseFingerprint(ctx.response.content)].slice(-10),
+		}
+
+		const limitCheck = checkLimits(projected, resolvedLimits)
+
+		if (limitCheck.status === 'hard_limit') {
+			return { action: 'pause', reason: limitCheck.reason }
+		}
+
+		return null
+	})
+	.status((ctx) => {
+		const resolvedLimits = resolveAgentLimits(ctx.pluginAgentConfig?.limits)
+		const counters = ctx.pluginState.get(ctx.agentId)
+		if (!counters) return null
+
+		const parts: string[] = []
+
+		// Consecutive failures of the same tool — surface from count=2, well before the
+		// hard limit. The agent sees what it tried, how many times, and with what error,
+		// so it can change strategy rather than blindly retry.
+		for (const [toolName, entry] of Object.entries(counters.consecutiveToolFailures)) {
+			if (entry.count >= 2) {
+				const lastError = entry.lastError.length > 600
+					? entry.lastError.slice(0, 600) + '… [truncated]'
+					: entry.lastError
+				parts.push(
+					`⚠️ Tool "${toolName}" has failed ${entry.count} times in a row (hard limit: ${resolvedLimits.maxConsecutiveToolFailures}). `
+						+ `Last error: ${lastError}\n`
+						+ `Do NOT retry the same call again. Diagnose the root cause, change approach, or stop and report what you tried.`,
+				)
+			}
+		}
+
+		// Same tool call with identical arguments repeated — even successful calls
+		// that produce no new information are a waste. Warn from 2 repeats.
+		const repeatedCalls = countConsecutiveTailDuplicates(counters.recentToolCallHashes)
+		if (repeatedCalls >= 2) {
+			parts.push(
+				`⚠️ You have called the same tool with identical arguments ${repeatedCalls} times in a row `
+					+ `(hard limit: ${resolvedLimits.maxRepeatedToolCalls}). `
+					+ `Either the call is idempotent (stop repeating it) or your approach isn't working (change strategy).`,
+			)
+		}
+
+		// Existing counter-based soft warnings (maxTurns, maxToolCalls, etc.)
+		const limitCheck = checkLimits(counters, resolvedLimits)
+		if (limitCheck.status === 'soft_warning') {
+			parts.push(
+				`⚠️ Approaching ${limitCheck.limitName} limit: ${limitCheck.currentValue}/${limitCheck.hardLimit}. `
+					+ `Wrap up your current task or you will be stopped.`,
+			)
+		}
+
+		return parts.length > 0 ? parts.join('\n\n') : null
+	})
+	.build()

package/src/plugins/llm-debug/index.ts

@@ -0,0 +1 @@
+export { llmDebugPlugin } from './plugin.js'

package/src/plugins/llm-debug/llm-debug.integration.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, it } from 'bun:test'
+import z from 'zod/v4'
+import { LLMLogger } from '~/core/llm/logger.js'
+import { MockLLMProvider } from '~/core/llm/mock.js'
+import { ToolCallId } from '~/core/tools/schema.js'
+import { createNodeFileSystem } from '~/testing/node-platform.js'
+import { createTestPreset, TestHarness } from '~/testing/index.js'
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function okValue<T>(result: { ok: boolean; value?: unknown }, schema: z.ZodType<T>): T {
+	expect(result.ok).toBe(true)
+	if (!result.ok) throw new Error('Expected ok result')
+	return schema.parse(result.value)
+}
+
+const callEntrySchema = z.object({
+	id: z.string(),
+	status: z.string(),
+	response: z.object({
+		content: z.union([z.string(), z.null()]),
+		toolCalls: z.array(z.unknown()),
+		finishReason: z.string(),
+	}).passthrough(),
+}).passthrough()
+
+const getCallsSchema = z.object({
+	total: z.number(),
+	calls: z.array(callEntrySchema),
+})
+
+const getCallSchema = z.object({
+	id: z.string(),
+	status: z.string(),
+	request: z.object({
+		model: z.string(),
+		systemPrompt: z.string(),
+		messages: z.array(z.unknown()),
+	}).passthrough(),
+	response: z.object({
+		content: z.union([z.string(), z.null()]),
+		toolCalls: z.array(z.unknown()),
+		finishReason: z.string(),
+	}).passthrough(),
+	metrics: z.object({
+		promptTokens: z.number(),
+		completionTokens: z.number(),
+		totalTokens: z.number(),
+		latencyMs: z.number(),
+	}).passthrough(),
+}).passthrough()
+
+function createHarnessWithLogger(options: { llmProvider?: MockLLMProvider } = {}) {
+	const basePath = `/tmp/roj-test-llm-debug-${Math.random().toString(36).slice(2)}`
+	const llmLogger = new LLMLogger({ basePath, enabled: true, fs: createNodeFileSystem() })
+	const harness = new TestHarness({
+		presets: [createTestPreset()],
+		llmProvider: options.llmProvider,
+		llmLogger,
+	})
+	return harness
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe('llm-debug plugin', () => {
+	it('after inference → getCalls returns at least one call entry', async () => {
+		const harness = createHarnessWithLogger({
+			llmProvider: MockLLMProvider.withFixedResponse({ content: 'Hello!', toolCalls: [] }),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Hi')
+
+		const result = await session.callPluginMethod('llm.getCalls', {})
+		const data = okValue(result, getCallsSchema)
+
+		expect(data.total).toBeGreaterThanOrEqual(1)
+		expect(data.calls.length).toBeGreaterThanOrEqual(1)
+
+		await harness.shutdown()
+	})
+
+	it('getCall with specific callId → returns request, response, metrics', async () => {
+		const harness = createHarnessWithLogger({
+			llmProvider: MockLLMProvider.withFixedResponse({ content: 'Response text', toolCalls: [] }),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Test message')
+
+		// Get calls to find a callId
+		const listResult = await session.callPluginMethod('llm.getCalls', {})
+		const listData = okValue(listResult, getCallsSchema)
+		expect(listData.calls.length).toBeGreaterThanOrEqual(1)
+
+		const callId = listData.calls[0].id
+
+		// Get specific call
+		const callResult = await session.callPluginMethod('llm.getCall', { callId })
+		const callData = okValue(callResult, getCallSchema)
+
+		expect(callData.id).toBe(callId)
+		expect(callData.status).toBe('success')
+
+		// Check request
+		expect(callData.request.model).toBe('mock')
+		expect(typeof callData.request.systemPrompt).toBe('string')
+		expect(Array.isArray(callData.request.messages)).toBe(true)
+
+		// Check response
+		expect(callData.response.content).toBe('Response text')
+		expect(callData.response.finishReason).toBe('stop')
+
+		// Check metrics
+		expect(typeof callData.metrics.promptTokens).toBe('number')
+		expect(typeof callData.metrics.completionTokens).toBe('number')
+		expect(typeof callData.metrics.totalTokens).toBe('number')
+		expect(typeof callData.metrics.latencyMs).toBe('number')
+
+		await harness.shutdown()
+	})
+
+	it('multiple inferences → getCalls returns all in order', async () => {
+		const harness = createHarnessWithLogger({
+			llmProvider: MockLLMProvider.withSequence([
+				{ content: null, toolCalls: [{ id: ToolCallId('tc1'), name: 'tell_user', input: { message: 'Hi' } }] },
+				{ content: 'Done', toolCalls: [] },
+			]),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Hello')
+
+		const result = await session.callPluginMethod('llm.getCalls', {})
+		const data = okValue(result, getCallsSchema)
+
+		// Two inferences: first returns tool call, second returns text
+		expect(data.total).toBe(2)
+		expect(data.calls).toHaveLength(2)
+
+		// listCalls returns most recent first, so calls[0] is the second inference
+		const secondCall = data.calls[0]
+		const firstCall = data.calls[1]
+
+		expect(firstCall.response.content).toBeNull()
+		expect(firstCall.response.toolCalls.length).toBe(1)
+
+		expect(secondCall.response.content).toBe('Done')
+
+		await harness.shutdown()
+	})
+
+	it('getCalls with limit/offset → pagination', async () => {
+		const harness = createHarnessWithLogger({
+			llmProvider: MockLLMProvider.withSequence([
+				{ content: null, toolCalls: [{ id: ToolCallId('tc1'), name: 'tell_user', input: { message: 'A' } }] },
+				{ content: null, toolCalls: [{ id: ToolCallId('tc2'), name: 'tell_user', input: { message: 'B' } }] },
+				{ content: 'Done', toolCalls: [] },
+			]),
+		})
+
+		const session = await harness.createSession('test')
+		await session.sendAndWaitForIdle('Go')
+
+		// Total should be 3
+		const allResult = await session.callPluginMethod('llm.getCalls', {})
+		const allData = okValue(allResult, getCallsSchema)
+		expect(allData.total).toBe(3)
+
+		// Limit to 1
+		const limitResult = await session.callPluginMethod('llm.getCalls', { limit: 1 })
+		const limitData = okValue(limitResult, getCallsSchema)
+		expect(limitData.total).toBe(3)
+		expect(limitData.calls.length).toBe(1)
+
+		// Offset 1, limit 1
+		const offsetResult = await session.callPluginMethod('llm.getCalls', { limit: 1, offset: 1 })
+		const offsetData = okValue(offsetResult, getCallsSchema)
+		expect(offsetData.total).toBe(3)
+		expect(offsetData.calls.length).toBe(1)
+
+		// The offset call should return a different call than limit-only
+		expect(limitData.calls[0].id).not.toBe(offsetData.calls[0].id)
+
+		await harness.shutdown()
+	})
+})

package/src/plugins/llm-debug/plugin.ts

@@ -0,0 +1,172 @@
+/**
+ * LLM Debug Plugin
+ *
+ * Provides session-level methods for querying LLM call logs:
+ * - llm.getCalls — list LLM calls for a session
+ * - llm.getCall — get single LLM call detail
+ * - llm.getCurlCommand — export LLM call as curl command (with resolved images)
+ */
+
+import type { LLMMessage } from '~/core/agents/state.js'
+import { ValidationErrors } from '~/core/errors.js'
+import type { LLMCallLogEntry, LLMCallMessage } from '~/core/llm/llm-log-types.js'
+import type { RawInferenceRequest, RawToolSpec } from '~/core/llm/provider.js'
+import { LLMCallId } from '~/core/llm/schema.js'
+import { ModelId } from '~/core/llm/schema.js'
+import { definePlugin } from '~/core/plugins/index.js'
+import { ToolCallId } from '~/core/tools/schema.js'
+import { Err, Ok } from '~/lib/utils/result.js'
+
+import z4 from 'zod/v4'
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Convert stored LLMCallMessage[] back to LLMMessage[] for buildHttpRequest.
+ */
+function logMessagesToLLMMessages(messages: LLMCallMessage[]): LLMMessage[] {
+	return messages.map((m): LLMMessage => {
+		switch (m.role) {
+			case 'user':
+				return { role: 'user', content: m.content, cacheControl: m.cacheControl }
+			case 'system':
+				return {
+					role: 'system',
+					content: typeof m.content === 'string' ? m.content : '',
+					cacheControl: m.cacheControl,
+				}
+			case 'assistant':
+				return {
+					role: 'assistant',
+					content: typeof m.content === 'string' ? m.content : '',
+					toolCalls: m.toolCalls?.map((tc) => ({
+						id: ToolCallId(tc.id),
+						name: tc.name,
+						input: tc.input,
+					})),
+					cacheControl: m.cacheControl,
+				}
+			case 'tool':
+				return {
+					role: 'tool',
+					content: m.content,
+					toolCallId: ToolCallId(m.toolCallId ?? ''),
+					cacheControl: m.cacheControl,
+				}
+		}
+	})
+}
+
+/**
+ * Format a ProviderHttpRequest as a curl command string.
+ */
+function formatCurl(httpRequest: { url: string; method: string; headers: Record<string, string>; body: unknown }): string {
+	const parts = [`curl -X ${httpRequest.method}`]
+	parts.push(`  '${httpRequest.url}'`)
+
+	for (const [key, value] of Object.entries(httpRequest.headers)) {
+		parts.push(`  -H '${key}: ${value}'`)
+	}
+	// Placeholder for auth header
+	parts.push(`  -H 'Authorization: Bearer YOUR_API_KEY'`)
+
+	parts.push(`  -d '${JSON.stringify(httpRequest.body)}'`)
+
+	return parts.join(' \\\n')
+}
+
+// ============================================================================
+// LLM Debug Plugin
+// ============================================================================
+
+export const llmDebugPlugin = definePlugin('llm')
+	.method('getCalls', {
+		input: z4.object({
+			limit: z4.number().int().optional(),
+			offset: z4.number().int().optional(),
+		}),
+		output: z4.object({
+			calls: z4.array(z4.unknown()),
+			total: z4.number(),
+		}),
+		handler: async (ctx, input) => {
+			if (!ctx.llmLogger) {
+				return Ok({ calls: [], total: 0 })
+			}
+
+			return Ok(
+				await ctx.llmLogger.listCalls(ctx.sessionId, {
+					limit: input.limit ?? 100,
+					offset: input.offset ?? 0,
+				}),
+			)
+		},
+	})
+	.method('getCall', {
+		input: z4.object({
+			callId: z4.string(),
+		}),
+		output: z4.unknown(),
+		handler: async (ctx, input) => {
+			const callId = LLMCallId(input.callId)
+
+			if (!ctx.llmLogger) {
+				return Err(ValidationErrors.invalid('LLM logging is not enabled'))
+			}
+
+			const call = await ctx.llmLogger.getCall(ctx.sessionId, callId)
+			if (!call) {
+				return Err(ValidationErrors.invalid(`LLM call not found: ${input.callId}`))
+			}
+
+			return Ok(call)
+		},
+	})
+	.method('getCurlCommand', {
+		input: z4.object({
+			callId: z4.string(),
+		}),
+		output: z4.object({
+			curl: z4.string(),
+		}),
+		handler: async (ctx, input) => {
+			const callId = LLMCallId(input.callId)
+
+			if (!ctx.llmLogger) {
+				return Err(ValidationErrors.invalid('LLM logging is not enabled'))
+			}
+
+			const call = await ctx.llmLogger.getCall(ctx.sessionId, callId)
+			if (!call) {
+				return Err(ValidationErrors.invalid(`LLM call not found: ${input.callId}`))
+			}
+
+			if (!ctx.llm.buildHttpRequest) {
+				return Err(ValidationErrors.invalid('LLM provider does not support HTTP request building'))
+			}
+
+			const rawRequest: RawInferenceRequest = {
+				model: ModelId(call.request.model),
+				systemPrompt: call.request.systemPrompt,
+				messages: logMessagesToLLMMessages(call.request.messages),
+				tools: call.request.tools?.map((t): RawToolSpec => ({
+					name: t.name,
+					description: t.description,
+					parameters: t.parameters ?? {},
+				})),
+				maxTokens: call.request.maxTokens,
+				temperature: call.request.temperature,
+			}
+
+			const httpRequest = await ctx.llm.buildHttpRequest(rawRequest, {
+				sessionId: ctx.sessionId,
+				agentId: call.agentId,
+				fileStore: ctx.files,
+			})
+
+			return Ok({ curl: formatCurl(httpRequest) })
+		},
+	})
+	.build()

package/src/plugins/logs/index.ts

@@ -0,0 +1 @@
+export { logsPlugin } from './plugin.js'