Contextual AI Assistant Architecture

Version scope

tSM 2.4 provides the top-bar AI chat and SpEL editor integration. This page describes the unreleased extension for Form, TQL, and BPMN authoring and for business screens configured through Assistant Profiles.

Decision Summary

tSM uses one universal AI shell across configuration and business screens. For a new conversation, the backend matches an Assistant Profile by the screen's exact surfaceRef. That profile selects one reusable Agent Profile, maps the current UI context to its typed input, chooses available context providers and actions, and supplies the scenario goal and starter questions.

Agent and Assistant Profiles are normal audited tSM entities. They have a UUID, standard change-counter version, validity interval, derived valid value, and JaVers history. They do not have draft, publish, retire, release-assignment, evaluation, or test-console states. The latest currently valid versions are used for a new conversation and their exact id + JaVers commitId values are then pinned. Existing conversations do not change behavior after a profile edit, although live authorization and kill switches are always rechecked. Editing follows the same last-write-wins behavior as other tSM API v2 code-table screens.

The browser sends only a small typed Context Envelope. Server-side providers load authorized facts and evidence. The assistant returns typed content, artifacts, and action proposals; all visual components remain hard-wired in TSM-UI.

The deployable backend, Agent Runtime, profile administration, and process communication are described in tSM AI and Agent Runtime.

Design Principles

• The same AI shell adapts to the current screen without trusting browser-supplied authorization.
• Profiles compose only certified components; they cannot embed server code, credentials, arbitrary endpoints, or Angular components.
• The browser supplies stable identifiers and UI state. Authoritative business data is loaded and authorized server-side.
• An Assistant may narrow its Agent Profile but cannot grant a provider, Tool, capability, limit, or privilege.
• Missing required context blocks inference; missing optional selected context remains visible as partial context.
• Results and proposals are typed. Deterministic APIs, Scripts, or processes own side effects.
• Long work is represented by durable process or Action state, not an unbounded synchronous call.

Existing Foundation

The top-bar chat already provides streamed responses, conversation threads, attachments, feedback, and contextual SpEL assistance. Form, TQL, and BPMN authoring use the same shell and server-side conversation contract while keeping their domain-specific validation and review behavior.

SpEL, Form, TQL, and BPMN become built-in Assistant/Agent Profile bindings rather than separate profile models. Existing editor endpoints remain compatible. Their certified Tools, grounding, artifact contracts, and deterministic finish gates preserve specialized behavior.

TSM-UI and tsm-ai share a versioned Surface Descriptor catalog. Each client integration sends one exact opaque surfaceRef plus only the entity, document, selection, locale, and closed surfaceData fields allowed by that descriptor. surfaceData carries the current editor content for that request and is never persisted. A route or Angular component may change without changing the reference when its semantic context contract is unchanged.

Profile Model

Agent Profile

An Agent Profile defines reusable instructions, model policy, typed input/result/artifact contracts, Context Providers, Tool allow-list, limits, and fixed response behavior. It also declares a non-empty set of supported invocations: ASSISTANT, AGENT_TASK, or AGENTIC_SUBPROCESS.

It is a maximum capability, not a security identity. The caller, surface, business entity, provider, Tool, and Action are still authorized at their owning boundaries. See Agent Profile for its complete configuration and administration UI.

Assistant Profile

An Assistant Profile contains only scenario-specific UI configuration:

Area	Contract
Standard entity	UUID, change-counter version, code, localized name/description, origin, data tags, validity, audit
Agent	Required Agent Profile UUID; no stored Agent version
Surfaces	One or more unique exact Surface Descriptor references
Priority	Required integer, default 0; higher wins within the same resolver tier
Starter questions	Optional ordered localized list, at most eight
Scenario	Required internal goal and structured input mapping
Context	Explicitly disabled DEFAULT and enabled AVAILABLE providers
Actions	Exact certified Action Definitions allowed for this scenario

It deliberately has no configurable conversation scope, separate presentation title/description, runtime limits, eligibility rules, result renderer, data policy, or evaluation policy:

