@better-openclaw/core 1.0.26 → 1.0.31

package/src/logger/logger.ts

@@ -0,0 +1,326 @@
+import { randomUUID } from "node:crypto";
+import type {
+	LogLevel,
+	LogSink,
+	LogSource,
+	OperationCategory,
+	OperationOutcome,
+	OperationStep,
+	OperationsLogEntry,
+	OperationsLoggerOptions,
+} from "./types.js";
+
+/** Keys that must never appear in logged context. */
+const SENSITIVE_KEYS = new Set([
+	"apikey",
+	"api_key",
+	"password",
+	"token",
+	"secret",
+	"authorization",
+	"credentials",
+	"private_key",
+	"privatekey",
+]);
+
+const LEVEL_ORDER: Record<LogLevel, number> = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3,
+};
+
+/** Strip sensitive keys from a context object (shallow). */
+function sanitizeContext(
+	ctx: Record<string, unknown> | undefined,
+): Record<string, unknown> | undefined {
+	if (!ctx) return ctx;
+	const clean: Record<string, unknown> = {};
+	for (const [key, value] of Object.entries(ctx)) {
+		if (SENSITIVE_KEYS.has(key.toLowerCase())) {
+			clean[key] = "[REDACTED]";
+		} else {
+			clean[key] = value;
+		}
+	}
+	return clean;
+}
+
+/**
+ * Tracks individual steps within a multi-step operation (e.g. deploy, generate).
+ */
+export class StepTracker {
+	private steps: OperationStep[] = [];
+	private currentStep: OperationStep | null = null;
+	private readonly operationStart = Date.now();
+
+	constructor(
+		private readonly logger: OperationsLogger,
+		private readonly category: OperationCategory,
+		private readonly operationName: string,
+	) {}
+
+	/** Start a new step. Automatically completes the previous step if still open. */
+	begin(name: string, detail?: string): void {
+		if (this.currentStep && this.currentStep.status === "in_progress") {
+			this.currentStep.status = "success";
+			this.currentStep.completedAt = new Date().toISOString();
+			this.currentStep.durationMs = Date.now() - new Date(this.currentStep.startedAt).getTime();
+		}
+		this.currentStep = {
+			name,
+			status: "in_progress",
+			detail,
+			startedAt: new Date().toISOString(),
+		};
+		this.steps.push(this.currentStep);
+		this.logger.debug(this.category, `[${this.operationName}] ${name}`, {
+			step: name,
+			detail,
+		});
+	}
+
+	/** Mark the current step as completed. */
+	complete(detail?: string): void {
+		if (!this.currentStep) return;
+		this.currentStep.status = "success";
+		this.currentStep.completedAt = new Date().toISOString();
+		this.currentStep.durationMs = Date.now() - new Date(this.currentStep.startedAt).getTime();
+		if (detail) this.currentStep.detail = detail;
+	}
+
+	/** Mark the current step as failed. */
+	fail(error: string): void {
+		if (!this.currentStep) return;
+		this.currentStep.status = "failure";
+		this.currentStep.completedAt = new Date().toISOString();
+		this.currentStep.durationMs = Date.now() - new Date(this.currentStep.startedAt).getTime();
+		this.currentStep.detail = error;
+	}
+
+	/** Record a skipped step. */
+	skip(name: string, reason?: string): void {
+		this.steps.push({
+			name,
+			status: "skipped",
+			detail: reason,
+			startedAt: new Date().toISOString(),
+			completedAt: new Date().toISOString(),
+			durationMs: 0,
+		});
+	}
+
+	/** Finalize and log the full operation summary. Returns all steps. */
+	finalize(outcome: OperationOutcome): OperationStep[] {
+		// Close any open step
+		if (this.currentStep && this.currentStep.status === "in_progress") {
+			this.currentStep.status = outcome === "failure" ? "failure" : "success";
+			this.currentStep.completedAt = new Date().toISOString();
+			this.currentStep.durationMs = Date.now() - new Date(this.currentStep.startedAt).getTime();
+		}
+
+		this.logger.log({
+			level: outcome === "failure" ? "error" : "info",
+			category: this.category,
+			message: `${this.operationName} ${outcome}`,
+			outcome,
+			durationMs: Date.now() - this.operationStart,
+			steps: this.steps,
+		});
+		return this.steps;
+	}
+
+	/** Get the current list of steps (snapshot). */
+	getSteps(): OperationStep[] {
+		return [...this.steps];
+	}
+}
+
+/**
+ * Centralized operations logger.
+ *
+ * Follows fire-and-forget semantics — sink errors are silently caught and
+ * logging never blocks or crashes the main flow.
+ */
+export class OperationsLogger {
+	private readonly source: LogSource;
+	private readonly sinks: LogSink[];
+	private readonly correlationId: string;
+	private readonly sessionId: string;
+	private readonly minLevel: LogLevel;
+
+	constructor(options: OperationsLoggerOptions) {
+		this.source = options.source;
+		this.sinks = options.sinks ?? [];
+		this.correlationId = options.correlationId ?? randomUUID();
+		this.sessionId = options.sessionId ?? randomUUID();
+		this.minLevel = options.minLevel ?? "info";
+	}
+
+	/** Create a child logger that inherits correlation/session but can override source or sinks. */
+	child(overrides: Partial<OperationsLoggerOptions>): OperationsLogger {
+		return new OperationsLogger({
+			source: overrides.source ?? this.source,
+			sinks: overrides.sinks ?? this.sinks,
+			correlationId: overrides.correlationId ?? this.correlationId,
+			sessionId: overrides.sessionId ?? this.sessionId,
+			minLevel: overrides.minLevel ?? this.minLevel,
+		});
+	}
+
+	/** Log an operation with full context. Fire-and-forget to all sinks. */
+	log(
+		entry: Omit<OperationsLogEntry, "id" | "timestamp" | "source" | "correlationId" | "sessionId">,
+	): void {
+		if (!this.shouldLog(entry.level)) return;
+
+		const full: OperationsLogEntry = {
+			id: randomUUID(),
+			timestamp: new Date().toISOString(),
+			source: this.source,
+			correlationId: this.correlationId,
+			sessionId: this.sessionId,
+			...entry,
+			context: sanitizeContext(entry.context),
+		};
+
+		for (const sink of this.sinks) {
+			try {
+				const result = sink.write(full);
+				if (result instanceof Promise) {
+					result.catch(() => {});
+				}
+			} catch {
+				// Sink failures must never crash the main flow
+			}
+		}
+	}
+
+	info(category: OperationCategory, message: string, context?: Record<string, unknown>): void {
+		this.log({ level: "info", category, message, context });
+	}
+
+	warn(category: OperationCategory, message: string, context?: Record<string, unknown>): void {
+		this.log({ level: "warn", category, message, context });
+	}
+
+	error(
+		category: OperationCategory,
+		message: string,
+		err?: Error | null,
+		context?: Record<string, unknown>,
+	): void {
+		this.log({
+			level: "error",
+			category,
+			message,
+			context,
+			error: err
+				? {
+						name: err.name,
+						message: err.message,
+						stack: err.stack,
+						code: (err as { code?: string }).code,
+					}
+				: undefined,
+		});
+	}
+
+	debug(category: OperationCategory, message: string, context?: Record<string, unknown>): void {
+		this.log({ level: "debug", category, message, context });
+	}
+
+	/**
+	 * Log a timed operation. Wraps an async/sync function with start/end/duration logging.
+	 * Re-throws the original error on failure.
+	 */
+	async timed<T>(
+		category: OperationCategory,
+		message: string,
+		fn: () => T | Promise<T>,
+		context?: Record<string, unknown>,
+	): Promise<T> {
+		const start = Date.now();
+		this.log({
+			level: "info",
+			category,
+			message,
+			outcome: "in_progress",
+			context,
+		});
+		try {
+			const result = await fn();
+			this.log({
+				level: "info",
+				category,
+				message,
+				outcome: "success",
+				durationMs: Date.now() - start,
+				context,
+			});
+			return result;
+		} catch (err) {
+			this.log({
+				level: "error",
+				category,
+				message,
+				outcome: "failure",
+				durationMs: Date.now() - start,
+				error:
+					err instanceof Error
+						? {
+								name: err.name,
+								message: err.message,
+								stack: err.stack,
+								code: (err as { code?: string }).code,
+							}
+						: { name: "UnknownError", message: String(err) },
+				context,
+			});
+			throw err;
+		}
+	}
+
+	/** Create a step tracker for multi-step operations (deploy, generate pipeline). */
+	createStepTracker(category: OperationCategory, operationName: string): StepTracker {
+		return new StepTracker(this, category, operationName);
+	}
+
+	/** Flush all sinks. */
+	async flush(): Promise<void> {
+		for (const sink of this.sinks) {
+			if (sink.flush) {
+				try {
+					await sink.flush();
+				} catch {
+					// Silent
+				}
+			}
+		}
+	}
+
+	/** Destroy all sinks (cleanup timers, close streams). */
+	async destroy(): Promise<void> {
+		for (const sink of this.sinks) {
+			if (sink.destroy) {
+				try {
+					await sink.destroy();
+				} catch {
+					// Silent
+				}
+			}
+		}
+	}
+
+	getCorrelationId(): string {
+		return this.correlationId;
+	}
+
+	getSessionId(): string {
+		return this.sessionId;
+	}
+
+	private shouldLog(level: LogLevel): boolean {
+		return LEVEL_ORDER[level] >= LEVEL_ORDER[this.minLevel];
+	}
+}

