@roj-ai/sdk 0.1.36 → 0.2.1

package/src/lib/logger/console.ts

@@ -1,5 +1,5 @@
 import type { LogContext, Logger, LogLevel } from './logger.js'
-import { shouldLog } from './logger.js'
+import { BaseLogger, shouldLog } from './logger.js'
 
 export interface ConsoleLoggerConfig {
 	level: LogLevel
@@ -15,45 +15,20 @@ const COLORS = {
 	error: '\x1b[31m', // red
 }
 
-export class ConsoleLogger implements Logger {
+export class ConsoleLogger extends BaseLogger {
 	readonly level: LogLevel
 	private useColors: boolean
 	private showTimestamps: boolean
 	private baseContext: LogContext
 
 	constructor(config: ConsoleLoggerConfig, baseContext: LogContext = {}) {
+		super()
 		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(
@@ -66,7 +41,7 @@ export class ConsoleLogger implements Logger {
 		)
 	}
 
-	private log(level: LogLevel, message: string, context?: LogContext): void {
+	protected log(level: LogLevel, message: string, context?: LogContext): void {
 		if (!shouldLog(level, this.level)) return
 
 		const fullContext = { ...this.baseContext, ...context }
@@ -118,47 +93,22 @@ export class ConsoleLogger implements Logger {
 /**
  * JSON Logger for production (structured output)
  */
-export class JsonLogger implements Logger {
+export class JsonLogger extends BaseLogger {
 	readonly level: LogLevel
 	private baseContext: LogContext
 
 	constructor(level: LogLevel, baseContext: LogContext = {}) {
+		super()
 		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 {
+	protected log(level: LogLevel, message: string, context?: LogContext): void {
 		if (!shouldLog(level, this.level)) return
 
 		const entry = {

package/src/lib/logger/file.ts

@@ -1,65 +1,43 @@
 import type { FileSystem } from '~/platform/fs.js'
-import type { LogContext, Logger, LogLevel } from './logger.js'
+import { JsonlLogger } from './jsonl.js'
+import type { LogContext, Logger } from './logger.js'
+
+/**
+ * Appends in flight per path, so lines land in the order they were logged.
+ *
+ * Keyed by path rather than held per instance because `child()` returns a new
+ * logger over the same file, and two independent `appendFile` calls to one path
+ * may complete in either order.
+ */
+const pendingByPath = new Map<string, Promise<void>>()
 
 /**
  * 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)
+export class FileLogger extends JsonlLogger {
+	constructor(private readonly filePath: string, private readonly fs: FileSystem, baseContext: LogContext = {}) {
+		super(baseContext)
 	}
 
 	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
+	protected writeLine(line: string): void {
+		const path = this.filePath
+		const previous = pendingByPath.get(path) ?? Promise.resolve()
+		// A failed append must not break the chain — the next line still has to be written.
+		const next = previous.then(() => this.fs.appendFile(path, line + '\n')).catch(() => {})
+		pendingByPath.set(path, next)
+		void next.then(() => {
+			if (pendingByPath.get(path) === next) pendingByPath.delete(path)
 		})
 	}
 }
+
+/** Resolves once every line logged so far has been written. For tests and shutdown. */
+export function flushFileLogs(filePath?: string): Promise<void> {
+	if (filePath !== undefined) return pendingByPath.get(filePath) ?? Promise.resolve()
+	return Promise.all([...pendingByPath.values()]).then(() => undefined)
+}

package/src/lib/logger/index.ts

@@ -1,4 +1,6 @@
 export { ConsoleLogger, JsonLogger } from './console.js'
 export type { ConsoleLoggerConfig } from './console.js'
-export { FileLogger } from './file.js'
+export { FileLogger, flushFileLogs } from './file.js'
+export { JsonlLogger } from './jsonl.js'
+export { createSessionLogger, SessionLogStoreLogger } from './session-log.js'
 export { TeeLogger } from './tee.js'

package/src/lib/logger/jsonl.ts

@@ -0,0 +1,36 @@
+import type { LogContext, Logger, LogLevel } from './logger.js'
+import { BaseLogger } from './logger.js'
+
+/**
+ * One JSON object per entry, always at debug level.
+ *
+ * The level is deliberately not `config.logLevel`: the session log is the
+ * detailed record and the console logger is the filtered one.
+ *
+ * Shared by the file sink and the store sink so a host that moves the log into
+ * a table emits exactly the same entries — the sink is the only difference.
+ */
+export abstract class JsonlLogger extends BaseLogger {
+	readonly level: LogLevel = 'debug'
+
+	constructor(protected readonly baseContext: LogContext = {}) {
+		super()
+	}
+
+	abstract child(context: LogContext): Logger
+
+	/** Takes one finished entry, no trailing newline. Must never throw. */
+	protected abstract writeLine(line: string): void
+
+	protected log(level: LogLevel, message: string, context?: LogContext): void {
+		const entry = {
+			timestamp: new Date().toISOString(),
+			level,
+			message,
+			...this.baseContext,
+			...context,
+		}
+
+		this.writeLine(JSON.stringify(entry))
+	}
+}

package/src/lib/logger/logger.ts

@@ -112,3 +112,51 @@ export interface ToolLogContext extends LogContext {
 	toolCallId: string
 	durationMs?: number
 }
+
+/**
+ * Shared base for sink-backed loggers.
+ *
+ * The four level methods and the Error->context flattening in error() were
+ * copied verbatim into ConsoleLogger, JsonLogger and FileLogger. The flattening
+ * is the part worth having in one place — it is the only path by which a stack
+ * trace reaches a structured log, so a sink that misses it drops the field
+ * silently.
+ *
+ * Subclasses supply only log() and child(); child() stays per-class because each
+ * returns its own type with its own config. TeeLogger does NOT extend this — it
+ * fans out to other loggers rather than writing to a sink.
+ */
+export abstract class BaseLogger implements Logger {
+	abstract readonly level: LogLevel
+
+	protected abstract log(level: LogLevel, message: string, context?: LogContext): void
+
+	abstract child(context: LogContext): Logger
+
+	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)
+	}
+}

package/src/lib/logger/session-log.ts

@@ -0,0 +1,42 @@
+import type { Platform } from '~/platform/index.js'
+import type { SessionLogStore } from '~/platform/session-log.js'
+import { FileLogger } from './file.js'
+import { JsonlLogger } from './jsonl.js'
+import type { LogContext, Logger } from './logger.js'
+
+/** The same JSONL FileLogger writes, into a {@link SessionLogStore} row. */
+export class SessionLogStoreLogger extends JsonlLogger {
+	constructor(private readonly store: SessionLogStore, private readonly sessionId: string, baseContext: LogContext = {}) {
+		super(baseContext)
+	}
+
+	child(context: LogContext): Logger {
+		return new SessionLogStoreLogger(this.store, this.sessionId, { ...this.baseContext, ...context })
+	}
+
+	protected writeLine(line: string): void {
+		try {
+			this.store.append(this.sessionId, line)
+		} catch {
+			// Dropped exactly as a failed file append is — nothing on the agent loop awaits this.
+		}
+	}
+}
+
+/**
+ * The session's own log sink: rows where the host has a table for them, the
+ * `session.log` file everywhere else.
+ *
+ * The absence of `platform.sessionLog` is the status quo — same file, same
+ * bytes, same byte-offset cursor in `logs.tail`.
+ */
+export function createSessionLogger(
+	platform: Pick<Platform, 'fs' | 'sessionLog'>,
+	sessionId: string,
+	logPath: string,
+): Logger {
+	const store = platform.sessionLog
+	return store === undefined
+		? new FileLogger(logPath, platform.fs, { sessionId })
+		: new SessionLogStoreLogger(store, sessionId, { sessionId })
+}

package/src/lib/utils/concurrency.ts

@@ -33,7 +33,11 @@ export async function mapWithConcurrency<T, R>(
  */
 export class Semaphore {
 	private active = 0
-	private readonly waiters: Array<() => void> = []
+	private readonly waiters: Array<{
+		resolve: () => void
+		signal?: AbortSignal
+		onAbort?: () => void
+	}> = []
 
 	constructor(private readonly limit: number) {
 		if (!Number.isInteger(limit) || limit < 1) {
@@ -41,22 +45,44 @@ export class Semaphore {
 		}
 	}
 
-	async run<T>(fn: () => Promise<T>): Promise<T> {
-		await this.acquire()
+	async run<T>(fn: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+		let acquired = false
 		try {
+			await this.acquire(signal)
+			acquired = true
+			signal?.throwIfAborted()
 			return await fn()
 		} finally {
-			this.release()
+			if (acquired) this.release()
 		}
 	}
 
-	private acquire(): Promise<void> {
+	private acquire(signal?: AbortSignal): Promise<void> {
+		if (signal?.aborted) {
+			return Promise.reject(signal.reason)
+		}
 		if (this.active < this.limit) {
 			this.active++
 			return Promise.resolve()
 		}
-		return new Promise<void>(resolve => {
-			this.waiters.push(resolve)
+		return new Promise<void>((resolve, reject) => {
+			const waiter: {
+				resolve: () => void
+				signal?: AbortSignal
+				onAbort?: () => void
+			} = { resolve, signal }
+			if (signal) {
+				const onAbort = () => {
+					const index = this.waiters.indexOf(waiter)
+					if (index === -1) return
+					this.waiters.splice(index, 1)
+					signal.removeEventListener('abort', onAbort)
+					reject(signal.reason)
+				}
+				waiter.onAbort = onAbort
+				signal.addEventListener('abort', onAbort, { once: true })
+			}
+			this.waiters.push(waiter)
 		})
 	}
 
@@ -64,7 +90,10 @@ export class Semaphore {
 		const next = this.waiters.shift()
 		if (next) {
 			// Slot transfers directly to the next waiter; active stays unchanged.
-			next()
+			if (next.signal && next.onAbort) {
+				next.signal.removeEventListener('abort', next.onAbort)
+			}
+			next.resolve()
 		} else {
 			this.active--
 		}

package/src/lib/utils/fs-batch.ts

@@ -0,0 +1,49 @@
+/**
+ * Reading a known set of files, however the platform prefers to be asked.
+ *
+ * `FileSystem.readFiles` is optional — a plain node:fs platform has no use for
+ * it, a database-backed one answers a whole set in about the work it spends on
+ * one file. Every caller with a list of paths wants the same two things from
+ * that difference: the batch where it exists, and the loop where it does not,
+ * with a missing file reported rather than thrown either way.
+ *
+ * So it lives here once instead of at each call site.
+ */
+
+import type { FileSystem } from '~/platform/fs.js'
+import { mapWithConcurrency } from './concurrency.js'
+
+/** Files read at once when the platform has no batch verb. */
+const READ_CONCURRENCY = 16
+
+/** Every path's bytes, in order, `undefined` where there was nothing to read. */
+export async function readFilesOrUndefined(
+	fs: FileSystem,
+	paths: readonly string[],
+): Promise<(Buffer | undefined)[]> {
+	if (paths.length === 0) return []
+
+	if (fs.readFiles) {
+		const read = await fs.readFiles(paths)
+		return paths.map((_path, index) => read[index]?.content)
+	}
+
+	return mapWithConcurrency(paths, READ_CONCURRENCY, (path) => readOrUndefined(fs, path))
+}
+
+/** The same, decoded as UTF-8. */
+export async function readTextFilesOrUndefined(
+	fs: FileSystem,
+	paths: readonly string[],
+): Promise<(string | undefined)[]> {
+	const read = await readFilesOrUndefined(fs, paths)
+	return read.map((bytes) => bytes?.toString('utf-8'))
+}
+
+async function readOrUndefined(fs: FileSystem, path: string): Promise<Buffer | undefined> {
+	try {
+		return await fs.readFile(path)
+	} catch {
+		return undefined
+	}
+}

package/src/lib/utils/result.ts

@@ -1,35 +1,11 @@
 /**
  * Result type for explicit error handling without exceptions.
- * Inspired by Rust/Go approach.
+ *
+ * Re-exported from @roj-ai/transport, which owns the definition — sdk already
+ * depends on it, and three byte-identical copies (here, transport, shared) meant
+ * any addition to the vocabulary had to be written three times or silently
+ * diverge. The ~58 in-package importers keep using `~/lib/utils/result.js`.
  */
 
-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
-}
+export type { Result } from '@roj-ai/transport'
+export { Err, flatMapResult, isErr, isOk, mapResult, Ok, unwrapOr, unwrapOrThrow } from '@roj-ai/transport'

package/src/lib/utils/sleep.ts

@@ -0,0 +1,23 @@
+/**
+ * Cancellable sleep.
+ *
+ * Resolves early (rather than rejecting) when `signal` aborts, so a retry or
+ * poll loop can check its own abort condition and exit on the next iteration.
+ * Prefer this over a bare `setTimeout` promise anywhere inside such a loop —
+ * a non-cancellable wait is what makes shutdown take as long as the backoff.
+ */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+	if (signal?.aborted) return Promise.resolve()
+	return new Promise<void>((resolve) => {
+		let settled = false
+		const finish = () => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			signal?.removeEventListener('abort', finish)
+			resolve()
+		}
+		const timer = setTimeout(finish, ms)
+		signal?.addEventListener('abort', finish, { once: true })
+	})
+}

package/src/platform/fs-revision.ts

@@ -0,0 +1,21 @@
+/**
+ * Filesystem revision adapter.
+ *
+ * One number that moves whenever anything in the host's filesystem changes, so a
+ * caller holding an answer derived from the tree can tell "nothing happened" from
+ * "read it again" without doing the read. A gate, never a source.
+ */
+
+export interface FsRevision {
+	/**
+	 * Current revision, or `undefined` when the host cannot tell — which callers
+	 * read as "recompute", the same as a host with no port at all.
+	 *
+	 * The number is opaque and only comparable for equality. It covers the whole
+	 * filesystem the host exposes, so it moves for writes the caller does not care
+	 * about: a gate on it recomputes more often than needed, never less.
+	 *
+	 * Never rejects: a host that cannot answer says so with `undefined`.
+	 */
+	current(): Promise<number | undefined>
+}