@roj-ai/sdk 0.0.2

package/src/transport/adapter/client-adapter.ts

@@ -0,0 +1,81 @@
+/**
+ * Client Adapter
+ *
+ * Worker mode - agent connects to DO as WebSocket client.
+ * Simplified for broadcast-only communication (agent -> DO -> SPA).
+ * User messages and answers are handled via REST API.
+ *
+ * Authentication: Token is passed in the WebSocket URL as query parameter
+ * and Authorization header (handled by DO before upgrade).
+ */
+
+import type { IWebSocketFactory, ProtocolDef, ReconnectOptions } from '@roj-ai/transport'
+import { ClientConnection } from '@roj-ai/transport/client'
+import type { Logger } from '../../lib/logger/logger.js'
+import type { IAgentTransport, PluginNotification } from './types.js'
+
+export interface ClientAdapterConfig {
+	url: string
+	wsFactory: IWebSocketFactory
+	reconnect?: Partial<ReconnectOptions>
+	logger?: Logger
+}
+
+export class ClientAdapter implements IAgentTransport {
+	private readonly config: ClientAdapterConfig
+	private readonly connection: ClientConnection<ProtocolDef, ProtocolDef>
+	private readonly logger?: Logger
+	private heartbeatTimer: ReturnType<typeof setInterval> | null = null
+
+	constructor(config: ClientAdapterConfig) {
+		this.config = config
+		this.logger = config.logger?.child({ component: 'ClientAdapter' })
+		this.connection = new ClientConnection({
+			url: config.url,
+			wsFactory: config.wsFactory,
+			reconnect: config.reconnect ?? {
+				baseDelayMs: 1000,
+				maxDelayMs: 30000,
+				maxAttempts: Infinity,
+				jitterFactor: 0.3,
+			},
+		})
+	}
+
+	async start(): Promise<void> {
+		this.logger?.info('Connecting to DO', { url: this.config.url })
+		await this.connection.connect()
+		this.logger?.info('Connected to DO')
+		this.startHeartbeat()
+	}
+
+	async stop(): Promise<void> {
+		this.stopHeartbeat()
+		this.logger?.info('Disconnecting from DO')
+		await this.connection.disconnect()
+		this.logger?.info('Disconnected from DO')
+	}
+
+	private startHeartbeat(): void {
+		this.stopHeartbeat()
+		this.heartbeatTimer = setInterval(() => {
+			this.connection.send(JSON.stringify({ type: 'heartbeat', ts: Date.now() }))
+		}, 10_000)
+	}
+
+	private stopHeartbeat(): void {
+		if (this.heartbeatTimer) {
+			clearInterval(this.heartbeatTimer)
+			this.heartbeatTimer = null
+		}
+	}
+
+	broadcast(notification: PluginNotification): void {
+		// Send as wire message — protocol validation happens at the DO side
+		this.connection.send(JSON.stringify({
+			type: notification.type,
+			payload: notification.payload,
+			ts: Date.now(),
+		}))
+	}
+}

package/src/transport/adapter/index.ts

@@ -0,0 +1,42 @@
+/**
+ * Transport Adapter Module
+ *
+ * Simplified for broadcast-only WebSocket communication.
+ * User messages and answers are handled via REST API.
+ */
+
+export type { IAgentTransport, PluginNotification } from './types.js'
+
+export { ServerAdapter } from './server-adapter.js'
+export type { ServerAdapterConfig } from './server-adapter.js'
+
+export { ClientAdapter } from './client-adapter.js'
+export type { ClientAdapterConfig } from './client-adapter.js'
+
+// ============================================================================
+// Factory
+// ============================================================================
+
+import { ClientAdapter, type ClientAdapterConfig } from './client-adapter.js'
+import { ServerAdapter, type ServerAdapterConfig } from './server-adapter.js'
+import type { IAgentTransport } from './types.js'
+
+export interface StandaloneConfig extends ServerAdapterConfig {
+	mode: 'standalone'
+}
+
+export interface WorkerConfig extends ClientAdapterConfig {
+	mode: 'worker'
+}
+
+export type AgentTransportConfig = StandaloneConfig | WorkerConfig
+
+export function createAgentTransport(config: AgentTransportConfig): IAgentTransport {
+	if (config.mode === 'standalone') {
+		const { mode: _mode, ...rest } = config
+		return new ServerAdapter(rest)
+	} else {
+		const { mode: _mode, ...rest } = config
+		return new ClientAdapter(rest)
+	}
+}

