Assistant Response Sources

Assistant responses can carry source metadata so users and developers can tell what supported an answer, what was only checked, and what actions are safe to show. The canonical contract lives in docs/features/chat/; this page is the short map for contributors.

What Users Get

A Sources action appears on assistant messages when source metadata exists.
The Sources panel is the full inventory for that message.
Source content and detail sections stay collapsed by default so the panel opens to a scannable inventory.
Quiet inline citation tokens appear only when a source is structurally attached to specific response text.
Mixed sourced/general answers can show compact section labels such as Source-backed or General knowledge when privacy-safe groundingSegments metadata targets rendered markdown blocks.
The assistant should not write its own Sources section, footnotes, or citation markers in the answer body.
Shared chat snapshots strip raw source metadata, direct source links, download controls, and inline source actions.

Screenshot Placeholder

Inline source tokens in an assistant response

Replace with a focused chat screenshot showing quiet inline citation tokens beside the answer text they support.

Screenshot Placeholder

Sources panel for a sourced assistant response

Replace with a focused Sources panel screenshot showing used evidence before checked or listed inventory, plus Coverage/Freshness hints when present.

Metadata Fields

Each source entry has required identity, usage, and action fields, plus optional display, trust, authorization, and placement fields. Source metadata is separate from message-level grounding metadata such as groundingMode and groundingContributors.

Identity: id, type, and sourceLabel identify the source, its kind (connector-file, external-link, email, contact, calendar-event, or item), and its user-facing origin.
Usage and actions: sourceUsage and availableActions tell the UI whether the source was used, checked, or listed, and whether open or download may appear.
Display details: title, snippet, confidence, provider, createdAt, sourceAccountLabel, and metadata provide user-safe panel details, relevance, account provenance, and curated provider-specific display metadata.
Trust hints: readinessHint and recencyHint render as Coverage and Freshness copy when evidence is partial, bounded, or timestamp-sensitive.
Private authorization: connectorId and fileId keep private source actions permission-scoped.
Connector account provenance: owner source panels prefer the source-owned sourceAccountLabel when present and may fall back to connectorId lookup for current linked Connector OAuth accounts. Rendered labels must be meaningful profile values such as email, username, or name. Raw account ids, connector ids, and provider subject ids are never display labels, and account provenance is not participant evidence.
Open targets: webViewLink, itemLink, and itemId support safe provider/public opens and item display.
Inline placement: toolName and citationTarget carry domain tool provenance and structural markdown-block placement for quiet inline citations.
Section grounding: groundingSegments lives on message metadata, targets rendered markdown blocks, and carries only groundingMode plus contributor categories. It must not include source ids, snippets, provider ids, tool payloads, or reasoning.

Generic display metadata is not a raw provider payload. It must not expose opaque provider identifiers such as Slack user/channel ids, Outlook conversation ids, raw folder ids, connector ids, or placeholder labels such as unknown/#unknown. Keep those ids only in private action-resolution fields when the UI needs them for authorization or open/download actions.

Public Chat Sources

Public chat sources are public web sources returned by the selected public provider path when that capability is available and allowed by server policy.

What we get	How it is used
Website source parts	Feed quiet inline citations and the Sources panel.
Title and URL	Let the user open the public source as a third-party link.
Coverage and Freshness hints	Explain bounded web-search coverage and mutable page freshness in the Sources panel.

Public sources never grant private connector access. Public chat must not show private connector, workspace, focus, or file-download controls.

Private Chat Sources

Private chat sources come from authorized private evidence paths: indexed retrieval, live query, tabular reasoning, or connector resource browsing.

Source path	Typical source shape
Indexed retrieval	Connector files or indexed documents with snippets and optional confidence.
Live mail	Gmail or Outlook email sources with sender/subject/date-style metadata and safe provider links when available.
Live calendar	Google or Microsoft calendar events with event windows, organizer/attendee metadata, response status, and limited-detail/private-event source kinds when applicable.
Live workspace chat	Slack or Microsoft workspace-chat items, usually with bounded coverage hints for recent/latest modes.
Live work items	Jira items with issue metadata and safe provider links when available.
Connector resource list	Browse/list results such as files or folders; these are usually listed inventory, not cited answer evidence.
Tabular reasoning	Table/data sources that supported calculations, filtering, ranking, or explanation.

Private sources stay inside the thread’s locked mode, focus, connector ownership, and authorization policy. If expected private evidence cannot be fully checked, the answer should say that in user-safe language instead of pretending coverage is complete.

For workspace-chat sources, missing channel or conversation labels should be omitted unless the provider returned a real display name or the app can derive a trustworthy structural label such as a direct message. Do not fabricate channel names to make the panel look complete.

Source Usage Labels

Every source uses one of three usage labels:

Label	Meaning	UI treatment
`used`	Materially supported answer text.	Grouped first in the Sources panel; may become an inline citation only with a source part or structural target.
`checked`	Inspected or retained as inventory but did not support answer text.	Stays in the Sources panel, separate from used evidence.
`listed`	Returned as a browse/list result.	Stays panel-scoped unless a structured item-to-text association later proves answer support.

Broad live-query list modes such as recent workspace-chat results or assigned-open Jira issues should stay listed until the response has a structural association for the rows that actually support answer text.

Action Rules

Source actions are explicit. The UI must render only actions listed in availableActions.

Action	Required source data	Rule
`open`	Safe `itemLink` or `webViewLink`	Opens as a third-party or provider link with secure relationship attributes.
`download`	Connector-file source with canonical `fileId`	Resolves through the authenticated citation download route.

Do not infer open/download behavior from provider-native ids, filenames, markdown text, source titles, provider labels, or connector labels.

Where Code Lives

Shared source contract: packages/contracts/src/chat/source.ts
API source normalization and merge rules: apps/api/src/chats/chatSourceMetadata.ts
Private inline source parts: apps/api/src/chats/chatInlineSourceParts.ts
Structural citation placement: apps/api/src/chats/chatCitationPlacement.ts
Section grounding derivation: apps/api/src/chats/chatSourceMetadata.ts
Public web-source trust hints: apps/api/src/chats/publicWebSourceTrust.ts
Live-query source creation: apps/api/src/mastra/tools/canonicalLiveTools.ts and apps/api/src/connectors/liveAccess*Contracts.ts
Web source parsing and panel grouping: apps/web/app/utils/chatSources.ts and apps/web/app/utils/chatSourcePresentation.ts
Message rendering: apps/web/app/components/chat/ChatMarkdownContent.vue and apps/web/app/components/chat/ChatSourcesSlideover.vue

Canonical Sources

docs/features/chat/spec.md
docs/features/chat/spec-amendments/chat-sources-metadata-schema.md
docs/features/chat/tests/chat-sources-and-citations.feature
docs/features/live-query/spec.md
docs/features/live-query/stories/source-attribution.stories.md
docs/features/live-query/tests/source-attribution.feature
packages/contracts/src/chat/source.ts

Official Docs

AI SDK Core sources