feat(canvas): distinguish agent-directed thread messages

Generated-By: PostHog Code
Task-Id: 87a79e23-20c4-440b-818b-28154924ffbc

Author: k11kirky

packages/api-client/src/posthog-client.test.ts

@@ -1,3 +1,4 @@
+import type { TaskThreadMessage } from "@posthog/shared/domain-types";
 import { describe, expect, it, vi } from "vitest";
 import { PostHogAPIClient } from "./posthog-client";
 
@@ -1696,3 +1697,66 @@ describe("PostHogAPIClient", () => {
     });
   });
 });
+
+describe("task thread messages", () => {
+  function message(
+    overrides: Partial<TaskThreadMessage> = {},
+  ): TaskThreadMessage {
+    return {
+      id: "message-id",
+      task: "task-id",
+      content: "@agent investigate this",
+      created_at: "2026-07-16T00:00:00Z",
+      ...overrides,
+    };
+  }
+
+  it("creates a message before forwarding it to the agent", async () => {
+    const client = new PostHogAPIClient(
+      "http://localhost:8000",
+      async () => "token",
+      async () => "token",
+      123,
+    );
+    const create = vi
+      .spyOn(client, "createTaskThreadMessage")
+      .mockResolvedValue(message());
+    const send = vi
+      .spyOn(client, "sendTaskThreadMessageToAgent")
+      .mockResolvedValue(
+        message({ forwarded_to_agent_at: "2026-07-16T00:00:01Z" }),
+      );
+
+    await client.createTaskThreadMessageForAgent(
+      "task-id",
+      "@agent investigate this",
+    );
+
+    expect(create).toHaveBeenCalledWith("task-id", "@agent investigate this");
+    expect(send).toHaveBeenCalledWith("task-id", "message-id");
+    expect(create.mock.invocationCallOrder[0]).toBeLessThan(
+      send.mock.invocationCallOrder[0],
+    );
+  });
+
+  it("returns the created message when forwarding fails", async () => {
+    const client = new PostHogAPIClient(
+      "http://localhost:8000",
+      async () => "token",
+      async () => "token",
+      123,
+    );
+    const sendError = new Error("No active run");
+    vi.spyOn(client, "createTaskThreadMessage").mockResolvedValue(message());
+    vi.spyOn(client, "sendTaskThreadMessageToAgent").mockRejectedValue(
+      sendError,
+    );
+
+    await expect(
+      client.createTaskThreadMessageForAgent(
+        "task-id",
+        "@agent investigate this",
+      ),
+    ).resolves.toEqual({ message: message(), sendError });
+  });
+});

packages/api-client/src/posthog-client.ts

@@ -2630,6 +2630,21 @@ export class PostHogAPIClient {
     return (await response.json()) as TaskThreadMessage;
   }
 
