@praxisui/ai 8.0.0-beta.8 → 8.0.0-beta.80

package/README.md

@@ -1,7 +1,7 @@
 ---
 title: "AI"
 slug: "ai-overview"
-description: "Overview of @praxisui/ai with backend-orchestrated provider flows, deterministic suggestions, patch generation, and tenant-aware risk policy."
+description: "Overview of @praxisui/ai with backend-orchestrated provider flows, governed assistant UX, structured configuration proposals, and tenant-aware risk policy."
 doc_type: "guide"
 document_kind: "component-overview"
 component: "ai"
@@ -27,13 +27,13 @@ related_docs:
 
 # @praxisui/ai
 
-AI building blocks and assistant integration for Praxis UI applications. The package is designed for Angular hosts that need provider orchestration, metadata-aware UX and integration with the broader `@praxisui/*` ecosystem.
+AI building blocks and assistant integration for Praxis UI applications. The package is designed for Angular hosts that need AI to understand existing runtime materializers, ask for clarification, answer consultative questions, and propose governed configuration changes without turning the browser into a free-form code generator.
 
 Short mental model:
 
 - `@praxisui/ai` is not a direct wrapper around external LLM providers.
 - the canonical path is backend orchestration through Praxis Config endpoints under `/api/praxis/config/ai/**`.
-- the library helps the host compose suggestions, clarifications, risk policy, and patch application without turning AI into a host-local sidecar.
+- the library helps the host compose suggestions, clarifications, risk policy, and governed apply flows without turning AI into a host-local sidecar or disposable screen generator.
 
 ## Documentation
 
@@ -54,15 +54,15 @@ Peer dependencies (Angular v20):
 
 ## When to use
 
-- Add AI-assisted suggestions and patch generation to Praxis UI components
+- Add AI-assisted consultation, clarification, and governed configuration proposals to Praxis UI components
 - Centralize provider and model validation behind backend-controlled endpoints
 - Apply tenant-aware confirmation and risk policies in enterprise environments
 
 ## What this package is responsible for
 
 - assistant UX surfaces and interaction flow
-- reusable assistant shell primitives such as conversation messages, quick replies, prompt composer, apply actions and drag/resize chrome
-- backend API orchestration for provider catalog, suggestions, and patch generation
+- reusable assistant shell primitives such as conversation messages, quick replies, prompt composer, governed actions, viewport-level drag/resize chrome, layout restore and minimized-session dock
+- backend API orchestration for provider catalog, suggestions, structured proposals, and governed apply flows
 - local lightweight session history with tenant/env/user scoping
 - confirmation and risk policy integration for sensitive changes
 
@@ -72,13 +72,36 @@ Peer dependencies (Angular v20):
 
 `PraxisAiAssistantShellComponent` is the canonical chrome for Praxis assistant experiences that need a conversational surface. Hosts should prefer it for new specialized flows instead of creating component-local assistant UI.
 
+`PraxisAiAssistantComponent` remains exported only as a compatibility surface for older configuration-assistant integrations. New Praxis components, demos and cockpit flows should use `PraxisAiAssistantShellComponent` with `PraxisAssistantTurnOrchestratorService` and, when the assistant can be minimized or resumed, `PraxisAssistantSessionRegistryService`.
+
 The shell owns the shared UX primitives:
 - conversation messages and message actions such as edit/resend/custom actions
 - prompt composer, Enter-to-submit behavior, pasted or selected file attachments, submit/apply actions and attach/remove attachment events
 - active context chips for component, schema, selection, route, tenant or custom context
+- rich quick reply chips with optional description, icon, tone and structured context hints
 - attached context metadata for files, images, JSON, schema and text payloads
 - mode and state labels for `config`, `agentic-authoring`, `chat`, `diagnostic`, `review` and `inline-help`
