[Feature]: P0 presentation profile contract, selection, and native delivery

[roomote-community]

Parent

• [Feature]: Add configurable cross-chat rich presentation profiles #1058

Goal

Establish the reliable, provider-neutral contract and selection foundation for Presentation Profiles, including native cross-chat media delivery and deterministic fallbacks.

Scope

• Define a versioned Presentation Profile schema that keeps skill, recipe, style, and delivery independently configurable.
• Define deterministic selection precedence for explicit message settings, current action/composer selection, task/thread overrides, user and organization defaults, and automatic recommendation.
• Support natural-language and quick-action profile selection at the shared contract level.
• Add typed image, animation, video, and document media contracts.
• Implement provider-native media delivery for Discord, Slack, Teams, Telegram, and Roomote web where supported.
• Implement motion -> PNG -> text fallback without losing the answer, status, or citations.
• Record profile/version, selection source, generated variants, delivery method, response, and fallback outcome.
• Add mock transport coverage and a documented real-platform golden-media smoke suite.

Acceptance criteria

• Profile schema is versioned, validated, and excludes secrets, credentials, remote scripts, and unrestricted executable HTML/CSS.
• Selection precedence is deterministic and covered by tests.
• Skill, recipe, style, and delivery remain independently configurable.
• Applied profile and version can be included in results.
• Discord uses native GIF/video attachments for motion.
• Telegram supports sendAnimation and sendVideo.
• Teams supports an Adaptive Card selection path or documented conversational fallback.
• Every motion delivery can fall back to PNG and text with citations intact.
• Provider mocks validate methods, payloads, retries, threading, and fallbacks.
• Real-client smoke checks cover playback, mobile layout, reduced motion, and CDN transformations.

Out of scope

Persisted organization/user profiles, built-in profile templates, the full web Present composer, brand kits, and publishing are tracked in later phases.

Dependency

This is the first delivery phase and blocks P1 and P2.

[easonLiangWorldedtech]

@roomote

[roomote-community]

I'm on it. I started a task for this issue, and I'll keep updates here.

See task

[roomote-community]

Thanks for the mention. What would you like me to do on this issue: produce an implementation plan, implement a specific slice, or review existing work?

[roomote-community]

I've analyzed this issue and here's my proposed implementation plan:

1. Add a strict, versioned Presentation Profile contract in a new packages/types/src/presentation-profiles.ts module and export it from packages/types/src/index.ts. Model skill, recipe, style, and delivery as independent, optional, namespaced references rather than a coupled enum; use a discriminated schema version, reject unknown fields, and expose only bounded declarative style/delivery properties so credentials, scripts, executable HTML, and unrestricted CSS cannot enter the contract.
2. Add a pure shared selection resolver alongside the contract. It should accept candidates tagged as explicit_message, action_or_composer, task_or_thread, user_default, organization_default, or automatic, apply that precedence in one place, and return the resolved profile/version plus source and reason. P0 callers can leave user/organization candidates unset until persisted defaults are introduced, while tests lock the future precedence order. Represent natural-language and quick-action choices as the same validated selection intent so provider handlers do not create separate policy paths.
3. Extend packages/types/src/task-launch-api.ts and the relevant task/message result contracts in packages/types/src/task-messages.ts / packages/types/src/task-events.ts so a validated selection can enter a run and the applied profile/version can be returned. Store the resolved selection and delivery audit in the existing task_runs.result or task-message payload JSONB from packages/db/src/schema.ts; no new user/organization profile tables or migration are needed for this phase.
4. Replace the image-only outbound shape in packages/communication/src/provider.ts with a typed media union for image, animation, video, and document variants. Use signed artifact/CDN references plus MIME type, dimensions/duration/size where applicable, alt text, and a stable variant ID. Add structured delivery results containing generated variants, selected method, provider response IDs, attempts, and fallback outcome.
5. Add a provider-neutral delivery coordinator in packages/communication that receives a canonical text response (including status and citations) and ordered generated variants, then deterministically attempts motion, PNG, and finally the unchanged text response. Keep conversion/generation upstream: the coordinator selects already-generated variants rather than downloading or transcoding media during chat delivery. Reuse the existing claim/release pattern in packages/sdk/src/server/lib/task-runs/show-widget-fallback-delivery.ts where duplicate delivery is possible.
6. Implement native provider behavior in the existing adapters: multipart GIF/video attachments with nonce/thread preservation in packages/communication/src/discord-provider.ts; sendAnimation, sendVideo, and document support with the existing retry and reply/topic fields in packages/communication/src/telegram-provider.ts; Slack file upload and threaded message association through packages/slack/src/communication-provider.ts and packages/slack/src/slack-notifier.ts; supported Bot Framework attachments in packages/communication/src/teams-provider.ts; and typed task-message/artifact rendering in the web transcript under apps/web/src/app/(sandbox)/task/[taskId]/messages/. For P0, use Teams' existing conversational/link fallback for profile selection and document the Adaptive Card path rather than introducing an unvalidated card renderer.
7. Thread the new contract through apps/api/src/handlers/mcp/communication-channel-posts.ts and the provider task/reply handlers so explicit message/action/thread selections are normalized before resolution, delivery outcomes are persisted, and text with citations is never replaced by a media-only success or failure. Preserve each provider's existing retry, idempotency, rate-limit, and threading behavior.
8. Extend mock-discord-server.ts, mock-telegram-server.ts, and Slack's mock-slack-server.ts, and add an equivalent reusable Teams Bot Framework request recorder. Cover selection precedence and schema rejection in packages/types, media methods/payloads/retries/thread IDs in provider tests, and forced motion -> PNG -> text failures in communication/API tests, including citation-preservation assertions.
9. Document the contract and provider capability/fallback matrix in apps/docs/file-attachments.mdx (or a focused presentation-profile page), plus a maintainer-run golden-media checklist covering desktop/mobile playback, reduced-motion behavior, CDN URL transformations, expired/unreachable media, threading, and the PNG/text fallback on real Discord, Slack, Teams, Telegram, and Roomote web clients. Keep this credentialed real-client suite manual/documented for P0; mocks remain the CI gate.

This approach centralizes selection and fallback policy, leaves provider formatting in the adapters that already own retries and threading, records an auditable outcome without prematurely adding persisted profile tables, and preserves the complete text answer when richer delivery is unsupported or fails.

Please tag @roomote if you'd like me to implement this, or reply with feedback on the plan.