@roj-ai/sdk 0.0.2

package/src/core/agents/retry.ts

@@ -0,0 +1,164 @@
+import type { LLMError } from '~/core/llm/provider.js'
+import type { Result } from '~/lib/utils/result.js'
+import { Err } from '~/lib/utils/result.js'
+import type { Logger } from '../../lib/logger/logger.js'
+
+// ============================================================================
+// Retry Options
+// ============================================================================
+
+export interface RetryOptions {
+	maxAttempts?: number
+	baseDelayMs?: number
+	maxDelayMs?: number
+}
+
+export const DEFAULT_RETRY_OPTIONS: Required<RetryOptions> = {
+	maxAttempts: 5,
+	baseDelayMs: 1000,
+	maxDelayMs: 60000,
+}
+
+// ============================================================================
+// Generic Retry Helper
+// ============================================================================
+
+export interface WithRetryOptions<E> extends RetryOptions {
+	isRetryable: (error: E) => boolean
+	getRetryDelay?: (error: E) => number | undefined
+	/** Error to return when aborted before first attempt */
+	abortError?: E
+	logger?: Logger
+	context?: string
+	signal?: AbortSignal
+}
+
+/**
+ * Generic retry wrapper with exponential backoff.
+ */
+export async function withRetry<T, E>(
+	fn: () => Promise<Result<T, E>>,
+	options: WithRetryOptions<E>,
+): Promise<Result<T, E>> {
+	const opts = {
+		maxAttempts: options.maxAttempts ?? DEFAULT_RETRY_OPTIONS.maxAttempts,
+		baseDelayMs: options.baseDelayMs ?? DEFAULT_RETRY_OPTIONS.baseDelayMs,
+		maxDelayMs: options.maxDelayMs ?? DEFAULT_RETRY_OPTIONS.maxDelayMs,
+	}
+
+	let attempt = 0
+	let lastError: E | null = null
+
+	while (attempt < opts.maxAttempts) {
+		if (options.signal?.aborted) {
+			const error = lastError ?? options.abortError
+			if (error !== undefined) {
+				return Err(error)
+			}
+			break
+		}
+
+		const result = await fn()
+
+		if (result.ok) {
+			if (attempt > 0 && options.logger) {
+				options.logger.info('Operation succeeded after retries', {
+					context: options.context,
+					attempt: attempt + 1,
+				})
+			}
+			return result
+		}
+
+		lastError = result.error
+
+		if (!options.isRetryable(lastError)) {
+			return result
+		}
+
+		attempt++
+		const delay = calculateDelay(attempt, lastError, opts, options.getRetryDelay)
+
+		if (options.logger) {
+			options.logger.warn('Operation failed, retrying', {
+				context: options.context,
+				attempt,
+				delayMs: delay,
+			})
+		}
+
+		await sleep(delay, options.signal)
+	}
+
+	return Err(lastError!)
+}
+
+function calculateDelay<E>(
+	attempt: number,
+	error: E,
+	opts: Required<RetryOptions>,
+	getRetryDelay?: (error: E) => number | undefined,
+): number {
+	// Use error-specific delay if available
+	const errorDelay = getRetryDelay?.(error)
+	if (errorDelay !== undefined) {
+		return Math.min(errorDelay, opts.maxDelayMs)
+	}
+
+	// Exponential backoff: baseDelay * 2^(attempt-1)
+	const exponentialDelay = opts.baseDelayMs * Math.pow(2, attempt - 1)
+
+	// Add jitter (0-30%) to prevent thundering herd
+	const jitter = Math.random() * 0.3 * exponentialDelay
+
+	return Math.min(exponentialDelay + jitter, opts.maxDelayMs)
+}
+
+function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	if (signal?.aborted) return Promise.resolve()
+	return new Promise<void>((resolve) => {
+		const timer = setTimeout(resolve, ms)
+		signal?.addEventListener('abort', () => {
+			clearTimeout(timer)
+			resolve()
+		}, { once: true })
+	})
+}
+
+// ============================================================================
+// LLM-specific helpers
+// ============================================================================
+
+/**
+ * Determines if an LLM error is retryable.
+ * Retryable: rate_limit, server_error, network_error, timeout
+ * Non-retryable: invalid_request, context_length (permanent failures)
+ */
+export function isRetryableLLMError(error: LLMError): boolean {
+	return ['rate_limit', 'server_error', 'network_error', 'timeout'].includes(
+		error.type,
+	)
+}
+
+/**
+ * Gets retry delay from LLM error if available (e.g., rate limit retry-after).
+ */
+export function getLLMRetryDelay(error: LLMError): number | undefined {
+	return error.retryAfterMs
+}
+
+/**
+ * Convenience wrapper for LLM inference with retry.
+ */
+export async function withLLMRetry<T>(
+	fn: () => Promise<Result<T, LLMError>>,
+	options?: RetryOptions & { logger?: Logger; signal?: AbortSignal },
+): Promise<Result<T, LLMError>> {
+	return withRetry(fn, {
+		...options,
+		isRetryable: isRetryableLLMError,
+		getRetryDelay: getLLMRetryDelay,
+		abortError: { type: 'aborted', message: 'Aborted before first attempt' },
+		context: 'LLM inference',
+	})
+}

