@roj-ai/sdk 0.0.2

package/src/lib/logger/console.ts

@@ -0,0 +1,185 @@
+import type { LogContext, Logger, LogLevel } from './logger.js'
+import { shouldLog } from './logger.js'
+
+export interface ConsoleLoggerConfig {
+	level: LogLevel
+	colors?: boolean
+	timestamps?: boolean
+}
+
+const COLORS = {
+	reset: '\x1b[0m',
+	debug: '\x1b[36m', // cyan
+	info: '\x1b[32m', // green
+	warn: '\x1b[33m', // yellow
+	error: '\x1b[31m', // red
+}
+
+export class ConsoleLogger implements Logger {
+	readonly level: LogLevel
+	private useColors: boolean
+	private showTimestamps: boolean
+	private baseContext: LogContext
+
+	constructor(config: ConsoleLoggerConfig, baseContext: LogContext = {}) {
+		this.level = config.level
+		this.useColors = config.colors ?? true
+		this.showTimestamps = config.timestamps ?? true
+		this.baseContext = baseContext
+	}
+
+	debug(message: string, context?: LogContext): void {
+		this.log('debug', message, context)
+	}
+
+	info(message: string, context?: LogContext): void {
+		this.log('info', message, context)
+	}
+
+	warn(message: string, context?: LogContext): void {
+		this.log('warn', message, context)
+	}
+
+	error(message: string, error?: Error, context?: LogContext): void {
+		const errorContext = error
+			? {
+				...context,
+				error: {
+					name: error.name,
+					message: error.message,
+					stack: error.stack,
+				},
+			}
+			: context
+
+		this.log('error', message, errorContext)
+	}
+
+	child(context: LogContext): Logger {
+		return new ConsoleLogger(
+			{
+				level: this.level,
+				colors: this.useColors,
+				timestamps: this.showTimestamps,
+			},
+			{ ...this.baseContext, ...context },
+		)
+	}
+
+	private log(level: LogLevel, message: string, context?: LogContext): void {
+		if (!shouldLog(level, this.level)) return
+
+		const fullContext = { ...this.baseContext, ...context }
+		const timestamp = this.showTimestamps ? new Date().toISOString() : ''
+		const colorStart = this.useColors ? COLORS[level] : ''
+		const colorEnd = this.useColors ? COLORS.reset : ''
+
+		const parts: string[] = []
+
+		if (timestamp) {
+			parts.push(`[${timestamp}]`)
+		}
+
+		parts.push(`${colorStart}${level.toUpperCase().padEnd(5)}${colorEnd}`)
+		parts.push(message)
+
+		if (Object.keys(fullContext).length > 0) {
+			parts.push(this.formatContext(fullContext))
+		}
+
+		const output = parts.join(' ')
+
+		switch (level) {
+			case 'error':
+				console.error(output)
+				break
+			case 'warn':
+				console.warn(output)
+				break
+			default:
+				console.log(output)
+		}
+	}
+
+	private formatContext(context: LogContext): string {
+		const entries = Object.entries(context)
+			.map(([key, value]) => {
+				const formatted = typeof value === 'object'
+					? JSON.stringify(value)
+					: String(value)
+				return `${key}=${formatted}`
+			})
+			.join(' ')
+
+		return `{ ${entries} }`
+	}
+}
+
+/**
+ * JSON Logger for production (structured output)
+ */
+export class JsonLogger implements Logger {
+	readonly level: LogLevel
+	private baseContext: LogContext
+
+	constructor(level: LogLevel, baseContext: LogContext = {}) {
+		this.level = level
+		this.baseContext = baseContext
+	}
+
+	debug(message: string, context?: LogContext): void {
+		this.log('debug', message, context)
+	}
+
+	info(message: string, context?: LogContext): void {
+		this.log('info', message, context)
+	}
+
+	warn(message: string, context?: LogContext): void {
+		this.log('warn', message, context)
+	}
+
+	error(message: string, error?: Error, context?: LogContext): void {
+		const errorContext = error
+			? {
+				...context,
+				error: {
+					name: error.name,
+					message: error.message,
+					stack: error.stack,
+				},
+			}
+			: context
+
+		this.log('error', message, errorContext)
+	}
+
+	child(context: LogContext): Logger {
+		return new JsonLogger(this.level, { ...this.baseContext, ...context })
+	}
+
+	private log(level: LogLevel, message: string, context?: LogContext): void {
+		if (!shouldLog(level, this.level)) return
+
+		const entry = {
+			timestamp: new Date().toISOString(),
+			level,
+			message,
+			...this.baseContext,
+			...context,
+		}
+
+		const output = JSON.stringify(entry)
+
+		switch (level) {
+			case 'error':
+				console.error(output)
+				break
+			case 'warn':
+				console.warn(output)
+				break
+			default:
+				console.log(output)
+		}
+	}
+}

