fix: unify agent attention notification payloads (#55)

* fix: simplify tmux session creation in paseo.json

* fix: unify agent attention notification payloads

packages/server/src/shared/agent-attention-notification.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildAgentAttentionNotificationPayload,
+  findLatestAssistantMessageFromTimeline,
+  findLatestPermissionRequest,
+} from "./agent-attention-notification.js";
+
+describe("buildAgentAttentionNotificationPayload", () => {
+  it("builds finished notifications from markdown assistant text", () => {
+    const payload = buildAgentAttentionNotificationPayload({
+      reason: "finished",
+      serverId: "srv-1",
+      agentId: "agent-1",
+      assistantMessage:
+        "**Done**. Updated `README.md` and [link](https://example.com).",
+    });
+
+    expect(payload).toEqual({
+      title: "Agent finished",
+      body: "Done. Updated README.md and link.",
+      data: {
+        serverId: "srv-1",
+        agentId: "agent-1",
+        reason: "finished",
+      },
+    });
+  });
+
+  it("builds permission notifications from request details", () => {
+    const payload = buildAgentAttentionNotificationPayload({
+      reason: "permission",
+      serverId: "srv-2",
+      agentId: "agent-2",
+      permissionRequest: {
+        id: "perm-1",
+        provider: "claude",
+        name: "exec",
+        kind: "tool",
+        title: "**Approve command**",
+        description: "Run `git push`",
+      },
+    });
+
+    expect(payload).toEqual({
+      title: "Agent needs permission",
+      body: "Approve command - Run git push",
+      data: {
+        serverId: "srv-2",
+        agentId: "agent-2",
+        reason: "permission",
+      },
+    });
+  });
+
+  it("uses error-specific defaults when reason is error", () => {
+    const payload = buildAgentAttentionNotificationPayload({
+      reason: "error",
+      serverId: "srv-3",
+      agentId: "agent-3",
+    });
+
+    expect(payload).toEqual({
+      title: "Agent needs attention",
+      body: "Encountered an error.",
+      data: {
+        serverId: "srv-3",
+        agentId: "agent-3",
+        reason: "error",
+      },
+    });
+  });
+});
+
+describe("findLatestAssistantMessageFromTimeline", () => {
+  it("joins the latest contiguous assistant chunks", () => {
+    expect(
+      findLatestAssistantMessageFromTimeline([
+        { type: "user_message", text: "start" },
+        { type: "assistant_message", text: "Part " },
+        { type: "assistant_message", text: "one" },
+        { type: "reasoning", text: "thinking..." },
+        { type: "assistant_message", text: "Done " },
+        { type: "assistant_message", text: "now" },
+      ])
+    ).toBe("Done now");
+  });
+});
+
+describe("findLatestPermissionRequest", () => {
+  it("returns the most recently inserted request", () => {
+    const pending = new Map([
+      [
+        "first",
+        { id: "first", provider: "claude", name: "a", kind: "tool" } as const,
+      ],
+      [
+        "second",
+        { id: "second", provider: "claude", name: "b", kind: "tool" } as const,
+      ],
+    ]);
+
+    expect(findLatestPermissionRequest(pending)?.id).toBe("second");
+  });
+});

packages/server/src/shared/agent-attention-notification.ts

