Skip to content
Leverage AI Developer Support

Live Query

Live query is the runtime path for answering from provider APIs when indexed retrieval is too stale, incomplete, or not the right source of truth.

Implemented

Section titled “Implemented”
  • Gmail and Outlook support live mail access through the mail-live-query domain.
  • Google Calendar and Microsoft Calendar support live calendar event lookup through the calendar-live-query domain.
  • Google Contacts and Microsoft Contacts support live contact/person lookup through the contact-live-query domain.
  • Slack and Microsoft workspace chat use the workspace-chat-live-query domain.
  • Jira uses the work-item-live-query domain and requires site/project-scoped connector configuration.
  • GitHub Issues and GitHub Pull Requests use the work-item-live-query domain for issue/PR search, details, comments, reviews, review comments, and changed files.
  • GitHub Repositories uses the code-repository-live-query domain for repository list/search/detail, code search, bounded file reads, and recent commits.
  • Odoo and SharePoint lists use the business-record-live-query tool for model/list discovery, field/column discovery, record search/list/detail, and aggregate only when provider metadata shows the model/list supports it.
  • Confluence, SharePoint site pages, and OneNote pages use the knowledge-page-live-query tool for knowledge-container discovery, page search/list/detail, recent pages, and hierarchy.
  • Google Drive, OneDrive, and SharePoint document libraries use the file-resource-live-query tool for live document search and bounded transient file reads.
  • Live-query failures return structured recovery information so chat can offer reconnect, reauthorize, retry, or fallback behavior.
  • Live source metadata stays tied to connector ownership and provider authorization checks.
  • Live sources use the shared chat source contract: sourceUsage: "used" means evidence supported answer text, checked means inspected inventory, and listed means browse/list output. Broad recent and assigned-open modes stay listed until a structured source association proves row-level answer support.
  • Open and download controls come only from availableActions; connector-file downloads require the canonical fileId path through chat citation authorization.
  • Source-level coverage and freshness hints render quietly in the Sources panel when structured live-query state shows partial connected-source coverage or timestamp-bounded evidence.
  • Workspace-chat latest/recent sources also include a Coverage hint when evidence returns, because provider search/list matches are bounded and do not prove complete workspace activity.
  • Workspace-chat latest mode checks every eligible connected workspace-chat provider/resource in scope and orders message evidence newest-first by provider timestamp before synthesis.
  • Workspace-chat grounding labels the actual provider message author as Sender for both returned messages and surrounding context. Names inside message text are content, not speaker attribution.
  • Natural-language date windows are shared orchestration behavior. Connector adapters receive canonical timeMin/timeMax/timeZone; they should not re-parse common prompt phrases such as today, yesterday, a week ago, last Friday, or explicit dates.
  • Work-item comment grounding keeps author and text structured, then labels Comment author and Comment text explicitly so answers do not misattribute Jira comments.
  • GitHub work-item grounding keeps repo full name, issue or PR number, author, assignees, reviewers, labels, state, branch refs, review state, changed files, timestamps, and provider URLs structured as source actions so answers can cite user-recognizable labels such as owner/repo#123 without printing URLs in prose.
  • Work-item facet inventory, such as GitHub labels and milestones, is provider-bounded. Broad inventory checks sample eligible parent resources, balance returned facet rows across those parents before the final cap, and should disclose sampled or incomplete coverage instead of implying every repository or project was enumerated.
  • Direct facet inventory for a named parent resource should distinguish inaccessible resources from empty checked results. If a provider rejects a named repository, project, folder, or account lookup, the answer should say that source could not be checked and should not imply the facet does not exist. If bounded provider discovery finds same-name accessible resources, mention them only as naming suggestions.
  • Code-repository grounding keeps repository full name, owner/name, visibility, default branch, language, topics, file path, ref, commit sha, snippet/body text for bounded file reads, and GitHub URLs structured as source actions. It must not expose opaque internal connector ids as the only citation label or print provider URLs in answer prose.
  • Business-record grounding keeps provider model, model label, record name/title, status/stage, owner, customer, company, amount, currency, quantity, dates, deadlines, tags, URL, custom fields, relationships, provider metadata, and coverage hints structured. It must preserve Odoo custom fields structurally instead of flattening provider-specific fields into prose.
  • Calendar grounding keeps event windows, all-day state, calendar label, organizer, attendees, response status, visibility/sensitivity, recurrence/series metadata, and private/limited-detail source kinds explicit. Relative prompts such as today, tomorrow, this week, and next seven days use typed planner windows before runtime derives exact provider bounds, and provider-returned records outside those bounds are filtered before grounding. Google Calendar checks user-visible calendars through CalendarList and Events; Microsoft Calendar checks Graph calendars/calendarView and Search event results where supported.
  • Contact grounding keeps sourceKind explicit so saved contacts, directory people, organization contacts, and relevance-ranked people do not collapse into one ambiguous source. Google Contacts searches and lists saved CONTACT-source contacts; Microsoft Contacts uses Graph Search person results for focused people search and /me/contacts for saved-contact list prompts. Microsoft people search is not a complete tenant directory dump.
  • Model-facing live-query grounding should avoid opaque provider identifiers such as mail conversation ids, Slack user/channel ids, and raw file ids unless the user explicitly asks for identifiers. Keep ids in internal action/source-resolution fields.
  • Sources panel details render curated metadata only. Opaque provider ids and placeholder labels such as unknown or #unknown should not appear in user-facing source details.
  • Real-provider accuracy checks, when credentials are configured, are the right place for live provider API calls that verify ordering, attribution, metadata hygiene, and upstream payload drift. Unit tests and chat evals stay deterministic with mocked or sanitized captured provider payloads.
  • Chat evals for temporal live-query behavior should pin the prompt turn clock and mock provider-shaped live data at the canonical live-query seam so production Mastra workflow preparation still runs.