• the standard localized profile name and description are used in both administration and chat;
• conversation scope comes from the Surface Descriptor;
• runtime ceilings come from Agent Profile and tenant/platform policy;
• authorization and feature flags are central/live controls;
• TSM-UI maps the Agent result/artifact contract to a hard-wired Angular component.

scenario.goal is a required bounded internal instruction appended after Agent Profile instructions. It cannot grant capability. starterQuestions are ordinary localized texts shown only in a new empty conversation. Selecting one sends its text immediately as a normal user message; there is no separate starter-question API or message type.

The Assistant validity interval must be contained within its Agent's interval. An Agent edit is rejected when it would make a current or future Assistant invalid or incompatible. Administrators first update or deactivate dependencies or introduce a compatible additive contract change.

Structured Input Mapping

The Assistant maps fields from the Context Envelope to the Agent input contract as target field -> source field rows. Administrators select both sides; they never type JSONPath. The stored representation uses only this closed source set:

$.surfaceRef
$.entity
$.entity.type
$.entity.id
$.entity.code
$.document
$.document.type
$.document.id
$.document.revision
$.document.contentHash
$.selection
$.locale
$.surfaceData
$.surfaceData.<field allowed by the Surface Descriptor>

Functions, predicates, wildcards, recursive descent, scripts, and custom expressions are invalid. All required Agent input fields must be mapped, types must be compatible, and the produced input is validated again before model work.

Deterministic Resolution and Conversation Scope

For a new conversation, tsm-ai resolves:

1. a valid exact built-in editor binding for surfaceRef;
2. otherwise a valid business Assistant Profile for that exact surfaceRef;
3. otherwise the product-owned read-only documentation fallback;
4. otherwise NOT_CONFIGURED without a model call.

Within one tier, higher priority wins. Code, creation time, database order, and cache order never break a tie. Saving overlapping profiles with the same tier, surface, priority, and validity is rejected. Runtime repeats the guard and returns AMBIGUOUS_ASSISTANT_PROFILE if ambiguity still exists. An editor binding wins over a business profile regardless of numeric priority.

Conversation scope is fixed by the matched Surface Descriptor:

Descriptor scope	Stable contextKey material
SURFACE	exact surfaceRef
ENTITY	canonical authorized entity type and id
DOCUMENT	canonical document type and id
DOCUMENT_OR_SURFACE	document identity when a saved document exists; otherwise exact surfaceRef

GLOBAL is not supported initially. The server creates contextKey; the browser cannot submit it. Display code, locale, selection, document revision/content hash, URL, and priority do not enter the key.

For the same user, tenant, Assistant, and contextKey, the first send reopens the most recently used authorized conversation or creates one atomically. New conversation clears the local selection; its first send always creates another thread for the same context. Changing the context key switches to another authorized conversation or creates one; facts from a new entity/document are never appended silently to the old thread.

A new thread pins exact Assistant and Agent id + JaVers commitId values and an effective-bundle digest. Profile edits affect only new threads. Existing threads restore their exact JaVers snapshots and repeat live authorization. Revocation stops the thread instead of silently selecting another profile.

Context Envelope

The browser creates a small versioned envelope:

{
  "schemaVersion": "1",
  "surfaceRef": "surface/tsm-ui.crm.customer.detail@1",
  "entity": {
    "type": "Customer",
    "id": "018f...",
    "code": "C-100045"
  },
  "selection": [],
  "locale": "en",
  "surfaceData": {}
}

surfaceRef is required and must identify a server-allow-listed Surface Descriptor. The descriptor owns the conversation scope, states whether entity or document data is required, which type is allowed, selection bounds, and the exact versioned surfaceData contract. TQL sends microserviceCode, current query and parameters; SpEL sends microserviceCode, Script identity and current Script; Form sends entity/form type and current schema; BPMN sends process/process-type code and current BPMN XML. Business detail screens send an exact empty surfaceData object.

The server reauthorizes every referenced object under the authenticated identity. Raw URL, Angular component, module, tenant host, roles, privileges, Tool access, credentials, and data classification are not browser-owned fields. Unknown references, descriptor mismatch, missing required context, and unauthorized objects return typed errors before profile resolution or model execution.

