AI UI System

@prox-os/ai-ui is the OS-native AI interaction layer for Próx OS. It provides frontend contracts and composable primitives for AI sessions, messages, runs, tool calls, approvals, artifacts, context sources, citations, model selection, agent status, usage, risk display, and AI Control Plane cards.

It is deliberately separate from model inference, streaming transport, tool execution, RAG, MCP, and backend persistence.

Architecture Position

AI UI sits between app surfaces and future AI/runtime systems:

app/resource/editor/search/file context
  -> AI context source / citation / session
  -> run and tool-call proposal
  -> approval card for risky work
  -> action intent or artifact handoff
  -> app/runtime/backend executes later

The package owns what the user sees and what other packages can exchange. It does not own the runtime that makes model calls or executes tools.

AI UI vs AI Runtime

@prox-os/ai-ui owns:

• AI object contracts.
• Chat, context, citation, tool-call, approval, artifact, agent-status, and insight components.
• AI Control Plane schemas for Action Cards, permission cards, connector choice cards, workflow steps, ambient observation status, and rail suggested commands.
• OsAlmaPanel, a pure Alma UI primitive that can render current Studio context, action cards, permission cards, and suggested commands without importing Shell runtime state.
• Mock data and Storybook examples.
• Adapter examples to other frontend packages.

Future runtime/backend packages own:

• Provider credentials and SDK calls.
• Streaming protocol and retry logic.
• Tool registry and execution.
• Agent orchestration and workflow state.
• RAG, embeddings, vector search, and crawler pipelines.
• Policy enforcement, audit, persistence, billing, and quotas.

Human-in-the-loop Model

Tool calls and write operations are modeled as proposals. A tool call can mark requiresApproval, set riskLevel, link to an OsAiApprovalRequest, and show a before/after preview. The package can render approve/reject events, but it does not execute the action. Runtime code must decide what approvals mean.

This default is intentional for:

• Editor rewrites.
• File writes.
• Workspace setting changes.
• Notifications or collaboration comments created by AI.
• Security-sensitive or restricted context.
• External requests.

Context Flow

Context from the OS becomes OsAiContextSource:

• editor selection or document;
• search result;
• file preview;
• notification digest;
• collaboration thread or review;
• workspace item;
• security event;
• route, app, or external URL.

AI answers cite evidence with OsAiCitation. Citation display is a UI boundary, not a guarantee of grounding. A future runtime must decide how context is assembled, filtered, ranked, and redacted.

Artifact Flow

An AI output can become an OsAiArtifact:

• markdown summary;
• code patch draft;
• JSON config;
• image placeholder;
• table or dataset preview;
• action plan;
• review summary.

Artifacts can map to @prox-os/files file-like nodes, editor patch proposals, or action/review handoffs. The AI UI package does not write files or mutate documents.

Provider Boundary

Phase 1 defines OsAiProviderRef and OsAiModelRef for display and selection only. Mock providers and model capabilities are placeholders. A later runtime adapter can decide whether a provider is OpenAI-compatible, local, hosted, workspace-scoped, or policy-routed.

No Phase 1 dependency may bind the package to:

• AI SDK or LLM provider SDKs;
• LangChain or LlamaIndex;
• MCP SDKs;
• WebSocket/streaming clients;
• vector database SDKs;
• embedding SDKs.

Event Flow

user prompt
  -> OsAiEvent(ai:message-submit)
  -> future runtime creates OsAiRun
  -> tool calls and context/citations are displayed
  -> approval request for risky operation
  -> action intent emitted after human approval
  -> runtime/app/backend executes outside ai-ui

OsAiEvent is a UI callback contract. It is not persistence or delivery.

Relationships

• @prox-os/actions: AI UI can create action intent; actions are not executed in this package.
• @prox-os/editor: selections and documents become context; rewrites become proposals or artifacts.
• @prox-os/search: results become context and citations; Search owns retrieval.
• @prox-os/files: files become context; artifacts can become file-like nodes.
• @prox-os/notifications: AI run states and approvals can become notification drafts.
• @prox-os/collaboration: AI actors can become participants or review comments; Collaboration owns threads/reviews.
• @prox-os/command: prompt suggestions and sessions can be command metadata.
• Future @prox-os/security-ui: consumes risk, sensitive context, and approval metadata.
• Future @prox-os/workspace-ui: consumes workspace-scoped sessions and context.
• Future @prox-os/activity: consumes AI events and run updates as timeline drafts.

Safety Boundaries

• The package does not sanitize or trust model output as executable content.
• Context source sensitivity is visible UI metadata, not enforcement.
• Prompt injection defense is represented as warning UI and risk metadata only.
• Citation confidence is a display hint, not verified truth.
• Approval cards do not grant permissions or execute writes.
• Provider/model badges can show mock or unavailable states without implying production connectivity.

Future Provider Adapters

Potential later adapters:

• mock provider;
• backend AI gateway;
• OpenAI-compatible provider;
• local model provider;
• streaming transport adapter;
• tool registry adapter;
• MCP bridge;
• per-workspace AI policy router.

These belong in a runtime/provider layer, not in Phase 1 UI primitives.

Data Model Sketch

OsAiSession
  messages: OsAiMessage[]
  contextSources: OsAiContextSource[]
  model: OsAiModelRef

OsAiRun
  steps: OsAiRunStep[]
  toolCalls: OsAiToolCall[]
  approvals: OsAiApprovalRequest[]

OsAiMessage
  parts: OsAiMessagePart[]
  citations: OsAiCitation[]
  toolCallIds: string[]
  artifactIds: string[]

OsAiArtifact
  kind, title, content, route/href/fileId, createdBy

Phase Roadmap

Phase 1: AI UI contracts and mock primitives

• Contracts, helpers, adapters, mock data, React primitives, Storybook, docs.
• No real LLM provider, streaming, agent runtime, MCP, tool execution, RAG, or vector search.

Phase 2: Provider boundary and local state

• OsAiProvider / OsAiRuntimeAdapter.
• Mock provider.
• Local session state.
• Streaming event shape.
• Prompt suggestion registry.
• 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 integration.
• Approval handoff to actions/runtime.
• Activity timeline integration.

Phase 4: Backend AI gateway and tools

• Backend AI gateway.
• OpenAI-compatible and local model adapters.
• 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.
• Public/private creator app context boundaries.
• AI-readable product system and AI swarm workflows.