package/src/transport/adapter/server-adapter.ts

@@ -0,0 +1,93 @@
+/**
+ * Server Adapter
+ *
+ * Standalone mode - agent is the WebSocket server.
+ * Simplified for broadcast-only communication (agent -> SPA).
+ * User messages and answers are handled via REST API.
+ */
+
+import type { IServerWebSocket, ProtocolDef } from '@roj-ai/transport'
+import { ConnectionManager, ServerConnection } from '@roj-ai/transport/server'
+import type { Logger } from '../../lib/logger/logger.js'
+import type { IAgentTransport, PluginNotification } from './types.js'
+
+export interface ServerAdapterConfig {
+	logger?: Logger
+}
+
+export class ServerAdapter implements IAgentTransport {
+	private readonly connectionManager: ConnectionManager
+	private readonly logger?: Logger
+	private readonly wsToConnectionId = new WeakMap<IServerWebSocket, string>()
+
+	constructor(config: ServerAdapterConfig = {}) {
+		this.logger = config.logger?.child({ component: 'ServerAdapter' })
+		this.connectionManager = new ConnectionManager()
+	}
+
+	async start(): Promise<void> {
+		this.logger?.info('Server adapter started')
+	}
+
+	async stop(): Promise<void> {
+		this.connectionManager.clear()
+		this.logger?.info('Server adapter stopped')
+	}
+
+	broadcast(notification: PluginNotification): void {
+		// Extract sessionId from payload for routing to the correct session's subscribers
+		const payload = notification.payload
+		if (typeof payload !== 'object' || payload === null || !('sessionId' in payload)) {
+			this.logger?.warn('Notification dropped: no sessionId in payload', { type: notification.type })
+			return
+		}
+		const sessionId = String(payload.sessionId)
+		const wireMessage = JSON.stringify({ type: notification.type, payload: notification.payload, ts: Date.now() })
+		this.connectionManager.broadcast(sessionId, wireMessage)
+	}
+
+	// ============================================================================
+	// WebSocket Handler Integration (called from Bun server)
+	// ============================================================================
+
+	handleOpen(ws: IServerWebSocket, sessionId?: string): void {
+		const connection = new ServerConnection<ProtocolDef, ProtocolDef>({})
+
+		// No handlers needed - SPA doesn't send anything via WebSocket
+		// Session subscription is determined by sessionId passed at connection time
+
+		connection.attach(ws)
+		this.connectionManager.add(connection)
+		this.wsToConnectionId.set(ws, connection.getConnectionId())
+
+		// If sessionId provided, auto-subscribe
+		if (sessionId) {
+			this.connectionManager.subscribe(connection.getConnectionId(), sessionId)
+			this.logger?.debug('Client connected and subscribed', { connectionId: connection.getConnectionId(), sessionId })
+		} else {
+			this.logger?.debug('Client connected', { connectionId: connection.getConnectionId() })
+		}
+	}
+
+	handleClose(ws: IServerWebSocket, code: number, reason: string): void {
+		const connectionId = this.wsToConnectionId.get(ws)
+		if (connectionId) {
+			this.connectionManager.remove(connectionId)
+			this.wsToConnectionId.delete(ws)
+			this.logger?.debug('Client disconnected', { connectionId, code, reason })
+		}
+	}
+
+	handleMessage(ws: IServerWebSocket, message: string): void {
+		// Forward message to the connection's onmessage handler
+		ws.onmessage?.(message)
+	}
+
+	handleError(_ws: IServerWebSocket, error: Error): void {
+		this.logger?.error('WebSocket error', error)
+	}
+
+	getConnectionManager(): ConnectionManager {
+		return this.connectionManager
+	}
+}

package/src/transport/adapter/types.ts