-- draggable/resizable panel layout and accessibility labels
+- viewport-level draggable/resizable panel layout, pointer-only resize handles, layout restore, minimize affordance and accessibility labels
+
+The shell is a viewport-level assistant surface, not a component-bounded popover. A component trigger opens the assistant with local semantic context, but the panel can move across the page, resize from any edge or corner, and be restored to its initial safe layout through the shared "Restaurar posição do assistente" affordance. The default close affordance is "Minimizar assistente" because specialized hosts usually preserve the governed session through `PraxisAssistantSessionRegistryService`; hosts that truly close/discard the session may override the label.
+
+The assistant chrome belongs to the platform, not to the component that opened it. Hosts should provide contextual labels, mode, state and context chips, while `PraxisAiAssistantShellComponent` keeps the shared visual hierarchy: assistant identity first, contextual title/subtitle second, and operational mode/state as compact metadata. Component-specific styling should not make the shell look owned by Page Builder, Table, Dynamic Form or any other individual runtime.
+
+Composer actions are state-aware. The primary action changes from "Interpretar pedido" to clarification, review, applying, success or error labels according to the current turn state. Secondary recovery actions such as retry and cancel are surfaced by the shell when the active turn can be recovered, while hosts still own the flow-specific semantics.
+
+Hosts can render the primary action as icon-only with `iconOnly=true` when that matches modern LLM chat composer conventions. The action must still provide a semantic `label` or `ariaLabel`; the shell uses it for accessibility and tooltip text while omitting the visible label.
+
+Message-level actions can also be rendered as icon-only controls by setting `icon` or `iconOnly=true` on `PraxisAssistantShellMessageAction`. Built-in `edit`, `resend` and `copy` actions use `edit`, `replay` and `content_copy` icons by default, with the visible label moved to tooltip and `aria-label`.
+
+`PraxisAiAssistantDockComponent` is the companion minimized-session surface for the same assistant identity. Hosts use it when a specialized assistant session remains active but the full shell is minimized. The dock owns the shared visual language for assistant presence, state badges and reopen affordance; hosts still provide the semantic session summary and decide what reopening means.
+
+`PraxisAssistantSessionRegistryService` is the canonical in-memory registry for assistant sessions opened by different Praxis components in the same application shell. Component hosts register their active or minimized sessions with stable `ownerId`/`ownerType` metadata so a global assistant host can present one shared experience while preserving each component's semantic context. Sessions can use the default `presence: 'global-dock'` when the App Shell should render the minimized card, or `presence: 'origin-anchor'` when the owning component keeps the minimized affordance on its original trigger. The registry accepts an optional `PraxisAssistantContextSnapshot`, normalizes it before storage and rejects snapshots whose `identity.sessionId`, `identity.ownerId` or `identity.ownerType` do not match the session descriptor. Components that already have a canonical context snapshot should prefer the context helpers: `upsertContextSession`, `openContextSession`, `minimizeContextSession`, `getContextSession` and `removeContextSession`.
+
+`PraxisAiAssistantSessionHostComponent` is the canonical presence host for minimized assistant sessions in an application or page shell. It reads `PraxisAssistantSessionRegistryService`, renders the shared dock for each minimized `global-dock` session, and emits the opened session snapshot after promoting that session to active in the registry. Hosts can opt into `includeOriginAnchored=true` for diagnostics or custom shells, but the default respects owner-local minimized affordances. Specialized components still own the full shell events until their authoring action contracts are promoted to shared platform contracts.
+
+`PraxisAssistantContextSnapshot` is the canonical, UI-agnostic context contract for intelligent Praxis components. It represents safe assistant context: stable identity, current target, context chips, manifest reference, resource/schema hints, digests, governance hints, attachment summaries and declarative action contracts. It is intentionally not a raw component payload. Hosts should normalize snapshots with `normalizePraxisAssistantContextSnapshot` before storing them in a registry, passing them between components or using them as a handoff boundary.
+
+Context snapshots must not contain full configs, form values, table rows, `currentState`, `runtimeState`, `pendingPatch`, arbitrary diagnostics, `File`, bytes, base64 or local `blob:` preview URLs. Use `dataProfileDigest`, `runtimeStateDigest`, `schemaFields` and `PraxisAssistantAttachmentSummary` instead. `@praxisui/ai` can declare handoff actions such as `shared-rule-handoff`, `governed-publication-handoff`, `materialization-handoff` and `enforcement-validation-handoff`, but the executable semantics of approving, publishing, materializing or enforcing domain rules belong to Praxis Config/domain-rules contracts.
 
 The shell intentionally does not own component semantics. Specialized flows still own their adapter/service contract:
 - configuration assistants continue to use `AiConfigAdapter`, capabilities, suggestions and patch review
@@ -87,13 +110,24 @@ The shell intentionally does not own component semantics. Specialized flows stil
 
 This keeps a single assistant identity across Praxis components while preserving the canonical owner of each config or authoring document.
 
