@xl0/pi-lovely-agents 0.1.0

package/extensions/lovely-agents/notifications.ts

@@ -0,0 +1,220 @@
+import type { Dirent } from "node:fs"
+import { readdir } from "node:fs/promises"
+import { resolve } from "node:path"
+import { getAgentCoordinator } from "./coordinator.js"
+import {
+	MAX_NOTIFICATION_CONTENT_BYTES,
+	MAX_TASK_NOTIFICATIONS,
+	mutateTaskMetadata,
+	parentStoragePaths,
+	readTaskMetadata,
+	retainedPaths,
+	TASK_REFERENCE_PATTERN,
+	type TaskMetadata,
+	type TaskStoragePaths,
+	taskStoragePaths
+} from "./state.js"
+import { loadTaskList } from "./tools.js"
+
+export const NOTIFICATION_CUSTOM_TYPE = "lovely-agents:notification"
+export const NOTIFICATION_OUTPUT_PREVIEW_BYTES = 2 * 1024
+const NOTIFICATION_IN_FLIGHT_SYMBOL = Symbol.for("@xl0/pi-lovely-agents/notification-in-flight/v1")
+
+type TaskNotification = TaskMetadata["notifications"][number]
+type NotificationType = TaskNotification["type"]
+type ActiveRun = NonNullable<TaskMetadata["activeRun"]>
+
+/** Stable process-global route identity for one workspace/session partition. */
+export function notificationRouteKey(cwd: string, parentSessionId: string): string {
+	return `${resolve(cwd)}\0${parentSessionId}`
+}
+
+/** Drops process-local send suppression when an exact parent runtime closes. */
+export function clearNotificationInFlight(cwd: string, parentSessionId: string): void {
+	const prefix = `${notificationRouteKey(cwd, parentSessionId)}\0`
+	const inFlight = notificationInFlight()
+	for (const key of [...inFlight]) {
+		if (key.startsWith(prefix)) inFlight.delete(key)
+	}
+}
+
+/** Builds one bounded durable notification before its state transition commits. */
+export async function prepareTaskNotification(
+	paths: TaskStoragePaths,
+	metadata: TaskMetadata,
+	run: ActiveRun,
+	type: NotificationType,
+	outcome?: TaskMetadata["latestOutcome"]
+): Promise<TaskNotification> {
+	const output = truncateUtf8(metadata.latestReply?.text ?? "", NOTIFICATION_OUTPUT_PREVIEW_BYTES)
+	const taskList = await loadTaskList(paths.workspace, metadata.parentSessionId).catch(() => undefined)
+	const descendants = taskList?.details.tasks.find(task => task.id === metadata.taskRef)?.descendants
+	const descendantText = descendants && descendants.total > 0 ? `\nDescendants: ${JSON.stringify(descendants)}` : ""
+	const pathsForDisplay = retainedPaths(paths)
+	const status = type === "suspension" ? "suspended by a provider limit" : type === "interruption" ? "interrupted" : `completed: ${outcome}`
+	const content = truncateUtf8(
+		[
+			`[Lovely ${metadata.kind === "bash" ? "Bash" : "Agent"} ${metadata.taskRef}:${run.id}:${type}]`,
+			`Task ${metadata.taskRef} ${JSON.stringify(metadata.label)} ${status}`,
+			metadata.kind === "bash"
+				? `Command: ${truncateUtf8(metadata.command, 1024)}\nExit: ${metadata.exitCode ?? "unknown"}${metadata.signal ? ` signal=${metadata.signal}` : ""}`
+				: `Model: ${metadata.model.provider}/${metadata.model.id}:${metadata.thinking}`,
+			output ? `Output:\n${output}` : "Output: (empty)",
+			`Files: history=${pathsForDisplay.history} ${metadata.kind === "bash" ? `output=${pathsForDisplay.output}` : `session=${pathsForDisplay.session}`}${descendantText}`
+		].join("\n"),
+		MAX_NOTIFICATION_CONTENT_BYTES
+	)
+	return {
+		id: `${metadata.taskRef}:${run.id}:${type}`,
+		type,
+		runId: run.id,
+		content,
+		createdAt: Date.now()
+	}
+}
+
+/** Appends idempotently while keeping the durable queue bounded. */
+export function appendTaskNotification(notifications: TaskNotification[], notification: TaskNotification): TaskNotification[] {
+	if (notifications.some(existing => existing.id === notification.id)) return notifications
+	if (notifications.length < MAX_TASK_NOTIFICATIONS) return [...notifications, notification]
+	const delivered = notifications.findIndex(existing => existing.deliveredAt !== undefined)
+	const retained = notifications.filter((_, index) => index !== (delivered >= 0 ? delivered : 0))
+	return [...retained, notification]
+}
+
+/** Sends every pending notification for one task, without marking delivery. */
+export async function deliverTaskNotifications(paths: TaskStoragePaths): Promise<number> {
+	const loaded = await readTaskMetadata(paths)
+	if (loaded.status !== "ok" || loaded.metadata.discardedAt !== null) return 0
+	const routeKey = notificationRouteKey(paths.workspace, loaded.metadata.parentSessionId)
+	const route = getAgentCoordinator().getNotificationRoute(routeKey)
+	if (!route) return 0
+	const inFlight = notificationInFlight()
+	let sent = 0
+	for (const notification of loaded.metadata.notifications) {
+		if (notification.deliveredAt !== undefined) continue
+		const key = `${routeKey}\0${notification.id}`
+		if (inFlight.has(key)) continue
+		inFlight.add(key)
+		try {
+			await route({ id: notification.id, taskRef: loaded.metadata.taskRef, content: notification.content })
+			sent++
+		} catch (error) {
+			inFlight.delete(key)
+			throw error
+		}
+	}
+	return sent
+}
+
+/** Reconciles transcript evidence, then resends only still-absent direct notices. */
+export async function reconcileParentNotifications(
+	cwd: string,
+	parentSessionId: string,
+	entries: readonly unknown[]
+): Promise<{ delivered: number; sent: number; diagnostics: string[] }> {
+	const observed = observedNotificationIds(entries)
+	const result = { delivered: 0, sent: 0, diagnostics: [] as string[] }
+	for (const paths of await directTaskPaths(cwd, parentSessionId)) {
+		const loaded = await readTaskMetadata(paths)
+		if (loaded.status !== "ok") {
+			if (loaded.status === "invalid") result.diagnostics.push(`${paths.taskDirectory}: ${loaded.diagnostic.message}`)
+			continue
+		}
+		const pendingObserved = loaded.metadata.notifications.filter(
+			notification => notification.deliveredAt === undefined && observed.has(notification.id)
+		)
+		if (pendingObserved.length > 0) {
+			const ids = new Set(pendingObserved.map(notification => notification.id))
+			await mutateTaskMetadata(paths, metadata => ({
+				...metadata,
+				notifications: metadata.notifications.map(notification =>
+					ids.has(notification.id) && notification.deliveredAt === undefined ? { ...notification, deliveredAt: Date.now() } : notification
+				),
+				updatedAt: Date.now()
+			}))
+			result.delivered += ids.size
+		}
+		try {
+			result.sent += await deliverTaskNotifications(paths)
+		} catch (error) {
+			result.diagnostics.push(`${paths.taskDirectory}: notification delivery failed: ${errorMessage(error)}`)
+		}
+	}
+	return result
+}
+
+/** Marks one observed custom message delivered in its owning direct task. */
+export async function observeNotification(cwd: string, parentSessionId: string, taskRef: string, notificationId: string): Promise<boolean> {
+	const paths = taskStoragePaths(parentStoragePaths(cwd, parentSessionId), taskRef)
+	let changed = false
+	await mutateTaskMetadata(paths, metadata => {
+		if (metadata.parentSessionId !== parentSessionId || metadata.taskRef !== taskRef) return metadata
+		const notifications = metadata.notifications.map(notification => {
+			if (notification.id !== notificationId || notification.deliveredAt !== undefined) return notification
+			changed = true
+			return { ...notification, deliveredAt: Date.now() }
+		})
+		return changed ? { ...metadata, notifications, updatedAt: Date.now() } : metadata
+	})
+	notificationInFlight().delete(`${notificationRouteKey(cwd, parentSessionId)}\0${notificationId}`)
+	return changed
+}
+
+export function observedNotificationIds(entries: readonly unknown[]): Set<string> {
+	const ids = new Set<string>()
+	for (const entry of entries) {
+		if (!entry || typeof entry !== "object") continue
+		const candidate = entry as { type?: unknown; customType?: unknown; details?: unknown }
+		if (candidate.type !== "custom_message" || candidate.customType !== NOTIFICATION_CUSTOM_TYPE) continue
+		if (!candidate.details || typeof candidate.details !== "object") continue
+		const id = (candidate.details as { notificationId?: unknown }).notificationId
+		if (typeof id === "string" && id) ids.add(id)
+	}
+	return ids
+}
+
+export function notificationDetails(value: unknown): { notificationId: string; taskRef: string } | undefined {
+	if (!value || typeof value !== "object") return undefined
+	const details = value as { notificationId?: unknown; taskRef?: unknown }
+	return typeof details.notificationId === "string" && typeof details.taskRef === "string"
+		? { notificationId: details.notificationId, taskRef: details.taskRef }
+		: undefined
+}
+
+function notificationInFlight(): Set<string> {
+	const global = globalThis as typeof globalThis & { [NOTIFICATION_IN_FLIGHT_SYMBOL]?: Set<string> }
+	global[NOTIFICATION_IN_FLIGHT_SYMBOL] ??= new Set()
+	return global[NOTIFICATION_IN_FLIGHT_SYMBOL]
+}
+
+async function directTaskPaths(cwd: string, parentSessionId: string): Promise<TaskStoragePaths[]> {
+	const parent = parentStoragePaths(cwd, parentSessionId)
+	let entries: Dirent[]
+	try {
+		entries = await readdir(parent.parentDirectory, { withFileTypes: true })
+	} catch (error) {
+		if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") return []
+		throw error
+	}
+	return entries
+		.filter(entry => entry.isDirectory() && !entry.isSymbolicLink() && TASK_REFERENCE_PATTERN.test(entry.name))
+		.map(entry => taskStoragePaths(parent, entry.name))
+		.sort((left, right) => left.taskDirectory.localeCompare(right.taskDirectory))
+}
+
+function truncateUtf8(content: string, maximumBytes: number): string {
+	const bytes = Buffer.from(content)
+	if (bytes.length <= maximumBytes) return content
+	let end = maximumBytes - 3
+	while (end > 0 && isUtf8Continuation(bytes[end])) end--
+	return `${bytes.subarray(0, end).toString("utf8")}...`
+}
+
+function isUtf8Continuation(byte: number | undefined): boolean {
+	return byte !== undefined && (byte & 0xc0) === 0x80
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error)
+}

