Skip to content
Leverage AI Developer Support

Chat Reasoning And Work Notes

Chat reasoning summaries and work notes are owner-visible details that can appear in the chat owner activity rail and the message Activity panel. Canonical requirements live in docs/features/chat/; this page is a short implementation map for contributors.

What This Covers

Section titled “What This Covers”
  • Where reasoning summaries and work notes may appear in the owner chat UI.
  • Which boundaries strip owner-only display parts from shared chats and later model input.
  • What is implemented today versus intentionally deferred.

Implemented

Section titled “Implemented”
  • Public owner chat may request provider-native reasoning summaries for allowlisted public OpenAI reasoning models through API-owned policy.
  • Private owner chat omits provider-native reasoning chunks because even provider summaries can expose prompt, policy, or private orchestration details.
  • Private owner chat can show app-owned work notes from code-driven data-activity-note parts. These are safe progress details, not model reasoning, and completed owner activity rail disclosures use Worked for Ns when reliable activity timestamps are available.
  • Owner chat renders public reasoning and private work notes through the owner activity rail, while the Activity Slideover renders the chronological owner activity timeline. Public reasoning still uses Nuxt UI UChatReasoning, with each real reasoning part shown as a muted note row so it does not read like assistant answer prose; private work notes use Nuxt UI UChatTool work-note chrome.
  • Optional Mastra background-task streaming is reserved for explicitly allowlisted optional enrichment after foreground answer correctness is already safe. Required evidence, HITL, live/latest, and tabular-critical paths stay foreground.
  • Shared chat snapshots and shared transcript views are text-only and do not expose reasoning or work-note parts.
  • Provider reasoning metadata is stripped before client-visible owner stream and transcript responses.
  • Owner reasoning transport is a strict stream allowlist: only AI SDK reasoning-start, reasoning-delta, and reasoning-end chunks are owner-visible. Redacted reasoning, reasoning signatures, and raw single reasoning artifacts are never owner-transport artifacts; persisted owner reasoning is projected only to { type, text, state }.
  • Later chat turns do not replay reasoning as model input:
    • web outbound transport removes reasoning parts before sending chat messages back to the API
    • Mastra input processors remove reasoning parts and top-level reasoning fields from recalled history and follow-up model steps before model execution
    • activity-note/work-note parts are also excluded through the shared display part type set in @repo/contracts

Planned / Not Yet Implemented

Section titled “Planned / Not Yet Implemented”
  • Private model reasoning presentation is not implemented.
  • Future work may add a separate sanitized private reasoning artifact, but it must not pass through provider-native reasoning text.
  • Future work may further convert public provider wording into app-owned display copy without changing the assistant answer generation path.
  • Reasoning sanitization must stay owner-only, excluded from shared snapshots, and excluded from future model input.

Current Limits

Section titled “Current Limits”
  • Work notes are not a substitute for raw model reasoning. They describe app/tool execution in user-safe terms; public reasoning describes provider-emitted model summary content.
  • Reasoning is not a public/share-safe artifact.
  • Public reasoning note rows are presentation-only separation; they do not make provider summary text share-safe or private-mode safe.
  • Private provider-native reasoning is not an owner-display artifact in the current implementation.
  • Reasoning policy is owned by the API/web product surface, not cms-customer.
  • Reasoning presentation cleanup must not use brittle prompt-keyword matching as a policy layer.

Canonical Sources

Section titled “Canonical Sources”
  • docs/features/chat/spec.md
  • docs/features/chat/tests/assistant-orchestration.feature
  • docs/features/chat/tests/chat-sharing.feature
  • packages/contracts/src/chat/messages.ts
  • apps/api/src/chats/chatReasoningPolicy.ts
  • apps/api/src/chats/mastraConversationHistory.ts
  • apps/api/src/mastra/processors/chatHistoryInvariantProcessor.ts
  • apps/api/src/mastra/processors/privateAssistantOutputProcessors.ts
  • apps/web/app/components/chat/ChatAssistantActivityRail.vue
  • apps/web/app/components/chat/ChatOwnerActivityTimeline.vue
  • apps/web/app/components/chat/ChatMessageBodyParts.vue
  • apps/web/app/components/chat/ChatActivitySlideover.vue
  • apps/web/app/utils/chatOwnerActivityTimeline.ts
  • apps/web/app/utils/chatTransportMessages.ts

Official Docs

Section titled “Official Docs”
  • Nuxt UI ChatReasoning
  • Nuxt UI ChatTool
  • Nuxt UI Timeline
  • AI SDK UI message reasoning parts
  • Mastra processor interface and memory processors