package/src/logger/sinks/callback-sink.ts

@@ -0,0 +1,13 @@
+import type { LogSink, OperationsLogEntry } from "../types.js";
+
+/**
+ * Callback sink — delegates to a user-provided function.
+ * Useful for tests, Sentry breadcrumbs, WebSocket streaming, etc.
+ */
+export class CallbackSink implements LogSink {
+	constructor(private readonly onEntry: (entry: OperationsLogEntry) => void | Promise<void>) {}
+
+	write(entry: OperationsLogEntry): void | Promise<void> {
+		return this.onEntry(entry);
+	}
+}

package/src/logger/sinks/console-sink.ts

@@ -0,0 +1,51 @@
+import type { LogSink, OperationsLogEntry } from "../types.js";
+
+/**
+ * Human-readable console output sink.
+ * Formats log entries as single-line summaries with optional step details.
+ */
+export class ConsoleSink implements LogSink {
+	write(entry: OperationsLogEntry): void {
+		const time = entry.timestamp.slice(11, 19);
+		const lvl = entry.level.toUpperCase().padEnd(5);
+		const src = entry.source;
+		const outcome = entry.outcome ? ` (${entry.outcome})` : "";
+		const duration = entry.durationMs != null ? ` [${entry.durationMs}ms]` : "";
+
+		const line = `[${time}] [${lvl}] [${src}] ${entry.category}: ${entry.message}${outcome}${duration}`;
+
+		switch (entry.level) {
+			case "error":
+				console.error(line);
+				break;
+			case "warn":
+				console.warn(line);
+				break;
+			default:
+				console.log(line);
+		}
+
+		if (entry.steps) {
+			for (const step of entry.steps) {
+				const icon =
+					step.status === "success"
+						? "+"
+						: step.status === "failure"
+							? "x"
+							: step.status === "skipped"
+								? "-"
+								: "~";
+				const stepDuration = step.durationMs != null ? ` [${step.durationMs}ms]` : "";
+				const detail = step.detail ? ` (${step.detail})` : "";
+				console.log(`  ${icon} ${step.name}${detail}${stepDuration}`);
+			}
+		}
+
+		if (entry.error) {
+			console.error(`  Error: ${entry.error.message}`);
+			if (entry.error.stack) {
+				console.error(`  ${entry.error.stack}`);
+			}
+		}
+	}
+}

