@roj-ai/shared 0.0.2

package/src/projections/types.ts

@@ -0,0 +1,237 @@
+/**
+ * View model types for client-side projections.
+ */
+
+import type {
+	AgentCounters,
+	AgentId,
+	AgentPauseReason,
+	AskUserInputType,
+	ChatMessageId,
+	DomainEvent,
+	LLMCallId,
+	MessageId,
+	ProtocolAgentStatus,
+	ToolCallId,
+} from '@roj-ai/sdk'
+
+// ============================================================================
+// Debug view types (computed client-side from SessionState)
+// ============================================================================
+
+/**
+ * Agent tree node for visualization.
+ */
+export interface AgentTreeNode {
+	id: AgentId
+	definitionName: string
+	status: ProtocolAgentStatus
+	parentId: AgentId | null
+	children: AgentTreeNode[]
+	mailboxCount: number
+	pendingToolCalls: number
+	isExecuting: boolean
+	cost: number
+}
+
+/**
+ * Agent detail response - computed client-side from SessionState.
+ */
+export interface GetAgentDetailResponse {
+	id: AgentId
+	definitionName: string
+	status: ProtocolAgentStatus
+	parentId: AgentId | null
+	mailbox: MailboxMessageView[]
+	conversationHistory: ConversationMessageView[]
+	pendingToolCalls: ToolCallView[]
+	counters: AgentCounters
+	loadedSkills: { id: string; name: string; loadedAt: number }[]
+	cost: number
+	typedInput?: unknown
+	pauseReason?: AgentPauseReason
+	pauseMessage?: string
+}
+
+export interface MailboxMessageView {
+	id: MessageId
+	from: string // Can be AgentId, WorkerId, "user", or system role
+	content: string
+	timestamp: number
+	consumed: boolean
+}
+
+export type ConversationMessageView =
+	| UserConversationMessageView
+	| AssistantConversationMessageView
+	| ToolConversationMessageView
+	| SystemConversationMessageView
+
+export interface UserConversationMessageView {
+	role: 'user'
+	content: string
+	fullContent: string
+	timestamp?: number
+}
+
+export interface AssistantConversationMessageView {
+	role: 'assistant'
+	content: string
+	fullContent: string
+	toolCalls?: { id: ToolCallId; name: string; input: unknown }[]
+	timestamp?: number
+	cost?: number
+	llmCallId?: LLMCallId
+	promptTokens?: number
+	cachedTokens?: number
+	cacheWriteTokens?: number
+}
+
+export interface ToolConversationMessageView {
+	role: 'tool'
+	toolCallId: ToolCallId
+	content: string
+	fullContent: string
+	isError: boolean
+	timestamp?: number
+}
+
+export interface SystemConversationMessageView {
+	role: 'system'
+	content: string
+	fullContent: string
+	timestamp?: number
+}
+
+export interface ToolCallView {
+	id: ToolCallId
+	name: string
+	input: unknown
+	status: 'pending' | 'executing' | 'completed' | 'failed'
+	result?: unknown
+	error?: string
+}
+
+// ============================================================================
+// Events response type
+// ============================================================================
+
+/**
+ * Events response - used by sessions.getEvents RPC method.
+ */
+export interface GetEventsResponse {
+	events: DomainEvent[]
+	total: number
+	lastIndex: number
+}
+
+// ============================================================================
+// Metrics types
+// ============================================================================
+
+/**
+ * Metrics view - computed client-side from events.
+ */
+export interface ProviderMetrics {
+	llmCalls: number
+	totalTokens: number
+	promptTokens: number
+	completionTokens: number
+	totalCost: number
+}
+
+export interface GetMetricsResponse {
+	totalTokens: number
+	promptTokens: number
+	completionTokens: number
+	totalCost?: number
+	llmCalls: number
+	toolCalls: number
+	agentCount: number
+	durationMs: number
+	byProvider: Record<string, ProviderMetrics>
+}
+
+// ============================================================================
+// Timeline types
+// ============================================================================
+
+/**
+ * Timeline item representing an LLM call, tool execution, or context compaction.
+ */
+export interface TimelineItem {
+	id: string
+	type: 'llm' | 'tool' | 'compaction'
+	agentId: AgentId
+	agentName: string
+	startedAt: number
+	completedAt?: number
+	durationMs?: number
+	status: 'running' | 'success' | 'error'
+	// LLM specific
+	model?: string
+	promptTokens?: number
+	completionTokens?: number
+	cachedTokens?: number
+	cacheWriteTokens?: number
+	cost?: number
+	llmCallId?: LLMCallId
+	// Tool specific
+	toolName?: string
+	toolCallId?: ToolCallId
+	toolInput?: unknown
+	toolResult?: unknown
+	// Compaction specific
+	originalTokens?: number
+	compactedTokens?: number
+	messagesRemoved?: number
+	// Error
+	error?: string
+}
+
+// ============================================================================
+// Global mailbox types
+// ============================================================================
+
+/**
+ * Message in the global mailbox view.
+ */
+export interface GlobalMailboxMessage {
+	id: MessageId
+	fromAgentId: string // Can be AgentId, "user", or system role
+	fromAgentName: string
+	toAgentId: AgentId
+	toAgentName: string
+	content: string
+	timestamp: number
+	consumed: boolean
+}
+
+// ============================================================================
+// Chat debug types
+// ============================================================================
+
+/**
+ * Debug chat message with links to related entities.
+ */
+export interface DebugChatMessage {
+	// Base
+	type: 'user_message' | 'agent_message' | 'ask_user'
+	messageId: MessageId | ChatMessageId
+	content: string
+	timestamp: number
+	eventIndex: number
+
+	// Links
+	agentId?: AgentId
+	agentName?: string
+	llmCallId?: LLMCallId
+	toolCallId?: ToolCallId
+	mailboxMessageId?: MessageId
+
+	// Type-specific
+	format?: 'text' | 'markdown'
+	inputType?: AskUserInputType
+	answered?: boolean
+	answer?: unknown
+}