Current Implementation Notes

Section titled “Current Implementation Notes”
  • Shared chat orchestration owns current-turn temporal windows for live query. The canonical tools receive timeMin, timeMax, and timeZone; connector adapters should treat those as already interpreted.
  • The workspace-chat huddle eval pack now includes explicit-date and relative-date prompts with stale and wrong-channel decoys, so a wrong “no huddles” or stale-evidence answer fails deterministically.
  • Prompt-variant clocks make natural-language evals stable across calendar days without adding connector-specific prompt parsing.
  • The private chat orchestration skill documents this eval mocking pattern so future connectors joining an existing live domain do not need their own copy of the same temporal fix.

Chat Recovery UI

Section titled “Chat Recovery UI”

When a live-query answer is blocked by connector authorization, chat keeps the recovery action in the thread. Reauthorize starts the provider account relink flow and returns to the same chat so the failed assistant turn can be regenerated after the provider callback succeeds. Retry-only fallback states use Retry for regenerate; they should not replace auth recovery.

In-chat connector reauthorization action

Current Limits

Section titled “Current Limits”
  • Google Drive and OneDrive support live provider-backed file/folder resource listing for picker and focus flows, plus file-resource-live-query for live document-content search with bounded transient reads. Browse lists the current direct parent; connector-wide document search uses provider search and does not retain extracted live-only text. Broad chat inventory prompts sample bounded owned/shared top-level locations through connector-resource-list, disclose checked and unchecked sampled locations, and should not be read as a complete file dump.
  • Indexed retrieval is the persisted RAG path: when enabled, eligible connector content is stored as extracted chunk text and vectors. Live-only connectors and live-only mode avoid that indexed storage.
  • Drive and OneDrive live file search covers shared files/folders as part of the accepted launch behavior. Drive covers My Drive, direct shared-with-me items, and accessible Shared Drives; OneDrive uses Files.Read.All, shared-with-me traversal, and remoteItem resolution.
  • Chat should prefer live file evidence for current/latest/recent document prompts, stale or unhealthy indexed snapshots, weak/empty indexed evidence, or live/indexed conflicts. If generated source-limited file text violates source boundaries, chat falls back to source-stated user-safe copy instead of leaving the turn empty.
  • Calendar connectors are live-only for storage. Do not expect calendar sync, Meltano taps, embeddings, or indexed calendar mode.
  • Contact connectors are live-only for storage. Do not expect contact sync, Meltano taps, embeddings, or indexed contact mode.
  • GitHub connectors are live-only for storage. Do not expect GitHub sync, Meltano taps, embeddings, retained GitHub file contents, or indexed issue/PR/code snapshots.
  • GitHub code search is provider-bounded keyword/code search, not semantic whole-codebase recall. Discussions, Projects, Actions/check rollups, Releases, Packages, security alerts, exhaustive large-org inventory, and GitHub Enterprise Server are out of scope until separate provider/domain coverage is accepted.
  • Odoo is provider-bounded live business-record access through JSON-2 only. Odoo XML-RPC, JSON-RPC, webhooks, write methods, indexed sync, semantic historical recall, and embeddings are out of scope.
  • Odoo model coverage starts with res.partner, crm.lead, sale.order, account.move, project.task, helpdesk.ticket, product.template, stock.picking, and purchase.order. Unavailable or inaccessible models are skipped with coverage hints rather than treated as empty checked results.
  • Odoo requires a valid customer CMS credential profile. Existing users do not reconnect when the customer CMS operator rotates the API key because the API reads the active mounted/local credential slot through the shared resolver.
  • The current GitHub OAuth App profile uses the broad provider repo scope for private repository access. That token is write-capable at the provider scope level, while runtime GitHub behavior stays read-only through app policy, tool registration, and adapter implementation.
  • Live query must not receive private connector or focused-library content outside the connector and mode policy accepted for that request.
  • Expected-source coverage copy must stay attached to explicit source or response metadata derived from structured live-query state; the UI does not infer coverage limits from provider names, filenames, prompt text, or rendered answer text.
  • Objective latest workspace-chat answers are still bounded by connector configuration, provider scopes, and provider search limits. If any eligible connector cannot be checked, the answer and source hints should describe the coverage gap instead of implying complete workspace coverage.
Section titled “Read Next”

Canonical Sources

Section titled “Canonical Sources”
  • docs/features/live-query/spec.md
  • docs/features/chat/spec-amendments/chat-sources-metadata-schema.md
  • docs/features/live-query/decisions/
  • docs/features/live-query/stories/
  • docs/features/live-query/tests/
  • packages/contracts/src/chat/source.ts
  • apps/api/src/mastra/tools/canonicalLiveTools.ts
  • apps/api/src/connectors/providerManifests.ts
  • apps/web/app/utils/chatConnectorRemediation.ts
  • apps/web/app/pages/chat/[id].vue