+  async createTaskThreadMessageForAgent(
+    taskId: string,
+    content: string,
+  ): Promise<{ message: TaskThreadMessage; sendError: unknown | null }> {
+    const message = await this.createTaskThreadMessage(taskId, content);
+    try {
+      return {
+        message: await this.sendTaskThreadMessageToAgent(taskId, message.id),
+        sendError: null,
+      };
+    } catch (sendError) {
+      return { message, sendError };
+    }
+  }
+
   async deleteTaskThreadMessage(
     taskId: string,
     messageId: string,

packages/core/src/canvas/threadTimeline.test.ts

@@ -2,9 +2,22 @@ import { describe, expect, it } from "vitest";
 import {
   buildThreadTimeline,
   deriveThreadAgentStatus,
+  hasAgentMention,
   shouldSuspendThreadSession,
 } from "./threadTimeline";
 
+describe("hasAgentMention", () => {
+  it.each([
+    ["at the start", "@agent investigate this", true],
+    ["after other text", "Could you @Agent check this?", true],
+    ["inside an email-like token", "person@agent.com", false],
+    ["as part of a longer handle", "@agents", false],
+    ["without a mention", "human-only note", false],
+  ])("detects an agent mention %s", (_name, content, expected) => {
+    expect(hasAgentMention(content)).toBe(expected);
+  });
+});
+
 describe("buildThreadTimeline", () => {
   it("interleaves prompts, human replies, and agent turns chronologically", () => {
     const timeline = buildThreadTimeline({

packages/core/src/canvas/threadTimeline.ts

@@ -68,6 +68,12 @@ export interface ThreadAgentStatus {
   label: string;
 }
 
+const AGENT_MENTION_PATTERN = /(^|\s)@agent\b/i;
+
+export function hasAgentMention(content: string): boolean {
+  return AGENT_MENTION_PATTERN.test(content);
+}
+
 export function deriveThreadAgentStatus({
   hasActivity = false,
   hasError = false,

packages/ui/src/features/canvas/components/MentionComposer.tsx

@@ -1,10 +1,12 @@
+import { RobotIcon } from "@phosphor-icons/react";
 import { Avatar, AvatarFallback, InputGroup } from "@posthog/quill";
 import type { UserBasic } from "@posthog/shared/domain-types";
 import { getUserInitials } from "@posthog/ui/features/auth/userInitials";
 import {
+  type ComposerMentionCandidate,
   contentToDoc,
   docToContent,
-  filterMentionCandidates,
+  filterComposerMentionCandidates,
 } from "@posthog/ui/features/canvas/utils/mentionComposer";
 import { userDisplayName } from "@posthog/ui/features/canvas/utils/userDisplay";
 import { Text } from "@radix-ui/themes";
@@ -23,6 +25,7 @@ interface MentionComposerProps {
   onSubmit: () => void;
   /** The taggable pool; typically the org's members. */
   members: UserBasic[];
+  allowAgentMention?: boolean;
   onMentionInsert?: (member: UserBasic) => void;
   placeholder?: string;
   rows?: number;
@@ -40,8 +43,8 @@ const EDITOR_CLASS =
   "w-full px-2.5 py-2 outline-none break-words [overflow-wrap:break-word] [white-space:pre-wrap] [word-break:break-word]";
 
 interface SuggestionSession {
-  items: UserBasic[];
-  command: (member: UserBasic) => void;
+  items: ComposerMentionCandidate[];
+  command: (candidate: ComposerMentionCandidate) => void;
 }
 
 /**
@@ -55,6 +58,7 @@ export function MentionComposer({
   onValueChange,
   onSubmit,
   members,
+  allowAgentMention = false,
   onMentionInsert,
   placeholder,
   rows,
@@ -78,6 +82,8 @@ export function MentionComposer({
   // latest props and popup state.
   const membersRef = useRef(members);
   membersRef.current = members;
+  const allowAgentMentionRef = useRef(allowAgentMention);
+  allowAgentMentionRef.current = allowAgentMention;
   const onValueChangeRef = useRef(onValueChange);
   onValueChangeRef.current = onValueChange;
   const onSubmitRef = useRef(onSubmit);
@@ -121,11 +127,21 @@ export function MentionComposer({
             char: "@",
             allowSpaces: true,
             items: ({ query }) =>
-              filterMentionCandidates(membersRef.current, query),
-            // The suggestion pipeline carries whole members, not node attrs,
-            // so member data survives into `command`.
+              filterComposerMentionCandidates(
+                membersRef.current,
+                query,
+                allowAgentMentionRef.current,
+              ),
             command: ({ editor: e, range, props }) => {
-              const member = props as unknown as UserBasic;
+              const candidate = props as unknown as ComposerMentionCandidate;
+              if (candidate.kind === "agent") {
+                e.chain()
+                  .focus()
+                  .insertContentAt(range, { type: "text", text: "@agent " })
+                  .run();
+                return;
+              }
+              const { member } = candidate;
               e.chain()
                 .focus()
                 .insertContentAt(range, [
@@ -143,17 +159,17 @@ export function MentionComposer({
                 setDismissed(false);
                 setSelectedIndex(0);
                 setSession({
-                  items: props.items as unknown as UserBasic[],
-                  command: (member) =>
-                    props.command(member as unknown as MentionNodeAttrs),
+                  items: props.items as unknown as ComposerMentionCandidate[],
+                  command: (candidate) =>
+                    props.command(candidate as unknown as MentionNodeAttrs),
                 });
               },
               onUpdate: (props) => {
                 setSelectedIndex(0);
                 setSession({
-                  items: props.items as unknown as UserBasic[],
-                  command: (member) =>
-                    props.command(member as unknown as MentionNodeAttrs),
+                  items: props.items as unknown as ComposerMentionCandidate[],
+                  command: (candidate) =>
+                    props.command(candidate as unknown as MentionNodeAttrs),
                 });
               },
               onKeyDown: ({ event }) => {
@@ -172,8 +188,8 @@ export function MentionComposer({
                   return true;
                 }
                 if (event.key === "Enter" || event.key === "Tab") {
-                  const member = items[highlightedRef.current];
-                  if (member) sessionRef.current?.command(member);
+                  const candidate = items[highlightedRef.current];
+                  if (candidate) sessionRef.current?.command(candidate);
                   return true;
                 }
                 return false;
@@ -227,37 +243,49 @@ export function MentionComposer({
         <div className="absolute inset-x-0 bottom-full z-50 mb-1 flex flex-col overflow-hidden rounded-md border border-[var(--gray-a6)] bg-[var(--color-panel-solid)] text-[13px] shadow-lg">
           <div
             role="listbox"
-            aria-label="Mention a teammate"
+            aria-label="Mention a teammate or agent"
             className="max-h-56 overflow-y-auto py-1"
           >
-            {session.items.map((member, index) => (
+            {session.items.map((candidate, index) => (
               <button
                 type="button"
                 role="option"
                 aria-selected={index === highlightedIndex}
-                key={member.uuid}
+                key={
+                  candidate.kind === "agent" ? "agent" : candidate.member.uuid
+                }
                 ref={(el) => {
                   itemRefs.current[index] = el;
                 }}
                 // Keep focus in the editor so insertion lands at the caret.
                 onMouseDown={(event) => event.preventDefault()}
-                onClick={() => session.command(member)}
+                onClick={() => session.command(candidate)}
                 onMouseEnter={() => setSelectedIndex(index)}
                 className={`flex w-full items-center gap-2 border-none px-2 py-1 text-left ${
                   index === highlightedIndex ? "bg-[var(--accent-a4)]" : ""
                 }`}
               >
                 <Avatar size="xs" className="shrink-0">
-                  <AvatarFallback>{getUserInitials(member)}</AvatarFallback>
+                  <AvatarFallback>
+                    {candidate.kind === "agent" ? (
+                      <RobotIcon size={12} />
+                    ) : (
+                      getUserInitials(candidate.member)
+                    )}
+                  </AvatarFallback>
                 </Avatar>
                 <Text size="1" weight="medium" className="truncate">
-                  {userDisplayName(member)}
+                  {candidate.kind === "agent"
+                    ? "Agent"
+                    : userDisplayName(candidate.member)}
                 </Text>
                 <Text
                   size="1"
                   className="ml-auto shrink-0 truncate text-muted-foreground"
                 >
-                  {member.email}
+                  {candidate.kind === "agent"
+                    ? "Send to agent"
+                    : candidate.member.email}
                 </Text>
               </button>
             ))}

packages/ui/src/features/canvas/components/ThreadPanel.test.tsx

@@ -1,6 +1,6 @@
 import { render, screen } from "@testing-library/react";
 import { describe, expect, it } from "vitest";
-import { AgentTurnRow } from "./ThreadPanel";
+import { AgentTurnRow, UserPromptRow } from "./ThreadPanel";
 
 describe("AgentTurnRow", () => {
   it.each([
@@ -17,3 +17,17 @@ describe("AgentTurnRow", () => {
     expect(status.closest('[data-slot="thread-item-body"]')).not.toBeNull();
   });
 });
+
+describe("UserPromptRow", () => {
+  it("prefixes direct task prompts with @agent", () => {
+    render(
+      <UserPromptRow
+        message={{ id: "prompt", text: "Investigate this", timestamp: 1 }}
+        author={{ id: 1, uuid: "user", email: "user@example.com" }}
+      />,
+    );
+
+    expect(screen.getByText("@agent")).toBeInTheDocument();
+    expect(screen.getByText("Investigate this")).toBeInTheDocument();
+  });
+});