package/src/core/agents/schema.ts

@@ -0,0 +1,75 @@
+/**
+ * Agent domain types and schemas
+ *
+ * Contains all types related to agents:
+ * - Branded ID type and constructor
+ * - Agent status types (domain and protocol)
+ * - Zod schemas for validation
+ */
+
+import z from 'zod/v4'
+
+// ============================================================================
+// AgentId - Branded type
+// ============================================================================
+
+/** AgentId schema - validates any string and brands as AgentId. */
+export const agentIdSchema = z.string().brand('AgentId')
+
+/** Branded AgentId type */
+export type AgentId = z.infer<typeof agentIdSchema>
+
+/** Constructor for AgentId */
+export const AgentId = (id: string): AgentId => id as AgentId
+
+/**
+ * Generate a short agent ID based on definition name and sequence number.
+ * Format: {definitionName}_{seq} e.g., "orchestrator_1", "planner_2"
+ */
+export const generateAgentId = (definitionName: string, seq: number): AgentId => AgentId(`${definitionName}_${seq}`)
+
+// ============================================================================
+// AgentId - Zod schemas
+// ============================================================================
+
+// ============================================================================
+// AgentStatus - Domain type (internal state machine)
+// ============================================================================
+
+/**
+ * Domain agent status - represents the internal state machine.
+ * Used by the agent runtime and event sourcing.
+ */
+export type AgentStatus = 'pending' | 'inferring' | 'tool_exec' | 'errored' | 'paused'
+
+/**
+ * Zod schema for domain agent status.
+ */
+export const agentStatusSchema = z.enum(['pending', 'inferring', 'tool_exec', 'errored', 'paused'])
+
+// ============================================================================
+// AgentStatus - Protocol type (for UI/SPA)
+// ============================================================================
+
+/**
+ * Protocol agent status - represents the UI-friendly status.
+ * Maps from domain status for display in the SPA.
+ */
+export type ProtocolAgentStatus = 'idle' | 'thinking' | 'responding' | 'waiting_for_user' | 'error' | 'paused'
+
+/**
+ * Zod schema for protocol agent status.
+ */
+export const protocolAgentStatusSchema = z.enum(['idle', 'thinking', 'responding', 'waiting_for_user', 'error', 'paused'])
+
+// ============================================================================
+// Test helpers
+// ============================================================================
+
+let testCounter = 0
+
+/**
+ * Generate a test agent ID (for tests only).
+ * Uses incrementing counter for uniqueness.
+ */
+export const generateTestAgentId = (definitionName = 'test-agent'): AgentId => AgentId(`${definitionName}_${++testCounter}`)

package/src/core/agents/state.ts

