pi-harness-runtime 0.9.2 → 0.9.5

package/packages/notification/src/adapters/webhook-adapter.ts

@@ -0,0 +1,75 @@
+/**
+ * Webhook Adapter — RFC-0022
+ *
+ * Sends notifications to a generic webhook endpoint.
+ */
+
+import type {
+	NotificationPayload,
+	NotificationResult,
+	WebhookConfig,
+} from "../types.js";
+import { BaseChannelAdapter } from "../base-adapter.js";
+
+export class WebhookAdapter extends BaseChannelAdapter {
+	readonly id = "webhook";
+	readonly type = "webhook";
+
+	constructor(config: WebhookConfig) {
+		super({ id: "webhook", type: "webhook", enabled: true, config });
+	}
+
+	async initialize(): Promise<boolean> {
+		try {
+			const cfg = this.config.config as WebhookConfig;
+			return Boolean(cfg.url && cfg.url.startsWith("http"));
+		} catch {
+			return false;
+		}
+	}
+
+	async send(payload: NotificationPayload): Promise<NotificationResult> {
+		try {
+			const cfg = this.config.config as WebhookConfig;
+			const headers: Record<string, string> = {
+				"Content-Type": "application/json",
+				...(cfg.headers ?? {}),
+			};
+
+			// Add auth token if configured
+			if (cfg.authToken) {
+				headers["Authorization"] = `Bearer ${cfg.authToken}`;
+			}
+
+			const response = await fetch(cfg.url, {
+				method: cfg.method ?? "POST",
+				headers,
+				body: JSON.stringify({
+					event: payload.event,
+					jobId: payload.jobId,
+					timestamp: payload.timestamp,
+					title: payload.title,
+					message: payload.message,
+					details: payload.details,
+				}),
+			});
+
+			if (!response.ok) {
+				const error = await response.text();
+				return {
+					success: false,
+					channel: this.id,
+					error: `Webhook error ${response.status}: ${error}`,
+				};
+			}
+
+			return { success: true, channel: this.id };
+		} catch (error) {
+			return {
+				success: false,
+				channel: this.id,
+				error: String(error),
+			};
+		}
+	}
+}

package/packages/notification/src/base-adapter.ts

@@ -0,0 +1,75 @@
+/**
+ * Notification Base Adapter — RFC-0022
+ *
+ * Abstract base class for all notification channel adapters.
+ */
+
+import type {
+	NotificationPayload,
+	NotificationChannelConfig,
+	NotificationResult,
+} from "./types.js";
+
+export interface ChannelAdapter {
+	readonly id: string;
+	readonly type: string;
+
+	/**
+	 * Initialize the adapter (e.g., verify credentials)
+	 */
+	initialize(): Promise<boolean>;
+
+	/**
+	 * Send a notification
+	 */
+	send(payload: NotificationPayload): Promise<NotificationResult>;
+
+	/**
+	 * Check if the adapter is properly configured
+	 */
+	isConfigured(): boolean;
+}
+
+export abstract class BaseChannelAdapter implements ChannelAdapter {
+	abstract readonly id: string;
+	abstract readonly type: string;
+
+	constructor(protected config: NotificationChannelConfig) {}
+
+	abstract initialize(): Promise<boolean>;
+	abstract send(payload: NotificationPayload): Promise<NotificationResult>;
+
+	isConfigured(): boolean {
+		return this.config.enabled;
+	}
+
+	/**
+	 * Redact sensitive data from payload before sending
+	 */
+	protected redact(
+		payload: NotificationPayload,
+		patterns: RegExp[],
+	): NotificationPayload {
+		if (patterns.length === 0) return payload;
+
+		const redacted: string[] = [];
+		const details = payload.details ? { ...payload.details } : {};
+
+		for (const [key, value] of Object.entries(details)) {
+			const valStr = String(value);
+			for (const pattern of patterns) {
+				if (pattern.test(valStr)) {
+					redacted.push(key);
+					(details as Record<string, unknown>)[key] = "[REDACTED]";
+					break;
+				}
+			}
+		}
+
+		return {
+			...payload,
+			details,
+			redacted: redacted.length > 0 ? redacted : undefined,
+		};
+	}
+}