package/src/lib/logger/file.ts

@@ -0,0 +1,65 @@
+import type { FileSystem } from '~/platform/fs.js'
+import type { LogContext, Logger, LogLevel } from './logger.js'
+
+/**
+ * FileLogger - writes JSONL to a file, always at debug level.
+ * Each line is a JSON object with timestamp, level, message, and context.
+ */
+export class FileLogger implements Logger {
+	readonly level: LogLevel = 'debug'
+	private filePath: string
+	private baseContext: LogContext
+	private fs: FileSystem
+
+	constructor(filePath: string, fs: FileSystem, baseContext: LogContext = {}) {
+		this.filePath = filePath
+		this.fs = fs
+		this.baseContext = baseContext
+	}
+
+	debug(message: string, context?: LogContext): void {
+		this.log('debug', message, context)
+	}
+
+	info(message: string, context?: LogContext): void {
+		this.log('info', message, context)
+	}
+
+	warn(message: string, context?: LogContext): void {
+		this.log('warn', message, context)
+	}
+
+	error(message: string, error?: Error, context?: LogContext): void {
+		const errorContext = error
+			? {
+				...context,
+				error: {
+					name: error.name,
+					message: error.message,
+					stack: error.stack,
+				},
+			}
+			: context
+
+		this.log('error', message, errorContext)
+	}
+
+	child(context: LogContext): Logger {
+		return new FileLogger(this.filePath, this.fs, { ...this.baseContext, ...context })
+	}
+
+	private log(level: LogLevel, message: string, context?: LogContext): void {
+		const entry = {
+			timestamp: new Date().toISOString(),
+			level,
+			message,
+			...this.baseContext,
+			...context,
+		}
+
+		const line = JSON.stringify(entry) + '\n'
+		this.fs.appendFile(this.filePath, line).catch(() => {
+			// Silently ignore write errors to avoid disrupting the application
+		})
+	}
+}

package/src/lib/logger/index.ts

@@ -0,0 +1,4 @@
+export { ConsoleLogger, JsonLogger } from './console.js'
+export type { ConsoleLoggerConfig } from './console.js'
+export { FileLogger } from './file.js'
+export { TeeLogger } from './tee.js'

package/src/lib/logger/logger.ts