@@ -0,0 +1,272 @@
+// ============================================================================
+// Agent status
+// ============================================================================
+
+import z4 from 'zod/v4'
+import type { AgentId } from '~/core/agents/schema.js'
+import { agentIdSchema } from '~/core/agents/schema.js'
+import { createEventsFactory } from '~/core/events/types'
+import type { ToolResultContent } from '~/core/llm/llm-log-types.js'
+import type { ChatMessageContentItem } from '~/core/llm/llm-log-types.js'
+import type { PendingToolResult, ToolCallId } from '~/core/tools/schema.js'
+import { MessageId } from '../../plugins/mailbox/schema'
+
+export { MessageId }
+
+// ============================================================================
+// Agent events
+// ============================================================================
+
+/**
+ * Union of all possible handler results (stored in handler_completed event).
+ */
+export type HandlerResult =
+	| null
+	| { action: 'skip'; response: { content: string | null; toolCalls: Array<{ id: string; name: string; input: unknown }> } }
+	| { action: 'modify'; response: { content: string | null; toolCalls: Array<{ id: string; name: string; input: unknown }> } }
+	| { action: 'retry' }
+	| { action: 'block'; reason: string }
+	| { action: 'replace'; toolCall: { id: string; name: string; input: unknown } }
+	| { action: 'modify'; result: { isError: boolean; content: unknown } }
+	| { action: 'pause'; reason?: string }
+
+export const agentEvents = createEventsFactory({
+	events: {
+		agent_spawned: z4.object({
+			agentId: agentIdSchema,
+			definitionName: z4.string(),
+			parentId: agentIdSchema.nullable(),
+			typedInput: z4.unknown().optional(),
+		}),
+		agent_state_changed: z4.object({
+			agentId: agentIdSchema,
+			fromState: z4.enum(['pending', 'inferring', 'tool_exec', 'errored', 'paused']),
+			toState: z4.enum(['pending', 'inferring', 'tool_exec', 'errored', 'paused']),
+		}),
+		handler_started: z4.object({
+			agentId: agentIdSchema,
+			handlerName: z4.enum(['onStart', 'beforeInference', 'afterInference', 'beforeToolCall', 'afterToolCall', 'onComplete', 'onError']),
+		}),
+		handler_completed: z4.object({
+			agentId: agentIdSchema,
+			handlerName: z4.enum(['onStart', 'beforeInference', 'afterInference', 'beforeToolCall', 'afterToolCall', 'onComplete', 'onError']),
+			result: z4.unknown(), // HandlerResult - too complex for Zod
+		}),
+		preamble_added: z4.object({
+			agentId: agentIdSchema,
+			messages: z4.array(z4.custom<LLMMessage>()),
+		}),
+		agent_paused: z4.object({
+			agentId: agentIdSchema,
+			reason: z4.enum(['limit', 'handler', 'manual']),
+			message: z4.string().optional(),
+		}),
+		agent_resumed: z4.object({
+			agentId: agentIdSchema,
+		}),
+		communicator_linked: z4.object({
+			communicatorId: agentIdSchema,
+			orchestratorId: agentIdSchema,
+		}),
+		agent_conversation_spliced: z4.object({
+			agentId: agentIdSchema,
+			start: z4.number().int().min(0),
+			deleteCount: z4.number().int().min(0),
+			insert: z4.array(z4.custom<LLMMessage>()).optional(),
+		}),
+	},
+})
+
+export type AgentSpawnedEvent = (typeof agentEvents)['Events']['agent_spawned']
+export type AgentStateChangedEvent = (typeof agentEvents)['Events']['agent_state_changed']
+export type HandlerStartedEvent = (typeof agentEvents)['Events']['handler_started']
+export type HandlerCompletedEvent = (typeof agentEvents)['Events']['handler_completed']
+export type PreambleAddedEvent = (typeof agentEvents)['Events']['preamble_added']
+export type AgentPausedEvent = (typeof agentEvents)['Events']['agent_paused']
+export type AgentResumedEvent = (typeof agentEvents)['Events']['agent_resumed']
+export type CommunicatorLinkedEvent = (typeof agentEvents)['Events']['communicator_linked']
+export type AgentConversationSplicedEvent = (typeof agentEvents)['Events']['agent_conversation_spliced']
+
+// ============================================================================
+// Agent status
+// ============================================================================
+
+export type AgentStatus = 'pending' | 'inferring' | 'tool_exec' | 'errored' | 'paused'
+
+/**
+ * Reason why an agent was paused.
+ * - 'limit' — agent hit a hard limit (replaces limitStopped)
+ * - 'handler' — handler returned { action: 'pause' }
+ * - 'manual' — paused via API call
+ */
+export type AgentPauseReason = 'limit' | 'handler' | 'manual'
+
+// ============================================================================
+// LLM Message types (unified for both LLM API and conversation history)
+// ============================================================================
+
+/**
+ * Prompt cache breakpoint marker.
+ * When set on an LLMMessage, providers place `cache_control: { type: 'ephemeral' }`
+ * on the LAST content block of the mapped message (regardless of block type),
+ * marking it as a prompt cache checkpoint.
+ */
+export type LLMMessageCacheControl = { type: 'ephemeral' }
+
+/**
+ * User message - from mailbox or direct input.
+ * Supports multimodal content (text + images).
+ */
+export interface UserLLMMessage {
+	role: 'user'
+	content: string | ChatMessageContentItem[]
+	/** Track which mailbox messages were included (conversation metadata) */
+	sourceMessageIds?: MessageId[]
+	/** Marks this message as a prompt cache breakpoint. */
+	cacheControl?: LLMMessageCacheControl
+}
+
+/**
+ * Assistant message - LLM response.
+ */
+export interface AssistantLLMMessage {
+	role: 'assistant'
+	content: string
+	toolCalls?: ToolCall[]
+	/** Marks this message as a prompt cache breakpoint. */
+	cacheControl?: LLMMessageCacheControl
+}
+
+/**
+ * Tool result message - response from tool execution.
+ */
+export interface ToolLLMMessage {
+	role: 'tool'
+	content: ToolResultContent
+	toolCallId: ToolCallId
+	/** Tool name (conversation metadata) */
+	toolName?: string
+	/** Whether the tool execution failed (conversation metadata) */
+	isError?: boolean
+	/** When the tool completed (conversation metadata) */
+	timestamp?: number
+	/** Marks this message as a prompt cache breakpoint. */
+	cacheControl?: LLMMessageCacheControl
+}
+
+/**
+ * System message - injected context (e.g., from context compaction).
+ */
+export interface SystemLLMMessage {
+	role: 'system'
+	content: string
+	/** Marks this message as a prompt cache breakpoint. */
+	cacheControl?: LLMMessageCacheControl
+}
+
+/**
+ * Unified message type for LLM communication and conversation history.
+ */
+export type LLMMessage =
+	| UserLLMMessage
+	| AssistantLLMMessage
+	| ToolLLMMessage
+	| SystemLLMMessage
+
+// ============================================================================
+// AgentState - POJO for persistence
+// ============================================================================
+
+export interface AgentState {
+	id: AgentId
+	definitionName: string
+	parentId: AgentId | null
+	status: AgentStatus
+	conversationHistory: LLMMessage[]
+	/** Immutable preamble messages from onStart handlers - never compacted, always prepended before conversation */
+	preamble: LLMMessage[]
+	pendingToolCalls: ToolCall[]
+	/** Currently executing tool call (set by tool_started, cleared by tool_completed/tool_failed) */
+	executingToolCall?: {
+		toolCallId: ToolCallId
+		toolName: string
+		startedAt: number
+	}
+	/** Tool results awaiting LLM processing (set by tool_completed/tool_failed, cleared by inference_completed) */
+	pendingToolResults: PendingToolResult[]
+	/** Messages pending addition to history (set by inference_started, committed by inference_completed) */
+	pendingMessages: LLMMessage[]
+	/** Typed input for agents with inputSchema (set by agent_spawned event) */
+	typedInput?: unknown
+	/** Whether onStart handler has been executed (for first-run initialization) */
+	onStartCalled?: boolean
+	/** Reason for pause (set when status is 'paused') */
+	pauseReason?: AgentPauseReason
+	/** Human-readable pause message */
+	pauseMessage?: string
+}
+
+// ============================================================================
+// Tool types
+// ============================================================================
+
+export interface ToolCall {
+	id: ToolCallId
+	name: string
+	input: unknown
+}
+
+export interface ToolResult {
+	toolCallId: ToolCallId
+	result: unknown
+	isError: boolean
+}
+
+// ============================================================================
+// AgentState tree helpers
+// ============================================================================
+
+export const getChildren = (
+	session: { agents: Map<AgentId, AgentState> },
+	parentId: AgentId,
+): AgentState[] => {
+	const children: AgentState[] = []
+	for (const agent of session.agents.values()) {
+		if (agent.parentId === parentId) {
+			children.push(agent)
+		}
+	}
+	return children
+}
+
+export const getParent = (
+	session: { agents: Map<AgentId, AgentState> },
+	agent: AgentState,
+): AgentState | null => {
+	if (!agent.parentId) return null
+	return session.agents.get(agent.parentId) ?? null
+}
+
+// Factory for creating AgentState (useful for tests)
+// ============================================================================
+
+/**
+ * Create a new AgentState with default values.
+ * Useful for tests to avoid maintaining inline mocks when new fields are added.
+ */
+export const createAgentState = (
+	id: AgentId,
+	definitionName: string,
+	overrides: Partial<AgentState> = {},
+): AgentState => ({
+	id,
+	definitionName,
+	parentId: null,
+	status: 'pending',
+	conversationHistory: [],
+	preamble: [],
+	pendingToolCalls: [],
+	pendingToolResults: [],
+	pendingMessages: [],
+	...overrides,
+})