@@ -0,0 +1,20 @@
+/**
+ * Agent Transport Types
+ *
+ * Simplified for broadcast-only WebSocket communication.
+ * User messages and answers are handled via REST API.
+ */
+
+import type { PluginNotification } from '~/core/plugins/plugin-builder.js'
+
+export type { PluginNotification }
+
+// ============================================================================
+// Transport Interface (broadcast only)
+// ============================================================================
+
+export interface IAgentTransport {
+	start(): Promise<void>
+	stop(): Promise<void>
+	broadcast(notification: PluginNotification): void
+}

package/src/transport/http/app.ts

@@ -0,0 +1,129 @@
+/**
+ * Hono App Setup
+ *
+ * Creates the main HTTP application with middleware and routes.
+ */
+
+import { Hono } from 'hono'
+import { cors } from 'hono/cors'
+import type { PreprocessorRegistry } from '~/plugins/uploads/preprocessor.js'
+import type { Services } from '../../bootstrap.js'
+import type { SessionManager } from '../../core/sessions/session-manager.js'
+import { createBearerAuth } from './middleware/bearer-auth.js'
+import { errorHandler } from './middleware/error-handler.js'
+import { createFileRoutes } from './routes/files.js'
+import { createResourceRoutes } from './routes/resources.js'
+import { createRpcRoutes } from './routes/rpc.js'
+import { createUploadRoutes } from './routes/upload.js'
+
+/**
+ * Extended services with SessionManager for HTTP routes.
+ */
+export type AppServices = Services & {
+	sessionRuntime: SessionManager
+	/** Bearer token for authenticating HTTP requests. Optional - only used in worker mode. */
+	agentToken?: string
+	/** File preprocessor registry for upload routes. Optional - only available when uploads plugin is configured. */
+	preprocessorRegistry?: PreprocessorRegistry
+}
+
+/**
+ * Environment type for Hono app with injected services.
+ */
+export type AppEnv = {
+	Variables: {
+		services: AppServices
+	}
+}
+
+/**
+ * Hono context type for routes.
+ */
+export type AppContext = import('hono').Context<AppEnv>
+
+/**
+ * Type-safe accessor for services from Hono context.
+ * Guarantees services are present (set by middleware).
+ */
+export function getServices(c: AppContext): AppServices {
+	return c.get('services')
+}
+
+/**
+ * Creates the Hono application with all middleware and routes.
+ */
+export function createApp(services: AppServices): Hono<AppEnv> {
+	const app = new Hono<AppEnv>()
+
+	// Middleware
+	app.use('*', cors())
+	app.use('*', async (c, next) => {
+		c.set('services', services)
+		await next()
+	})
+
+	// Error handler
+	app.onError(errorHandler)
+
+	// Health check (public - no auth required)
+	app.get('/health', (c) => {
+		return c.json({
+			status: 'ok',
+			timestamp: Date.now(),
+		})
+	})
+
+	// Bearer auth for protected routes
+	const bearerAuth = createBearerAuth(services.agentToken)
+
+	// Activity status for DO polling (protected)
+	// Returns lastActivityAt timestamp for the caller to determine if agent is active
+	app.get('/status', bearerAuth, async (c) => {
+		const { sessionRuntime } = getServices(c)
+		const stats = await sessionRuntime.getStats()
+
+		return c.json({
+			lastActivityAt: stats.lastActivityAt,
+			stats: {
+				sessionCount: stats.sessionCount,
+				pendingAgents: stats.pendingAgents,
+				processingAgents: stats.processingAgents,
+			},
+			sessions: stats.sessions.map(s => ({
+				id: s.id,
+				presetId: s.presetId,
+				status: s.status,
+				metrics: s.metrics,
+			})),
+			timestamp: Date.now(),
+		})
+	})
+
+	// Protected routes
+	const rpcRoutes = createRpcRoutes()
+	const uploadRoutes = createUploadRoutes()
+	const resourceRoutes = createResourceRoutes()
+	const fileRoutes = createFileRoutes()
+
+	app.use('/rpc/*', bearerAuth)
+	app.use('/sessions/*', bearerAuth)
+	app.route('/rpc', rpcRoutes)
+	app.route('/sessions', uploadRoutes)
+	app.route('/sessions', resourceRoutes)
+	app.route('/sessions', fileRoutes)
+
+	// 404 handler
+	app.notFound((c) => {
+		return c.json(
+			{
+				error: {
+					type: 'not_found',
+					message: `Route not found: ${c.req.method} ${c.req.path}`,
+				},
+			},
+			404,
+		)
+	})
+
+	return app
+}