package/extensions/lovely-agents/provider-limits.ts

@@ -0,0 +1,13 @@
+const ACCOUNT_LIMIT =
+	/(?:GoUsageLimitError|FreeUsageLimitError|insufficient[_ -]?quota|\bquota\b|\bbilling\b|\bbudget\b|usage[_ -]?limit|usage[_ -]?not[_ -]?included|available balance)/i
+const EXPLICIT_LIMIT = /(?:\b429\b|ResourceExhausted|RESOURCE_EXHAUSTED)/i
+const TRANSIENT_LIMIT = /(?:rate[_ -]?limit|too many requests)/i
+const NON_LIMIT_TRANSIENT =
+	/(?:overload(?:ed)?|\b5\d\d\b|service[_ -]?unavailable|server[_ -]?error|internal[_ -]?error|network[_ -]?error|connection[_ -]?(?:error|refused|lost)|fetch failed|getaddrinfo|ENOTFOUND|EAI_AGAIN|upstream[_ -]?connect|reset before headers|socket hang up|timed? out|timeout|websocket[_ -]?(?:closed|error))/i
+
+/** True only for terminal provider errors that should suspend an exact model tuple. */
+export function isProviderLimitError(errorMessage: string | undefined): boolean {
+	if (!errorMessage) return false
+	if (ACCOUNT_LIMIT.test(errorMessage) || EXPLICIT_LIMIT.test(errorMessage)) return true
+	return TRANSIENT_LIMIT.test(errorMessage) && !NON_LIMIT_TRANSIENT.test(errorMessage)
+}