package/src/rpc/client.ts

@@ -0,0 +1,188 @@
+/**
+ * Type-safe RPC Client
+ *
+ * Provides a fully typed interface for calling RPC methods.
+ * All method names and input/output types are validated at compile time.
+ *
+ * Supports both single calls and batch calls:
+ * - Single: rpc.call("method", input) -> Result<output, RpcErrorInfo>
+ * - Batch:  rpc.batch(b => [b.add("m1", i1), b.add("m2", i2)]) -> Result<[o1, o2], RpcErrorInfo>
+ */
+
+import type { RpcInput, RpcMethodName, RpcOutput } from '@roj-ai/sdk/rpc'
+import type { Result } from '../lib/result.js'
+import { Err, Ok } from '../lib/result.js'
+
+/**
+ * Structured error info from RPC responses.
+ */
+export interface RpcErrorInfo {
+	type: string
+	message: string
+	details?: unknown
+}
+
+/**
+ * RPC error class for backwards compatibility.
+ */
+export class RpcError extends Error {
+	constructor(
+		public status: number,
+		public error: RpcErrorInfo,
+	) {
+		super(error.message)
+		this.name = 'RpcError'
+	}
+}
+
+/**
+ * RPC response envelope (new format).
+ */
+interface RpcResponse {
+	ok: boolean
+	value?: unknown
+	error?: RpcErrorInfo
+}
+
+interface BatchResponse {
+	results?: Array<{ ok: boolean; value?: unknown; error?: RpcErrorInfo }>
+	ok?: boolean
+	error?: RpcErrorInfo
+}
+
+/**
+ * A typed marker for a batch call entry. Carries the output type at compile time.
+ */
+export interface BatchEntry<_T> {
+	readonly method: string
+	readonly input: unknown
+}
+
+/**
+ * Batch call builder. Collects typed entries for a batch RPC request.
+ */
+export class BatchBuilder {
+	add<M extends RpcMethodName>(method: M, input: RpcInput<M>): BatchEntry<RpcOutput<M>> {
+		return { method, input }
+	}
+}
+
+/**
+ * Maps a tuple of BatchEntry<T> to a tuple of T.
+ */
+type BatchResults<T extends readonly BatchEntry<unknown>[]> = {
+	[K in keyof T]: T[K] extends BatchEntry<infer R> ? R : never
+}
+
+/**
+ * Type-safe RPC client for calling server methods.
+ */
+export class RpcClient {
+	private projectId: string | null = null
+
+	constructor(private baseUrl: string = '') {}
+
+	/**
+	 * Get the base URL for non-RPC requests.
+	 */
+	getBaseUrl(): string {
+		return this.baseUrl
+	}
+
+	/**
+	 * Set the project ID for DO-based RPC calls.
+	 * When set, the projectId is added as a query parameter to /rpc requests.
+	 */
+	setProjectId(projectId: string | null): void {
+		this.projectId = projectId
+	}
+
+	/**
+	 * Get the currently configured project ID.
+	 */
+	getProjectId(): string | null {
+		return this.projectId
+	}
+
+	private getRpcUrl(): string {
+		let url = `${this.baseUrl}/rpc`
+		if (this.projectId) {
+			url += `?project=${encodeURIComponent(this.projectId)}`
+		}
+		return url
+	}
+
+	/**
+	 * Call an RPC method with type-safe input and output.
+	 */
+	async call<M extends RpcMethodName>(
+		method: M,
+		input: RpcInput<M>,
+	): Promise<Result<RpcOutput<M>, RpcErrorInfo>> {
+		const response = await fetch(this.getRpcUrl(), {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({ method, input }),
+			credentials: 'include',
+		})
+
+		const data = (await response.json()) as RpcResponse
+
+		// Transport error (non-200 for invalid JSON, missing method)
+		if (!response.ok) {
+			return Err(data.error ?? { type: 'transport_error', message: 'Request failed' })
+		}
+
+		// Application result
+		if (data.ok) {
+			return Ok(data.value as RpcOutput<M>)
+		}
+
+		return Err(data.error ?? { type: 'unknown_error', message: 'Unknown error' })
+	}
+
+	/**
+	 * Execute multiple RPC calls as a batch.
+	 */
+	async batch<const T extends readonly BatchEntry<unknown>[]>(
+		buildCalls: (b: BatchBuilder) => T,
+	): Promise<Result<BatchResults<T>, RpcErrorInfo>> {
+		const entries = buildCalls(new BatchBuilder())
+
+		const response = await fetch(this.getRpcUrl(), {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify({
+				batch: entries.map(e => ({ method: e.method, input: e.input })),
+			}),
+			credentials: 'include',
+		})
+
+		const data = (await response.json()) as BatchResponse
+
+		// Transport error
+		if (!response.ok) {
+			return Err(data.error ?? { type: 'transport_error', message: 'Request failed' })
+		}
+
+		const results = data.results ?? []
+
+		// Check if any call in the batch failed
+		for (const entry of results) {
+			if (!entry.ok && entry.error) {
+				return Err(entry.error)
+			}
+		}
+
+		// If fewer results than entries, the batch was short-circuited by an error
+		if (results.length < entries.length) {
+			const lastResult = results[results.length - 1]
+			if (lastResult && !lastResult.ok && lastResult.error) {
+				return Err(lastResult.error)
+			}
+			return Err({ type: 'batch_incomplete', message: 'Batch execution was interrupted' })
+		}
+
+		return Ok(results.map(r => r.value) as BatchResults<T>)
+	}
+}

package/src/rpc/index.ts

@@ -0,0 +1,14 @@
+/**
+ * RPC Module - Shared re-exports for client/CLI consumers.
+ */
+
+// Client
+export { BatchBuilder, type BatchEntry, RpcClient, RpcError, type RpcErrorInfo } from './client.js'
+
+// Result types
+export { Err, flatMapResult, isErr, isOk, mapResult, Ok, unwrapOr, unwrapOrThrow } from '../lib/result.js'
+export type { Result } from '../lib/result.js'
+
+// Type-only re-exports from agent-server (zero runtime cost)
+export type { RpcInput, RpcMethodDef, RpcMethodName, RpcMethods, RpcOutput } from '@roj-ai/sdk/rpc'
+export type { AgentChatMessage, AskUserChatMessage, ChatMessage, UserChatMessage } from '@roj-ai/sdk/rpc'