+### Component Authoring Context
+
+Configurable components that support AI authoring should expose a safe `authoringContract` through `AiConfigAdapter.getAuthoringContext()`. The contract lives at component level, not per capability, and can declare the response modes the component supports:
+
+- `consult/answer` for questions about the current component, such as active resource path, endpoint, schema fields, styling capabilities or how-to guidance.
+- `edit/componentEditPlan` for governed changes that must be compiled and reviewed before they become a patch.
+
+When a component exposes factual grounding for consultative answers, include a `consultativeContext` with the minimal safe facts, such as `resourcePath` and `answerableQuestionKinds`. The frontend must not classify intent through local keywords; it sends this context to the backend/LLM orchestrator, which decides whether the turn is `consult/answer` or `edit/componentEditPlan`. Do not duplicate this declaration on every operation. Individual operations should still describe their own target, effects, validators and materialization through the component manifest or edit-plan contract.
+
+Use `createComponentAuthoringContext(...)` from `@praxisui/ai` when returning the adapter context. The helper normalizes the contract into a JSON-safe object, drops `undefined` fields and rejects non-JSON values before they leak into `contextHints`.
+
 The shell ships with centralized PT-BR default labels and accepts the `labels` input for a flow-specific override. The override is partial: omitted labels continue to come from the shared defaults.
 
 By default, the prompt composer submits with `Enter` and keeps `Shift+Enter` for multiline prompts. Hosts with custom composer behavior can set `submitOnEnter` to `false`.
 
 When a user pastes an image into the prompt composer, the shell emits `attachmentsPasted` with `PraxisAssistantShellAttachment` items containing the original `File`, image metadata, `source: 'paste'` and a local preview URL.
 
-Hosts can also enable button-based file selection with `enableFileAttachments`, `attachmentAccept` and `attachmentMultiple`. In that mode, the attach button opens the native file picker and emits `attachmentsSelected` with `source: 'file-picker'`. When file selection is disabled, the legacy `attach` event remains available for host-defined context actions. The shell does not upload or persist files; the host owns storage, redaction and backend forwarding.
+Hosts can also enable button-based file selection with `enableFileAttachments`, `attachmentAccept` and `attachmentMultiple`. In that mode, the attach button opens the native file picker and emits `attachmentsSelected` with `source: 'file-picker'`. When file selection is disabled, the legacy `attach` event remains available for host-defined context actions. Hosts that do not support attachment semantics should set `showAttachAction=false`; hosts that do not support pasted image context should set `enablePastedAttachments=false`. The shell does not upload or persist files; the host owns storage, redaction and backend forwarding.
 
 Flows that forward attachments to backend authoring endpoints should send only serializable attachment summaries, such as `id`, `name`, `kind`, `mimeType`, `sizeBytes`, `source` and `hasPreview`. Do not send `File`, bytes, base64 payloads or local `blob:` URLs to the assistant contract. When a backend clarification needs to keep attachment context for the next turn, the flow can return those summaries inside `pendingClarification.diagnostics.attachmentSummaries`; the turn orchestrator preserves that pending clarification state and sends it back with the next `clarify` action.
 
@@ -106,7 +140,7 @@ The orchestrator owns the turn lifecycle:
 - stable `sessionId` creation per controller when the host does not provide one
 - fresh `clientTurnId` creation for each executable submit/apply/retry/cancel turn
 - LLM-assisted clarification as a first-class `clarification` state
-- structured clarification questions and quick replies
+- structured clarification questions and quick replies, including rich chip metadata from backend flows
 - edit/resend actions for user messages, including conversation fork semantics
 - attached context add/remove state
 - apply/retry/cancel dispatch when the active flow supports it
@@ -118,6 +152,8 @@ When a flow asks for clarification, direct user input while the controller is in
 
 `pendingClarification.diagnostics` is opaque flow state. It is preserved across the next clarification answer so backend-owned semantics can keep metadata-only context, including attachment summaries, without the shell understanding the domain or retaining local file payloads.
 
+Backend-owned flows may return quick replies as clickable chips for candidate resources, catalog follow-ups or clarification options. Hosts should keep the full quick reply object: `description`, `icon` and `tone` are presentation hints, while `contextHints` carries structured values such as `resourcePath`, `submitUrl`, `operation` and `schemaUrl` for the next turn. Do not downcast these replies to label/prompt pairs or recompute the options in the UI.
+
 When a user edits or resends an earlier user message, the controller forks the conversation from that message before invoking the flow again. Downstream assistant/user messages, quick replies, pending clarification and preview state are cleared so the backend receives the revised conversation branch instead of stale follow-up context. Hosts that expose an edit composer should call `submitEditedMessage(messageId, text)` when the revised prompt is submitted.
 
 ## What this package does not own
