pi-harness-runtime 0.10.43 → 1.1.1

package/packages/notification/adapters/ntfy-adapter.ts

@@ -0,0 +1,100 @@
+/**
+ * Ntfy Adapter — RFC-0022
+ *
+ * Sends notifications via ntfy.sh (or self-hosted ntfy server).
+ */
+
+import type {
+	NotificationPayload,
+	NotificationResult,
+	NtfyConfig,
+} from "../types.js";
+import { BaseChannelAdapter } from "../base-adapter.js";
+
+export class NtfyAdapter extends BaseChannelAdapter {
+	readonly id = "ntfy";
+	readonly type = "ntfy";
+
+	constructor(config: NtfyConfig) {
+		super({ id: "ntfy", type: "ntfy", enabled: true, config });
+	}
+
+	async initialize(): Promise<boolean> {
+		// Ntfy doesn't require initialization; it's fire-and-forget
+		return true;
+	}
+
+	async send(payload: NotificationPayload): Promise<NotificationResult> {
+		try {
+			const cfg = this.config.config as NtfyConfig;
+			const message = this.formatMessage(payload);
+			const headers: Record<string, string> = {
+				"Content-Type": "text/plain",
+				Title: payload.title,
+				Tags: this.getTags(payload.event),
+			};
+
+			// Add auth if configured
+			if (cfg.authToken) {
+				headers["Authorization"] = `Bearer ${cfg.authToken}`;
+			}
+
+			const response = await fetch(`${cfg.server}/${cfg.topic}`, {
+				method: "POST",
+				headers,
+				body: message,
+			});
+
+			if (!response.ok) {
+				const error = await response.text();
+				return {
+					success: false,
+					channel: this.id,
+					error: `Ntfy error: ${error}`,
+				};
+			}
+
+			return { success: true, channel: this.id };
+		} catch (error) {
+			return {
+				success: false,
+				channel: this.id,
+				error: String(error),
+			};
+		}
+	}
+
+	private formatMessage(payload: NotificationPayload): string {
+		const lines = [payload.message];
+
+		if (payload.details?.taskTitle) {
+			lines.push(`\nTask: ${payload.details.taskTitle}`);
+		}
+		if (payload.details?.jobId) {
+			lines.push(`Job: ${payload.details.jobId}`);
+		}
+		if (payload.details?.error) {
+			lines.push(`\nError: ${payload.details.error}`);
+		}
+
+		return lines.join("");
+	}
+
+	private getTags(event: NotificationPayload["event"]): string {
+		const map: Record<string, string> = {
+			JobStarted: "rocket",
+			TaskCompleted: "white_check_mark",
+			TaskFailed: "x",
+			QuotaPaused: "pause_button",
+			ResumeScheduled: "play_button",
+			ContextCompacted: "package",
+			OutputLimitContinued: "repeat",
+			E2EFailed: "test_tube",
+			HumanReviewNeeded: "bust_in_silhouette",
+			ReadyForClient: "tada",
+			JobCancelled: "no_entry",
+			Error: "warning",
+		};
+		return map[event] ?? "bell";
+	}
+}

package/packages/notification/adapters/telegram-adapter.ts