@@ -0,0 +1,114 @@
+/**
+ * Logger port - interface pro structured logging
+ */
+
+/**
+ * Log levels
+ */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error'
+
+/**
+ * Log context - structured metadata
+ */
+export type LogContext = Record<string, unknown>
+
+/**
+ * Logger interface
+ */
+export interface Logger {
+	/**
+	 * Debug level - detailní informace pro debugging
+	 */
+	debug(message: string, context?: LogContext): void
+
+	/**
+	 * Info level - běžné informační zprávy
+	 */
+	info(message: string, context?: LogContext): void
+
+	/**
+	 * Warning level - něco není v pořádku, ale není to kritické
+	 */
+	warn(message: string, context?: LogContext): void
+
+	/**
+	 * Error level - chyba, která vyžaduje pozornost
+	 */
+	error(message: string, error?: Error, context?: LogContext): void
+
+	/**
+	 * Vytvoří child logger s předdefinovaným kontextem.
+	 * Child logger přidává svůj kontext ke každé zprávě.
+	 */
+	child(context: LogContext): Logger
+
+	/**
+	 * Aktuální log level
+	 */
+	readonly level: LogLevel
+}
+
+/**
+ * Logger factory type
+ */
+export type LoggerFactory = (name: string) => Logger
+
+/**
+ * Silent logger - nic neloguje (pro testy)
+ */
+export const silentLogger: Logger = {
+	debug: () => {},
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	child: () => silentLogger,
+	level: 'error',
+}
+
+/**
+ * Log level priority (pro filtering)
+ */
+export const LOG_LEVEL_PRIORITY: Record<LogLevel, number> = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3,
+}
+
+/**
+ * Helper pro porovnání log levels
+ */
+export const shouldLog = (messageLevel: LogLevel, configuredLevel: LogLevel): boolean =>
+	LOG_LEVEL_PRIORITY[messageLevel] >= LOG_LEVEL_PRIORITY[configuredLevel]
+
+/**
+ * Standardní kontext pro agent operace
+ */
+export interface AgentLogContext extends LogContext {
+	sessionId: string
+	agentId: string
+	definitionName?: string
+}
+
+/**
+ * Standardní kontext pro LLM operace
+ */
+export interface LLMLogContext extends LogContext {
+	sessionId: string
+	agentId: string
+	model: string
+	promptTokens?: number
+	completionTokens?: number
+	latencyMs?: number
+}
+
+/**
+ * Standardní kontext pro tool operace
+ */
+export interface ToolLogContext extends LogContext {
+	sessionId: string
+	agentId: string
+	toolName: string
+	toolCallId: string
+	durationMs?: number
+}

package/src/lib/logger/ring-buffer.ts

@@ -0,0 +1,65 @@
+/**
+ * RingBuffer - Circular buffer for log lines.
+ *
+ * Fixed-size buffer that overwrites oldest entries when full.
+ */
+export class RingBuffer {
+	private readonly buffer: string[]
+	private readonly capacity: number
+	private head = 0
+	private count = 0
+
+	constructor(capacity: number) {
+		this.capacity = capacity
+		this.buffer = new Array(capacity)
+	}
+
+	/**
+	 * Push a line into the buffer. Overwrites oldest if full.
+	 */
+	push(line: string): void {
+		this.buffer[this.head] = line
+		this.head = (this.head + 1) % this.capacity
+		if (this.count < this.capacity) {
+			this.count++
+		}
+	}
+
+	/**
+	 * Return all lines in order (oldest first).
+	 */
+	toArray(): string[] {
+		if (this.count < this.capacity) {
+			return this.buffer.slice(0, this.count)
+		}
+		// Buffer is full: head points to the oldest entry
+		return [
+			...this.buffer.slice(this.head, this.capacity),
+			...this.buffer.slice(0, this.head),
+		]
+	}
+
+	/**
+	 * Return the last N lines (most recent).
+	 */
+	last(n: number): string[] {
+		const all = this.toArray()
+		if (n >= all.length) return all
+		return all.slice(all.length - n)
+	}
+
+	/**
+	 * Clear the buffer.
+	 */
+	clear(): void {
+		this.head = 0
+		this.count = 0
+	}
+
+	/**
+	 * Current number of lines in the buffer.
+	 */
+	get size(): number {
+		return this.count
+	}
+}

package/src/lib/logger/tee.ts

@@ -0,0 +1,51 @@
+import type { LogContext, Logger, LogLevel } from './logger.js'
+import { LOG_LEVEL_PRIORITY } from './logger.js'
+
+/**
+ * TeeLogger - delegates all log calls to multiple loggers.
+ */
+export class TeeLogger implements Logger {
+	private loggers: Logger[]
+
+	constructor(loggers: Logger[]) {
+		this.loggers = loggers
+	}
+
+	get level(): LogLevel {
+		let mostPermissive: LogLevel = 'error'
+		for (const logger of this.loggers) {
+			if (LOG_LEVEL_PRIORITY[logger.level] < LOG_LEVEL_PRIORITY[mostPermissive]) {
+				mostPermissive = logger.level
+			}
+		}
+		return mostPermissive
+	}
+
+	debug(message: string, context?: LogContext): void {
+		for (const logger of this.loggers) {
+			logger.debug(message, context)
+		}
+	}
+
+	info(message: string, context?: LogContext): void {
+		for (const logger of this.loggers) {
+			logger.info(message, context)
+		}
+	}
+
+	warn(message: string, context?: LogContext): void {
+		for (const logger of this.loggers) {
+			logger.warn(message, context)
+		}
+	}
+
+	error(message: string, error?: Error, context?: LogContext): void {
+		for (const logger of this.loggers) {
+			logger.error(message, error, context)
+		}
+	}
+
+	child(context: LogContext): Logger {
+		return new TeeLogger(this.loggers.map(l => l.child(context)))
+	}
+}