package/src/transport/http/index.ts

@@ -0,0 +1,7 @@
+/**
+ * HTTP module exports
+ */
+
+export { createApp } from './app.js'
+export type { AppEnv } from './app.js'
+export { errorHandler } from './middleware/error-handler.js'

package/src/transport/http/middleware/bearer-auth.ts

@@ -0,0 +1,40 @@
+/**
+ * Bearer Auth Middleware
+ *
+ * Validates Authorization: Bearer <token> header against configured agentToken.
+ * Only active when agentToken is configured (worker mode).
+ */
+
+import type { MiddlewareHandler } from 'hono'
+import type { AppEnv } from '../app.js'
+
+/**
+ * Creates bearer auth middleware.
+ * Returns 401 if token is invalid or missing (when required).
+ *
+ * @param expectedToken - The expected bearer token. If undefined, middleware is a no-op.
+ */
+export function createBearerAuth(expectedToken: string | undefined): MiddlewareHandler<AppEnv> {
+	return async (c, next) => {
+		// Skip auth if no token configured (local dev mode)
+		if (!expectedToken) {
+			return next()
+		}
+
+		const authHeader = c.req.header('Authorization')
+		if (!authHeader) {
+			return c.json({ error: { type: 'unauthorized', message: 'Missing Authorization header' } }, 401)
+		}
+
+		const [scheme, token] = authHeader.split(' ')
+		if (scheme !== 'Bearer' || !token) {
+			return c.json({ error: { type: 'unauthorized', message: 'Invalid Authorization header format' } }, 401)
+		}
+
+		if (token !== expectedToken) {
+			return c.json({ error: { type: 'unauthorized', message: 'Invalid token' } }, 401)
+		}
+
+		return next()
+	}
+}

package/src/transport/http/middleware/error-handler.ts

@@ -0,0 +1,76 @@
+/**
+ * Error Handler Middleware
+ *
+ * Handles all errors thrown during request processing:
+ * - HTTPException from Hono
+ * - Domain errors from business logic (self-describing with httpStatus)
+ * - Validation errors from Zod
+ * - Unknown errors (logged and returned as 500)
+ */
+
+import type { Context } from 'hono'
+import { HTTPException } from 'hono/http-exception'
+import type { ContentfulStatusCode } from 'hono/utils/http-status'
+import { isDomainError } from '~/core/errors.js'
+import type { AppEnv } from '../app.js'
+
+/**
+ * Global error handler for Hono app.
+ */
+export const errorHandler = (error: Error, c: Context<AppEnv>) => {
+	const services = c.get('services')
+	const logger = services?.logger
+
+	// HTTPException (from Hono)
+	if (error instanceof HTTPException) {
+		return c.json(
+			{
+				error: {
+					type: 'http_error',
+					message: error.message,
+				},
+			},
+			error.status,
+		)
+	}
+
+	// Domain errors (self-describing — carry their own httpStatus)
+	if (isDomainError(error)) {
+		return c.json(
+			{ error: { type: error.type, message: error.message } },
+			error.httpStatus as ContentfulStatusCode,
+		)
+	}
+
+	// Validation errors (from Zod)
+	if (error.name === 'ZodError') {
+		const zodError = error as { issues?: unknown }
+		return c.json(
+			{
+				error: {
+					type: 'validation_error',
+					message: 'Invalid request',
+					details: zodError.issues,
+				},
+			},
+			400,
+		)
+	}
+
+	// Unknown errors
+	if (logger) {
+		logger.error('Unhandled error', error)
+	} else {
+		console.error('Unhandled error (no logger available):', error)
+	}
+
+	return c.json(
+		{
+			error: {
+				type: 'internal_error',
+				message: 'Internal server error',
+			},
+		},
+		500,
+	)
+}