package/src/core/context/state.ts

@@ -0,0 +1,38 @@
+import z4 from 'zod/v4'
+import { agentIdSchema } from '~/core/agents'
+import { createEventsFactory } from '~/core/events/types'
+
+// ============================================================================
+// Supporting types for context events
+// ============================================================================
+
+/**
+ * Conversation message stored in event for reconstruction.
+ */
+export type CompactedConversationMessage = {
+	role: 'user' | 'assistant' | 'system'
+	content: string
+}
+
+// ============================================================================
+// Context events
+// ============================================================================
+
+export const contextEvents = createEventsFactory({
+	events: {
+		context_compacted: z4.object({
+			agentId: agentIdSchema,
+			compactedContent: z4.string(),
+			newConversationHistory: z4.array(z4.object({
+				role: z4.enum(['user', 'assistant', 'system']),
+				content: z4.string(),
+			})),
+			originalTokens: z4.number(),
+			compactedTokens: z4.number(),
+			messagesRemoved: z4.number(),
+			historyPath: z4.string().optional(),
+		}),
+	},
+})
+
+export type ContextCompactedEvent = (typeof contextEvents)['Events']['context_compacted']

package/src/core/errors.ts

@@ -0,0 +1,55 @@
+/**
+ * Self-describing domain errors.
+ *
+ * Each error carries its own HTTP status and message — no central switch needed.
+ * Plugins can define any error type they want without touching central files.
+ */
+
+// ============================================================================
+// Base interface
+// ============================================================================
+
+export interface DomainError {
+	readonly type: string
+	readonly message: string
+	readonly httpStatus: number
+}
+
+export function createDomainError(type: string, message: string, httpStatus: number): DomainError {
+	return { type, message, httpStatus }
+}
+
+export function isDomainError(value: unknown): value is DomainError {
+	return typeof value === 'object'
+		&& value !== null
+		&& 'type' in value
+		&& typeof value.type === 'string'
+		&& 'message' in value
+		&& typeof value.message === 'string'
+		&& 'httpStatus' in value
+		&& typeof value.httpStatus === 'number'
+}
+
+// ============================================================================
+// Core error factories
+// ============================================================================
+
+export const SessionErrors = {
+	notFound: (id: string) => createDomainError('session_not_found', `Session not found: ${id}`, 404),
+	closed: (id: string) => createDomainError('session_closed', `Session is closed: ${id}`, 409),
+	alreadyExists: (id: string) => createDomainError('session_already_exists', `Session already exists: ${id}`, 409),
+}
+
+export const AgentErrors = {
+	notFound: (id: string) => createDomainError('agent_not_found', `Agent not found: ${id}`, 404),
+	invalidState: (id: string, currentState: string, expectedState: string) =>
+		createDomainError('invalid_agent_state', `Agent ${id} in invalid state: ${currentState}, expected: ${expectedState}`, 409),
+}
+
+export const PresetErrors = {
+	notFound: (id: string) => createDomainError('preset_not_found', `Preset not found: ${id}`, 404),
+}
+
+export const ValidationErrors = {
+	invalid: (message: string) => createDomainError('validation_error', message, 400),
+}