AI UI Frontend Package

@prox-os/ai-ui is the OS-native AI interaction package for Próx OS. It owns the frontend contract and presentation primitives for AI sessions, messages, runs, tool calls, human approvals, artifacts, context sources, citations, model selectors, agent status, usage estimates, and risk indicators.

It is not an AI runtime. It does not call LLM providers, stream tokens from a backend, execute tools, run agents, implement MCP, or store artifacts. Apps and future runtime packages own inference, persistence, execution, policy routing, and provider credentials.

Why It Exists

Próx OS is a browser OS, not a single chat page. AI needs to appear inside editors, files, search results, notifications, collaboration reviews, security warnings, developer tools, and workspace planning flows. This package gives those surfaces one shared UI language before any real model backend is wired in.

Scope

• AI interaction contracts for sessions, messages, runs, tool calls, approvals, artifacts, context sources, citations, usage, risk, providers, and models.
• React primitives for chat, context, citations, tools, approval, artifacts, model selection, agent status, insight panels, and empty/loading/error states.
• Mock sessions, messages, runs, tool calls, approvals, artifacts, models, and prompt suggestions.
• Adapter examples for actions, editor, search, files, notifications, collaboration, security, workspace, activity, and command handoff.

Non-goals

• No real OpenAI, Anthropic, Google, DeepSeek, Ollama, Groq, OpenRouter, or other provider calls.
• No AI SDK, LangChain, LlamaIndex, MCP SDK, streaming transport, agent runtime, RAG pipeline, embeddings, vector search, quota, billing, or rate limiting.
• No tool execution. Tool calls become visible proposals and approval requests.
• No OS Shell private imports.

Core Concepts

• OsAiSession: a scoped AI conversation or agent work surface.
• OsAiMessage: user, assistant, system, tool, agent, or developer message.
• OsAiRun: a unit of agent work with progress, steps, tool calls, and approvals.
• OsAiToolCall: a proposed tool request such as search, file read, editor rewrite, open route, create notification, or workspace update.
• OsAiApprovalRequest: human-in-the-loop approval for write, risky, or sensitive work.
• OsAiContextSource: source material from apps, routes, documents, files, search results, notifications, threads, reviews, workspace items, security events, or manual context.
• OsAiCitation: evidence shown back to the user.
• OsAiArtifact: AI output that can be handed off later to files, editor, actions, reviews, or reports.
• OsAiRiskAssessment and OsAiUsageEstimate: UI-facing risk and cost/latency summaries. They are not enforcement or billing systems.

Core API

Types exported from src/types.ts include:

• OsAiProviderRef, OsAiModelRef, OsAiActor.
• OsAiSession, OsAiMessage, OsAiMessagePart.
• OsAiContextSource, OsAiCitation.
• OsAiToolCall, OsAiApprovalRequest, OsAiRun, OsAiRunStep.
• OsAiAgentStatus, OsAiArtifact, OsAiUsageEstimate, OsAiRiskAssessment, OsAiEvent.

Helpers include:

• Label helpers such as getAiRunStatusLabel, getAiRiskLevelLabel, and getAiModelLabel.
• State helpers such as isAiRunActive, isAiMessageStreaming, isAiToolCallPendingApproval, and isAiApprovalOpen.
• Creation helpers such as createAiTextMessage, createAiAssistantMessage, createAiToolCall, createAiApprovalRequest, createAiArtifact, and createAiRiskAssessment.
• Context and usage helpers such as getAiContextTokenEstimate, getIncludedAiContextSources, and formatAiUsageEstimate.

React Primitives

• Identity and badges: OsAiAvatar, OsAiStatusBadge, OsAiModelBadge, OsAiProviderBadge, OsAiRiskBadge.
• Chat: OsAiMessageBubble, OsAiMessageList, OsAiComposer, OsAiPromptSuggestions, OsAiChatShell.
• Model/context/citations: OsAiModelSelector, OsAiContextSourceList, OsAiCitationList.
• Tools and approvals: OsAiToolCallCard, OsAiToolCallTimeline, OsAiApprovalCard, OsAiRunProgress, OsAiAgentStatusCard.
• Artifacts and insight: OsAiArtifactCard, OsAiArtifactGallery, OsAiInsightPanel, OsAiUsageMeter.
• States: OsAiEmptyState, OsAiLoadingState, OsAiErrorState.

The component is named OsAiAgentStatusCard because OsAiAgentStatus is the contract type.

Storybook

Open UI Workshop and browse:

• AI UI / Overview
• AI UI / Chat Shell
• AI UI / Messages
• AI UI / Composer & Suggestions
• AI UI / Model Selector
• AI UI / Context & Citations
• AI UI / Tool Calls
• AI UI / Approval Flow
• AI UI / Artifacts
• AI UI / Run Progress & Agent Status
• AI UI / Search File Editor Integration
• AI UI / Notification Collaboration Security Workspace
• AI UI / Founder & Developer Agents

Package Relationships

• @prox-os/actions: AI tool calls and approvals can become action intent. AI UI never executes those actions.
• @prox-os/editor: selections and documents can become AI context; rewrites can become artifacts or patch proposals.
• @prox-os/search: results can become context sources and citations. AI UI does not implement search, RAG, embeddings, or vector retrieval.
• @prox-os/files: files can become context sources; artifacts can map to file-like nodes. AI UI does not write storage.
• @prox-os/notifications: AI run completion, failure, approval-needed, and artifact-ready states can become notification drafts.
• @prox-os/collaboration: AI actors can map to participants and review comments. AI UI does not own threads or review state.
• @prox-os/command: prompt suggestions and sessions can become command metadata. Command Palette remains separate.
• Future @prox-os/security-ui, @prox-os/workspace-ui, and @prox-os/activity can consume risk, policy, workspace, and timeline drafts.

Phase Roadmap

Phase 1: AI UI contracts and mock primitives

• TypeScript contracts.
• Mock sessions, messages, runs, tool calls, approvals, artifacts, context, and citations.
• Chat, tool-call, approval, artifact, model, context, citation, insight, and state primitives.
• Adapter examples and Storybook coverage.
• No real LLM provider, streaming, agent runtime, MCP, tool execution, RAG, or storage writes.

Phase 2: Provider boundary and local state

• Define OsAiProvider / OsAiRuntimeAdapter.
• Mock provider and local session state adapter.
• Streaming event shape.
• Prompt suggestion and model capability registry.
• AI settings form integration.

Phase 3: OS runtime integration

• OS AI assistant panel.
• App/window/resource context injection.
• Command Palette AI handoff.
• Editor/search/files/notifications/collaboration runtime integration.
• Approval handoff to actions/runtime.
• Activity timeline integration.

Phase 4: Backend AI gateway and tools

• Backend AI gateway.
• OpenAI-compatible provider adapter.
• Local model adapter.
• Streaming transport.
• Tool registry.
• RAG/search provider bridge.
• Per-workspace AI policy routing.
• Usage/quota telemetry.

Phase 5: Agent OS, MCP, and community AI

• MCP bridge.
• Agent workflow orchestration.
• Community app agent capabilities.
• Creator app context for /@creator/apps/....
• AI-readable product system and AI swarm workflows.

Acceptance Checklist

• Package exists as @prox-os/ai-ui.
• Public exports include types, helpers, adapters, mock data, and components.
• Storybook covers core chat, tools, approvals, artifacts, and integrations.
• Docs clarify that the package is UI/contract only.
• No real AI SDK, runtime, streaming backend, MCP, vector DB, or tool execution is introduced.