pi-harness-runtime 0.10.43 → 1.1.1

package/packages/notification/test/notification.test.ts

@@ -0,0 +1,372 @@
+/**
+ * Notification Center Tests
+ */
+
+import { describe, it, expect, beforeEach, vi } from "bun:test";
+import { NotificationCenter } from "../src/notification-center.js";
+import type { NotificationChannelConfig } from "../src/types.js";
+
+// Mock adapters
+const mockSend = vi.fn();
+const mockInitialize = vi.fn().mockResolvedValue(true);
+const mockIsConfigured = vi.fn().mockReturnValue(true);
+
+vi.mock("../src/adapters/telegram-adapter.js", () => ({
+	TelegramAdapter: vi.fn().mockImplementation(() => ({
+		send: mockSend,
+		initialize: mockInitialize,
+		isConfigured: mockIsConfigured,
+		id: "telegram",
+		type: "telegram",
+	})),
+}));
+
+vi.mock("../src/adapters/ntfy-adapter.js", () => ({
+	NtfyAdapter: vi.fn().mockImplementation(() => ({
+		send: mockSend,
+		initialize: mockInitialize,
+		isConfigured: mockIsConfigured,
+		id: "ntfy",
+		type: "ntfy",
+	})),
+}));
+
+vi.mock("../src/adapters/email-adapter.js", () => ({
+	EmailAdapter: vi.fn().mockImplementation(() => ({
+		send: mockSend,
+		initialize: mockInitialize,
+		isConfigured: mockIsConfigured,
+		id: "email",
+		type: "email",
+	})),
+}));
+
+vi.mock("../src/adapters/webhook-adapter.js", () => ({
+	WebhookAdapter: vi.fn().mockImplementation(() => ({
+		send: mockSend,
+		initialize: mockInitialize,
+		isConfigured: mockIsConfigured,
+		id: "webhook",
+		type: "webhook",
+	})),
+}));
+
+describe("NotificationCenter", () => {
+	beforeEach(() => {
+		mockSend.mockReset().mockResolvedValue({ success: true, channel: "mock" });
+		mockInitialize.mockReset().mockResolvedValue(true);
+		mockIsConfigured.mockReturnValue(true);
+	});
+
+	describe("construction", () => {
+		it("creates instance without config", () => {
+			const center = new NotificationCenter();
+			expect(center).toBeDefined();
+		});
+
+		it("has no channels by default", () => {
+			const center = new NotificationCenter();
+			expect(center.hasChannels()).toBe(false);
+			expect(center.listChannels()).toEqual([]);
+		});
+	});
+
+	describe("registerAdapter", () => {
+		it("registers a telegram adapter", () => {
+			const center = new NotificationCenter();
+			const config: NotificationChannelConfig = {
+				id: "telegram-main",
+				type: "telegram",
+				enabled: true,
+				config: { botToken: "tok", chatId: "chat" },
+			};
+			const result = center.registerAdapter(config);
+			expect(result).toBe(true);
+			expect(center.hasChannels()).toBe(true);
+			expect(center.listChannels()).toContain("telegram-main");
+		});
+
+		it("returns false when adapter not configured", () => {
+			const center = new NotificationCenter();
+			mockIsConfigured.mockReturnValue(false);
+			const config: NotificationChannelConfig = {
+				id: "telegram-fail",
+				type: "telegram",
+				enabled: false,
+				config: { botToken: "", chatId: "" },
+			};
+			expect(center.registerAdapter(config)).toBe(false);
+		});
+	});
+
+	describe("notify", () => {
+		it("notifies all channels", async () => {
+			const center = new NotificationCenter();
+			center.registerAdapter({
+				id: "ch1",
+				type: "telegram",
+				enabled: true,
+				config: { botToken: "tok", chatId: "chat" },
+			});
+			center.registerAdapter({
+				id: "ch2",
+				type: "ntfy",
+				enabled: true,
+				config: { server: "https://ntfy.sh", topic: "test" },
+			});
+
+			mockSend.mockResolvedValue({ success: true });
+
+			const results = await center.notify("JobStarted", {
+				jobId: "job-1",
+				requirement: "Fix login bug",
+			});
+
+			expect(results.length).toBeGreaterThanOrEqual(1);
+		});
+
+		it("returns failure result when adapter throws", async () => {
+			const center = new NotificationCenter();
+			center.registerAdapter({
+				id: "ch1",
+				type: "telegram",
+				enabled: true,
+				config: { botToken: "tok", chatId: "chat" },
+			});
+			mockSend.mockRejectedValue(new Error("network error"));
+
+			const results = await center.notify("TaskFailed", {
+				jobId: "job-2",
+				requirement: "Fix bug",
+				taskId: "task-1",
+				taskTitle: "Fix login",
+				error: "NullPointerException",
+			});
+
+			expect(results.some((r) => !r.success)).toBe(true);
+		});
+	});
+
+	describe("notifyChannel", () => {
+		it("notifies specific channel", async () => {
+			const center = new NotificationCenter();
+			center.registerAdapter({
+				id: "telegram-main",
+				type: "telegram",
+				enabled: true,
+				config: { botToken: "tok", chatId: "chat" },
+			});
+			mockSend.mockResolvedValue({ success: true });
+
+			const result = await center.notifyChannel(
+				"telegram-main",
+				"TaskCompleted",
+				{
+					jobId: "job-1",
+					requirement: "Add feature",
+					taskId: "task-1",
+					taskTitle: "Add login",
+				},
+			);
+
+			expect(result.success).toBe(true);
+		});
+
+		it("returns failure for unknown channel", async () => {
+			const center = new NotificationCenter();
+			const result = await center.notifyChannel("nonexistent", "Error", {
+				jobId: "job-1",
+				requirement: "test",
+			});
+
+			expect(result.success).toBe(false);
+			expect(result.error).toContain("not found");
+		});
+	});
+
+	describe("event content mapping", () => {
+		it("builds correct content for ReadyForClient", async () => {
+			const center = new NotificationCenter();
+			center.registerAdapter({
+				id: "ch1",
+				type: "telegram",
+				enabled: true,
+				config: { botToken: "tok", chatId: "chat" },
+			});
+			mockSend.mockImplementation(async (payload: any) => {
+				expect(payload.title).toBe("Ready for Review");
+				expect(payload.event).toBe("ReadyForClient");
+				return { success: true };
+			});
+
+			await center.notify("ReadyForClient", {
+				jobId: "job-1",
+				requirement: "Build feature X",
+			});
+
+			expect(mockSend).toHaveBeenCalled();
+		});
+
+		it("builds correct content for TaskFailed", async () => {
+			const center = new NotificationCenter();
+			center.registerAdapter({
+				id: "ch1",
+				type: "telegram",
+				enabled: true,
+				config: { botToken: "tok", chatId: "chat" },
+			});
+			mockSend.mockImplementation(async (payload: any) => {
+				expect(payload.title).toBe("Task Failed");
+				expect(payload.event).toBe("TaskFailed");
+				return { success: true };
+			});
+
+			await center.notify("TaskFailed", {
+				jobId: "job-1",
+				requirement: "Fix bug",
+				taskId: "task-1",
+				taskTitle: "Fix login",
+				error: "NullPointerException",
+			});
+
+			expect(mockSend).toHaveBeenCalled();
+		});
+
+		it("builds correct content for QuotaPaused", async () => {
+			const center = new NotificationCenter();
+			center.registerAdapter({
+				id: "ch1",
+				type: "telegram",
+				enabled: true,
+				config: { botToken: "tok", chatId: "chat" },
+			});
+			mockSend.mockImplementation(async (payload: any) => {
+				expect(payload.title).toBe("Quota Paused");
+				return { success: true };
+			});
+
+			await center.notify("QuotaPaused", {
+				jobId: "job-1",
+				requirement: "Continue work",
+			});
+
+			expect(mockSend).toHaveBeenCalled();
+		});
+
+		it("handles E2EFailed event", async () => {
+			const center = new NotificationCenter();
+			center.registerAdapter({
+				id: "ch1",
+				type: "telegram",
+				enabled: true,
+				config: { botToken: "tok", chatId: "chat" },
+			});
+			mockSend.mockImplementation(async (payload: any) => {
+				expect(payload.title).toBe("E2E Test Failed");
+				return { success: true };
+			});
+
+			await center.notify("E2EFailed", {
+				jobId: "job-1",
+				requirement: "Test workflow",
+			});
+
+			expect(mockSend).toHaveBeenCalled();
+		});
+
+		it("handles HumanReviewNeeded event", async () => {
+			const center = new NotificationCenter();
+			center.registerAdapter({
+				id: "ch1",
+				type: "telegram",
+				enabled: true,
+				config: { botToken: "tok", chatId: "chat" },
+			});
+			mockSend.mockImplementation(async (payload: any) => {
+				expect(payload.title).toBe("Human Review Needed");
+				return { success: true };
+			});
+
+			await center.notify("HumanReviewNeeded", {
+				jobId: "job-1",
+				requirement: "Approval needed",
+			});
+
+			expect(mockSend).toHaveBeenCalled();
+		});
+	});
+
+	describe("redaction", () => {
+		it("redacts bearer tokens", async () => {
+			const center = new NotificationCenter();
+			center.registerAdapter({
+				id: "ch1",
+				type: "telegram",
+				enabled: true,
+				config: { botToken: "tok", chatId: "chat" },
+			});
+			mockSend.mockImplementation(async (payload: any) => {
+				const details = payload.details ?? {};
+				expect(details.token).toBe("[REDACTED]");
+				return { success: true };
+			});
+
+			await center.notify("TaskCompleted", {
+				jobId: "job-1",
+				requirement: "Test",
+				taskId: "task-1",
+				taskTitle: "Test task",
+			});
+
+			expect(mockSend).toHaveBeenCalled();
+		});
+
+		it("redacts passwords", async () => {
+			const center = new NotificationCenter({
+				channels: [],
+				redactPatterns: [/password["\s:=]+[^\s,}]+/gi],
+			});
+			center.registerAdapter({
+				id: "ch1",
+				type: "telegram",
+				enabled: true,
+				config: { botToken: "tok", chatId: "chat" },
+			});
+			mockSend.mockImplementation(async (payload: any) => {
+				// Pattern should redact password field
+				expect(payload).toBeDefined();
+				return { success: true };
+			});
+
+			await center.notify("TaskCompleted", {
+				jobId: "job-1",
+				requirement: "Test",
+				taskId: "task-1",
+				taskTitle: "Test task",
+			});
+
+			expect(mockSend).toHaveBeenCalled();
+		});
+	});
+
+	describe("initialize", () => {
+		it("initializes all adapters", async () => {
+			const center = new NotificationCenter();
+			center.registerAdapter({
+				id: "ch1",
+				type: "telegram",
+				enabled: true,
+				config: { botToken: "tok", chatId: "chat" },
+			});
+			center.registerAdapter({
+				id: "ch2",
+				type: "ntfy",
+				enabled: true,
+				config: { server: "https://ntfy.sh", topic: "test" },
+			});
+
+			await center.initialize();
+			// Should not throw
+		});
+	});
+});

package/packages/notification/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;
+}

package/packages/observability/README.md

@@ -0,0 +1,241 @@
+# @pi/observability
+
+Comprehensive observability system with structured logging, distributed tracing, metrics collection, health monitoring, and alerting.
+
+## Features
+
+- **Structured Logging** - JSON and pretty-printed logs with correlation IDs
+- **Distributed Tracing** - OpenTelemetry-compatible tracing with spans and events
+- **Metrics Collection** - Prometheus-compatible metrics (counters, gauges, histograms)
+- **Health Monitoring** - Liveness and readiness probes for Kubernetes
+- **Alerting Engine** - Rule-based alerts with multiple action types
+
+## Installation
+
+```bash
+npm install @pi/observability
+```
+
+## Quick Start
+
+### Structured Logging
+
+```typescript
+import { createLogger } from "@pi/observability";
+
+const logger = createLogger({
+  level: "info",
+  format: "json",
+  output: "stdout"
+});
+
+// Basic logging
+logger.info("Application started");
+logger.error("Request failed", { requestId: "123" });
+
+// With correlation
+const jobLogger = logger.withJob("job-123");
+jobLogger.info("Processing task");
+```
+
+### Distributed Tracing
+
+```typescript
+import { createTracer } from "@pi/observability";
+
+const tracer = createTracer({
+  serviceName: "my-service",
+  exporter: "console",
+  sampleRate: 1.0
+});
+
+// Trace a function
+const result = await tracer.trace("processOrder", async (span) => {
+  span.setAttribute("orderId", order.id);
+  
+  await tracer.trace("validateOrder", async () => {
+    // validation logic
+  });
+  
+  return result;
+});
+```
+
+### Metrics
+
+```typescript
+import { createMetrics, createBuiltInMetrics } from "@pi/observability";
+
+const metrics = createMetrics({ serviceName: "my-service" });
+createBuiltInMetrics(metrics);
+
+// Counter
+metrics.incrementCounter("requests_total", { endpoint: "/api" });
+
+// Gauge
+metrics.setGauge("active_connections", 42);
+
+// Histogram
+metrics.observeHistogram("request_duration_seconds", 0.125, { method: "GET" });
+
+// Export metrics
+const prometheusOutput = metrics.exportPrometheus();
+```
+
+### Health Checks
+
+```typescript
+import { createHealthMonitor, createMemoryHealthCheck } from "@pi/observability";
+
+const health = createHealthMonitor("my-service", "1.0.0");
+
+// Register checks
+health.registerHealthCheck("memory", createMemoryHealthCheck("memory", 90));
+
+// Kubernetes probes
+app.get("/health/liveness", async (req, res) => {
+  const result = await health.checkLiveness();
+  res.status(result.status === "healthy" ? 200 : 503).json(result);
+});
+
+app.get("/health/readiness", async (req, res) => {
+  const result = await health.checkReadiness();
+  res.status(result.status === "healthy" ? 200 : 503).json(result);
+});
+```
+
+### Alerting
+
+```typescript
+import { createAlertEngine } from "@pi/observability";
+
+const alertEngine = createAlertEngine();
+
+alertEngine.registerRule({
+  name: "high_error_rate",
+  condition: {
+    type: "threshold",
+    metric: "error_rate",
+    operator: ">",
+    value: 0.05
+  },
+  severity: "critical",
+  cooldown: 300000, // 5 minutes
+  actions: [
+    { type: "log", level: "error" },
+    { type: "notify", channel: "slack", message: "High error rate detected" }
+  ]
+});
+
+// Evaluate alerts
+const alerts = await alertEngine.evaluate(metrics);
+```
+
+## API Reference
+
+### Logger
+
+```typescript
+const logger = createLogger({
+  level: "debug" | "info" | "warn" | "error" | "fatal",
+  format: "json" | "pretty",
+  output: "stdout" | "stderr" | "file",
+  filePath?: string,
+  defaultMeta?: Record<string, unknown>
+});
+
+logger.debug(message, meta?);
+logger.info(message, meta?);
+logger.warn(message, meta?);
+logger.error(message, error?, meta?);
+logger.fatal(message, error?, meta?);
+
+logger.child(defaults);  // Create child logger
+logger.withJob(jobId);   // Attach job ID
+logger.withTask(taskId); // Attach task ID
+logger.withCorrelationId(id); // Set correlation ID
+```
+
+### Tracer
+
+```typescript
+const tracer = createTracer({
+  serviceName: string,
+  exporter: "console" | "otlp" | "jaeger",
+  endpoint?: string,
+  sampleRate?: number
+});
+
+tracer.startSpan(name, options?);
+tracer.trace(name, fn);
+tracer.trace(name, options, fn);
+tracer.traceSync(name, fn);
+```
+
+### Metrics
+
+```typescript
+const metrics = createMetrics({
+  serviceName: string,
+  prefix?: string,
+  defaultLabels?: Labels
+});
+
+metrics.registerCounter(name, help, labels?);
+metrics.incrementCounter(name, labels?);
+metrics.registerGauge(name, help, labels?);
+metrics.setGauge(name, value, labels?);
+metrics.registerHistogram(name, help, buckets?, labels?);
+metrics.observeHistogram(name, value, labels?);
+
+metrics.asyncTimer(name, fn, labels?);
+metrics.timer(name, fn, labels?);
+
+metrics.exportPrometheus();
+metrics.exportJSON();
+```
+
+### Health Monitor
+
+```typescript
+const health = createHealthMonitor(serviceName, version);
+
+health.registerHealthCheck(name, check, critical?);
+health.checkHealth(name);
+health.checkHealthAll();
+health.checkLiveness();
+health.checkReadiness();
+```
+
+### Alert Engine
+
+```typescript
+const alertEngine = createAlertEngine(logger?);
+
+alertEngine.registerRule(rule);
+alertEngine.unregisterRule(name);
+alertEngine.evaluate(metrics);
+alertEngine.getActiveAlerts();
+alertEngine.getAlertHistory(limit?);
+```
+
+## Metrics Format
+
+Prometheus format example:
+
+```
+# HELP my_service_requests_total Total requests
+# TYPE my_service_requests_total counter
+my_service_requests_total{endpoint="/api"} 1234
+
+# HELP my_service_request_duration_seconds Request duration
+# TYPE my_service_request_duration_seconds histogram
+my_service_request_duration_seconds_bucket{le="0.1"} 1000
+my_service_request_duration_seconds_bucket{le="0.5"} 1200
+my_service_request_duration_seconds_sum 150.5
+my_service_request_duration_seconds_count 1234
+```
+
+## License
+
+MIT