package/src/logger/sinks/file-sink.ts

@@ -0,0 +1,121 @@
+import { appendFileSync, existsSync, mkdirSync, renameSync, statSync, unlinkSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { LogSink, OperationsLogEntry } from "../types.js";
+
+export interface FileSinkOptions {
+	/** Log directory. Default: ~/.better-openclaw/logs */
+	logDir?: string;
+	/** Max file size in bytes before rotation. Default: 10 MB */
+	maxFileSize?: number;
+	/** Max number of rotated files to keep. Default: 5 */
+	maxFiles?: number;
+	/** Base filename (without extension). Default: "operations" */
+	filename?: string;
+}
+
+const DEFAULT_MAX_SIZE = 10 * 1024 * 1024; // 10 MB
+const DEFAULT_MAX_FILES = 5;
+
+function defaultLogDir(): string {
+	return process.env.OPENCLAW_LOG_DIR ?? join(homedir(), ".better-openclaw", "logs");
+}
+
+/**
+ * NDJSON file sink with size-based rotation.
+ *
+ * Writes one JSON object per line (newline-delimited JSON).
+ * Rotates files when they exceed maxFileSize:
+ *   operations.log → operations.1.log → operations.2.log → ...
+ */
+export class FileSink implements LogSink {
+	private currentSize = 0;
+	private initialized = false;
+	private readonly logDir: string;
+	private readonly maxFileSize: number;
+	private readonly maxFiles: number;
+	private readonly filename: string;
+	private readonly logPath: string;
+
+	constructor(options?: FileSinkOptions) {
+		this.logDir = options?.logDir ?? defaultLogDir();
+		this.maxFileSize =
+			options?.maxFileSize ??
+			(process.env.OPENCLAW_LOG_MAX_SIZE
+				? Number.parseInt(process.env.OPENCLAW_LOG_MAX_SIZE, 10)
+				: DEFAULT_MAX_SIZE);
+		this.maxFiles =
+			options?.maxFiles ??
+			(process.env.OPENCLAW_LOG_MAX_FILES
+				? Number.parseInt(process.env.OPENCLAW_LOG_MAX_FILES, 10)
+				: DEFAULT_MAX_FILES);
+		this.filename = options?.filename ?? "operations";
+		this.logPath = join(this.logDir, `${this.filename}.log`);
+	}
+
+	write(entry: OperationsLogEntry): void {
+		this.ensureDir();
+		const line = `${JSON.stringify(entry)}\n`;
+		appendFileSync(this.logPath, line, "utf-8");
+		this.currentSize += Buffer.byteLength(line, "utf-8");
+
+		if (this.currentSize >= this.maxFileSize) {
+			this.rotate();
+		}
+	}
+
+	private ensureDir(): void {
+		if (this.initialized) return;
+
+		if (!existsSync(this.logDir)) {
+			mkdirSync(this.logDir, { recursive: true });
+		}
+
+		// Seed current size from existing file
+		if (existsSync(this.logPath)) {
+			try {
+				this.currentSize = statSync(this.logPath).size;
+			} catch {
+				this.currentSize = 0;
+			}
+		}
+
+		this.initialized = true;
+	}
+
+	private rotate(): void {
+		// Delete the oldest file if it exists
+		const oldest = join(this.logDir, `${this.filename}.${this.maxFiles}.log`);
+		if (existsSync(oldest)) {
+			try {
+				unlinkSync(oldest);
+			} catch {
+				// Ignore
+			}
+		}
+
+		// Shift existing rotated files: N-1 → N, N-2 → N-1, ..., 1 → 2
+		for (let i = this.maxFiles - 1; i >= 1; i--) {
+			const from = join(this.logDir, `${this.filename}.${i}.log`);
+			const to = join(this.logDir, `${this.filename}.${i + 1}.log`);
+			if (existsSync(from)) {
+				try {
+					renameSync(from, to);
+				} catch {
+					// Ignore
+				}
+			}
+		}
+
+		// Rename current log to .1.log
+		if (existsSync(this.logPath)) {
+			try {
+				renameSync(this.logPath, join(this.logDir, `${this.filename}.1.log`));
+			} catch {
+				// Ignore
+			}
+		}
+
+		this.currentSize = 0;
+	}
+}

package/src/logger/types.ts

@@ -0,0 +1,90 @@
+/** Log severity levels. */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+
+/** Outcome of an operation. */
+export type OperationOutcome = "success" | "failure" | "warning" | "skipped" | "in_progress";
+
+/** Source package that generated the log entry. */
+export type LogSource = "cli" | "api" | "mcp" | "web" | "core";
+
+/** High-level operation categories. */
+export type OperationCategory =
+	| "generation"
+	| "deployment"
+	| "file_operation"
+	| "server_interaction"
+	| "api_request"
+	| "mcp_tool_call"
+	| "validation"
+	| "resolution"
+	| "connection_test"
+	| "system";
+
+/** A single step within a multi-step operation. */
+export interface OperationStep {
+	name: string;
+	status: OperationOutcome;
+	detail?: string;
+	startedAt: string;
+	completedAt?: string;
+	durationMs?: number;
+}
+
+/** Core log entry — every log event produces one of these. */
+export interface OperationsLogEntry {
+	/** Unique ID for this log entry. */
+	id: string;
+	/** ISO 8601 timestamp. */
+	timestamp: string;
+	/** Severity level. */
+	level: LogLevel;
+	/** Source package. */
+	source: LogSource;
+	/** Operation category. */
+	category: OperationCategory;
+	/** Human-readable message. */
+	message: string;
+	/** Outcome of the operation. */
+	outcome?: OperationOutcome;
+	/** Correlation ID — links related operations across packages. */
+	correlationId: string;
+	/** Session ID — groups operations in a single CLI run / API session. */
+	sessionId?: string;
+	/** Duration in milliseconds (for completed operations). */
+	durationMs?: number;
+	/** Sub-steps for multi-step operations. */
+	steps?: OperationStep[];
+	/** Structured context data (varies by category). */
+	context?: Record<string, unknown>;
+	/** Error information. */
+	error?: {
+		name: string;
+		message: string;
+		stack?: string;
+		code?: string;
+	};
+	/** Files affected (for file_operation category). */
+	filesAffected?: {
+		created?: string[];
+		modified?: string[];
+		deleted?: string[];
+	};
+	/** Tags for filtering. */
+	tags?: string[];
+}
+
+/** A sink receives log entries and writes them somewhere (file, console, HTTP, etc.). */
+export interface LogSink {
+	write(entry: OperationsLogEntry): void | Promise<void>;
+	flush?(): void | Promise<void>;
+	destroy?(): void | Promise<void>;
+}
+
+/** Options for creating an OperationsLogger. */
+export interface OperationsLoggerOptions {
+	source: LogSource;
+	sinks?: LogSink[];
+	correlationId?: string;
+	sessionId?: string;
+	minLevel?: LogLevel;
+}

package/src/migrations.ts

@@ -1,4 +1,4 @@
-export const CURRENT_CONFIG_VERSION = 2;
+export const CURRENT_CONFIG_VERSION = 3;
 
 type MigrationFn = (input: Record<string, unknown>) => Record<string, unknown>;
 
@@ -9,6 +9,13 @@ const migrations: Record<number, MigrationFn> = {
 		configVersion: 2,
 		deploymentType: (input.deploymentType as string) ?? "docker",
 	}),
+	// v2 → v3: add primaryFramework (defaults to "openclaw" for existing configs)
+	2: (input) => ({
+		...input,
+		configVersion: 3,
+		primaryFramework: (input.primaryFramework as string) ?? "openclaw",
+		companionFrameworks: (input.companionFrameworks as string[]) ?? [],
+	}),
 };
 
 /**