Context Providers

A Context Provider accepts validated identifiers and returns typed facts with evidence metadata.

Provider type	Typical use
Public API provider	Stable entity and relationship reads through version-aligned typed clients
SpEL provider	Environment-specific certified synchronous composition
Knowledge provider	tSM documentation or project knowledge with source links
Process snapshot provider	Current process/task facts and stable identifiers

Every provider in the Agent Profile is REQUIRED, DEFAULT, or AVAILABLE. In the Assistant editor:

• REQUIRED is enabled and locked;
• DEFAULT is enabled and may be disabled;
• AVAILABLE is disabled and may be enabled.

The Assistant stores only disabledDefaultProviderRefs and enabledAvailableProviderRefs. It cannot change provider input mapping, timeout, freshness, size, evidence, or failure behavior.

Selected providers execute independently and in parallel under the delegated identity with finite technical limits; their results are ordered by the profile, not completion time. tsm-ai does not cache provider responses between turns. An owning service may cache them, but the provider reports observedAt and the runtime enforces the configured maximum age. A failed, unauthorized, invalid, or stale required provider returns BLOCKED and no model call occurs. A failed selected default/available provider returns PARTIAL with a visible warning and missing-source evidence.

Initial Business Surfaces

The first business release covers both Customer detail and User Group detail. Each uses the generic Context Provider mechanism; adding another entity does not change the chat API or runtime.

• Customer detail works from both UUID and customer/key/:key; the server resolves the key to the canonical Customer UUID so both routes share conversation history. Its safe context includes basic Customer data, primary contact and address, at most 50 accounts, and the newest 50 open requests. Characteristics, arbitrary custom/processing data, contact history, balances, GPS, payment behavior, and complete ticket bodies are excluded.
• User Group detail includes safe group fields and at most 100 authorized member summaries. It excludes credentials/authentication configuration, notifications, characteristics, custom data, and unrelated roles.

Base Customer or User Group access is required before inference. Optional sections have their own existing domain permissions. A missing optional permission omits that section and produces visible PARTIAL context; the browser cannot supply privileges or request a wider DTO.

Conversation and Turn Contract

The canonical browser endpoints are /api/v2/assistant/resolve and /api/v2/assistant/chat; the four existing editor chat routes remain compatibility aliases over the same backend. Resolve checks the current surface and authorization without creating a conversation or calling a model. Chat uses a client-generated clientTurnId: retrying an identical technical request returns the same turn, while reusing the ID for changed content is rejected. One conversation runs at most one turn at a time.

The first streamed event identifies the canonical conversation and turn. Subsequent typed events carry status, answer text, evidence, action proposals and warnings, followed by one terminal result. A required Context Provider failure finishes as BLOCKED; an optional failure finishes as PARTIAL. Closing or stopping the Phase 2 stream cancels its unfinished request-scoped work; only durable Agent Runs continue independently of a browser connection.

PostgreSQL is authoritative for conversations, turns, messages, evidence, proposals and feedback; Elasticsearch is only an optional search/telemetry projection. Conversation history is private to its owner, even from Agent Run administrators. The owner may physically delete a conversation when no turn or action is executing. Automatic cleanup defaults to 365 days after last activity and can be disabled by operations. Attachments remain inline and request-scoped: only safe name, type and size metadata is stored, so content must be selected again for a later turn.

Actions and Result Presentation

An Assistant explicitly enables certified Action Definitions. The selection LOV shows only actions whose bound ACTION_PROPOSAL Tool is allowed by the referenced Agent Profile. The administrator sees the action name, Tool, risk, required privileges, and presentation type read-only.

An Action Definition owns its exact Tool, proposal/confirmation contracts, risk, approval, executor, and stable presentationRef. The model cannot replace any of them. The server validates and stores an immutable typed proposal such as:

{
  "proposalId": "01J...",
  "proposalHash": "sha256:...",
  "actionDefinitionRef": "action/ticket-add-comment@1",
  "presentationRef": "action-preview/ticket-add-comment@1",
  "target": {"type": "Ticket", "id": "018f..."},
  "input": {"text": "Proposed customer update"},
  "evidenceRefs": ["provider:ticket-summary:..."],
  "expiresAt": "2026-09-02T12:30:00Z"
}