@@ -0,0 +1,107 @@
+/**
+ * Telegram Adapter — RFC-0022
+ *
+ * Sends notifications via Telegram Bot API.
+ */
+
+import type {
+	NotificationPayload,
+	NotificationResult,
+	TelegramConfig,
+} from "../types.js";
+import { BaseChannelAdapter } from "../base-adapter.js";
+
+export class TelegramAdapter extends BaseChannelAdapter {
+	readonly id = "telegram";
+	readonly type = "telegram";
+
+	constructor(config: TelegramConfig) {
+		super({ id: "telegram", type: "telegram", enabled: true, config });
+	}
+
+	async initialize(): Promise<boolean> {
+		try {
+			const cfg = this.config.config as TelegramConfig;
+			// Verify bot token by calling getMe
+			const response = await fetch(
+				`https://api.telegram.org/bot${cfg.botToken}/getMe`,
+			);
+			return response.ok;
+		} catch {
+			return false;
+		}
+	}
+
+	async send(payload: NotificationPayload): Promise<NotificationResult> {
+		try {
+			const cfg = this.config.config as TelegramConfig;
+			const message = this.formatMessage(payload);
+
+			const response = await fetch(
+				`https://api.telegram.org/bot${cfg.botToken}/sendMessage`,
+				{
+					method: "POST",
+					headers: { "Content-Type": "application/json" },
+					body: JSON.stringify({
+						chat_id: cfg.chatId,
+						text: message,
+						parse_mode: cfg.parseMode ?? "MarkdownV2",
+					}),
+				},
+			);
+
+			if (!response.ok) {
+				const error = await response.text();
+				return {
+					success: false,
+					channel: this.id,
+					error: `Telegram API error: ${error}`,
+				};
+			}
+
+			return { success: true, channel: this.id };
+		} catch (error) {
+			return {
+				success: false,
+				channel: this.id,
+				error: String(error),
+			};
+		}
+	}
+
+	private formatMessage(payload: NotificationPayload): string {
+		const emoji = this.getEmoji(payload.event);
+		const title = `${emoji} ${payload.title}`;
+		const lines = [title, "", payload.message];
+
+		if (payload.details?.taskTitle) {
+			lines.push("", `Task: ${payload.details.taskTitle}`);
+		}
+		if (payload.details?.jobId) {
+			lines.push(`Job: ${payload.details.jobId}`);
+		}
+		if (payload.details?.error) {
+			lines.push("", `Error: ${payload.details.error}`);
+		}
+
+		return lines.filter(Boolean).join("\n");
+	}
+
+	private getEmoji(event: NotificationPayload["event"]): string {
+		const map: Record<string, string> = {
+			JobStarted: "🚀",
+			TaskCompleted: "✅",
+			TaskFailed: "❌",
+			QuotaPaused: "⏸️",
+			ResumeScheduled: "▶️",
+			ContextCompacted: "📦",
+			OutputLimitContinued: "🔄",
+			E2EFailed: "🧪",
+			HumanReviewNeeded: "👤",
+			ReadyForClient: "🎉",
+			JobCancelled: "🚫",
+			Error: "⚠️",
+		};
+		return map[event] ?? "📢";
+	}
+}

package/packages/notification/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/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/index.ts

@@ -0,0 +1,51 @@
+/**
+ * Notification Center — RFC-0022
+ *
+ * Mobile notification system for harness runtime events.
+ *
+ * @example
+ * ```typescript
+ * import { NotificationCenter } from "./notification/index.js";
+ *
+ * const center = new NotificationCenter({
+ *   channels: [
+ *     {
+ *       id: "my-telegram",
+ *       type: "telegram",
+ *       enabled: true,
+ *       config: {
+ *         botToken: process.env.TELEGRAM_BOT_TOKEN,
+ *         chatId: "YOUR_CHAT_ID",
+ *       },
+ *     },
+ *   ],
+ * });
+ *
+ * await center.initialize();
+ *
+ * await center.notify("JobStarted", {
+ *   jobId: "job-123",
+ *   requirement: "Build a REST API",
+ * });
+ * ```
+ */
+
+export { NotificationCenter } from "./notification-center.js";
+export { TelegramAdapter } from "./adapters/telegram-adapter.js";
+export { NtfyAdapter } from "./adapters/ntfy-adapter.js";
+export { EmailAdapter } from "./adapters/email-adapter.js";
+export { WebhookAdapter } from "./adapters/webhook-adapter.js";
+
+export type {
+	NotificationEvent,
+	NotificationPayload,
+	NotificationConfig,
+	NotificationChannelConfig,
+	NotificationChannelType,
+	NotificationResult,
+	NotificationContext,
+	TelegramConfig,
+	NtfyConfig,
+	EmailConfig,
+	WebhookConfig,
+} from "./types.js";

package/packages/notification/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/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@pi-harness/notification",
+  "version": "0.10.30",
+  "description": "pi-harness-runtime — notification",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test"
+  },
+  "dependencies": {}
+}