Praxis AI Assistant Runtime
Use this skill for @praxisui/ai as shell, UX, HTTP client, history, and materializer of governed backend/LLM decisions. Do not turn browser UI into the primary intent router.
For deeper work, pair this umbrella skill with:
praxis-ai-shell-session-contextfor shell, dock, session host, session registry, and safe context snapshots.praxis-ai-composer-attachments-quick-repliesfor composer actions, quick replies, clarifications, attachments, message replay, and voice input.praxis-ai-turn-orchestration-transportfor turn controllers, lifecycle phases, runtime observations, stream events, and terminal result handling.praxis-ai-backend-config-contractsfor endpoint resolution, AI config tokens, headers, provider/model endpoints, manifest endpoints, and Praxis Config boundary.
Canonical Boundary
@praxisui/aisends prompt, messages, context, runtime state, capabilities, manifests, observations, and metadata to backend/LLM contracts.- Praxis Config backend endpoints under
/api/praxis/config/ai/**own provider calls, model execution, streams, and persisted AI config. - Frontend logic may manage interaction state, accessibility, history, replay, confirmations, quick replies, clarifications, diagnostics, preview rendering, and apply of already resolved operations.
- Runtime component observations are untrusted frontend evidence and must be marked with the trust boundary before backend grounding.
PraxisAssistantContextSnapshotcarries safe summaries and digests; shell/session code should not invent component semantics or transport raw runtime payloads.
Required Inventory
Inspect:
projects/praxis-ai/AGENTS.mdsrc/public-api.tssrc/lib/core/services/ai-backend-api.service.tssrc/lib/core/services/agentic-authoring-turn-client.service.tssrc/lib/core/services/assistant-turn-orchestrator.service.tssrc/lib/core/services/assistant-history.service.tssrc/lib/core/models/assistant-context.models.tssrc/lib/core/models/assistant-turn.models.tssrc/lib/ui/assistant-shell/**src/lib/ui/ai-assistant/**src/lib/ui/assistant-session-host/**src/lib/ui/assistant-dock/**- relevant specs for backend API, assistant shell, session host, history, validator, and turn client
Runtime Rules
- Do not call external providers directly from the Angular lib when the canonical Praxis Config backend contract exists.
- Preserve
currentState,dataProfile,schemaFields,runtimeState,contextHints,runtimeComponentObservations, pending clarification, preview, diagnostics, and apply payload shapes. - Stream/lifecycle events must update visible assistant state before terminal result when the backend emits intermediate reasoning, status, clarification, diagnostics, or quick replies.
- Manual confirmation is required for risky or destructive patches when the contract marks them as such.
- History persistence must respect tenant, env, userId, redaction, and local storage boundaries.
AssistantHistoryServiceis the canonical local-history owner. It keys the index bytenantId/env/userId, rejects cross-scope restore/delete/touch, honors storage unavailability, prunes old sessions, caps session count, and redacts API keys, tokens, bearer credentials, JWTs,sk-*secrets, passwords, and similar values before writing. Do not persist assistant history through ad hoc component localStorage keys.- Public exports in
@praxisui/aimust not become a transitive facade for@praxisui/core. - Treat the local runtime as a state machine: a clarification cannot expose apply, a review cannot apply without a pending governed patch, and retry/edit/resend/cancel must clear abandoned preview, diagnostics, quick replies, and clarification state before a new branch materializes.
PraxisAssistantTurnOrchestratorServiceprotects async materialization withclientTurnIdand clears replay/active-turn state. Preserve stale-result rejection and reset behavior when changing submit, edit, resend, retry, cancel, or apply.- Persist history only through
AssistantHistoryServiceunder the tenant/env/user scope. Respect storage unavailability, 30-day/session-count retention, redaction on write and legacy read, and never reuse a session across scopes. - Local confirmation may enforce stricter UI policy, but cannot downgrade backend risk or make a patch applicable. Manual patch editing/reapply in the legacy assistant remains an explicitly confirmed, auditable compatibility flow gated by
allowManualPatchEdit; do not present it as the canonical route for governed decisions or manifest-backed edits. - Intermediate SSE status/thought/diagnostic events are progress evidence. Terminal result/error/cancelled transitions determine final materialized state; raw errors and diagnostics remain redacted and are never promoted to business semantics.
heartbeat, replay diagnostics, watchdog progress, and lifecycle checkpoints may update visible status or structured diagnostics, but they must not create assistant messages, history facts, quick replies, apply buttons, pending patches, or semantic decisions by themselves.- Treat duplicate progress as a UX/status concern. Preserve diagnostic evidence such as
streamEventDiagnostics, but do not count duplicate phases,technicalDuplicate,replaySafe, orduplicatesDoNotIndicateExecutionevents as extra work, extra tool calls, or additional governed decisions. - Legacy snapshot fallback (
/patchafter a stream transport/schema failure) is compatibility materialization, not a second canonical decision route. It may show a clear snapshot/fallback badge and detail, but must not run after authorization/probe expiry failures, must not bypass stream auth/tenant scope, and must not make progress events or stale stream state applicable. - The shell may render quick-reply labels, descriptions, badges, and details, but only structured quick-reply payloads (
value,canonicalAction,semanticDecision,contextHints, diagnostics) may continue a turn. Never parse rendered labels, status text, or diagnostic text back into intent.
Validation
Use focused checks:
- backend payload/endpoints:
ai-backend-api.service.spec.ts - streaming/turns:
agentic-authoring-turn-client.service.spec.tsand orchestrator specs - history scope/redaction:
assistant-history.service.spec.ts - assistant UX:
assistant-shell.component.spec.ts,ai-assistant.component.spec.ts, session host/dock specs - contracts: generated contract specs and response validator specs
- public API changes: build
praxis-aiand at least one direct consumer when feasible
Review README and docs/ai-deployment-flow.md when endpoints, deployment, provider routing, or public behavior change.
For a runtime-wide change, map the affected specialist surfaces first and run their focused gate rather than relying on an umbrella build: context/session, composer, turn/transport, backend contract, history, and legacy assistant UI. State why each unaffected surface is outside the change.