package/extensions/lovely-agents/rendering.ts

@@ -0,0 +1,90 @@
+import { keyHint, type MessageRenderer, type Theme } from "@earendil-works/pi-coding-agent"
+import { Box, Spacer, Text, truncateToWidth } from "@earendil-works/pi-tui"
+
+const COLLAPSED_LINES = 10
+const COLLAPSED_HEAD_LINES = 6
+const COLLAPSED_TAIL_LINES = 3
+const COLLAPSED_CHARACTERS = 1_200
+const PREVIEW_LINE_CHARACTERS = 240
+
+type TextToolResult = {
+	content: Array<{ type: string; text?: string }>
+}
+
+/** Notifications have a distinct message shell; only the header is visible when collapsed. */
+export const renderAgentNotification: MessageRenderer = (message, { expanded, outputPad }, theme) => {
+	const content =
+		typeof message.content === "string"
+			? message.content
+			: message.content
+					.filter(part => part.type === "text")
+					.map(part => part.text)
+					.join("\n")
+	const lines = content.split("\n")
+	const summary = (/^\[Lovely (Agent|Bash) /.test(lines[0] ?? "") ? lines[1] : lines[0]) || "Notification"
+	return {
+		render(width) {
+			const box = new Box(outputPad, 0, text => theme.bg("customMessageBg", text))
+			box.addChild({
+				render: available => [
+					truncateToWidth(
+						theme.fg("customMessageLabel", theme.bold(`${expanded ? "▾" : "▸"} Lovely Agents · ${summary}`)),
+						available
+					).replaceAll("\x1b[0m", "\x1b[22;39m")
+				],
+				invalidate() {}
+			})
+			if (expanded && content) {
+				box.addChild(new Spacer(1))
+				box.addChild(new Text(theme.fg("customMessageText", content), 0, 0))
+			}
+			return box.render(width).map(line => truncateToWidth(line, width))
+		},
+		invalidate() {}
+	}
+}
+
+/** Renders short results whole and long results as a head/tail preview toggled by Ctrl+O. */
+export function renderExpandableResult(result: TextToolResult, expanded: boolean, theme: Theme, outputPad = 0): Text {
+	const output = result.content
+		.filter((part): part is { type: "text"; text: string } => part.type === "text" && typeof part.text === "string")
+		.map(part => part.text)
+		.join("\n")
+	if (!output) return new Text("", outputPad, 0)
+
+	const lines = output.split("\n")
+	const characterCount = Array.from(output).length
+	if (expanded || (lines.length <= COLLAPSED_LINES && characterCount <= COLLAPSED_CHARACTERS)) {
+		return new Text(lines.map(line => theme.fg("toolOutput", line)).join("\n"), outputPad, 0)
+	}
+
+	const preview =
+		lines.length > COLLAPSED_LINES
+			? [
+					...lines.slice(0, COLLAPSED_HEAD_LINES).map(line => theme.fg("toolOutput", previewLine(line))),
+					expansionHint(`${lines.length - COLLAPSED_HEAD_LINES - COLLAPSED_TAIL_LINES} more lines`, theme),
+					...lines.slice(-COLLAPSED_TAIL_LINES).map(line => theme.fg("toolOutput", previewLine(line)))
+				]
+			: characterPreview(output, theme)
+	return new Text(preview.join("\n"), outputPad, 0)
+}
+
+function characterPreview(output: string, theme: Theme): string[] {
+	const characters = Array.from(output)
+	const head = characters.slice(0, 800).join("")
+	const tail = characters.slice(-300).join("")
+	return [
+		...head.split("\n").map(line => theme.fg("toolOutput", line)),
+		expansionHint(`${characters.length - 1_100} more characters`, theme),
+		...tail.split("\n").map(line => theme.fg("toolOutput", line))
+	]
+}
+
+function previewLine(line: string): string {
+	const characters = Array.from(line)
+	return characters.length <= PREVIEW_LINE_CHARACTERS ? line : `${characters.slice(0, PREVIEW_LINE_CHARACTERS).join("")}...`
+}
+
+function expansionHint(omitted: string, theme: Theme): string {
+	return `${theme.fg("muted", `... (${omitted}, `)}${keyHint("app.tools.expand", "to expand")}${theme.fg("muted", ")")}`
+}