package/src/lib/mime.ts

@@ -0,0 +1,23 @@
+/**
+ * MIME type detection utilities.
+ */
+
+const IMAGE_MIME_TYPES: Record<string, string> = {
+	png: 'image/png',
+	jpg: 'image/jpeg',
+	jpeg: 'image/jpeg',
+	gif: 'image/gif',
+	webp: 'image/webp',
+	svg: 'image/svg+xml',
+	bmp: 'image/bmp',
+	ico: 'image/x-icon',
+}
+
+/**
+ * Get MIME type for an image file based on extension.
+ * Returns undefined if not a recognized image format.
+ */
+export function getImageMimeType(filename: string): string | undefined {
+	const ext = filename.split('.').pop()?.toLowerCase()
+	return ext ? IMAGE_MIME_TYPES[ext] : undefined
+}

package/src/lib/never.ts

@@ -0,0 +1,3 @@
+export const assertNever = (value: never): never => {
+	throw new Error(`Unexpected value: ${JSON.stringify(value)}`)
+}

package/src/lib/utils/hash.ts

@@ -0,0 +1,38 @@
+/**
+ * Synchronous hash utilities for anti-looping fingerprinting.
+ * Uses FNV-1a for fast, deterministic hashing in pure reducers.
+ */
+
+const FNV_OFFSET_BASIS = 2166136261
+const FNV_PRIME = 16777619
+const MAX_INPUT_LENGTH = 500
+
+/**
+ * FNV-1a 32-bit hash, returned as hex string.
+ */
+export function fnv1aHash(str: string): string {
+	let hash = FNV_OFFSET_BASIS
+	for (let i = 0; i < str.length; i++) {
+		hash ^= str.charCodeAt(i)
+		hash = Math.imul(hash, FNV_PRIME)
+	}
+	return (hash >>> 0).toString(16)
+}
+
+/**
+ * Fingerprint a tool call as "toolName:hash(input)".
+ * Input is JSON-stringified and truncated to 500 chars before hashing.
+ */
+export function toolCallFingerprint(toolName: string, input: unknown): string {
+	const inputStr = JSON.stringify(input ?? null).slice(0, MAX_INPUT_LENGTH)
+	return `${toolName}:${fnv1aHash(inputStr)}`
+}
+
+/**
+ * Fingerprint a text response.
+ * Content is truncated to 500 chars before hashing.
+ */
+export function responseFingerprint(content: string | null): string {
+	const str = (content ?? '').slice(0, MAX_INPUT_LENGTH)
+	return fnv1aHash(str)
+}

package/src/lib/utils/result.ts

@@ -0,0 +1,35 @@
+/**
+ * Result type for explicit error handling without exceptions.
+ * Inspired by Rust/Go approach.
+ */
+
+export type Result<T, E = Error> =
+	| { ok: true; value: T }
+	| { ok: false; error: E }
+
+// Constructors
+export const Ok = <T>(value: T): Result<T, never> => ({ ok: true, value })
+export const Err = <E>(error: E): Result<never, E> => ({ ok: false, error })
+
+// Type guards
+export const isOk = <T, E>(result: Result<T, E>): result is { ok: true; value: T } => result.ok
+export const isErr = <T, E>(result: Result<T, E>): result is { ok: false; error: E } => !result.ok
+
+// Helper functions
+export const mapResult = <T, U, E>(
+	result: Result<T, E>,
+	fn: (value: T) => U,
+): Result<U, E> => result.ok ? Ok(fn(result.value)) : result
+
+export const flatMapResult = <T, U, E>(
+	result: Result<T, E>,
+	fn: (value: T) => Result<U, E>,
+): Result<U, E> => result.ok ? fn(result.value) : result
+
+// Unwrap functions
+export const unwrapOr = <T, E>(result: Result<T, E>, defaultValue: T): T => result.ok ? result.value : defaultValue
+
+export const unwrapOrThrow = <T, E>(result: Result<T, E>): T => {
+	if (result.ok) return result.value
+	throw result.error
+}