@@ -0,0 +1,206 @@
+const NOTIFICATION_PREVIEW_LIMIT = 220;
+
+export type AgentAttentionReason = "finished" | "error" | "permission";
+
+export type AgentAttentionNotificationData = {
+  serverId: string;
+  agentId: string;
+  reason: AgentAttentionReason;
+};
+
+export type AgentAttentionNotificationPayload = {
+  title: string;
+  body: string;
+  data: AgentAttentionNotificationData;
+};
+
+type BuildAgentAttentionNotificationPayloadInput = {
+  reason: AgentAttentionReason;
+  serverId: string;
+  agentId: string;
+  assistantMessage?: string | null;
+  permissionRequest?: NotificationPermissionRequest | null;
+};
+
+export type NotificationPermissionRequest = {
+  id: string;
+  provider: string;
+  name: string;
+  kind: "tool" | "plan" | "question" | "mode" | "other";
+  title?: string;
+  description?: string;
+  input?: Record<string, unknown>;
+  metadata?: Record<string, unknown>;
+};
+
+export type AssistantTimelineItem =
+  | { type: "assistant_message"; text: string }
+  | { type: string; text?: string };
+
+const normalizeNotificationText = (text: string): string =>
+  text.replace(/\s+/g, " ").trim();
+
+const truncateNotificationText = (text: string, limit: number): string => {
+  if (text.length <= limit) {
+    return text;
+  }
+  const trimmed = text.slice(0, Math.max(0, limit - 3)).trimEnd();
+  return trimmed.length > 0 ? `${trimmed}...` : text.slice(0, limit);
+};
+
+const stripMarkdownToText = (markdown: string): string => {
+  let text = markdown.replace(/\r\n/g, "\n");
+
+  // Strip fenced code markers but keep the code content itself.
+  text = text.replace(/^\s*```[^\n]*$/gm, "");
+  text = text.replace(/^\s*~~~[^\n]*$/gm, "");
+
+  // Markdown links/images.
+  text = text.replace(/!\[([^\]]*)\]\((?:[^()\\]|\\.)*\)/g, "$1");
+  text = text.replace(/\[([^\]]+)\]\((?:[^()\\]|\\.)*\)/g, "$1");
+
+  // Structural prefixes.
+  text = text.replace(/^\s{0,3}#{1,6}\s+/gm, "");
+  text = text.replace(/^\s{0,3}>+\s?/gm, "");
+  text = text.replace(/^\s{0,3}(?:[*+-]|\d+\.)\s+/gm, "");
+  text = text.replace(/^\s{0,3}(?:[-*_]\s*){3,}$/gm, "");
+
+  // Inline markdown markers.
+  text = text.replace(/`([^`]+)`/g, "$1");
+  text = text.replace(/\*\*([^*]+)\*\*/g, "$1");
+  text = text.replace(/__([^_]+)__/g, "$1");
+  text = text.replace(/\*([^*\n]+)\*/g, "$1");
+  text = text.replace(/_([^_\n]+)_/g, "$1");
+  text = text.replace(/~~([^~]+)~~/g, "$1");
+
+  // Angle-bracketed URL autolinks.
+  text = text.replace(/<([^>\n]+)>/g, "$1");
+
+  return text;
+};
+
+const buildNotificationPreview = (
+  text: string | null | undefined
+): string | null => {
+  if (!text) {
+    return null;
+  }
+
+  const normalized = normalizeNotificationText(stripMarkdownToText(text));
+  if (!normalized) {
+    return null;
+  }
+
+  return truncateNotificationText(normalized, NOTIFICATION_PREVIEW_LIMIT);
+};
+
+const safeStringify = (value: unknown): string | null => {
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return null;
+  }
+};
+
+const buildPermissionDetails = (
+  request: NotificationPermissionRequest | null | undefined
+): string | null => {
+  if (!request) {
+    return null;
+  }
+
+  const title = request.title?.trim();
+  const description = request.description?.trim();
+  const details: string[] = [];
+
+  if (title) {
+    details.push(title);
+  }
+  if (description && description !== title) {
+    details.push(description);
+  }
+  if (details.length > 0) {
+    return details.join(" - ");
+  }
+
+  const inputPreview = request.input ? safeStringify(request.input) : null;
+  if (inputPreview) {
+    return inputPreview;
+  }
+
+  const metadataPreview = request.metadata ? safeStringify(request.metadata) : null;
+  if (metadataPreview) {
+    return metadataPreview;
+  }
+
+  return request.name?.trim() || request.kind;
+};
+
+export function findLatestAssistantMessageFromTimeline(
+  timeline: readonly AssistantTimelineItem[]
+): string | null {
+  // Providers may stream assistant content in consecutive chunks.
+  const chunks: string[] = [];
+  for (let i = timeline.length - 1; i >= 0; i -= 1) {
+    const item = timeline[i];
+    if (item.type !== "assistant_message" || typeof item.text !== "string") {
+      if (chunks.length > 0) {
+        break;
+      }
+      continue;
+    }
+    chunks.push(item.text);
+  }
+
+  if (chunks.length === 0) {
+    return null;
+  }
+
+  return chunks.reverse().join("");
+}
+
+export function findLatestPermissionRequest(
+  pendingPermissions: ReadonlyMap<string, NotificationPermissionRequest>
+): NotificationPermissionRequest | null {
+  let latest: NotificationPermissionRequest | null = null;
+  for (const request of pendingPermissions.values()) {
+    latest = request;
+  }
+  return latest;
+}
+
+export function buildAgentAttentionNotificationPayload(
+  input: BuildAgentAttentionNotificationPayloadInput
+): AgentAttentionNotificationPayload {
+  const title =
+    input.reason === "permission"
+      ? "Agent needs permission"
+      : input.reason === "error"
+        ? "Agent needs attention"
+        : "Agent finished";
+
+  const preview =
+    input.reason === "finished"
+      ? buildNotificationPreview(input.assistantMessage)
+      : input.reason === "permission"
+        ? buildNotificationPreview(buildPermissionDetails(input.permissionRequest))
+        : null;
+
+  const body =
+    preview ??
+    (input.reason === "permission"
+      ? "Permission requested."
+      : input.reason === "error"
+        ? "Encountered an error."
+        : "Finished working.");
+
+  return {
+    title,
+    body,
+    data: {
+      serverId: input.serverId,
+      agentId: input.agentId,
+      reason: input.reason,
+    },
+  };
+}

packages/server/src/shared/messages.ts

@@ -332,6 +332,17 @@ export const AgentStreamEventPayloadSchema = z.discriminatedUnion("type", [
       reason: z.enum(["finished", "error", "permission"]),
       timestamp: z.string(),
       shouldNotify: z.boolean(),
+      notification: z
+        .object({
+          title: z.string(),
+          body: z.string(),
+          data: z.object({
+            serverId: z.string(),
+            agentId: z.string(),
+            reason: z.enum(["finished", "error", "permission"]),
+          }),
+        })
+        .optional(),
     }),
 ]);