@@ -144,9 +180,18 @@ Hosts configure tenant/env/user headers and global AI config through the `@praxi
 
 - `AI_BACKEND_STORAGE_OPTIONS`: provides `headersFactory`, optional `defaultHeaders`, and the explicit `allowLocalIdentityFallback` demo mode.
 - `AI_BACKEND_CONFIG_STORE`: provides `getAiConfigSnapshot`, `aiConfigChanges$`, and `saveAiConfig` for provider/model/global AI settings.
+- `AI_BACKEND_ENDPOINTS`: optional explicit endpoint override for hosts that serve AI orchestration from a gateway different from the canonical application API.
 
 The library does not consume `@praxisui/core` storage tokens as a hidden fallback. Host applications should wire the AI tokens directly when integrating with `/api/praxis/config/ai/**`.
 
+Endpoint resolution follows the same platform boundary used by the rest of the metadata-driven runtime:
+
+1. `AI_BACKEND_ENDPOINTS.aiBaseUrl` and `AI_BACKEND_ENDPOINTS.aiContextBaseUrl`, when the host explicitly routes AI through a distinct gateway.
+2. `API_URL.default.baseUrl` from `@praxisui/core`, deriving `/praxis/config/ai/**` and `/praxis/config/ai-context/**` below that API root.
+3. Relative fallbacks `/api/praxis/config/ai` and `/api/praxis/config/ai-context` for proxied local hosts and existing integrations.
+
+Static hosts such as the Praxis landing page should normally configure `API_URL.default.baseUrl` to the Quickstart or production API origin and let `@praxisui/ai` derive the AI endpoints. This keeps the AI assistant aligned with the same backend origin used by metadata, config and dynamic examples.
+
 ### Provider catalog and validation
 - `GET /api/praxis/config/ai/providers/catalog`
 - `POST /api/praxis/config/ai/providers/models`
@@ -192,6 +237,30 @@ Payload:
 Notes:
 - `currentState` must be the config root (not wrapped under `config`).
 - Clarifications may return `{ type: "clarification", message, options }`.
+- Responses may include `observationId`. `PraxisAiAssistantShellComponent` uses it to send write-only quality feedback to the backend triage endpoint without exposing prompt listings in public clients.
+
+### Assistant observation feedback
+- `POST /api/praxis/config/ai/triage/observations/{observationId}/feedback`
+
+`AiBackendApiService.sendAssistantObservationFeedback` posts `rating`, `reasonCode` and optional `comment` to the governed triage endpoint. The shell renders positive/negative feedback controls only when an assistant message has an `observationId`; listing observations remains an administrative backend capability, not a public UI concern.
+
+### Agentic authoring manifest tools
+- `GET /api/praxis/config/ai/authoring/manifests/{componentId}`
+- `GET /api/praxis/config/ai/authoring/manifests/{componentId}/editable-targets`
+- `GET /api/praxis/config/ai/authoring/manifests/{componentId}/operations`
+- `POST /api/praxis/config/ai/authoring/manifests/{componentId}/resolve-target`
+- `POST /api/praxis/config/ai/authoring/manifests/{componentId}/validate-plan`
+- `POST /api/praxis/config/ai/authoring/manifests/{componentId}/compile-patch`
+
+`AiBackendApiService` exposes these endpoints through typed methods so hosts can inspect the executable manifest, resolve targets, validate a component edit plan and compile a backend-owned patch without routing by local keywords.
+
+### Agentic authoring turn streaming
+- `POST /api/praxis/config/ai/authoring/turn/stream/start`
+- `GET /api/praxis/config/ai/authoring/turn/stream/{streamId}`
+- `GET /api/praxis/config/ai/authoring/turn/stream/{streamId}/probe`
+- `POST /api/praxis/config/ai/authoring/turn/stream/{streamId}/cancel`
+
+`AiBackendApiService.startAgenticAuthoringTurnStream`, `connectAgenticAuthoringTurnStream` and `cancelAgenticAuthoringTurnStream` use the same SSE envelope contract as patch streaming. Browser `EventSource` cannot send custom headers, so signed stream tokens returned by the backend should be passed to `connectAgenticAuthoringTurnStream` and `cancelAgenticAuthoringTurnStream` when the backend uses signed-url stream auth.
 
 ## Assistant local history (UI)