package/src/platform/fs.ts

@@ -0,0 +1,38 @@
+/**
+ * FileSystem adapter interface.
+ *
+ * Platform-agnostic subset of `node:fs/promises` operations used across the SDK.
+ * Concrete implementations live in runtime-specific packages (e.g. `@roj-ai/sdk/bun-platform`).
+ */
+
+import type { Dirent, Stats } from 'node:fs'
+import type { FileHandle } from 'node:fs/promises'
+
+export type { Dirent, FileHandle, Stats }
+
+export interface FileSystem {
+	readFile(path: string): Promise<Buffer>
+	readFile(path: string, encoding: 'utf-8' | 'utf8'): Promise<string>
+
+	writeFile(path: string, data: string | Uint8Array): Promise<void>
+	appendFile(path: string, data: string | Uint8Array): Promise<void>
+
+	mkdir(path: string, options?: { recursive?: boolean }): Promise<void>
+	readdir(path: string): Promise<string[]>
+	readdir(path: string, options: { withFileTypes: true }): Promise<Dirent[]>
+
+	stat(path: string): Promise<Stats>
+	access(path: string, mode?: number): Promise<void>
+
+	unlink(path: string): Promise<void>
+	rm(path: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>
+	cp(source: string, dest: string, options?: { recursive?: boolean; force?: boolean }): Promise<void>
+
+	open(path: string, flags?: string): Promise<FileHandle>
+
+	/** Returns true if path exists and is accessible; never throws for missing paths. */
+	exists(path: string): Promise<boolean>
+
+	/** Resolves symlinks and returns the canonical pathname. */
+	realpath(path: string): Promise<string>
+}

package/src/platform/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Platform adapters — runtime-agnostic interfaces for host-environment capabilities.
+ *
+ * Code in `@roj-ai/sdk` MUST NOT import from `node:*` / `bun:*` directly;
+ * it goes through these adapters. Concrete implementations are provided by
+ * runtime packages (e.g. `@roj-ai/sdk/bun-platform`) and wired in at bootstrap time.
+ */
+
+import type { FileSystem } from './fs.js'
+import type { ProcessRunner } from './process.js'
+
+export type { Dirent, FileHandle, FileSystem, Stats } from './fs.js'
+export type { ChildProcess, ExecFileOptions, ExecFileResult, ProcessRunner, SpawnOptions } from './process.js'
+
+/**
+ * Aggregate platform capabilities passed through the system at bootstrap.
+ */
+export interface Platform {
+	fs: FileSystem
+	process: ProcessRunner
+	/** Absolute path to the OS temp directory (equivalent to `os.tmpdir()` on Node/Bun). */
+	tmpDir: string
+}

package/src/platform/process.ts

@@ -0,0 +1,28 @@
+/**
+ * ProcessRunner adapter interface.
+ *
+ * Platform-agnostic subset of `node:child_process` used across the SDK.
+ * Concrete implementations live in runtime-specific packages (e.g. `@roj-ai/sdk/bun-platform`).
+ */
+
+import type { ChildProcess, ExecFileOptions, SpawnOptions } from 'node:child_process'
+
+export type { ChildProcess, ExecFileOptions, SpawnOptions }
+
+export interface ExecFileResult {
+	stdout: string
+	stderr: string
+}
+
+export interface ProcessRunner {
+	/**
+	 * Execute a file with arguments; buffers stdout/stderr and resolves with them.
+	 * Rejects if the child exits with a non-zero code (Node semantics).
+	 */
+	execFile(file: string, args: string[], options?: ExecFileOptions): Promise<ExecFileResult>
+
+	/**
+	 * Spawn a child process; caller manages streams and lifecycle.
+	 */
+	spawn(command: string, args: string[], options?: SpawnOptions): ChildProcess
+}