Praxis AI Shell Session Context
Use this skill for the canonical Angular assistant context and session surfaces. The shell is a cockpit that displays and carries governed evidence; it does not become a store for raw business state, a semantic-intent router, or a source of apply permission.
Canonical Boundary
| Owner |
Responsibility |
| component lib or host |
produces domain-safe context, manifests, metadata/capability references, and a snapshot candidate |
assistant-context.models.ts |
validates, redacts, bounds, and normalizes PraxisAssistantContextSnapshot |
AiContextBuilderService |
builds focused/minified rule-prompt context for the existing rule assistant flow; it is not the canonical session envelope |
PraxisAssistantSessionRegistryService |
in-memory canonical session registry, identity consistency, visibility, presence, ordering, and session lookup |
| assistant shell, dock, and session host |
accessible presentation and interaction over normalized state; no backend policy or primary intent routing |
praxis-config-starter |
provider execution, semantic intent, authorization, persisted AI configuration, tool evidence, and apply policy |
Read projects/praxis-ai/AGENTS.md, workspace governance, codex-rules.md, src/public-api.ts, README.md, and the focused context/session/shell specs before editing. Read the producer's local AGENTS, manifest, adapter, README, and focused specs when the change starts outside @praxisui/ai.
Snapshot Is The Only Context Envelope
Create or accept context through normalizePraxisAssistantContextSnapshot; do not define a parallel host-specific context type or store arbitrary objects in a session descriptor.
The required identity is the stable tuple sessionId, ownerId, and ownerType. A target, component/route identity, tenant/environment/user scope, mode, manifest reference, resource path, schema fields, safe digests, capabilities, governance/risk hints, attachment summaries, and declared actions are optional evidence.
- A session descriptor that carries a snapshot must match all three identity values exactly. Reject mismatches instead of silently merging owners or sessions.
- Context text is sanitized, redacted, whitespace-normalized, and bounded. The current public budgets are text
160, context items 12, schema fields 40, and attachments 8; capability/action lists and governance hints are also capped internally. Preserve those limits; do not bypass them for a convenient label, diagnostic, or preview.
- The normalizer bounds context items, schema fields, attachments, capabilities, hints, actions, digest fields, and text length. Expand a limit only with a measured privacy/performance reason and a focused spec.
- Target metadata accepts scalar values only and excludes raw
file, blob, bytes, base64, previewUrl, currentState, runtimeState, form values, rows, pending patch, diagnostics, payload, and config keys. Keep the blacklist protective rather than copying raw data to a differently named field.
- Attachments in the snapshot are serializable summaries only: identity/name, kind, MIME type, size, source, and preview availability.
File, bytes, base64, blob URLs, and rich payloads stay on the composer/upload path.
- Shell attachments may carry live
File handles and local previewUrl values only while the composer/shell owns that interaction. Convert them to bounded attachmentSummaries before session/context registry use, and never persist, replay, reopen, or send blob URLs as grounding evidence.
- Digests are summaries, hashes, sources, fields, and counts. A digest is evidence, not a serialized runtime object.
- Turn runtime state is not snapshot context. Do not copy heartbeat, replay diagnostics, watchdog progress,
stream lifecycle checkpoints, assistant messages, quick replies, pending clarification, preview, pending patch,
canApply, or turn diagnostics into PraxisAssistantContextSnapshot or session descriptors as restorable facts.
Carry only bounded, redacted evidence that helps the next turn ground the UI safely.
- Treat
AiContextBuilderService as a specialized rule-prompt builder over minified schemas and allowed JSON Logic operators. Do not route new shell/session integrations through that service when the requirement is to carry cockpit/session context, governance hints, actions, attachments, or runtime evidence. Promote reusable assistant evidence through PraxisAssistantContextSnapshot instead.
Before adding a snapshot field, inventory existing metadata schemas, x-ui, actions, surfaces, capabilities, option sources, manifests, runtime observations, diagnostics, and context hints. Classify the need as ja-suportado-so-ux, ja-suportado-mal-nomeado-ou-mal-materializado, suportado-parcialmente, or lacuna-real-de-contrato. Only a real missing canonical evidence path warrants a new public field.
Session Registry And Presence
Use PraxisAssistantSessionRegistryService rather than host-local arrays, service clones, or dock-only state.
upsertContextSession normalizes the snapshot, derives identity and default title/mode, and stores the normalized result.
openContextSession, minimizeContextSession, removeContextSession, and getContextSession resolve through the canonical session identity. Preserve those helpers for snapshot-driven flows instead of duplicating owner-local session lookup code.
- The registry has at most one active session. Opening or upserting one as active minimizes every other session, then sorts sessions by
updatedAt.
- Visibility is
active or minimized; presence is global-dock or origin-anchor. Presence describes where an affordance belongs, not who owns semantic authority.
- The session host renders minimized sessions by default and omits origin-anchored ones unless explicitly asked. Filter by owner only for presentation; never use a dock filter as an authorization boundary.
- Open, minimize, remove, and lookup context sessions by the canonical session identity. Do not derive a new ID from a title, target label, route string, or prompt text.
- The registry is an Angular in-memory interaction registry. Do not add local persistence, cross-user reuse, or server synchronization as a convenience. A persistence requirement belongs to the canonical backend/config owner and must preserve tenant, user, environment, retention, redaction, and authorization semantics.
- Registry summaries, badges, icons, visibility, and dock ordering are presentation projections. They must not preserve
transient stream evidence or recreate a turn after reload; reopened sessions should start from normalized context,
not from the previous turn's heartbeat/progress/diagnostics trail.
Shell And Dock Materialization
- The shell renders messages, structured assistant content, context items, attachments, quick replies, status, and declared actions. It may choose accessible presentation, icon, tone, layout, and recovery affordances; it must not reinterpret displayed text into a decision.
- Dock tone is derived from shell state (
processing/applying, review, clarification, error, ready). Keep this projection separate from risk/governance authority.
- Use shell defaults and the shared i18n path for framework chrome. Do not expose raw errors, provider diagnostics, sensitive summaries, or untranslated ad hoc text. Use
praxis-angular-i18n-governance when changing internal labels.
- Preserve explicit semantic action/quick-reply presentation and the structured payload. Do not parse labels, summaries, chips, resource paths, or context hints with keywords/regex to infer intent, resources, actions, or permissions.
- Structured
assistantContent.blocks paragraph items may carry typed inlines ({ type: 'text', text } and { type: 'record-reference', label, quickView, identityContext }). assistant-shell and sanitizeAssistantContent (AssistantHistoryService) validate quickView via normalizeResourceQuickViewBinding, restrict identityContext to the primitive { [quickView.recordOpen.sourceIdentityField]: value } pair, degrade malformed/unverified references to plain text, redact secrets before history persistence, and render terminal assistant record references (status !== 'pending' && status !== 'error') with [praxisQuickView] (PraxisQuickViewTriggerDirective). Never reinterpret resource-list.id as a concrete record reference.
- Runtime observations crossing toward backend grounding remain untrusted frontend evidence; use
praxis-core-widget-observations and praxis-ai-turn-orchestration-transport for their contract and lifecycle.
Impact Map And Derived Artifacts
For transversal, arquitetural, or contrato-publico work, map the snapshot owner, session/shell consumers, backend/config effects, public exports, manifests/registry, docs/recipes/playgrounds, data sensitivity, and breaking risk before editing.
- Snapshot/model or public export change: review
src/public-api.ts, README.md, direct consumers, docs, generated AI artifacts, and backend contract implications with praxis-angular-public-api-governance.
- Producer/manifest change: use
praxis-ai-authoring-manifests and praxis-ai-registry-ingestion; a manifest/registry should refer to canonical evidence rather than copy it into UI state.
- Turn, quick-reply, clarification, or backend context change: use
praxis-ai-turn-orchestration-transport, praxis-ai-composer-attachments-quick-replies, and the config streaming skill.
- UI-only layout or accessibility change: retain the same snapshot and registry ownership; validate the actual shell/dock/host surface and state explicitly why public docs or registry output is unchanged.
Validation
Run the smallest command covering the changed behavior. This focused suite proves normalizing/redacting context, registry identity/visibility, dock projection, session-host filtering, and shell materialization:
npm exec -- ng test praxis-ai --watch=false --progress=false \
--include='projects/praxis-ai/src/lib/core/models/assistant-context.models.spec.ts' \
--include='projects/praxis-ai/src/lib/core/services/assistant-session-registry.service.spec.ts' \
--include='projects/praxis-ai/src/lib/ui/assistant-dock/assistant-dock.component.spec.ts' \
--include='projects/praxis-ai/src/lib/ui/assistant-session-host/assistant-session-host.component.spec.ts' \
--include='projects/praxis-ai/src/lib/ui/assistant-shell/assistant-shell.component.spec.ts'
Exercise normal context session creation; sensitive/raw input redaction; missing or mismatched identity; active-to-minimized transition; origin-anchor filtering; structured action/quick-reply rendering; public export/README alignment for consumed shell/session/context APIs; and a hostile label or context hint that must not create authority. Public API changes also require an AI library build, a direct consumer, and the local-AGENTS E2E evidence. State when docs, examples, manifests, or registry artifacts are unaffected.
Companion Skills
praxis-ai-semantic-intent for the semantic-routing boundary.
praxis-core-runtime-contracts and praxis-core-widget-observations for shared context/observation contracts.
praxis-ai-composer-attachments-quick-replies for live attachments and structured continuations.
praxis-ai-turn-orchestration-transport for a snapshot carried into a backend turn.
praxis-ai-backend-config-contracts and praxis-config-agentic-authoring-streaming for backend/config semantics.
praxis-angular-i18n-governance, praxis-angular-public-api-governance, and praxis-angular-validation-gates for cross-cutting work.
1---2name: praxis-ai-shell-session-context3description: Use when implementing, auditing, or consuming the `@praxisui/ai` assistant shell, dock, session host or registry, `PraxisAssistantContextSnapshot`, context normalization/redaction, safe summaries, session identity and visibility, governance/risk hints, attachments summaries, or public shell/context exports.4metadata:5 source: https://skillmd.com/skills/codexrodrigues/praxis-ai-shell-session-context6---78# Praxis AI Shell Session Context910Use this skill for the canonical Angular assistant context and session surfaces. The shell is a cockpit that displays and carries governed evidence; it does not become a store for raw business state, a semantic-intent router, or a source of apply permission.1112## Canonical Boundary1314| Owner | Responsibility |15| --- | --- |16| component lib or host | produces domain-safe context, manifests, metadata/capability references, and a snapshot candidate |17| `assistant-context.models.ts` | validates, redacts, bounds, and normalizes `PraxisAssistantContextSnapshot` |18| `AiContextBuilderService` | builds focused/minified rule-prompt context for the existing rule assistant flow; it is not the canonical session envelope |19| `PraxisAssistantSessionRegistryService` | in-memory canonical session registry, identity consistency, visibility, presence, ordering, and session lookup |20| assistant shell, dock, and session host | accessible presentation and interaction over normalized state; no backend policy or primary intent routing |21| `praxis-config-starter` | provider execution, semantic intent, authorization, persisted AI configuration, tool evidence, and apply policy |2223Read `projects/praxis-ai/AGENTS.md`, workspace governance, `codex-rules.md`, `src/public-api.ts`, `README.md`, and the focused context/session/shell specs before editing. Read the producer's local AGENTS, manifest, adapter, README, and focused specs when the change starts outside `@praxisui/ai`.2425## Snapshot Is The Only Context Envelope2627Create or accept context through `normalizePraxisAssistantContextSnapshot`; do not define a parallel host-specific context type or store arbitrary objects in a session descriptor.2829The required identity is the stable tuple `sessionId`, `ownerId`, and `ownerType`. A target, component/route identity, tenant/environment/user scope, mode, manifest reference, resource path, schema fields, safe digests, capabilities, governance/risk hints, attachment summaries, and declared actions are optional evidence.3031- A session descriptor that carries a snapshot must match all three identity values exactly. Reject mismatches instead of silently merging owners or sessions.32- Context text is sanitized, redacted, whitespace-normalized, and bounded. The current public budgets are text `160`, context items `12`, schema fields `40`, and attachments `8`; capability/action lists and governance hints are also capped internally. Preserve those limits; do not bypass them for a convenient label, diagnostic, or preview.33- The normalizer bounds context items, schema fields, attachments, capabilities, hints, actions, digest fields, and text length. Expand a limit only with a measured privacy/performance reason and a focused spec.34- Target metadata accepts scalar values only and excludes raw `file`, `blob`, `bytes`, `base64`, `previewUrl`, `currentState`, `runtimeState`, form values, rows, pending patch, diagnostics, payload, and config keys. Keep the blacklist protective rather than copying raw data to a differently named field.35- Attachments in the snapshot are serializable summaries only: identity/name, kind, MIME type, size, source, and preview availability. `File`, bytes, base64, blob URLs, and rich payloads stay on the composer/upload path.36- Shell attachments may carry live `File` handles and local `previewUrl` values only while the composer/shell owns that interaction. Convert them to bounded `attachmentSummaries` before session/context registry use, and never persist, replay, reopen, or send blob URLs as grounding evidence.37- Digests are summaries, hashes, sources, fields, and counts. A digest is evidence, not a serialized runtime object.38- Turn runtime state is not snapshot context. Do not copy heartbeat, replay diagnostics, watchdog progress,39 stream lifecycle checkpoints, assistant messages, quick replies, pending clarification, preview, pending patch,40 `canApply`, or turn diagnostics into `PraxisAssistantContextSnapshot` or session descriptors as restorable facts.41 Carry only bounded, redacted evidence that helps the next turn ground the UI safely.42- Treat `AiContextBuilderService` as a specialized rule-prompt builder over minified schemas and allowed JSON Logic operators. Do not route new shell/session integrations through that service when the requirement is to carry cockpit/session context, governance hints, actions, attachments, or runtime evidence. Promote reusable assistant evidence through `PraxisAssistantContextSnapshot` instead.4344Before adding a snapshot field, inventory existing metadata schemas, `x-ui`, actions, surfaces, capabilities, option sources, manifests, runtime observations, diagnostics, and context hints. Classify the need as `ja-suportado-so-ux`, `ja-suportado-mal-nomeado-ou-mal-materializado`, `suportado-parcialmente`, or `lacuna-real-de-contrato`. Only a real missing canonical evidence path warrants a new public field.4546## Session Registry And Presence4748Use `PraxisAssistantSessionRegistryService` rather than host-local arrays, service clones, or dock-only state.4950- `upsertContextSession` normalizes the snapshot, derives identity and default title/mode, and stores the normalized result.51- `openContextSession`, `minimizeContextSession`, `removeContextSession`, and `getContextSession` resolve through the canonical session identity. Preserve those helpers for snapshot-driven flows instead of duplicating owner-local session lookup code.52- The registry has at most one active session. Opening or upserting one as active minimizes every other session, then sorts sessions by `updatedAt`.53- Visibility is `active` or `minimized`; presence is `global-dock` or `origin-anchor`. Presence describes where an affordance belongs, not who owns semantic authority.54- The session host renders minimized sessions by default and omits origin-anchored ones unless explicitly asked. Filter by owner only for presentation; never use a dock filter as an authorization boundary.55- Open, minimize, remove, and lookup context sessions by the canonical session identity. Do not derive a new ID from a title, target label, route string, or prompt text.56- The registry is an Angular in-memory interaction registry. Do not add local persistence, cross-user reuse, or server synchronization as a convenience. A persistence requirement belongs to the canonical backend/config owner and must preserve tenant, user, environment, retention, redaction, and authorization semantics.57- Registry summaries, badges, icons, visibility, and dock ordering are presentation projections. They must not preserve58 transient stream evidence or recreate a turn after reload; reopened sessions should start from normalized context,59 not from the previous turn's heartbeat/progress/diagnostics trail.6061## Shell And Dock Materialization6263- The shell renders messages, structured assistant content, context items, attachments, quick replies, status, and declared actions. It may choose accessible presentation, icon, tone, layout, and recovery affordances; it must not reinterpret displayed text into a decision.64- Dock tone is derived from shell state (`processing`/`applying`, `review`, `clarification`, error, ready). Keep this projection separate from risk/governance authority.65- Use shell defaults and the shared i18n path for framework chrome. Do not expose raw errors, provider diagnostics, sensitive summaries, or untranslated ad hoc text. Use `praxis-angular-i18n-governance` when changing internal labels.66- Preserve explicit semantic action/quick-reply presentation and the structured payload. Do not parse labels, summaries, chips, resource paths, or context hints with keywords/regex to infer intent, resources, actions, or permissions.67- Structured `assistantContent.blocks` `paragraph` items may carry typed `inlines` (`{ type: 'text', text }` and `{ type: 'record-reference', label, quickView, identityContext }`). `assistant-shell` and `sanitizeAssistantContent` (`AssistantHistoryService`) validate `quickView` via `normalizeResourceQuickViewBinding`, restrict `identityContext` to the primitive `{ [quickView.recordOpen.sourceIdentityField]: value }` pair, degrade malformed/unverified references to plain text, redact secrets before history persistence, and render terminal assistant record references (`status !== 'pending' && status !== 'error'`) with `[praxisQuickView]` (`PraxisQuickViewTriggerDirective`). Never reinterpret `resource-list.id` as a concrete record reference.68- Runtime observations crossing toward backend grounding remain untrusted frontend evidence; use `praxis-core-widget-observations` and `praxis-ai-turn-orchestration-transport` for their contract and lifecycle.6970## Impact Map And Derived Artifacts7172For `transversal`, `arquitetural`, or `contrato-publico` work, map the snapshot owner, session/shell consumers, backend/config effects, public exports, manifests/registry, docs/recipes/playgrounds, data sensitivity, and breaking risk before editing.7374- Snapshot/model or public export change: review `src/public-api.ts`, `README.md`, direct consumers, docs, generated AI artifacts, and backend contract implications with `praxis-angular-public-api-governance`.75- Producer/manifest change: use `praxis-ai-authoring-manifests` and `praxis-ai-registry-ingestion`; a manifest/registry should refer to canonical evidence rather than copy it into UI state.76- Turn, quick-reply, clarification, or backend context change: use `praxis-ai-turn-orchestration-transport`, `praxis-ai-composer-attachments-quick-replies`, and the config streaming skill.77- UI-only layout or accessibility change: retain the same snapshot and registry ownership; validate the actual shell/dock/host surface and state explicitly why public docs or registry output is unchanged.7879## Validation8081Run the smallest command covering the changed behavior. This focused suite proves normalizing/redacting context, registry identity/visibility, dock projection, session-host filtering, and shell materialization:8283```sh84npm exec -- ng test praxis-ai --watch=false --progress=false \85 --include='projects/praxis-ai/src/lib/core/models/assistant-context.models.spec.ts' \86 --include='projects/praxis-ai/src/lib/core/services/assistant-session-registry.service.spec.ts' \87 --include='projects/praxis-ai/src/lib/ui/assistant-dock/assistant-dock.component.spec.ts' \88 --include='projects/praxis-ai/src/lib/ui/assistant-session-host/assistant-session-host.component.spec.ts' \89 --include='projects/praxis-ai/src/lib/ui/assistant-shell/assistant-shell.component.spec.ts'90```9192Exercise normal context session creation; sensitive/raw input redaction; missing or mismatched identity; active-to-minimized transition; origin-anchor filtering; structured action/quick-reply rendering; public export/README alignment for consumed shell/session/context APIs; and a hostile label or context hint that must not create authority. Public API changes also require an AI library build, a direct consumer, and the local-AGENTS E2E evidence. State when docs, examples, manifests, or registry artifacts are unaffected.9394## Companion Skills9596- `praxis-ai-semantic-intent` for the semantic-routing boundary.97- `praxis-core-runtime-contracts` and `praxis-core-widget-observations` for shared context/observation contracts.98- `praxis-ai-composer-attachments-quick-replies` for live attachments and structured continuations.99- `praxis-ai-turn-orchestration-transport` for a snapshot carried into a backend turn.100- `praxis-ai-backend-config-contracts` and `praxis-config-agentic-authoring-streaming` for backend/config semantics.101- `praxis-angular-i18n-governance`, `praxis-angular-public-api-governance`, and `praxis-angular-validation-gates` for cross-cutting work.