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

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

@@ -0,0 +1,896 @@
+import { AXPMultiLanguageString, AXPOutputTranscriptSegmentId, AXPFileListItem, AXPContextDefinition, AXPAgentOutputKind, AXPMetaData } from '@acorex-platform/framework-shared/core';
+import { AXPEntityModel } from '@acorex-platform/framework-shared/entity';
+
+/**
+ * Edition / feature flags for AI Management.
+ * `ManageCatalog` is Platform Console only (Intelligence config menu).
+ */
+declare const AXPAiManagementFeatureKeys: {
+    /** Configuration → Intelligence (agents, assists, models, endpoints, rules). */
+    readonly ManageCatalog: "AiManagement:Feature:ManageCatalog";
+};
+
+/**
+ * AI Management menu keys.
+ * Pattern: AiManagement:Menu:{Path}
+ */
+declare const AXPAiManagementMenuKeys: {
+    /** Configuration > AI Management (models, assists) */
+    readonly AiManagementConfig: "Common:Menu:Configuration:AiManagement";
+    /** OpenAI-compatible HTTP endpoints (base URL + API key). */
+    readonly OpenAiEndpoints: "AiManagement:Menu:OpenAiEndpoints";
+    /** List of AI models (from providers). */
+    readonly Models: "AiManagement:Menu:Models";
+    /** List of Assists. */
+    readonly Assists: "AiManagement:Menu:Assists";
+    /** Delegated specialist agents (supervisor routing). */
+    readonly Agents: "AiManagement:Menu:Agents";
+    /** Reusable system-prompt rules (Markdown fragments). */
+    readonly Rules: "AiManagement:Menu:Rules";
+};
+
+/**
+ * Administration capabilities used by this module.
+ * Domain capability keys for this module. Root groups live in `AXPCommonPermissionGroupKeys` (common contracts).
+ */
+declare const AXPAdministrationPermissionKeys: {
+    readonly Access: "Administration:Permission:Access";
+    readonly MaintainUsersAndRoles: "Administration:Permission:MaintainUsersAndRoles";
+    readonly ManageSessions: "Administration:Permission:ManageSessions";
+    readonly MaintainPolicies: "Administration:Permission:MaintainPolicies";
+    readonly ViewIntegrations: "Administration:Permission:ViewIntegrations";
+    readonly MaintainConnections: "Administration:Permission:MaintainConnections";
+    readonly MaintainWorkflows: "Administration:Permission:MaintainWorkflows";
+    readonly ManageWorkflowActions: "Administration:Permission:ManageWorkflowActions";
+    readonly ViewRules: "Administration:Permission:ViewRules";
+    readonly MaintainRules: "Administration:Permission:MaintainRules";
+    readonly ManageRuleActions: "Administration:Permission:ManageRuleActions";
+    readonly MaintainAi: "Administration:Permission:MaintainAi";
+    readonly UseAiAssist: "Administration:Permission:UseAiAssist";
+    readonly MaintainDashboards: "Administration:Permission:MaintainDashboards";
+    readonly ViewJobs: "Administration:Permission:ViewJobs";
+    readonly ManageJobActions: "Administration:Permission:ManageJobActions";
+    readonly ViewObservability: "Administration:Permission:ViewObservability";
+    readonly MaintainObservability: "Administration:Permission:MaintainObservability";
+};
+/**
+ * Dynamic assist access permissions (`Assist.{name}.Use`) as children of UseAiAssist.
+ * Parent Assist.Use maps to {@link AXPAdministrationPermissionKeys.UseAiAssist}.
+ */
+declare const AXMAiAssistPermissionKeys: {
+    readonly Use: "Administration:Permission:UseAiAssist";
+    readonly useForAssist: (assistName: string) => string;
+};
+/**
+ * @deprecated Prefer {@link AXPAdministrationPermissionKeys}.
+ * Legacy nested shape kept so existing imports compile during migration.
+ */
+declare const AXMPermissionsKeys: {
+    readonly AiManagement: {
+        readonly Management: "Administration:Permission:MaintainAi";
+        readonly Assist: {
+            readonly Use: "Administration:Permission:UseAiAssist";
+            readonly useForAssist: (assistName: string) => string;
+        };
+    };
+};
+
+/**
+ * AI Management setting keys.
+ * Pattern: AiManagement:Setting:{Path}
+ */
+declare const AXPAiManagementSettings: {
+    /** Assist primary key (`id`) used when no assist is explicitly selected (tenant-scoped). */
+    readonly DefaultAssistId: "AiManagement:Setting:DefaultAssistId";
+    /**
+     * System instructions prepended to every assist/agent chat system prompt in {@link AXPAiEngine}.
+     * Empty string means no global layer (default).
+     */
+    readonly GlobalSystemPrompt: "AiManagement:Setting:GlobalSystemPrompt";
+    readonly Providers: {
+        readonly Gemini: {
+            readonly ApiKey: "AiManagement:Setting:Providers.Gemini.ApiKey";
+        };
+    };
+};
+
+declare const RootConfig: {
+    config: {
+        i18n: string;
+        module: string;
+        route: string;
+    };
+    module: {
+        name: string;
+        route: string;
+        title: string;
+        icon: string;
+    };
+    entities: {
+        model: {
+            name: string;
+            fullName: string;
+            title: string;
+            titlePlural: string;
+            icon: string;
+        };
+        assist: {
+            name: string;
+            fullName: string;
+            title: string;
+            titlePlural: string;
+            icon: string;
+        };
+        agent: {
+            name: string;
+            fullName: string;
+            title: string;
+            titlePlural: string;
+            icon: string;
+        };
+        openAiEndpoint: {
+            name: string;
+            fullName: string;
+            title: string;
+            titlePlural: string;
+            icon: string;
+        };
+        rule: {
+            name: string;
+            fullName: string;
+            title: string;
+            titlePlural: string;
+            icon: string;
+        };
+        mcpServer: {
+            name: string;
+            fullName: string;
+            title: string;
+            titlePlural: string;
+            icon: string;
+        };
+    };
+};
+
+/** Denormalized {@link AiRule} snapshot on assist/agent rows (multi-lookup expose). */
+interface AXMAiManagementRuleRef {
+    id: string;
+    /** Unique programmatic key used by the engine (`includeRules` / `excludeRules`). */
+    name: string;
+    title: AXPMultiLanguageString;
+}
+/**
+ * Persisted AiRule catalog row — reusable system-prompt fragments referenced by name.
+ */
+interface AXMAiManagementRuleEntityModel extends AXPEntityModel<string> {
+    /** Programmatic key (e.g. `markdown`); referenced from assist/agent `rules` and engine run options. */
+    name: string;
+    title: AXPMultiLanguageString;
+    description?: AXPMultiLanguageString;
+    /** Rule body merged into the engine system prompt when the rule is included. */
+    markdown: string;
+}
+
+/**
+ * Persisted AiAgent catalog row (entity storage shape).
+ */
+interface AXMAiManagementAgentEntityModel extends AXPEntityModel<string> {
+    name: string;
+    title: AXPMultiLanguageString;
+    description?: AXPMultiLanguageString;
+    /**
+     * Supervisor routing: when the main assist should call this delegated specialist (`agent:<id>` tool).
+     * Merged into the tool description at runtime — not used in specialist sub-runs.
+     */
+    /** Plain-text routing for the supervisor LLM (tool description); not localized. */
+    supervisorWhenToUse?: string;
+    /** Supervisor routing: intents or turns where this specialist must not be used. */
+    supervisorWhenNotToUse?: string;
+    /** Optional chaining hints (e.g. call platform-entity before widget-form-layout). */
+    supervisorChainsWith?: string;
+    /** Optional intent keywords for admin UI and compact routing summaries. */
+    supervisorIntentTags?: string[] | null;
+    systemPrompt?: string;
+    /** Selected {@link AiRule} catalog ids (multi-lookup value field). */
+    ruleIds?: string[] | null;
+    /** Denormalized rule rows from multi-lookup expose (`title` = display, `name` = engine key). */
+    rules?: AXMAiManagementRuleRef[] | null;
+    /** Transcript segment preset id (`text` | `node` | `followUp`); resolved via segment providers at runtime. */
+    outputContract?: AXPOutputTranscriptSegmentId | string | null;
+    modelEntityId?: string | null;
+    commandIds?: unknown;
+    queryIds?: unknown;
+    /** Linked {@link McpServer} catalog ids for external MCP tools. */
+    mcpServerIds?: string[] | null;
+    maxSteps?: number;
+}
+
+/** Aligns with {@link AXPAiPlanningMode} in ai-engine.types (avoid circular imports). */
+type AXMAiManagementAssistPlanningMode = 'off' | 'once' | 'when-needed';
+/**
+ * Persisted Assist catalog row.
+ */
+interface AXMAiManagementAssistEntityModel extends AXPEntityModel<string> {
+    name: string;
+    title: AXPMultiLanguageString;
+    description?: AXPMultiLanguageString;
+    professionImageUrl?: string;
+    planningMode?: AXMAiManagementAssistPlanningMode;
+    modelId: string;
+    /** Denormalized lookup snapshot when the row is expanded for list/detail. */
+    aiModel?: {
+        id?: string;
+        title?: AXPMultiLanguageString;
+        name?: string;
+    };
+    initialMessages?: string | null;
+    /** Suggested first user messages shown in chat before the user sends anything. */
+    starterPrompts?: {
+        text: AXPMultiLanguageString;
+    }[] | null;
+    systemPrompt?: string;
+    /** Default output contract for runs using this assist (overridden by agent or run input). */
+    outputContract?: any;
+    /** Selected {@link AiRule} catalog ids (multi-lookup value field). */
+    ruleIds?: string[] | null;
+    /** Denormalized rule rows from multi-lookup expose (`title` = display, `name` = engine key). */
+    rules?: AXMAiManagementRuleRef[] | null;
+    /** Knowledge-base attachments (PDF and image formats) for this assist. */
+    knowledgeFiles?: AXPFileListItem[] | null;
+    /** Command registry bindings the assist may call directly in the same session. */
+    commandIds?: unknown;
+    /** Query registry bindings the assist may call directly in the same session. */
+    queryIds?: unknown;
+    /** Linked {@link McpServer} catalog ids for external MCP tools. */
+    mcpServerIds?: string[] | null;
+    delegatedAgents?: {
+        agent: {
+            type?: string;
+            options?: Record<string, unknown>;
+        };
+    }[] | null;
+}
+
+/** Aligns with {@link AXPAiChatTransport} in ai-engine.types (avoid circular imports). */
+type AXMAiManagementModelChatTransport = 'openai' | 'gemini' | 'demis';
+type AXMAiManagementModelPurposeSlug = 'chat' | 'vision' | 'image' | 'speech' | 'tts' | 'video';
+/**
+ * Persisted AI model catalog row.
+ */
+interface AXMAiManagementModelEntityModel extends AXPEntityModel<string> {
+    title: AXPMultiLanguageString;
+    description?: AXPMultiLanguageString;
+    /** Vendor API model id (exact string sent to the provider). */
+    name: string;
+    modelPurposes?: AXMAiManagementModelPurposeSlug[];
+    chatTransport: AXMAiManagementModelChatTransport;
+    openAiEndpointId?: string | null;
+    maxContextTokens?: number;
+    maxOutputTokens?: number;
+    maxInputTokens?: number;
+    inputPricePerMillion?: number;
+    outputPricePerMillion?: number;
+    cachedInputPricePerMillion?: number;
+    openAiEndpointIsDisabled?: boolean;
+}
+
+type AXMAiManagementMcpServerTransport = 'http' | 'sse';
+/**
+ * Persisted external MCP server catalog row.
+ */
+interface AXMAiManagementMcpServerEntityModel extends AXPEntityModel<string> {
+    name: string;
+    title: string;
+    transport: AXMAiManagementMcpServerTransport;
+    url: string;
+    apiKey?: string | null;
+    isDisabled?: boolean;
+    /** Optional prefix applied to tool names exposed to the AI engine. */
+    toolPrefix?: string | null;
+    /** When set, only these upstream MCP tool names may be called. */
+    allowedToolNames?: string[] | null;
+}
+
+/**
+ * Persisted OpenAI-compatible endpoint row.
+ */
+interface AXMAiManagementOpenAiEndpointEntityModel extends AXPEntityModel<string> {
+    title: AXPMultiLanguageString;
+    description?: AXPMultiLanguageString;
+    apiBase: string;
+    apiKey?: string | null;
+    /**
+     * When false, chat completions use a single non-streaming JSON response (no SSE).
+     * Omitted or true keeps streaming, which matches most cloud OpenAI-compatible APIs.
+     */
+    stream?: boolean;
+}
+
+declare const AXM_AI_PLATFORM_RUNTIME_CONTEXT_DEFINITIONS: AXPContextDefinition[];
+
+/** @see {@link AXPAgentOutputKind} */
+type AXPAiAgentOutputKind = AXPAgentOutputKind;
+/** @see {@link AXPOutputTranscriptSegmentId} */
+type AXPAiOutputTranscriptSegment = AXPOutputTranscriptSegmentId;
+/**
+ * Minimal JSON-Schema-like object for native provider hints and local validation.
+ */
+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;
+}
+/** Provider-native structured output hint (OpenAI `response_format`, Gemini `responseMimeType`). */
+type AXPAiResponseFormat = {
+    type: 'text';
+} | {
+    type: 'json_object';
+} | {
+    type: 'json_schema';
+    schema: AXPAiJsonSchemaLike;
+    name?: string;
+    strict?: boolean;
+};
+/**
+ * Catalog row contract for specialist final output (separate from domain `systemPrompt`).
+ * Field paths align with agent/assist entity `outputContract` JSON.
+ */
+interface AXPAiAgentOutputContract {
+    kind: AXPAiAgentOutputKind;
+    /**
+     * When `kind` is `object`: `text` = generic JSON object as text; `node` = inner widget node in chat;
+     * `followUp` = `{"type":"followUp","content":[...]}` envelope.
+     */
+    transcriptSegment?: AXPAiOutputTranscriptSegment;
+    instruction?: string;
+    schemaSummary?: string;
+    schema?: AXPAiJsonSchemaLike;
+    schemaName?: string;
+    schemaStrict?: boolean;
+    validationCommandName?: string;
+    structuredRetries?: number;
+    providerResponseFormat?: AXPAiResponseFormat;
+}
+/** Default structured retry count when `structuredRetries` is omitted on structured kinds. */
+declare const AXPAI_AGENT_OUTPUT_CONTRACT_DEFAULT_STRUCTURED_RETRIES = 2;
+declare function parseJsonSchemaLike(raw: unknown): AXPAiJsonSchemaLike | undefined;
+declare function parseResponseFormat(raw: unknown): AXPAiResponseFormat | undefined;
+/** Resolved transcript mapping for an object contract (defaults to `text`). */
+declare function resolveOutputTranscriptSegment(contract: AXPAiAgentOutputContract): AXPAiOutputTranscriptSegment;
+/**
+ * Normalizes persisted `outputContract` (object or JSON string from entity forms).
+ * Returns `null` when absent or invalid (engine treats as implicit `string`).
+ */
+declare function parseAgentOutputContract(raw: unknown): AXPAiAgentOutputContract | null;
+/** Resolved contract for engine (never null; defaults to string). */
+declare function resolveAgentOutputContract(raw: unknown): AXPAiAgentOutputContract;
+declare function axpAiAgentOutputContractUsesStructuredFinalize(contract: AXPAiAgentOutputContract): boolean;
+/** Structured kinds omit the string role baseline (Markdown prose hint) in the mock engine. */
+declare function axpAiAgentOutputContractOmitsRoleBaseline(contract: AXPAiAgentOutputContract): boolean;
+declare function axpAiAgentOutputContractStructuredRetryCap(contract: AXPAiAgentOutputContract): number;
+
+type AXPAiChatTransport = 'openai' | 'gemini' | 'demis';
+/**
+ * Live platform context for AI runs: keys match {@link AXPContextDefinition.name}, values are opaque.
+ * Built by {@link AXPAiPlatformRuntimeContextBuilder}. Display facts go into the system prompt; identity ids are not included.
+ */
+type AXPAiPlatformRuntimeContext = Record<string, unknown>;
+/**
+ * Effective Assist entity row (chat policy, prompts, delegated routing).
+ * Fields are partial except `id` because API payloads may omit unused slices.
+ */
+type AXPAiEffectiveAssistRow = Partial<Omit<AXMAiManagementAssistEntityModel, 'id'>> & {
+    id: string;
+};
+/**
+ * Effective AiAgent catalog row for UI and engine requests.
+ * Engine-specific fields are normalized in connectivity (mock / API).
+ */
+type AXPAiEffectiveAgentRow = Partial<Omit<AXMAiManagementAgentEntityModel, 'id'>> & {
+    id: string;
+    outputContract?: AXPAiAgentOutputContract | null;
+};
+interface AXPAiChatModelListRequest {
+    assistId?: string | null;
+    directAgentId?: string | null;
+}
+interface AXPAiChatModelListItem {
+    id: string;
+    name: string;
+    title: string;
+    /** `modelPurposes` from the catalog row (provided by the API). */
+    modelPurposes?: string[];
+    chatTransport?: string;
+    maxContextTokens?: number;
+    inputPricePerMillion?: number;
+    outputPricePerMillion?: number;
+    cachedInputPricePerMillion?: number;
+}
+interface AXPAiChatTextResponse {
+    type: 'text';
+    content: string;
+}
+/** Model reasoning / planning segment; paired with {@link AXPAiChatTextResponse} in assistant messages. */
+interface AXPAiChatThinkResponse {
+    type: 'think';
+    content: string;
+}
+/**
+ * Stored binary in tenant file storage (user attachment or assistant/tool output replay).
+ * MIME type and display name are resolved from {@link fileId} via file storage — not carried on the segment.
+ */
+interface AXPAiChatFileResponse {
+    type: 'file';
+    content: {
+        fileId: string;
+        /** When true, UI offers download; default false (inline preview / playback). Set by the model when the user asks for a downloadable file. */
+        isDownloadable?: boolean;
+    };
+}
+interface AXPAiChatNodeResponse {
+    type: 'node';
+    content: unknown;
+}
+interface AXPAiChatFollowUpCommand {
+    name: string;
+    options?: unknown;
+}
+interface AXPAiChatFollowUpItem {
+    text: string | AXPMultiLanguageString;
+    command: AXPAiChatFollowUpCommand;
+}
+interface AXPAiChatFollowUpResponse {
+    type: 'followUp';
+    content: AXPAiChatFollowUpItem[];
+}
+interface AXPAiChatToolInvocationContent {
+    command: string;
+    arguments: unknown;
+}
+interface AXPAiChatToolAssistantResponse {
+    type: 'tool';
+    content: AXPAiChatToolInvocationContent;
+    callId?: string;
+    /** Provider-specific replay data (e.g. Gemini `thought_signature` under a provider-owned metadata key). */
+    metadata?: AXPMetaData;
+}
+interface AXPAiChatAgentAssistantResponse {
+    type: 'agent';
+    content: AXPAiChatToolInvocationContent;
+    callId?: string;
+    metadata?: AXPMetaData;
+}
+interface AXPAiChatToolResultResponse {
+    type: 'tool_result';
+    callId: string;
+    content: unknown;
+}
+/** Segments a delegated specialist returns to the supervisor (replayable in UI). */
+type AXPAiDelegatedAgentResultSegment = AXPAiChatTextResponse | AXPAiChatThinkResponse | AXPAiChatFileResponse | AXPAiChatNodeResponse | AXPAiChatFollowUpResponse;
+/** Tool-role `agent_result` body from the engine (normalized by connectivity). */
+interface AXPAiDelegatedAgentResultPayload {
+    success: boolean;
+    error?: string;
+    data?: {
+        agentName?: string;
+        agentId?: string;
+        responses: AXPAiDelegatedAgentResultSegment[];
+    };
+}
+interface AXPAiChatAgentResultResponse {
+    type: 'agent_result';
+    callId: string;
+    name?: string;
+    content: AXPAiDelegatedAgentResultPayload;
+}
+type AXPAiChatResponse = AXPAiChatTextResponse | AXPAiChatThinkResponse | AXPAiChatFileResponse | AXPAiChatNodeResponse | AXPAiChatFollowUpResponse | AXPAiChatToolAssistantResponse | AXPAiChatAgentAssistantResponse | AXPAiChatToolResultResponse | AXPAiChatAgentResultResponse;
+/**
+ * One chat line in the persisted transcript (`user` / `assistant` / `system` / `tool`).
+ */
+interface AXPAiChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    responses: AXPAiChatResponse[];
+    name?: string;
+    /** Ephemeral delegated sub-run reflection (excluded from user-facing replay). */
+    delegatedReflection?: boolean;
+}
+interface AXPAiToolCall {
+    id: string;
+    name: string;
+    arguments: unknown;
+    metadata?: AXPMetaData;
+}
+interface AXPAiEngineUsageTotals {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cachedPromptTokens?: number;
+}
+interface AXPAiEngineLastProviderPayload {
+    messages: AXPAiChatMessage[];
+    toolCalls?: AXPAiToolCall[];
+    /** Platform-neutral usage from the Vercel adapter. Engine must not parse vendor `rawResponse`. */
+    usage?: AXPAiEngineUsageTotals;
+    rawResponse?: unknown;
+}
+/** Serializable {@link AXPAiEngineRunOptions} passed to a delegated specialist sub-run (debug export). */
+interface AXPAiDelegatedAgentTranscriptRunInput {
+    delegationCallId: string;
+    agentId: string;
+    agentName?: string;
+    specialistArguments: unknown;
+    run: Omit<AXPAiEngineRunOptions, 'onRunEvent'>;
+}
+interface AXPAiDelegatedAgentTranscriptEntry {
+    agentName?: string;
+    messages: AXPAiChatMessage[];
+    runInput?: AXPAiDelegatedAgentTranscriptRunInput;
+    /** Provider API model id used for this specialist sub-run (e.g. `gpt-5`). */
+    modelLabel?: string;
+}
+interface AXPAiDelegatedNestedToolCallContext {
+    delegationCallId: string;
+    agentId: string;
+    agentName?: string;
+}
+type AXPAiEngineRunEvent = {
+    type: 'assistant_stream_reset';
+} | {
+    type: 'assistant_stream_delta';
+    delta: string;
+    segment?: 'text' | 'think';
+} | {
+    type: 'tool_call_start';
+    call: AXPAiToolCall;
+} | {
+    type: 'tool_call_end';
+    call: AXPAiToolCall;
+    resultMessage: AXPAiChatMessage;
+    /** Present when the tool was a delegated specialist — available immediately after the sub-run finishes. */
+    delegatedTranscript?: AXPAiDelegatedAgentTranscriptEntry;
+} | {
+    type: 'delegated_agent_nested_tool_call_start';
+    ctx: AXPAiDelegatedNestedToolCallContext;
+    call: AXPAiToolCall;
+} | {
+    type: 'delegated_agent_nested_tool_call_end';
+    ctx: AXPAiDelegatedNestedToolCallContext;
+    call: AXPAiToolCall;
+    resultMessage: AXPAiChatMessage;
+} | {
+    type: 'delegated_agent_nested_stream_reset';
+    ctx: AXPAiDelegatedNestedToolCallContext;
+} | {
+    type: 'delegated_agent_nested_stream_delta';
+    ctx: AXPAiDelegatedNestedToolCallContext;
+    delta: string;
+} | {
+    type: 'delegated_agent_reflection_phase';
+    active: boolean;
+};
+interface AXPAiEngineRunOptions {
+    messages: AXPAiChatMessage[];
+    assistId?: string;
+    demisSessionUuid?: string;
+    directAgentId?: string;
+    modelEntityId?: string;
+    modelId?: string;
+    maxSteps?: number;
+    maxTokens?: number;
+    temperature?: number;
+    planningMode?: 'off' | 'once' | 'when-needed';
+    includeRules?: string[];
+    excludeRules?: string[];
+    /** Adds delegated specialists for this run only (AiAgent catalog `id` or programmatic `name`). */
+    includeAgents?: string[];
+    /** Removes delegated specialists for this run (matches catalog `id` or `name`, case-insensitive). */
+    excludeAgents?: string[];
+    platformRuntimeContext?: AXPAiPlatformRuntimeContext | null;
+    outputContract?: AXPAiAgentOutputContract;
+    onRunEvent?: (event: AXPAiEngineRunEvent) => void;
+    /** When aborted, provider streams and multi-step loops should stop promptly. */
+    abortSignal?: AbortSignal;
+}
+interface AXPAiEngineRunResult {
+    messages: AXPAiChatMessage[];
+    lastProviderResult?: AXPAiEngineLastProviderPayload;
+    usageTotals?: AXPAiEngineUsageTotals;
+    delegatedTranscriptsByCallId?: Record<string, AXPAiDelegatedAgentTranscriptEntry>;
+}
+
+type AXPAiChatResult = AXPAiEngineLastProviderPayload;
+type AXPAiChatToolChoice = 'auto' | 'none' | {
+    type: 'tool';
+    name: string;
+};
+interface AXPAiToolSchema {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+}
+interface AXPAiChatOptionsDemis {
+    /** Demisco bearer token; when omitted the server loads tenant settings. */
+    bearerToken?: string;
+    /** Demisco `agent_uuid` (`/core/agent/chat/` body field). */
+    agentUuid?: string;
+    /** Demisco `session_uuid` for server-side conversation history. */
+    sessionUuid?: string;
+    /** Demisco transcribe `language` form field (e.g. `FA`, `EN`). */
+    transcribeLanguage?: string;
+    /** Catalog model id for inline audio transcription before chat. */
+    speechModelEntityId?: string;
+}
+interface AXPAiChatOptions {
+    messages: AXPAiChatMessage[];
+    /** Catalog model entity id — preferred; adapter resolves credentials server-side. */
+    modelEntityId?: string;
+    /** API model id override; when omitted, resolved from `modelEntityId`. */
+    modelId?: string | {
+        value?: string;
+    };
+    /** Catalog transport metadata for runtime context only — not for credential loading. */
+    chatTransport?: AXPAiChatTransport;
+    /** @deprecated Adapter resolves credentials from `modelEntityId`; do not pass from Engine. */
+    openAi?: {
+        apiBase: string;
+        apiKey: string;
+        stream?: boolean;
+    };
+    /** @deprecated Adapter resolves credentials from `modelEntityId`; do not pass from Engine. */
+    geminiApiKey?: string;
+    /** @deprecated Demis runtime is disabled; kept for contract compatibility. */
+    demis?: AXPAiChatOptionsDemis;
+    tools?: AXPAiToolSchema[];
+    toolChoice?: AXPAiChatToolChoice;
+    maxTokens?: number;
+    temperature?: number;
+    stream?: boolean;
+    responseFormat?: AXPAiResponseFormat;
+    onStreamDelta?: (delta: string) => void;
+    /** Cancels in-flight generateText / streamText when aborted. */
+    abortSignal?: AbortSignal;
+    /**
+     * AI SDK `runtimeContext` — run metadata that must not be added to the model prompt
+     * (ids, transport, catalog keys). Not used to execute tools.
+     */
+    runtimeContext?: Record<string, string>;
+    /**
+     * Unused for execution. SDK tools have no `execute`; ToolCoordinator runs tools.
+     * Kept only so the adapter can forward a payload if present — do not add `tool.execute`.
+     */
+    toolsContext?: Record<string, string>;
+}
+interface AXPAiExtractDocumentTextOptions {
+    /** Catalog model entity id — preferred; adapter resolves credentials server-side. */
+    modelEntityId?: string;
+    modelId?: string | {
+        value?: string;
+    };
+    chatTransport?: AXPAiChatTransport;
+    /** @deprecated Adapter resolves from `modelEntityId`. */
+    openAi?: {
+        apiBase: string;
+        apiKey: string;
+    };
+    /** @deprecated Adapter resolves from `modelEntityId`. */
+    geminiApiKey?: string;
+    /** Agent catalog prompt. Omitted or empty: no system message is sent. */
+    systemPrompt?: string;
+    userInstruction: string;
+    mimeType: string;
+    /** Raw document bytes from file storage. */
+    bytes: Uint8Array;
+    filename?: string;
+}
+interface AXPAiGenerateImageOptions {
+    modelEntityId?: string;
+    chatTransport?: AXPAiChatTransport;
+    catalogApiModelName?: string;
+    prompt: string;
+    size?: string;
+    openAi?: {
+        apiBase: string;
+        apiKey: string;
+    };
+    geminiApiKey?: string;
+}
+interface AXPAiGenerateVideoOptions {
+    modelEntityId?: string;
+    chatTransport?: AXPAiChatTransport;
+    catalogApiModelName?: string;
+    prompt: string;
+    aspectRatio?: string;
+    duration?: number;
+    openAi?: {
+        apiBase: string;
+        apiKey: string;
+    };
+    geminiApiKey?: string;
+}
+interface AXPAiTranscribeSpeechOptions {
+    modelEntityId?: string;
+    chatTransport?: AXPAiChatTransport;
+    catalogApiModelName?: string;
+    audioBytes: ArrayBuffer;
+    mimeType: string;
+    fileName?: string;
+    language?: string;
+    openAi?: {
+        apiBase: string;
+        apiKey: string;
+    };
+    geminiApiKey?: string;
+}
+interface AXPAiSynthesizeSpeechOptions {
+    modelEntityId?: string;
+    chatTransport?: AXPAiChatTransport;
+    catalogApiModelName?: string;
+    text: string;
+    voice?: string;
+    responseFormat?: string;
+    openAi?: {
+        apiBase: string;
+        apiKey: string;
+    };
+    geminiApiKey?: string;
+}
+
+interface AXPAiSdkChatContextBundle {
+    runtimeContext?: Record<string, string>;
+    toolsContext?: Record<string, string>;
+    promptAddendum: string;
+}
+declare const AXP_AI_SDK_TOOL_CONTEXT_JSON_SCHEMA: Record<string, unknown>;
+/**
+ * Turns registered AI-capable context definitions + live values into the
+ * `## Platform runtime` system-prompt block. Identity ids are never assembled into values.
+ */
+declare function formatAxpAiPlatformRuntimePrompt(platformRuntimeContext: AXPAiPlatformRuntimeContext | null | undefined, definitions: readonly AXPContextDefinition[] | null | undefined): string;
+declare function buildAxpAiSdkChatContextBundle(input: {
+    platformRuntimeContext?: AXPAiPlatformRuntimeContext | null;
+    contextDefinitions?: readonly AXPContextDefinition[] | null;
+    runId?: string;
+    assistId?: string;
+    agentId?: string;
+    agentName?: string;
+    chatTransport?: string;
+    modelEntityId?: string;
+    demisSessionUuid?: string;
+}): AXPAiSdkChatContextBundle;
+declare function attachAxpAiSdkChatContext<T extends AXPAiChatOptions>(options: T, bundle: AXPAiSdkChatContextBundle): T;
+interface AXPAiPlatformRuntimeContextSources {
+    userDisplayName?: string;
+    tenantTitle?: string;
+    applicationTitle?: string;
+    locale?: string;
+    calendarSystem?: string;
+    timeZone?: string;
+    country?: string;
+    notes?: string;
+    now?: Date;
+}
+declare function formatAxpAiPlatformRuntimeLocalDateTime(now: Date, ianaTimeZone?: string): string;
+declare function assembleAxpAiPlatformRuntimeContext(sources: AXPAiPlatformRuntimeContextSources): AXPAiPlatformRuntimeContext;
+
+interface ResolveEffectiveOutputContractInput {
+    /** Highest priority: per engine run (programmatic / automation). */
+    runtime?: AXPAiAgentOutputContract | unknown | null;
+    /** Assist `run` / `show` input. */
+    input?: AXPAiAgentOutputContract | unknown | null;
+    /** Active AiAgent catalog row. */
+    agent?: AXPAiAgentOutputContract | unknown | null;
+    /** Active Assist catalog row. */
+    assist?: AXPAiAgentOutputContract | unknown | null;
+}
+/**
+ * Resolves the effective output contract for one engine turn.
+ *
+ * Priority: runtime > input > agent > assist > `{ kind: 'string' }`.
+ */
+declare function resolveEffectiveOutputContract(params: ResolveEffectiveOutputContractInput): AXPAiAgentOutputContract;
+
+/** Default structured retry count for a contract kind when `structuredRetries` is omitted. */
+declare function defaultRetriesForKind(kind: AXPAiAgentOutputKind): number;
+/**
+ * Maps an effective output contract to a provider request hint.
+ * Explicit {@link AXPAiAgentOutputContract.providerResponseFormat} wins; otherwise derived from `kind` + `schema`.
+ */
+declare function deriveProviderResponseFormat(contract: AXPAiAgentOutputContract): AXPAiResponseFormat | undefined;
+
+/**
+ * JSON Schema hint for {@link AXPWidgetNode} roots returned by layout specialists.
+ * Intentionally permissive (`additionalProperties`) — strict validation runs via
+ * `AiFormbuilder:ValidateLayoutJsonForAi` when configured on the agent contract.
+ */
+declare const AXP_WIDGET_NODE_JSON_SCHEMA: AXPAiJsonSchemaLike;
+/** JSON Schema for the followUp transcript envelope (`type` + `content` chips). */
+declare const AXP_FOLLOW_UP_ENVELOPE_JSON_SCHEMA: AXPAiJsonSchemaLike;
+/** Built-in JSON Schema for known transcript segments when the contract omits `schema`. */
+declare function resolveBuiltinSchemaForOutputContract(contract: AXPAiAgentOutputContract): AXPAiJsonSchemaLike | undefined;
+
+type AXPAiChatStructuredOutputGate = {
+    responseFormat?: AXPAiResponseFormat;
+    hasTools?: boolean;
+    toolChoice?: 'auto' | 'none' | {
+        type: 'tool';
+        name: string;
+    };
+};
+/**
+ * Native structured output (AI SDK `output` / provider schema) must not run on tool-calling
+ * turns — only when tools are absent or explicitly disabled (`toolChoice: 'none'`).
+ */
+declare function axpAiShouldApplyChatStructuredOutput(params: AXPAiChatStructuredOutputGate): boolean;
+declare function axpAiTryParseJsonValueFromAssistantText(text: string): unknown | undefined;
+/** True when assistant `text` duplicates a structured segment already attached as `node` / `followUp`. */
+declare function axpAiTextDuplicatesStructuredSegment(text: string, segment: 'node' | 'followUp'): boolean;
+
+/** Prefix for supervisor-delegated specialist tools (`${AXPAI_SUPERVISOR_AGENT_TOOL_PREFIX}${agentId}`). */
+declare const AXPAI_SUPERVISOR_AGENT_TOOL_PREFIX: "agent:";
+declare function axpAiSupervisorAgentToolName(agentCatalogId: string): string;
+declare function axpAiParseSupervisorAgentToolName(toolName: string): string | null;
+declare function axpAiChatTextMessage(role: AXPAiChatMessage['role'], text: string): AXPAiChatMessage;
+declare function axpAiChatToolResultMessage(callId: string, content: unknown, toolName?: string): AXPAiChatMessage;
+declare function axpAiChatMessageGetText(message: AXPAiChatMessage): string;
+declare function axpAiNormalizeHandlerResultToToolBody(handlerResult: unknown): unknown;
+
+type AXPAiEngineWireEvent = AXPAiEngineRunEvent | {
+    type: 'run_started';
+    runId: string;
+} | {
+    type: 'frontend_tool_call';
+    runId: string;
+    call: AXPAiToolCall;
+} | {
+    type: 'run_completed';
+    result: AXPAiEngineRunResult;
+} | {
+    type: 'run_failed';
+    error: string;
+};
+type AXPAiEngineRunRequest = Omit<AXPAiEngineRunOptions, 'onRunEvent'>;
+
+type AXPAiExtractDocumentKind = 'image' | 'pdf' | 'text' | 'unsupported';
+/**
+ * Classifies a document for AI text extraction (image OCR, PDF file part, or UTF-8 text).
+ * Does not include Office formats.
+ */
+declare function classifyAiExtractDocument(mimeType: string | undefined | null, filename?: string | null): AXPAiExtractDocumentKind;
+declare function canAiExtractDocument(mimeType: string | undefined | null, filename?: string | null): boolean;
+
+declare const AIMANAGEMENT_CHAT_GENERATE_IMAGE_COMMAND_KEY = "AiManagement:ChatGenerateImage";
+declare const AIMANAGEMENT_CHAT_TRANSCRIBE_SPEECH_COMMAND_KEY = "AiManagement:ChatTranscribeSpeech";
+declare const AIMANAGEMENT_CHAT_SYNTHESIZE_SPEECH_COMMAND_KEY = "AiManagement:ChatSynthesizeSpeech";
+declare const AIMANAGEMENT_EXTRACT_DOCUMENT_TEXT_COMMAND_KEY = "AiManagement:ExtractDocumentText";
+declare const AIMANAGEMENT_STRUCTURED_TEXT_COMPLETION_COMMAND_KEY = "AiManagement:StructuredTextCompletion";
+
+declare const AXMAiManagementTransportKeys: {
+    readonly Engine: {
+        readonly Run: "AiManagement:Engine:Run";
+        readonly SubmitToolResult: "AiManagement:Engine:SubmitToolResult";
+    };
+    readonly ConversationAssist: {
+        readonly Subscribe: "ConversationManagement:Assist:Subscribe";
+        readonly AssistSync: "ConversationManagement:Assist:AssistSync";
+        readonly RetryAssist: "ConversationManagement:Assist:RetryAssist";
+        readonly CancelAssist: "ConversationManagement:Assist:CancelAssist";
+    };
+};
+
+type AXMAiModelPurposeSlug = 'chat' | 'vision' | 'image' | 'speech' | 'tts' | 'video';
+declare function readModelPurposes(row: Record<string, unknown> | null | undefined): string[];
+declare function modelRowHasPurpose(row: Record<string, unknown> | null | undefined, purpose: AXMAiModelPurposeSlug): boolean;
+declare function isChatPurposeModelRow(row: Record<string, unknown> | null | undefined): boolean;
+
+declare function parseChatTransport(raw: unknown): AXPAiChatTransport | undefined;
+
+declare function axpAiChatMessagesFromProviderAssistant(text: string, toolCalls?: AXPAiToolCall[]): AXPAiChatMessage[];
+declare function axcResolveAiMlOrPlainString(value: unknown, locale?: string): string;
+
+export { AIMANAGEMENT_CHAT_GENERATE_IMAGE_COMMAND_KEY, AIMANAGEMENT_CHAT_SYNTHESIZE_SPEECH_COMMAND_KEY, AIMANAGEMENT_CHAT_TRANSCRIBE_SPEECH_COMMAND_KEY, AIMANAGEMENT_EXTRACT_DOCUMENT_TEXT_COMMAND_KEY, AIMANAGEMENT_STRUCTURED_TEXT_COMPLETION_COMMAND_KEY, AXMAiAssistPermissionKeys, AXMAiManagementTransportKeys, AXMPermissionsKeys, AXM_AI_PLATFORM_RUNTIME_CONTEXT_DEFINITIONS, AXPAI_AGENT_OUTPUT_CONTRACT_DEFAULT_STRUCTURED_RETRIES, AXPAI_SUPERVISOR_AGENT_TOOL_PREFIX, AXPAdministrationPermissionKeys, AXPAiManagementFeatureKeys, AXPAiManagementMenuKeys, AXPAiManagementSettings, AXP_AI_SDK_TOOL_CONTEXT_JSON_SCHEMA, AXP_FOLLOW_UP_ENVELOPE_JSON_SCHEMA, AXP_WIDGET_NODE_JSON_SCHEMA, RootConfig, assembleAxpAiPlatformRuntimeContext, attachAxpAiSdkChatContext, axcResolveAiMlOrPlainString, axpAiAgentOutputContractOmitsRoleBaseline, axpAiAgentOutputContractStructuredRetryCap, axpAiAgentOutputContractUsesStructuredFinalize, axpAiChatMessageGetText, axpAiChatMessagesFromProviderAssistant, axpAiChatTextMessage, axpAiChatToolResultMessage, axpAiNormalizeHandlerResultToToolBody, axpAiParseSupervisorAgentToolName, axpAiShouldApplyChatStructuredOutput, axpAiSupervisorAgentToolName, axpAiTextDuplicatesStructuredSegment, axpAiTryParseJsonValueFromAssistantText, buildAxpAiSdkChatContextBundle, canAiExtractDocument, classifyAiExtractDocument, defaultRetriesForKind, deriveProviderResponseFormat, formatAxpAiPlatformRuntimeLocalDateTime, formatAxpAiPlatformRuntimePrompt, isChatPurposeModelRow, modelRowHasPurpose, parseAgentOutputContract, parseChatTransport, parseJsonSchemaLike, parseResponseFormat, readModelPurposes, resolveAgentOutputContract, resolveBuiltinSchemaForOutputContract, resolveEffectiveOutputContract, resolveOutputTranscriptSegment };
+export type { AXMAiManagementAgentEntityModel, AXMAiManagementAssistEntityModel, AXMAiManagementAssistPlanningMode, AXMAiManagementMcpServerEntityModel, AXMAiManagementMcpServerTransport, AXMAiManagementModelChatTransport, AXMAiManagementModelEntityModel, AXMAiManagementModelPurposeSlug, AXMAiManagementOpenAiEndpointEntityModel, AXMAiManagementRuleEntityModel, AXMAiManagementRuleRef, AXMAiModelPurposeSlug, AXPAiAgentOutputContract, AXPAiAgentOutputKind, AXPAiChatAgentAssistantResponse, AXPAiChatAgentResultResponse, AXPAiChatFileResponse, AXPAiChatFollowUpCommand, AXPAiChatFollowUpItem, AXPAiChatFollowUpResponse, AXPAiChatMessage, AXPAiChatModelListItem, AXPAiChatModelListRequest, AXPAiChatNodeResponse, AXPAiChatOptions, AXPAiChatOptionsDemis, AXPAiChatResponse, AXPAiChatResult, AXPAiChatStructuredOutputGate, AXPAiChatTextResponse, AXPAiChatThinkResponse, AXPAiChatToolAssistantResponse, AXPAiChatToolChoice, AXPAiChatToolInvocationContent, AXPAiChatToolResultResponse, AXPAiChatTransport, AXPAiDelegatedAgentResultPayload, AXPAiDelegatedAgentResultSegment, AXPAiDelegatedAgentTranscriptEntry, AXPAiDelegatedAgentTranscriptRunInput, AXPAiDelegatedNestedToolCallContext, AXPAiEffectiveAgentRow, AXPAiEffectiveAssistRow, AXPAiEngineLastProviderPayload, AXPAiEngineRunEvent, AXPAiEngineRunOptions, AXPAiEngineRunRequest, AXPAiEngineRunResult, AXPAiEngineUsageTotals, AXPAiEngineWireEvent, AXPAiExtractDocumentKind, AXPAiExtractDocumentTextOptions, AXPAiGenerateImageOptions, AXPAiGenerateVideoOptions, AXPAiJsonSchemaLike, AXPAiOutputTranscriptSegment, AXPAiPlatformRuntimeContext, AXPAiPlatformRuntimeContextSources, AXPAiResponseFormat, AXPAiSdkChatContextBundle, AXPAiSynthesizeSpeechOptions, AXPAiToolCall, AXPAiToolSchema, AXPAiTranscribeSpeechOptions, ResolveEffectiveOutputContractInput };