@acorex-platform/module-ai-management-client 0.0.20

package/types/acorex-platform-module-ai-management-client.d.ts

@@ -0,0 +1,797 @@
+import * as i0 from '@angular/core';
+import { OnInit, OnDestroy } from '@angular/core';
+import * as i1 from '@acorex-platform/framework-client/core';
+import { AXPModuleManifest } from '@acorex-platform/framework-client/core';
+import * as i2 from '@acorex-platform/framework-client/layout/widgets';
+import * as i3 from '@acorex-platform/framework-client/runtime';
+import { AXPAiAgentOutputKind, AXPAiChatFollowUpItem, AXPAiChatMessage, AXPAiAgentOutputContract, AXPAiChatResponse, AXPAiDelegatedAgentResultSegment, AXPAiEffectiveAssistRow, AXPAiPlatformRuntimeContext, AXPAiChatTransport, AXPAiEngineLastProviderPayload, AXPAiEngineRunOptions, AXPAiDelegatedAgentTranscriptRunInput, AXPAiEngineRunResult, AXPAiChatModelListRequest, AXPAiChatModelListItem } from '@acorex-platform/module-ai-management-contracts';
+export * from '@acorex-platform/module-ai-management-contracts';
+import { AXPMenuProvider, AXPMenuProviderContext, AXPFileStorageService } from '@acorex-platform/framework-client/common';
+import { AXPEntityService } from '@acorex-platform/framework-client/layout/entity';
+import { AXPPermissionDefinitionProvider, AXPPermissionDefinitionProviderContext } from '@acorex-platform/framework-client/auth';
+import { AXPMultiLanguageString } from '@acorex-platform/framework-shared/core';
+import { AXMAiManagementAssistEntityModel } from '@acorex-platform/module-ai-management-client/contracts';
+
+declare class AXMAiManagementModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXMAiManagementModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<AXMAiManagementModule, never, [typeof i1.AXPComponentSlotModule, typeof i2.AXPWidgetsModule, typeof i3.AXPRuntimeModule], never>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<AXMAiManagementModule>;
+}
+
+interface AXPAiAssistValidationError {
+    phase: 'parse' | 'validator';
+    message: string;
+    details?: unknown;
+}
+interface AXPAiAssistCannotComplete {
+    reason: 'missingInput' | 'unsafe' | 'unsupported';
+    missing?: string[];
+    message?: string;
+}
+/**
+ * Normalized result of an assist run or structured-output pipeline session.
+ */
+interface AXPAiAssistExecutionResult<TData = unknown> {
+    success: boolean;
+    outputKind: AXPAiAgentOutputKind;
+    text: string;
+    data?: TData;
+    followUp?: {
+        items: AXPAiChatFollowUpItem[];
+    };
+    followUpRequired?: boolean;
+    followUpQuestion?: string;
+    validationErrors?: AXPAiAssistValidationError[];
+    cannotComplete?: AXPAiAssistCannotComplete;
+    raw?: unknown;
+    messages?: AXPAiChatMessage[];
+}
+
+/** Default max completion tokens when the AiModel row has no `maxOutputTokens` and the caller omits `maxTokens`. */
+declare const AXPAiAssistDefaultStructuredMaxTokens = 128000;
+/** Default maximum follow-up turns after the first model response when validating structured JSON (implementation may use this). */
+declare const AXPAiAssistDefaultMaxStructuredRetries = 3;
+/**
+ * Validates parsed JSON from the assistant. Return the validated value (possibly narrowed), or throw with a message
+ * the pipeline can send back to the model on retry.
+ */
+type AXPAiStructuredValidator<T = unknown> = (parsed: unknown) => T | Promise<T>;
+/**
+ * Thrown when {@link AXPAiAssistRunInput.expectStructuredOutput} is true but the assistant output could not be
+ * parsed and optionally validated after all attempts.
+ */
+declare class AXPAiStructuredOutputError extends Error {
+    /** 1-based count of engine runs performed for this structured-output session. */
+    readonly attempts: number;
+    /** Truncated snapshot of the last assistant plain text (for debugging). */
+    readonly lastAssistantText: string;
+    /** Human-readable validation or parse failure detail. */
+    readonly validationMessage: string;
+    /** Why the pipeline stopped. */
+    readonly code?: 'duplicate_assistant_output' | 'validation_exhausted';
+    constructor(options: {
+        message: string;
+        attempts: number;
+        lastAssistantText: string;
+        validationMessage: string;
+        cause?: unknown;
+        code?: 'duplicate_assistant_output' | 'validation_exhausted';
+    });
+}
+/** One persisted user attachment (same storage contract as the AI chat composer). */
+interface AXPAiAssistUserMediaAttachment {
+    /** `image` / `audio` / `file` (PDF, text, spreadsheets, and other document MIME types). */
+    kind: 'image' | 'audio' | 'file';
+    fileId: string;
+    mimeType: string;
+    name?: string;
+}
+/**
+ * Payload when submitting the assist prompt box (text, optional target assist/agent, optional media).
+ */
+interface AXPAiAssistPromptSubmitPayload {
+    prompt: string;
+    assistId?: string;
+    directAgentId?: string;
+    userMediaAttachments: AXPAiAssistUserMediaAttachment[];
+}
+/**
+ * Optional structured hints for a single assist run (serialized into the user message by the implementation).
+ */
+interface AXPAiAssistRunContext {
+    /** Short bullet hints appended to the prompt for the model. */
+    hints?: string[];
+    /** Extra system-level instruction for this run (implementation may emit a system message). */
+    systemInstruction?: string;
+    /** Arbitrary structured payload (JSON-serialized in the user message when present). */
+    structuredContext?: unknown;
+}
+/**
+ * Input for the AI assist `run` API (implemented in ai-management).
+ */
+interface AXPAiAssistRunInput {
+    prompt: string;
+    /**
+     * Optional images, audio, or documents (`fileId` from tenant storage). When non-empty, the implementation builds one multimodal
+     * user message (same shape as the AI chat composer) plus the serialized prompt body as text segments.
+     */
+    userMediaAttachments?: AXPAiAssistUserMediaAttachment[];
+    context?: AXPAiAssistRunContext;
+    /**
+     * Catalog assist id. When omitted together with {@link directAgentId}, the platform default assist is used.
+     */
+    assistId?: string;
+    directAgentId?: string;
+    maxSteps?: number;
+    temperature?: number;
+    /**
+     * Max completion tokens for this engine run (when the provider supports it). Structured JSON runs apply a higher
+     * default unless {@link structuredOutputMaxTokens} is set.
+     */
+    maxTokens?: number;
+    /**
+     * Declarative output contract for this run (preferred over legacy {@link expectStructuredOutput} flags).
+     * Resolved with agent/assist defaults via {@link resolveEffectiveOutputContract}.
+     */
+    outputContract?: AXPAiAgentOutputContract;
+    /** When true, implementation tries to parse assistant text as JSON into {@link AXPAiAssistRunResult.structured}. */
+    expectStructuredOutput?: boolean;
+    /** Extra instruction appended so the model returns JSON (used when {@link expectStructuredOutput} is true). */
+    structuredOutputInstruction?: string;
+    /**
+     * Shallow merge over built-in platform runtime context fields (see ai-management implementation).
+     */
+    platformRuntimeNotes?: Record<string, unknown>;
+    /**
+     * Max extra engine turns after the first response when structured output is invalid (default {@link AXPAiAssistDefaultMaxStructuredRetries}).
+     * Total attempts = 1 + maxStructuredRetries.
+     */
+    maxStructuredRetries?: number;
+    /** Optional schema or domain validation after JSON parse. */
+    structuredValidator?: AXPAiStructuredValidator;
+    /**
+     * When false, only one engine run is performed; invalid structured output throws {@link AXPAiStructuredOutputError}.
+     * When true (default for {@link expectStructuredOutput}), invalid output triggers follow-up user messages in the same transcript.
+     */
+    retryOnInvalidStructure?: boolean;
+    /**
+     * Optional description of the expected JSON shape (TypeScript-style or JSON schema summary), appended to the first
+     * user message and to retry prompts so the model stays aligned and retries are more accurate.
+     */
+    structuredOutputSchemaSummary?: string;
+    /**
+     * Overrides {@link maxTokens} for {@link expectStructuredOutput} runs only. Prefer setting this or leaving defaults so
+     * the implementation can apply {@link AXPAiAssistDefaultStructuredMaxTokens} and avoid truncated JSON.
+     */
+    structuredOutputMaxTokens?: number;
+}
+/**
+ * Result of the AI assist `run` API.
+ */
+interface AXPAiAssistRunResult {
+    /** When false, structured validation exhausted or cannotComplete (future). */
+    success?: boolean;
+    /** Effective output contract kind for this run. */
+    outputKind?: AXPAiAgentOutputKind;
+    /** Primary assistant reply text (extracted from the engine transcript). */
+    text: string;
+    /**
+     * Present when {@link AXPAiAssistRunInput.expectStructuredOutput} is true: validated structured payload
+     * (parse + optional {@link AXPAiAssistRunInput.structuredValidator}). On failure the implementation throws
+     * {@link AXPAiStructuredOutputError} instead of returning.
+     */
+    structured?: unknown;
+    /** Same as {@link structured} when using the execution-result envelope. */
+    data?: unknown;
+    /** Validation failures when returned without throwing (reserved). */
+    validationErrors?: AXPAiAssistValidationError[];
+    /** Full normalized transcript when available. */
+    messages?: AXPAiChatMessage[];
+    /**
+     * When {@link AXPAiAssistRunInput.expectStructuredOutput} is false: engine usage / provider payload for that single run.
+     * When true: {@link AXPAiAssistStructuredOutputRunRaw} with per-attempt usage and totals for debugging.
+     */
+    raw?: unknown;
+}
+/**
+ * Token usage for a single engine run; numeric fields align with {@link AXPAiEngineUsageTotals} in this module
+ * for stable client-side debugging contracts.
+ */
+interface AXPAiAssistTokenUsageSnapshot {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cachedPromptTokens?: number;
+}
+/**
+ * One engine execution within a structured-output session.
+ */
+interface AXPAiAssistStructuredOutputAttemptRecord {
+    /** 1-based index of this engine run. */
+    attemptIndex: number;
+    /** Usage reported for this run only. */
+    usage?: AXPAiAssistTokenUsageSnapshot;
+    /** Whether a last-provider payload was present for this run. */
+    hasLastProviderResult: boolean;
+}
+/**
+ * Explicit `raw` shape for {@link AXPAiAssistRunResult} when {@link AXPAiAssistRunInput.expectStructuredOutput} is true.
+ */
+interface AXPAiAssistStructuredOutputRunRaw {
+    kind: 'structured-output';
+    /** One entry per engine call (`runEngine` / structured-output retries). */
+    attempts: AXPAiAssistStructuredOutputAttemptRecord[];
+    /** Cumulative usage across all attempts. */
+    totalUsage?: AXPAiAssistTokenUsageSnapshot;
+    /** Count of engine runs in this session (same as the last `attemptIndex`). */
+    finalAttempt: number;
+    lastProviderResult?: unknown;
+}
+/**
+ * Typical max width of the prompt box column inside the bottom overlay (maps to `contentMaxWidthPx`).
+ */
+type AXPAiAssistPopupSize = 'sm' | 'md' | 'lg' | 'xl' | 'full';
+/**
+ * Indeterminate loading dialog shown while the prompt box executes an assist run after Send (model work /
+ * structured-output retries).
+ */
+interface AXPAiAssistRunLoadingDialogSpec {
+    title: string;
+    text: string;
+}
+/**
+ * Options for the AI assist `show` prompt API: same run-related fields as {@link AXPAiAssistRunInput} except `prompt`,
+ * plus UI chrome. The user-entered prompt from the surface is merged on Send.
+ */
+interface AXPAiAssistShowOptions {
+    /**
+     * Prompt box header; must be translated by the caller. Entity list assist uses
+     * `@extensions-ai-entity:assist.dialog-title.{type-level|selected|individual}`.
+     */
+    title: string;
+    placeholder?: string;
+    initialPrompt?: string;
+    size?: AXPAiAssistPopupSize;
+    context?: AXPAiAssistRunContext;
+    /**
+     * Optional catalog assist. When omitted (and {@link directAgentId} is not set), the tenant/platform default assist applies.
+     */
+    assistId?: string;
+    directAgentId?: string;
+    maxSteps?: number;
+    temperature?: number;
+    maxTokens?: number;
+    outputContract?: AXPAiAgentOutputContract;
+    expectStructuredOutput?: boolean;
+    structuredOutputInstruction?: string;
+    platformRuntimeNotes?: Record<string, unknown>;
+    maxStructuredRetries?: number;
+    structuredValidator?: AXPAiStructuredValidator;
+    retryOnInvalidStructure?: boolean;
+    structuredOutputSchemaSummary?: string;
+    structuredOutputMaxTokens?: number;
+    /**
+     * When set, shows an indeterminate loading dialog for the duration of each submitted run until `run` settles.
+     * Callers supply translated strings.
+     */
+    runLoadingDialog?: AXPAiAssistRunLoadingDialogSpec;
+}
+
+/**
+ * AI Management Module Manifest.
+ * Defines module metadata for AI provider and API key management.
+ */
+declare const AiManagementManifest: AXPModuleManifest;
+
+declare class AXMAiManagementMenuProvider implements AXPMenuProvider {
+    private readonly entityService;
+    provide(context: AXPMenuProviderContext): Promise<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXMAiManagementMenuProvider, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXMAiManagementMenuProvider>;
+}
+
+/** One assist row mapped for permission definition children. */
+interface AXMAiAssistPermissionRow {
+    name: string;
+    title: string;
+    description?: string;
+}
+/**
+ * Loads assist catalog rows for dynamic permission definitions.
+ * Skips rows without a stable programmatic `name`.
+ */
+declare function loadAssistPermissionRows(entityService: AXPEntityService, localeId: string): Promise<AXMAiAssistPermissionRow[]>;
+
+/**
+ * Registers AI section capabilities under Administration (including assist children).
+ */
+declare class AXMPermissionDefinitionProvider implements AXPPermissionDefinitionProvider {
+    private readonly entityService;
+    private readonly localeId;
+    define(context: AXPPermissionDefinitionProviderContext): Promise<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXMPermissionDefinitionProvider, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXMPermissionDefinitionProvider>;
+}
+
+/**
+ * Human-readable specialist prompt from delegated-agent tool arguments (conversation / mini-chat UI).
+ */
+declare function axpAiDelegatedAgentPromptPreview(argumentsValue: unknown): string;
+
+declare function axpAiChatUserMessage(responses: AXPAiChatResponse[]): AXPAiChatMessage;
+declare function axpAiChatMessageIsDelegatedReflectionExcluded(message: AXPAiChatMessage): boolean;
+/** Reads typed specialist segments from a normalized {@code agent_result} payload. */
+declare function axpAiDelegatedAgentResultSegments(payload: {
+    success?: boolean;
+    data?: {
+        responses?: AXPAiDelegatedAgentResultSegment[];
+    };
+}): AXPAiDelegatedAgentResultSegment[];
+/** Plain text from specialist segments (text + think) for debug / preview UI. */
+declare function axpAiDelegatedAgentOutcomeResponsesPlainText(segments: AXPAiDelegatedAgentResultSegment[]): string;
+declare function axpAiChatToolResultBodyJson(message: AXPAiChatMessage): string;
+declare function axpAiChatToolOrAgentResultBodyJson(message: AXPAiChatMessage): string;
+
+/**
+ * Strips HTML tags and decodes a few common entities for safe plain-text transcript lines.
+ * Used for Assist `initialMessages` (may be stored as rich text HTML).
+ */
+declare function axpAiStripAssistInitialHtmlToPlain(raw: string): string;
+/**
+ * Converts assist `initialMessages` (HTML or plain) into one or more `assistant` transcript lines.
+ * Non-empty paragraphs (split by blank lines) become separate messages; single block stays one message.
+ */
+declare function axpAiAssistInitialMessagesToTranscript(raw: string | null | undefined): AXPAiChatMessage[];
+
+type AssistStarterPromptsSource = Pick<AXMAiManagementAssistEntityModel, 'starterPrompts'> | Pick<AXPAiEffectiveAssistRow, 'starterPrompts'> | null | undefined;
+/**
+ * Returns non-empty starter prompt labels, preserving repeater order.
+ * Resolve locale in the template via the translate pipe.
+ */
+declare function axpAiAssistStarterPromptLabels(source: AssistStarterPromptsSource): Array<string | AXPMultiLanguageString>;
+/**
+ * Returns non-empty starter prompt strings for the active locale, preserving repeater order.
+ */
+declare function axpAiAssistStarterPromptTexts(source: AssistStarterPromptsSource, locale: string): string[];
+
+/**
+ * Builds {@link AXPAiPlatformRuntimeContext} from session and user-scoped regional settings.
+ */
+declare class AXPAiPlatformRuntimeContextBuilder {
+    private readonly session;
+    private readonly settings;
+    private readonly translation;
+    /**
+     * Resolves current user, tenant, application, UI language, and regional preferences from storage.
+     */
+    build(): Promise<AXPAiPlatformRuntimeContext>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPAiPlatformRuntimeContextBuilder, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPAiPlatformRuntimeContextBuilder>;
+}
+
+interface AXPAiChatToolRunContext {
+    assistId: string;
+    chatTransport: AXPAiChatTransport;
+    /** AiModel catalog row id for the active chat model (when resolved). */
+    modelEntityId?: string;
+    /** Set during a delegated agent sub-run (specialist executing registry tools). */
+    agentId?: string;
+    /** Assist or AiAgent catalog `name` (Demisco `agent_uuid` for Demis transport). */
+    agentName?: string;
+    /** Optional Demisco chat session id (`session_uuid` in multipart). */
+    demisSessionUuid?: string;
+}
+/**
+ * Per chat run: stores which assist and chat transport are active.
+ * Injected commands (e.g. image generation) read this instead of receiving assist/transport inside tool args.
+ */
+declare class AXPAiChatToolRunContextService {
+    private readonly runContext;
+    setContext(ctx: AXPAiChatToolRunContext | null): void;
+    getContext(): AXPAiChatToolRunContext | null;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPAiChatToolRunContextService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPAiChatToolRunContextService>;
+}
+
+/**
+ * Registry rows map inputs to string-typed JSON schemas. Override parameters for AI chat tools
+ * so models receive accurate types (arrays, booleans, nested objects).
+ */
+declare function getAiChatCommandLlmParametersOverride(commandName: string): Record<string, unknown> | null;
+
+/** Max length for relaying an https image URL in tool_result when persistence fails (CORS, etc.). */
+declare const AI_GENERATED_IMAGE_MAX_REMOTE_URL_IN_TOOL = 2048;
+/** refType for files created from in-chat image tool output. */
+declare const AI_CHAT_GENERATED_IMAGE_REF_TYPE: string;
+/** refType for files created from in-chat text-to-speech tool output. */
+declare const AI_CHAT_GENERATED_SPEECH_REF_TYPE: string;
+/** refType for user-attached images in AI chat; {@link persistAiChatAttachmentImage} uses a batch ref id. */
+declare const AI_CHAT_ATTACHMENT_REF_TYPE: string;
+/** File storage category for user chat image attachments. */
+declare const AI_CHAT_ATTACHMENT_CATEGORY = "ai-chat-attachment";
+/**
+ * Builds a File from a vendor image URL (https) or data URL (base64 image).
+ */
+declare function blobOrFileFromImageResult(imageUrl: string, defaultName?: string): Promise<File>;
+/**
+ * Saves the file and commits it so it appears in storage queries as committed.
+ */
+declare function persistAiGeneratedImage(fileStorage: AXPFileStorageService, file: File, ref: {
+    refId: string;
+    refType: string;
+}): Promise<{
+    fileId: string;
+}>;
+/**
+ * Persists a user-selected chat image; refId groups files uploaded in the same composer batch.
+ */
+declare function persistAiChatAttachmentImage(fileStorage: AXPFileStorageService, file: File, refId: string): Promise<{
+    fileId: string;
+}>;
+/**
+ * Saves synthesized speech bytes and commits so the file id can be replayed in chat.
+ */
+declare function persistAiGeneratedSpeech(fileStorage: AXPFileStorageService, file: File, ref: {
+    refId: string;
+    refType: string;
+}): Promise<{
+    fileId: string;
+}>;
+
+/** OpenAI / OpenRouter `pcm` TTS output: 16-bit signed LE, mono, 24 kHz. */
+declare const AI_CHAT_TTS_PCM_SAMPLE_RATE = 24000;
+declare function isRawPcmMimeType(mimeType: string): boolean;
+/**
+ * Wraps raw 16-bit signed little-endian PCM in a RIFF WAV container for HTML5 audio playback.
+ */
+declare function wrapPcm16LeInWav(pcmBytes: ArrayBuffer, sampleRate?: number, numChannels?: number): ArrayBuffer;
+interface AiChatTtsPlaybackBytes {
+    audioBytes: ArrayBuffer;
+    mimeType: string;
+    extension: string;
+}
+/** Normalizes synthesized speech bytes to a browser-playable container (PCM → WAV). */
+declare function prepareTtsBytesForBrowserPlayback(audioBytes: ArrayBuffer, mimeType: string): AiChatTtsPlaybackBytes;
+/**
+ * Builds a blob URL for chat voice playback, wrapping legacy PCM TTS files when needed.
+ */
+declare function createBrowserPlayableTtsBlobUrl(binary: Blob, mimeType: string, fileName?: string): Promise<string>;
+
+/**
+ * Removes ephemeral SSE chunk arrays from provider `rawResponse` objects.
+ * Assistant text is accumulated during streaming; chunk blobs must not be persisted or exported.
+ */
+declare function axpStripEphemeralStreamChunksFromProviderRaw(raw: unknown): unknown;
+/** Strips stream chunks from {@link AXPAiEngineLastProviderPayload} before message metadata / debug export. */
+declare function axpSanitizeLastProviderPayloadForPersistence(payload: AXPAiEngineLastProviderPayload | undefined): AXPAiEngineLastProviderPayload | undefined;
+
+/** Builds a JSON-serializable delegated specialist {@link AXPAiEngineRunOptions} snapshot (no callbacks). */
+declare function axpBuildDelegatedAgentRunInputSnapshot(delegationCallId: string, agentId: string, agentName: string | undefined, specialistArguments: unknown, runOptions: AXPAiEngineRunOptions): AXPAiDelegatedAgentTranscriptRunInput;
+
+interface ResolveEffectiveOutputContractInput {
+    /** Highest priority: per engine run (programmatic / automation). */
+    runtime?: AXPAiAgentOutputContract | null;
+    /** Assist `run` / `show` input. */
+    input?: AXPAiAgentOutputContract | null;
+    /** Active AiAgent catalog row. */
+    agent?: AXPAiAgentOutputContract | unknown | null;
+    /** Active Assist catalog row. */
+    assist?: AXPAiAgentOutputContract | unknown | null;
+}
+
+declare class AXPAiOutputContractResolveService {
+    private readonly segmentService;
+    /**
+     * Resolves a persisted agent/assist `outputContract` value (segment id string)
+     * or a full contract object (runtime / programmatic).
+     */
+    resolveFromPersisted(raw: unknown): Promise<AXPAiAgentOutputContract | null>;
+    /**
+     * Effective contract for one engine turn.
+     * Priority: runtime > input > agent > assist > `{ kind: 'string' }`.
+     */
+    resolveEffective(params: ResolveEffectiveOutputContractInput): Promise<AXPAiAgentOutputContract>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPAiOutputContractResolveService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPAiOutputContractResolveService>;
+}
+
+/**
+ * User follow-up appended to the transcript when structured JSON parse/validation fails.
+ *
+ * @param validationDetail - Parse or schema validation error text.
+ * @param schemaSummary - Optional expected shape (e.g. TypeScript-style) to improve retry quality.
+ * @param failurePhase - Parse failures get stronger anti-truncation wording; validator failures focus on schema/rules.
+ */
+declare function buildStructuredOutputRetryUserText(validationDetail: string, schemaSummary?: string, failurePhase?: 'parse' | 'validator'): string;
+
+type StructuredAssistantValidation = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    errorMessage: string;
+    failurePhase: 'parse' | 'validator';
+};
+/**
+ * Parses JSON from assistant text (including lightweight local repair), then optionally runs a custom validator.
+ *
+ * @param textSegmentsFallback - When provided, each segment is tried after combined text (last segment first); helps when prose and JSON sit in separate assistant text blocks.
+ */
+declare function validateStructuredAssistantResponse(assistantPlainText: string, structuredValidator: AXPAiStructuredValidator | undefined, textSegmentsFallback?: readonly string[]): Promise<StructuredAssistantValidation>;
+
+interface ContractValidationError {
+    phase: 'parse' | 'validator';
+    message: string;
+    details?: unknown;
+}
+type ContractValidationResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    errors: ContractValidationError[];
+};
+interface ValidateAgainstContractCommandExecutor {
+    execute(commandName: string, args: Record<string, unknown>): Promise<unknown>;
+}
+interface ValidateAgainstContractParams {
+    contract: AXPAiAgentOutputContract;
+    assistantPlainText: string;
+    textSegmentsFallback?: readonly string[];
+    structuredValidator?: AXPAiStructuredValidator;
+    commandExecutor?: ValidateAgainstContractCommandExecutor;
+    /**
+     * When the command returns `{ success, data: { valid, errors?, normalizedJson? } }` envelope shape.
+     */
+    parseCommandEnvelope?: (raw: unknown) => {
+        valid: boolean;
+        errorMessage?: string;
+        normalizedJson?: string;
+    };
+}
+/**
+ * Parses assistant text and validates against contract schema, registry command, and optional custom validator.
+ */
+declare function validateAgainstContract(params: ValidateAgainstContractParams): Promise<ContractValidationResult>;
+
+/**
+ * Minimal JSON-Schema-like object for native provider hints and local validation.
+ * Aligns with shapes emitted by {@link inputOptionDefinitionsToJsonSchema} in connectivity mock support.
+ */
+interface AXPAiJsonSchemaLike {
+    type?: 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+    properties?: Record<string, AXPAiJsonSchemaLike>;
+    items?: AXPAiJsonSchemaLike | AXPAiJsonSchemaLike[];
+    required?: string[];
+    enum?: unknown[];
+    additionalProperties?: boolean | AXPAiJsonSchemaLike;
+    description?: string;
+    [key: string]: unknown;
+}
+
+interface JsonSchemaMiniValidationError {
+    path: string;
+    message: string;
+}
+type JsonSchemaMiniValidationResult = {
+    ok: true;
+} | {
+    ok: false;
+    errors: JsonSchemaMiniValidationError[];
+};
+/**
+ * Validates a value against a minimal JSON Schema subset (types, required, enum, properties, items).
+ */
+declare function validateJsonSchemaMini(schema: AXPAiJsonSchemaLike, value: unknown): JsonSchemaMiniValidationResult;
+
+/**
+ * Backend boundary for AI assist runs (chat + tool rounds). Connectivity implementations execute registry
+ * commands/queries during the run loop.
+ * Wire a concrete implementation via Angular providers (for example `provide: AXPAiEngine` with `useClass`).
+ */
+declare abstract class AXPAiEngine {
+    /**
+     * Sends the conversation to the AI backend and returns updated messages (including tool rounds).
+     */
+    abstract run(options: AXPAiEngineRunOptions): Promise<AXPAiEngineRunResult>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPAiEngine, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPAiEngine>;
+}
+
+/**
+ * Optional cross-cutting AI assist: programmatic {@link run} and dialog {@link show}.
+ * Implemented by {@link AXPAiManagerService}. Consumers outside ai-management should prefer hooks or optional injection.
+ */
+declare abstract class AXPAiAssistService {
+    abstract run(input: AXPAiAssistRunInput): Promise<AXPAiAssistRunResult>;
+    /** Opens prompt UI; on Send runs {@link run} and closes the dialog. Cancel resolves `null`. */
+    abstract show(options: AXPAiAssistShowOptions): Promise<AXPAiAssistRunResult | null>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPAiAssistService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPAiAssistService>;
+}
+
+/**
+ * Frontend facade for AI: assist catalog, tenant defaults, engine runs, structured assist runs, and prompt UI.
+ */
+declare class AXPAiManagerService extends AXPAiAssistService {
+    private readonly aiEngine;
+    private readonly outputContractResolve;
+    private readonly entityService;
+    private readonly settings;
+    private readonly runtimeContextBuilder;
+    private readonly assistPromptBox;
+    private readonly localeId;
+    private readonly loadingDialog;
+    private readonly assistData;
+    private readonly modelEntityData;
+    private readonly agentEntityData;
+    /**
+     * Loads the effective assist from `DefaultAssistId` (tenant setting), or the assist named `platform-assistant`.
+     */
+    getEffectiveAssist(): Promise<AXPAiEffectiveAssistRow>;
+    private findAssistByName;
+    /**
+     * Resolves the assist row for chat: explicit primary key, otherwise the effective default from settings.
+     */
+    getAssistForChat(assistId?: string | null): Promise<AXPAiEffectiveAssistRow>;
+    /**
+     * Primary catalog model transport for an assist (`modelId` row).
+     */
+    getAssistPrimaryChatTransport(assistId?: string | null): Promise<AXPAiChatTransport | undefined>;
+    /**
+     * Low-level engine run (chat streaming and tool orchestration).
+     */
+    runEngine(options: AXPAiEngineRunOptions): Promise<AXPAiEngineRunResult>;
+    /**
+     * Normalizes AiModel.maxOutputTokens from the catalog.
+     */
+    private normalizeMaxOutputTokens;
+    /**
+     * Reads {@link AXMAiModelMaxTokensRow.maxOutputTokens} for the model bound to the assist or direct agent.
+     */
+    private resolveCatalogMaxOutputTokens;
+    /** @inheritdoc */
+    run(input: AXPAiAssistRunInput): Promise<AXPAiAssistRunResult>;
+    /** @inheritdoc */
+    show(options: AXPAiAssistShowOptions): Promise<AXPAiAssistRunResult | null>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPAiManagerService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPAiManagerService>;
+}
+
+/**
+ * Lists chat-purpose AI models (catalog), without using {@link AXPAiEngine}.
+ */
+declare class AXPAiAssistChatModelCatalogService {
+    private readonly entityService;
+    private readonly localeId;
+    private readonly modelData;
+    /**
+     * All active chat-purpose models in the catalog (assist / agent policy is applied at engine runtime).
+     */
+    listModels(_request?: AXPAiChatModelListRequest): Promise<AXPAiChatModelListItem[]>;
+    /**
+     * Chat pickers only use enabled models. Endpoint disabled state is denormalized on the
+     * model (`openAiEndpointIsDisabled`) so tenants never need OpenAI endpoint entity reads.
+     */
+    private filterModelsActiveForChat;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPAiAssistChatModelCatalogService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPAiAssistChatModelCatalogService>;
+}
+
+declare class AXPAiDefaultModelPickerService {
+    /**
+     * Picks a model from chat/vision catalog candidates.
+     * Prefers {@link preferredModelId} when it supports the purpose; otherwise the first
+     * purpose-capable entry; otherwise the first candidate.
+     */
+    pickFromChatCatalogForPurpose(models: AXPAiChatModelListItem[], purpose: 'chat' | 'vision', preferredModelId?: string | null): AXPAiChatModelListItem | undefined;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXPAiDefaultModelPickerService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXPAiDefaultModelPickerService>;
+}
+
+/**
+ * Opens the AI assist prompt box in a bottom overlay using {@link AXOverlayService} (`centered: false`, panel CSS).
+ */
+declare class AXMAiAssistPromptBoxService {
+    private readonly overlayService;
+    private overlayRef;
+    private pendingResolve;
+    private settled;
+    /**
+     * Presents the assist prompt box and resolves when the user submits, cancels, or dismisses the overlay.
+     */
+    open(options: AXPAiAssistShowOptions, executeRun: (payload: AXPAiAssistPromptSubmitPayload) => Promise<AXPAiAssistRunResult>): Promise<AXPAiAssistRunResult | null>;
+    private settle;
+    private disposeOverlayOnly;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXMAiAssistPromptBoxService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AXMAiAssistPromptBoxService>;
+}
+
+interface AXMAiAssistDraftImage {
+    clientId: string;
+    previewUrl: string;
+    mimeType: string;
+    name?: string;
+    fileId?: string;
+}
+interface AXMAiAssistDraftAudio {
+    clientId: string;
+    mimeType: string;
+    name?: string;
+    fileId?: string;
+}
+interface AXMAiAssistDraftFile {
+    clientId: string;
+    mimeType: string;
+    name?: string;
+    fileId?: string;
+}
+/**
+ * Floating prompt UI for AI assist: gradient chrome, inner composer, and image/audio/document attachments. Target assist/agent comes from optional initial ids on open.
+ */
+declare class AXMAiAssistPromptBoxComponent implements OnInit, OnDestroy {
+    private readonly toastService;
+    private readonly translation;
+    private readonly fileStorage;
+    private readonly fileService;
+    private readonly platformId;
+    readonly title: i0.InputSignal<string>;
+    readonly placeholder: i0.InputSignal<string>;
+    readonly initialPrompt: i0.InputSignal<string>;
+    readonly contentMaxWidthPx: i0.InputSignal<number>;
+    readonly initialAssistId: i0.InputSignal<string | undefined>;
+    readonly initialDirectAgentId: i0.InputSignal<string | undefined>;
+    readonly runPrompt: i0.InputSignal<(payload: AXPAiAssistPromptSubmitPayload) => Promise<AXPAiAssistRunResult>>;
+    readonly requestClose: i0.InputSignal<(result: AXPAiAssistRunResult | null) => void>;
+    readonly promptDraft: i0.WritableSignal<string>;
+    readonly busy: i0.WritableSignal<boolean>;
+    readonly isComposerSaving: i0.WritableSignal<boolean>;
+    readonly draftAttachmentGroupId: i0.WritableSignal<string | null>;
+    readonly draftComposerImages: i0.WritableSignal<AXMAiAssistDraftImage[]>;
+    readonly draftComposerAudios: i0.WritableSignal<AXMAiAssistDraftAudio[]>;
+    readonly draftComposerFiles: i0.WritableSignal<AXMAiAssistDraftFile[]>;
+    readonly assistTargetKey: i0.WritableSignal<string>;
+    readonly canSend: i0.Signal<boolean>;
+    ngOnInit(): Promise<void>;
+    ngOnDestroy(): void;
+    onPromptDraftChange(value: string | null | undefined): void;
+    /**
+     * Enter sends; Shift+Enter inserts a newline. IME composition Enter is left unchanged.
+     */
+    onPromptKeydown(event: KeyboardEvent): void;
+    onCancel(): void;
+    onMenuCancel(panel: {
+        close: () => void;
+    }): void;
+    /**
+     * Dismisses the prompt box like Cancel (disabled while a run is in flight, same as footer Cancel).
+     */
+    onDocumentEscape(): void;
+    openImagePicker(): void;
+    openAudioPicker(): void;
+    openDocumentPicker(): void;
+    onSend(): Promise<void>;
+    removeDraftImage(clientId: string): void;
+    removeDraftAudio(clientId: string): void;
+    removeDraftFile(clientId: string): void;
+    private pickComposerImages;
+    private pickComposerAudios;
+    private pickComposerDocuments;
+    private processComposerImageFiles;
+    private processComposerAudioFiles;
+    private processComposerDocumentFiles;
+    private showUploadWarning;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AXMAiAssistPromptBoxComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<AXMAiAssistPromptBoxComponent, "axm-ai-assist-prompt-box", never, { "title": { "alias": "title"; "required": true; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "initialPrompt": { "alias": "initialPrompt"; "required": false; "isSignal": true; }; "contentMaxWidthPx": { "alias": "contentMaxWidthPx"; "required": false; "isSignal": true; }; "initialAssistId": { "alias": "initialAssistId"; "required": false; "isSignal": true; }; "initialDirectAgentId": { "alias": "initialDirectAgentId"; "required": false; "isSignal": true; }; "runPrompt": { "alias": "runPrompt"; "required": true; "isSignal": true; }; "requestClose": { "alias": "requestClose"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Combined text for structured JSON extraction (text segments only).
+ */
+declare function extractLastAssistantStructuredParts(messages: AXPAiChatMessage[]): {
+    combined: string;
+    segments: string[];
+};
+
+export { AI_CHAT_ATTACHMENT_CATEGORY, AI_CHAT_ATTACHMENT_REF_TYPE, AI_CHAT_GENERATED_IMAGE_REF_TYPE, AI_CHAT_GENERATED_SPEECH_REF_TYPE, AI_CHAT_TTS_PCM_SAMPLE_RATE, AI_GENERATED_IMAGE_MAX_REMOTE_URL_IN_TOOL, AXMAiAssistPromptBoxComponent, AXMAiAssistPromptBoxService, AXMAiManagementMenuProvider, AXMAiManagementModule, AXMPermissionDefinitionProvider, AXPAiAssistChatModelCatalogService, AXPAiAssistDefaultMaxStructuredRetries, AXPAiAssistDefaultStructuredMaxTokens, AXPAiAssistService, AXPAiChatToolRunContextService, AXPAiDefaultModelPickerService, AXPAiEngine, AXPAiManagerService, AXPAiOutputContractResolveService, AXPAiPlatformRuntimeContextBuilder, AXPAiStructuredOutputError, AiManagementManifest, axpAiAssistInitialMessagesToTranscript, axpAiAssistStarterPromptLabels, axpAiAssistStarterPromptTexts, axpAiChatMessageIsDelegatedReflectionExcluded, axpAiChatToolOrAgentResultBodyJson, axpAiChatToolResultBodyJson, axpAiChatUserMessage, axpAiDelegatedAgentOutcomeResponsesPlainText, axpAiDelegatedAgentPromptPreview, axpAiDelegatedAgentResultSegments, axpAiStripAssistInitialHtmlToPlain, axpBuildDelegatedAgentRunInputSnapshot, axpSanitizeLastProviderPayloadForPersistence, axpStripEphemeralStreamChunksFromProviderRaw, blobOrFileFromImageResult, buildStructuredOutputRetryUserText, createBrowserPlayableTtsBlobUrl, extractLastAssistantStructuredParts, getAiChatCommandLlmParametersOverride, isRawPcmMimeType, loadAssistPermissionRows, persistAiChatAttachmentImage, persistAiGeneratedImage, persistAiGeneratedSpeech, prepareTtsBytesForBrowserPlayback, validateAgainstContract, validateJsonSchemaMini, validateStructuredAssistantResponse, wrapPcm16LeInWav };
+export type { AXMAiAssistPermissionRow, AXPAiAssistCannotComplete, AXPAiAssistExecutionResult, AXPAiAssistPopupSize, AXPAiAssistPromptSubmitPayload, AXPAiAssistRunContext, AXPAiAssistRunInput, AXPAiAssistRunLoadingDialogSpec, AXPAiAssistRunResult, AXPAiAssistShowOptions, AXPAiAssistStructuredOutputAttemptRecord, AXPAiAssistStructuredOutputRunRaw, AXPAiAssistTokenUsageSnapshot, AXPAiAssistUserMediaAttachment, AXPAiAssistValidationError, AXPAiChatToolRunContext, AXPAiStructuredValidator, AiChatTtsPlaybackBytes };