TSM-UI owns every result renderer and action preview. It maps known resultContractRef/artifactContractRef values to result components and known presentationRef values to action preview/confirmation components. The server never sends HTML, Angular component names, templates, or executable UI definitions. An unknown action presentation is visible as unsupported and cannot be confirmed.

Confirmation sends the exact proposalId, proposalHash, and a client action idempotency key. The server verifies that it is unchanged, unexpired, pending, enabled, and currently authorized before executing the certified action without asking the model again. Proposal states are PENDING, EXECUTING, COMPLETED, REJECTED, EXPIRED, or FAILED; similar proposals remain independent. The global default expiry is 15 minutes. A long action returns a durable operation identity and the UI polls proposal state, so closing the browser does not cancel it. Evidence is shown whenever a result supplies it; there is no separate Assistant result-renderer field. The first Customer and User Group assistants are read-only and register no production actions.

Turn Lifecycle

1. TSM-UI resolves the active Context Envelope without creating state.
2. On send, tsm-ai validates identity, clientTurnId, current surfaceData, and request bounds.
3. A new conversation resolves the latest valid Assistant and Agent JaVers commits; an existing one restores its pinned commits.
4. Live authorization and central policy are checked.
5. Required and selected context providers run with finite technical limits.
6. BLOCKED stops before inference; FULL or explicit PARTIAL context reaches the model.
7. The response streams typed status, content, evidence, artifact, and action-proposal events.
8. TSM-UI renders those event contracts with hard-wired Angular components.
9. The backend stores the normalized bounded turn, messages, evidence, feedback, provider status, usage, and terminal outcome in PostgreSQL.

Administration UI and Audit

Under AI agent, TSM-UI provides Agent Profiles, Assistant Profiles, and Agent Runs. Profile screens follow the existing ListingProfile listing, master/detail, standalone detail, creation dialog, tsm-form-inplace, people/date, audit, validation, and standard last-write-wins patterns.

Assistant Profile detail uses these exact tabs:

1. Basic — standard fields, Agent Profile, priority, validity, and data tags;
2. Surfaces — exact Surface Descriptor rows and derived scope;
3. Scenario — goal, starter questions, and structured input mapping;
4. Context and actions — inherited provider switches and enabled Action Definitions;
5. Audit — JaVers history, diff, and restore.

Built-in profiles are visible and read-only. Tenant profiles use full create/edit/delete permissions. Restore loads historical content and saves it as a new audited change through normal validation. There are no Publish, Retire, Assign, Test, inline-list editing, or raw whole-profile JSON controls.

Conversation Migration and Handover

A conversation created before profile pinning is adopted lazily on its first post-upgrade request. The server records one resolution and migration boundary without fabricating historical Agent Runs, events, Tool Calls, or evidence. If safe resolution is impossible, the old thread remains read-only and the UI offers a new conversation.

A handover to a user, durable process, or integration contains a typed summary, evidence, open questions, valid proposals, and completed actions. The receiver uses stable references rather than depending on an opaque transcript.

Delivery Sequence

1. Profile foundation and TQL parity: both entities, database, REST, permissions, typed LOVs, complete administration UI/audit, built-in registration, and TQL behavioral parity.
2. Contextual Assistant: remaining editor bindings, Surface Descriptors, deterministic resolution, PostgreSQL conversation/turn contracts, Context Envelope/providers, evidence, and Actions; prove Customer and User Group read-only business surfaces end to end.
3. Durable Agent Runtime: Agent Task first, then Agentic Subprocess and Agent Runs inspection UI.
4. Outbound A2A: remote Agent Registry and durable A2A client invocation.

Each phase has its own executable acceptance tests. A phase is not complete merely because its configuration schema or screens exist.

Related Documentation

• tSM AI and Agent Runtime
• AI Chat
• AI Smart Operations roadmap
• AI Assisted Development roadmap
• Agentic Process Automation
• Agent Task
• A2A Agent Task
• A2A Script Bindings
• MCP Script Bindings