Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
feat(agents): References section for agent sessions (#6740)
Eric Hayes8d0b359ec3d3
diff --git a/apps/web/src/features/block-agent/component/sidepanel/AgentSidePanelSections.tsx b/apps/web/src/features/block-agent/component/sidepanel/AgentSidePanelSections.tsxindex 942bfc1d69..fc2640d97d 100644--- a/apps/web/src/features/block-agent/component/sidepanel/AgentSidePanelSections.tsx+++ b/apps/web/src/features/block-agent/component/sidepanel/AgentSidePanelSections.tsx@@ -12,10 +12,12 @@import { DiffCounts } from '@app/features/agent-changes/components/DiffCounts';import { useOptionalAgentChanges } from '@app/features/agent-changes/context/agent-changes-controller';import { SidePanel } from '@components/app/side-panel';+import { References } from '@core/component/References';import { formatDate } from '@core/util/date';import { openExternalUrl } from '@core/util/url';import GitBranch from '@phosphor/git-branch.svg';-import { createMemo, For, Show } from 'solid-js';+import { useAttachmentReferencesQuery } from '@queries/storage/attachment-references';+import { createMemo, For, Show, Suspense } from 'solid-js';import { useAgentSession } from '../../context/AgentSessionContext';import { sessionStatus } from '../../state/session-status';import { activityCounts, latestPlan } from '../../state/session-summary';@@ -28,7 +30,7 @@ import {} from '../compose-agent-session-options';export function AgentSidePanelSections() {- const { session, bot, metadata, messages } = useAgentSession();+ const { sessionId, session, bot, metadata, messages } = useAgentSession();const plan = createMemo(() => latestPlan(messages()));const changes = useOptionalAgentChanges();@@ -174,10 +176,46 @@ export function AgentSidePanelSections() {</div></SidePanel.Section></Show>++ <ReferencesSectionConditional sessionId={sessionId()} /></>);}+/**+ * Where this session is referenced: channel messages that mention or attach+ * it, and documents that mention it. Same section the markdown, email, and+ * call blocks show; hidden until at least one reference exists.+ */+function ReferencesSectionConditional(props: { sessionId?: string }) {+ const references = useAttachmentReferencesQuery(+ () => props.sessionId,+ () => 'agent_session'+ );++ // Gate the resource read on status so a pending query never suspends the+ // enclosing block while the section is hidden anyway.+ const count = () => (references.isSuccess ? references.data.length : 0);++ return (+ <Show when={count() > 0 ? props.sessionId : undefined}>+ {(sessionId) => (+ <SidePanel.Section+ id="references"+ title={<SidePanel.CountTitle label="References" count={count()} />}+ order={40}+ >+ <Suspense fallback={<SidePanel.Loading />}>+ <div class="text-xs">+ <References documentId={sessionId()} entityType="agent_session" />+ </div>+ </Suspense>+ </SidePanel.Section>+ )}+ </Show>+ );+}+/** `https://github.com/org/repo.git` → `org/repo` for a compact pill. */function repoName(url: string): string {const path = urldiff --git a/apps/web/src/features/block-md/component/MarkdownEditor.tsx b/apps/web/src/features/block-md/component/MarkdownEditor.tsxindex 9e859e83e4..6fbcf22bb9 100644--- a/apps/web/src/features/block-md/component/MarkdownEditor.tsx+++ b/apps/web/src/features/block-md/component/MarkdownEditor.tsx@@ -404,10 +404,11 @@ export function MarkdownEditor(props: {const dragInsertPosition = getValidDragInsertPosition(editor, res.mousePos);if (!dragInsertPosition) return;- const mentionId =- res.item.type === 'agent_session'- ? undefined- : await trackMention(blockId, 'document', res.id);+ const mentionId = await trackMention(+ blockId,+ res.item.type === 'agent_session' ? 'agent_session' : 'document',+ res.id+ );let blockParams: Record<string, string> | undefined;if (res.blockName === 'channel') {diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/MentionsMenu/utils/agent-session-selection.test.ts b/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/MentionsMenu/utils/agent-session-selection.test.tsindex 00ba7ab31d..48be4ae036 100644--- a/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/MentionsMenu/utils/agent-session-selection.test.ts+++ b/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/MentionsMenu/utils/agent-session-selection.test.ts@@ -1,7 +1,8 @@import type { LexicalEditor } from 'lexical';-import { describe, expect, it, vi } from 'vitest';+import { beforeEach, describe, expect, it, vi } from 'vitest';-vi.mock('@core/signal/mention', () => ({ trackMention: vi.fn() }));+const { trackMention } = vi.hoisted(() => ({ trackMention: vi.fn() }));+vi.mock('@core/signal/mention', () => ({ trackMention }));vi.mock('./entityUtils', () => ({ getBlockNameFromEntity: vi.fn(() => 'md') }));vi.mock('../../../../plugins', () => ({REMOVE_INLINE_SEARCH_COMMAND: 'remove-search',@@ -41,6 +42,10 @@ const item: AgentSessionMentionItem = {};describe('agent session menu selection', () => {+ beforeEach(() => {+ trackMention.mockReset();+ });+it('inserts its own node without invoking user/document attachment callbacks', async () => {const dispatchCommand = vi.fn();const onDocumentMention = vi.fn();@@ -62,6 +67,45 @@ describe('agent session menu selection', () => {});expect(onDocumentMention).not.toHaveBeenCalled();expect(onUserMention).not.toHaveBeenCalled();+ expect(trackMention).not.toHaveBeenCalled();+ });++ it('records a document reference so the session lists the doc under References', async () => {+ trackMention.mockResolvedValue('mention-uuid');+ const dispatchCommand = vi.fn();+ const handler = createItemHandler({+ editor: { dispatchCommand } as unknown as LexicalEditor,+ blockId: 'doc-1',+ blockName: 'write',+ });+ await handler(item);+ expect(trackMention).toHaveBeenCalledWith(+ 'doc-1',+ 'agent_session',+ 'session'+ );+ expect(dispatchCommand).toHaveBeenNthCalledWith(2, 'insert-session', {+ id: 'session',+ label: 'Fix mentions',+ mentionUuid: 'mention-uuid',+ });+ });++ it('does not track when the host is a channel or chat composer', async () => {+ for (const blockName of ['channel', 'chat'] as const) {+ const dispatchCommand = vi.fn();+ const handler = createItemHandler({+ editor: { dispatchCommand } as unknown as LexicalEditor,+ blockId: 'host-1',+ blockName,+ });+ await handler(item);+ expect(trackMention).not.toHaveBeenCalled();+ expect(dispatchCommand).toHaveBeenNthCalledWith(2, 'insert-session', {+ id: 'session',+ label: 'Fix mentions',+ });+ }});it('participates in the mobile search list', () => {expect(sortMobileMentions([item], 'Ada')).toEqual([item]);diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/MentionsMenu/utils/mentionHandlers.ts b/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/MentionsMenu/utils/mentionHandlers.tsindex 02c7b9c722..87c46c36eb 100644--- a/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/MentionsMenu/utils/mentionHandlers.ts+++ b/apps/web/src/lib/core/component/LexicalMarkdown/component/menu/MentionsMenu/utils/mentionHandlers.ts@@ -32,6 +32,38 @@ function entityDisplayName(item: EntityItem): string {return '';}+/** Whether a mention inserted into this editor is recorded as a document reference. */+function tracksMentions(dependencies: HandlerDependencies): boolean {+ const { blockId, blockName, disableMentionTracking } = dependencies;+ return Boolean(+ blockId &&+ blockName !== 'channel' &&+ blockName !== 'chat' &&+ !disableMentionTracking+ );+}++/**+ * Insert an agent session chip. It is a reference, not a bot invocation, so+ * it skips the document/user attachment callbacks — but it is tracked like+ * any other entity mention so the session's References panel lists the doc.+ */+async function handleAgentSessionMention(+ session: { id: string; name?: string },+ dependencies: HandlerDependencies+): Promise<void> {+ const { editor, blockId } = dependencies;+ const mentionUuid =+ blockId && tracksMentions(dependencies)+ ? await trackMention(blockId, 'agent_session', session.id)+ : undefined;+ editor.dispatchCommand(INSERT_AGENT_SESSION_MENTION_COMMAND, {+ id: session.id,+ label: session.name,+ ...(mentionUuid ? { mentionUuid } : {}),+ });+}+/*** Handle entity mention (documents, channels, emails, etc.).*/@@ -39,34 +71,18 @@ async function handleEntityMention(item: EntityItem,dependencies: HandlerDependencies): Promise<void> {- const {- editor,- blockName,- blockId,- onDocumentMention,- disableMentionTracking,- onEmailMention,- } = dependencies;+ const { editor, blockId, onDocumentMention, onEmailMention } = dependencies;const entity = item.data;if (entity.type === 'agent_session') {- editor.dispatchCommand(INSERT_AGENT_SESSION_MENTION_COMMAND, {- id: entity.id,- label: entity.name,- });- return;+ return await handleAgentSessionMention(entity, dependencies);}const blockNameForMention = getBlockNameFromEntity(item);const itemName = entityDisplayName(item);let mentionId: string | undefined;- if (- blockId &&- blockName !== 'channel' &&- blockName !== 'chat' &&- !disableMentionTracking- ) {+ if (blockId && tracksMentions(dependencies)) {const trackType =item.bucket === 'channel' || item.bucket === 'dm'? 'channel'@@ -137,11 +153,10 @@ export function createItemHandler(dependencies: HandlerDependencies) {case 'group':return await handleGroupMentionItem(item.data, dependencies);case 'agentSession':- dependencies.editor.dispatchCommand(- INSERT_AGENT_SESSION_MENTION_COMMAND,- { id: item.id, label: item.data.name }+ return await handleAgentSessionMention(+ { id: item.id, name: item.data.name },+ dependencies);- return;case 'entity':return await handleEntityMention(item, dependencies);}diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/mentions/mentionsPlugin.ts b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/mentions/mentionsPlugin.tsindex ab9a532219..e4406a8836 100644--- a/apps/web/src/lib/core/component/LexicalMarkdown/plugins/mentions/mentionsPlugin.ts+++ b/apps/web/src/lib/core/component/LexicalMarkdown/plugins/mentions/mentionsPlugin.ts@@ -579,8 +579,13 @@ function registerMentionsPlugin(if (!$isAgentSessionMentionNode(node)) continue;if (mutation === 'created')onCreateMention?.($mentionItemFromNode(node));- if (mutation === 'destroyed')+ if (mutation === 'destroyed') {+ const mentionUuid = node.getMentionUuid();+ if (mentionUuid && sourceDocumentId) {+ untrackMention(sourceDocumentId, mentionUuid);+ }onRemoveMention?.($mentionItemFromNode(node));+ }}updateMentionsSignal();}diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/tests/mentionCallbacks.test.ts b/apps/web/src/lib/core/component/LexicalMarkdown/tests/mentionCallbacks.test.tsindex 9bd07be461..9e383a750e 100644--- a/apps/web/src/lib/core/component/LexicalMarkdown/tests/mentionCallbacks.test.ts+++ b/apps/web/src/lib/core/component/LexicalMarkdown/tests/mentionCallbacks.test.ts@@ -28,9 +28,8 @@ vi.hoisted(() => {vi.mock('@core/constant/allBlocks', () => ({verifyBlockName: (name: string) => name,}));-vi.mock('@core/signal/mention', () => ({- untrackMention: vi.fn(),-}));+const { untrackMention } = vi.hoisted(() => ({ untrackMention: vi.fn() }));+vi.mock('@core/signal/mention', () => ({ untrackMention }));vi.mock('@service-storage/client', () => ({blockNameToItemType: (name: string) => {const map: Record<string, string> = {@@ -70,6 +69,7 @@ import {type LexicalEditor,} from 'lexical';import {+ INSERT_AGENT_SESSION_MENTION_COMMAND,INSERT_CONTACT_MENTION_COMMAND,INSERT_DATE_MENTION_COMMAND,INSERT_DOCUMENT_MENTION_COMMAND,@@ -357,6 +357,51 @@ describe('mentionsPlugin callbacks', () => {cleanup();});+ test('removing an agent session mention untracks its document reference', () => {+ untrackMention.mockClear();+ const editor = createTestEditor();+ const created: ItemMention[] = [];+ const removed: ItemMention[] = [];+ const cleanup = mentionsPlugin({+ sourceDocumentId: 'doc-1',+ onCreateMention: (mention) => created.push(mention),+ onRemoveMention: (mention) => removed.push(mention),+ })(editor);++ editor.dispatchCommand(INSERT_AGENT_SESSION_MENTION_COMMAND, {+ id: 'session-1',+ label: 'Fix mentions',+ mentionUuid: 'uuid-session',+ });+ editor.read(() => {});++ expect(created).toContainEqual(+ expect.objectContaining({+ itemType: 'agent_session',+ itemId: 'session-1',+ })+ );+ expect(untrackMention).not.toHaveBeenCalled();++ editor.update(+ () => {+ $getRoot().clear().append($createParagraphNode());+ },+ { discrete: true }+ );+ editor.read(() => {});++ expect(removed).toContainEqual(+ expect.objectContaining({+ itemType: 'agent_session',+ itemId: 'session-1',+ })+ );+ expect(untrackMention).toHaveBeenCalledWith('doc-1', 'uuid-session');++ cleanup();+ });+test('custom plugin passed to builder runs and cleans up', () => {const editor = createTestEditor();const pluginInit = vi.fn();diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/utils/dragInsertUtils.ts b/apps/web/src/lib/core/component/LexicalMarkdown/utils/dragInsertUtils.tsindex e11b862c6e..933029a15d 100644--- a/apps/web/src/lib/core/component/LexicalMarkdown/utils/dragInsertUtils.ts+++ b/apps/web/src/lib/core/component/LexicalMarkdown/utils/dragInsertUtils.ts@@ -114,6 +114,7 @@ export function insertDocumentMentionAtDragInsertPosition(? $createAgentSessionMentionNode({id: mentionInfo.documentId,label: mentionInfo.documentName,+ mentionUuid: mentionInfo.mentionUuid,}): $createDocumentMentionNode({...mentionInfo,diff --git a/docs/AGENT_GUIDE/ai-chat.md b/docs/AGENT_GUIDE/ai-chat.mdindex 14c5e999fe..c1040ce309 100644--- a/docs/AGENT_GUIDE/ai-chat.md+++ b/docs/AGENT_GUIDE/ai-chat.md@@ -417,10 +417,15 @@ In the Agents workspace, saved sessions use the shared top-bar controls: sessionicon, title and action menu, Share, Copy Share Link, and a side-panel toggle.There is no breadcrumb because Agents has no subspaces. Unknown model providersfall back to the chat icon. The toggle (or `]`) opens the session's Details, Plan,-Changes, and Activity sections when available, beside the transcript in wide+Changes, Activity, and References sections when available, beside the transcript in widelayouts or over it in narrow layouts; it does not open another split.Details lists Status, Agent, Model, and dates for every session; the Harnessrow appears only for coding runtimes, never for in-memory chat agents.+`References` is the same section documents show: one row per channel message that+`@`-mentioned or shared the session (sender, channel chip, time, and a two-line+message excerpt) and per document that mentions it (author and document chip).+Click a row to open that message or document in a split. The section is hidden+until at least one reference exists, and only lists channels you belong to.New conversation pages have no disabled session action buttons. Older chatsalso have one header row, and empty chats show a simple conversation promptinstead of the standalone recent-sessions and tips surface.