Blinkin Legacy Docs Docs
PRDs · prds/04-chat-agents-controls-prd.md Docs Home

PRD 04: Chat, Agents, Tools, and Generated Controls

Problem Statement

Zweistein contains the legacy chat workspace, agent navigation, tool-driven AI workflows, generated controls, and dynamic UI rendering. These features are core to the old product, but the legacy controls runtime executes generated React code in the main browser context, which must not be preserved as-is.

The new platform must preserve chat and agent power while making generated UI safe, versioned, reviewable, and auditable.

Solution

Build a chat and agent system with:

  • conversations and message history;
  • streaming assistant responses;
  • attachments, voice, paste, and file inputs;
  • agents, bots, companions, agent threads, and tool calls;
  • generated controls/widgets as governed artifacts;
  • draft, review, publish, versioning, and sandboxed rendering for generated UI;
  • explicit tool status, cancellation, and result handling.

Legacy Source References

  • zweistein-reference/admin/src/common/chat/
  • zweistein-reference/admin/src/pages_chat/
  • zweistein-reference/admin/src/pages_chat/agents/
  • zweistein-reference/admin/src/pages_chat/bots/
  • zweistein-reference/admin/src/pages_chat/controls/
  • zweistein-reference/server/src/chat/
  • zweistein-reference/server/src/controls/
  • zweistein-reference/server/src/generate-anything/
  • zweistein-reference/server/src/tenant-tool-config/
  • zweistein-reference/server/src/mcp-servers/

User Stories

  1. As a user, I want conversation history, so that I can return to previous work.
  2. As a user, I want message streaming, so that long answers feel alive and responsive.
  3. As a user, I want attachments, so that I can ask questions about files and media.
  4. As a user, I want paste support, so that images and documents can enter the chat quickly.
  5. As a user, I want voice input, so that I can dictate instead of typing.
  6. As a user, I want message feedback, so that bad answers can be improved.
  7. As an agent builder, I want to create and manage agents, so that each agent has a clear role.
  8. As an agent builder, I want to configure tool access per tenant, so that agents only use approved capabilities.
  9. As an agent builder, I want tool calls shown as first-class events, so that I know what the agent is doing.
  10. As a user, I want to cancel a long-running tool, so that I am not trapped in a slow task.
  11. As a builder, I want to generate a UI control from a description, so that non-developers can create custom interfaces.
  12. As a reviewer, I want generated controls to enter a review queue, so that unsafe or broken widgets are not published.
  13. As a user, I want published widgets to render safely, so that generated UI cannot steal data.
  14. As an admin, I want widget versions and audit logs, so that I can see what changed and who approved it.
  15. As a developer/operator, I want generated UI isolated from the main app, so that runtime failure is contained.

Functional Requirements

Chat

  • Support message types: user, assistant, status, tool call, artifact/widget, file attachment, image, system notice.
  • Support markdown, code blocks, math, source links, and tool results.
  • Store message versions as structured data, not text split markers.
  • Support regenerate, cancel, feedback, and branch/version history.
  • Support durable conversation list and per-user access.

Composer

  • Support text, file attachments, image/audio/document classification, paste files, voice input, and upload progress.
  • Validate file size and type on frontend and backend.
  • Support context selection: space, agent, board, companion, collection, or thread where applicable.

Agents and Tools

  • Support agent records with name, description, prompt, model/provider config, allowed tools, tenant config, and visibility.
  • Support official, org, internal, and personal agents if needed.
  • Support tool calls with explicit lifecycle: queued, running, streamed, completed, failed, canceled, expired.
  • Support tenant tool allowlists.
  • Support audit logging for sensitive tools.

Generated Controls and Widgets

  • Preserve the old concept of generated controls: component code, schema, sample data, description, and generated JSON schema.
  • Add status: draft, needs_review, approved, published, deprecated.
  • Add version records.
  • Add server-side validation before save.
  • Render published generated UI in a sandboxed iframe or equivalent isolation.
  • Communicate through postMessage or a constrained runtime API.
  • Block direct access to cookies, localStorage, app DOM, and arbitrary network calls.

Non-Functional Requirements

  • No browser-side new Function() for generated controls in the main app context.
  • No unpinned CDN script injection for runtime controls.
  • Streaming must include heartbeat, reconnect strategy, and terminal status.
  • Tool calls must have timeouts and structured errors.
  • Generated UI must fail closed.

Implementation Decisions

  • Reuse chat message ideas, but define new structured message and tool-call contracts.
  • Reuse controls CRUD concept, but add lifecycle, versions, review, and sandboxed runtime.
  • Keep tenant tool configuration as a first-class admin surface.
  • Treat generated UI as an artifact, not arbitrary trusted application code.

Testing Decisions

  • Browser-test chat streaming, attachments, voice, cancellation, and feedback.
  • API-test agent CRUD and tool allowlists.
  • Security-test generated widget sandbox boundaries.
  • Unit-test widget schema validation and versioning.
  • E2E-test draft to review to publish lifecycle.

Out of Scope

  • Reusing old unsafe runtime execution.
  • Porting ABB-specific metadata as core platform behavior unless it is generalized.