package/packages/notification/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Notification Center (RFC-0029)
+ *
+ * Unified notification system for the harness runtime.
+ */
+
+export * from "./notification-center.js";
+export * from "./base-adapter.js";
+export * from "./types.js";

package/packages/notification/src/notification-center.ts

@@ -0,0 +1,286 @@
+/**
+ * Notification Center — RFC-0022
+ *
+ * Main orchestration class for sending notifications across multiple channels.
+ *
+ * Security Rules (RFC-0022):
+ * - Do not send raw cookies, passwords, provider tokens
+ * - Redact sensitive data before sending
+ * - Notification failure does not crash runtime
+ */
+
+import type {
+	NotificationEvent,
+	NotificationPayload,
+	NotificationConfig,
+	NotificationChannelConfig,
+	NotificationResult,
+	NotificationContext,
+} from "./types.js";
+import type { ChannelAdapter } from "./base-adapter.js";
+import { TelegramAdapter } from "./adapters/telegram-adapter.js";
+import { NtfyAdapter } from "./adapters/ntfy-adapter.js";
+import { EmailAdapter } from "./adapters/email-adapter.js";
+import { WebhookAdapter } from "./adapters/webhook-adapter.js";
+
+export class NotificationCenter {
+	private adapters: Map<string, ChannelAdapter> = new Map();
+	private redactPatterns: RegExp[];
+
+	constructor(config?: NotificationConfig) {
+		this.redactPatterns =
+			config?.redactPatterns ?? this.getDefaultRedactPatterns();
+
+		if (config?.channels) {
+			for (const channelConfig of config.channels) {
+				if (channelConfig.enabled) {
+					this.registerAdapter(channelConfig);
+				}
+			}
+		}
+	}
+
+	/**
+	 * Register a new adapter
+	 */
+	registerAdapter(config: NotificationChannelConfig): boolean {
+		try {
+			const adapter = this.createAdapter(config);
+			if (adapter && adapter.isConfigured()) {
+				this.adapters.set(config.id, adapter);
+				return true;
+			}
+		} catch (error) {
+			console.error(
+				`[NotificationCenter] Failed to register adapter: ${error}`,
+			);
+		}
+		return false;
+	}
+
+	/**
+	 * Initialize all registered adapters
+	 */
+	async initialize(): Promise<void> {
+		const adapterEntries = Array.from(this.adapters.entries());
+		for (const [id, adapter] of adapterEntries) {
+			try {
+				const ok = await adapter.initialize();
+				if (!ok) {
+					console.warn(
+						`[NotificationCenter] Adapter ${id} initialization failed`,
+					);
+				}
+			} catch (error) {
+				console.warn(
+					`[NotificationCenter] Adapter ${id} initialization error: ${error}`,
+				);
+			}
+		}
+	}
+
+	/**
+	 * Send a notification to all configured channels
+	 */
+	async notify(
+		event: NotificationEvent,
+		context: NotificationContext,
+	): Promise<NotificationResult[]> {
+		const payload = this.buildPayload(event, context);
+		const results: NotificationResult[] = [];
+
+		// Send to all adapters in parallel
+		const adapterEntries = Array.from(this.adapters.entries());
+		const promises = adapterEntries.map(async ([id, adapter]) => {
+			try {
+				// Redact sensitive data
+				const redactedPayload = this.redact(payload);
+				const result = await adapter.send(redactedPayload);
+				results.push(result);
+			} catch (error) {
+				// Never crash the runtime due to notification failure
+				results.push({
+					success: false,
+					channel: id,
+					error: String(error),
+				});
+			}
+		});
+
+		await Promise.all(promises);
+		return results;
+	}
+
+	/**
+	 * Send notification to a specific channel
+	 */
+	async notifyChannel(
+		channelId: string,
+		event: NotificationEvent,
+		context: NotificationContext,
+	): Promise<NotificationResult> {
+		const adapter = this.adapters.get(channelId);
+		if (!adapter) {
+			return { success: false, channel: channelId, error: "Adapter not found" };
+		}
+
+		try {
+			const payload = this.redact(this.buildPayload(event, context));
+			return await adapter.send(payload);
+		} catch (error) {
+			return { success: false, channel: channelId, error: String(error) };
+		}
+	}
+
+	/**
+	 * Check if any notifications are configured
+	 */
+	hasChannels(): boolean {
+		return this.adapters.size > 0;
+	}
+
+	/**
+	 * List all configured channels
+	 */
+	listChannels(): string[] {
+		return Array.from(this.adapters.keys());
+	}
+
+	// ─── Private Methods ────────────────────────────────────────────────
+
+	private createAdapter(
+		config: NotificationChannelConfig,
+	): ChannelAdapter | null {
+		switch (config.type) {
+			case "telegram":
+				return new TelegramAdapter(
+					config.config as import("./types.js").TelegramConfig,
+				);
+			case "ntfy":
+				return new NtfyAdapter(
+					config.config as import("./types.js").NtfyConfig,
+				);
+			case "email":
+				return new EmailAdapter(
+					config.config as import("./types.js").EmailConfig,
+				);
+			case "webhook":
+				return new WebhookAdapter(
+					config.config as import("./types.js").WebhookConfig,
+				);
+			default:
+				return null;
+		}
+	}
+
+	private buildPayload(
+		event: NotificationEvent,
+		context: NotificationContext,
+	): NotificationPayload {
+		const { title, message } = this.getEventContent(event, context);
+
+		return {
+			event,
+			jobId: context.jobId,
+			timestamp: new Date().toISOString(),
+			title,
+			message,
+			details: {
+				jobId: context.jobId,
+				requirement: context.requirement,
+				...(context.taskId && { taskId: context.taskId }),
+				...(context.taskTitle && { taskTitle: context.taskTitle }),
+				...(context.error && { error: context.error }),
+			},
+		};
+	}
+
+	private getEventContent(
+		event: NotificationEvent,
+		context: NotificationContext,
+	): { title: string; message: string } {
+		const requirement =
+			context.requirement.length > 50
+				? context.requirement.slice(0, 50) + "..."
+				: context.requirement;
+
+		const map: Record<NotificationEvent, { title: string; message: string }> = {
+			JobStarted: {
+				title: "Job Started",
+				message: `Harness job started for: "${requirement}"`,
+			},
+			TaskCompleted: {
+				title: "Task Completed",
+				message: `Task "${context.taskTitle ?? "Unknown"}" completed successfully`,
+			},
+			TaskFailed: {
+				title: "Task Failed",
+				message: `Task "${context.taskTitle ?? "Unknown"}" failed${context.error ? `: ${context.error}` : ""}`,
+			},
+			QuotaPaused: {
+				title: "Quota Paused",
+				message: `Job paused due to quota limit. Will auto-resume when quota resets.`,
+			},
+			ResumeScheduled: {
+				title: "Resume Scheduled",
+				message: `Job will resume work on: "${requirement}"`,
+			},
+			ContextCompacted: {
+				title: "Context Compacted",
+				message: `Session context was compacted to continue work on: "${requirement}"`,
+			},
+			OutputLimitContinued: {
+				title: "Output Limit Continued",
+				message: `Response was continued after hitting output token limit`,
+			},
+			E2EFailed: {
+				title: "E2E Test Failed",
+				message: `End-to-end tests failed for job: "${requirement}"`,
+			},
+			HumanReviewNeeded: {
+				title: "Human Review Needed",
+				message: `Job blocked. Please review and take action.`,
+			},
+			ReadyForClient: {
+				title: "Ready for Review",
+				message: `Job completed successfully and ready for your review: "${requirement}"`,
+			},
+			JobCancelled: {
+				title: "Job Cancelled",
+				message: `Job was cancelled: "${requirement}"`,
+			},
+			Error: {
+				title: "Runtime Error",
+				message: `An error occurred${context.error ? `: ${context.error}` : ""}`,
+			},
+		};
+
+		return map[event] ?? { title: event, message: `Event: ${event}` };
+	}
+
+	private redact(payload: NotificationPayload): NotificationPayload {
+		const details = payload.details ? { ...payload.details } : {};
+
+		// Redact sensitive patterns
+		for (const pattern of this.redactPatterns) {
+			for (const [key, value] of Object.entries(details)) {
+				if (typeof value === "string" && pattern.test(value)) {
+					details[key] = "[REDACTED]";
+				}
+			}
+		}
+
+		return { ...payload, details };
+	}
+
+	private getDefaultRedactPatterns(): RegExp[] {
+		return [
+			/Bearer\s+[\w-]+/gi, // Bearer tokens
+			/password["\s:=]+[^\s,}]+/gi, // passwords
+			/cookie["\s:=]+[^\s,}]+/gi, // cookies
+			/secret["\s:=]+[^\s,}]+/gi, // secrets
+			/api[_-]?key["\s:=]+[^\s,}]+/gi, // API keys
+			/auth["\s:=]+[^\s,}]+/gi, // auth tokens
+		];
+	}
+}

package/packages/notification/src/types.ts

@@ -0,0 +1,89 @@
+/**
+ * Notification Center Types — RFC-0022
+ *
+ * Type definitions for notification events, channels, and payloads.
+ */
+
+export type NotificationEvent =
+	| "JobStarted"
+	| "TaskCompleted"
+	| "TaskFailed"
+	| "QuotaPaused"
+	| "ResumeScheduled"
+	| "ContextCompacted"
+	| "OutputLimitContinued"
+	| "E2EFailed"
+	| "HumanReviewNeeded"
+	| "ReadyForClient"
+	| "JobCancelled"
+	| "Error";
+
+export interface NotificationPayload {
+	event: NotificationEvent;
+	jobId: string;
+	timestamp: string;
+	title: string;
+	message: string;
+	details?: Record<string, unknown>;
+	// Redacted fields for security
+	redacted?: string[];
+}
+
+export interface NotificationConfig {
+	channels: NotificationChannelConfig[];
+	// Global settings
+	enabled?: boolean;
+	redactPatterns?: RegExp[];
+}
+
+export interface NotificationChannelConfig {
+	id: string;
+	type: NotificationChannelType;
+	enabled: boolean;
+	config: TelegramConfig | NtfyConfig | EmailConfig | WebhookConfig;
+}
+
+export type NotificationChannelType = "telegram" | "ntfy" | "email" | "webhook";
+
+export interface TelegramConfig {
+	botToken: string;
+	chatId: string;
+	parseMode?: "MarkdownV2" | "HTML" | "Markdown";
+}
+
+export interface NtfyConfig {
+	server: string; // e.g., "https://ntfy.sh"
+	topic: string;
+	authToken?: string;
+}
+
+export interface EmailConfig {
+	smtpHost: string;
+	smtpPort: number;
+	smtpUser: string;
+	smtpPassword: string;
+	from: string;
+	to: string[];
+	tls?: boolean;
+}
+
+export interface WebhookConfig {
+	url: string;
+	method?: "POST" | "PUT";
+	headers?: Record<string, string>;
+	authToken?: string;
+}
+
+export interface NotificationResult {
+	success: boolean;
+	channel: string;
+	error?: string;
+}
+
+export interface NotificationContext {
+	jobId: string;
+	requirement: string;
+	taskId?: string;
+	taskTitle?: string;
+	error?: string;
+}