@newheap/platform-ai-chat 0.1.0

package/index.d.ts

@@ -0,0 +1,937 @@
+import * as _angular_core from '@angular/core';
+import { InjectionToken, Type, EnvironmentProviders, Signal, AfterViewInit, OnDestroy, PipeTransform } from '@angular/core';
+import { Observable } from 'rxjs';
+import { TranslationObject } from '@ngx-translate/core';
+import { TemplatePortal } from '@angular/cdk/portal';
+
+interface AssistantStatus {
+    enabled: boolean;
+    agents: AgentSummary[];
+    limits: {
+        maxMessageChars: number;
+        maxToolCallsPerTurn: number;
+    };
+    /** True when the caller also passes the admin policy and may use the `admin/*` endpoints. */
+    canAdminister: boolean;
+}
+interface AgentSummary {
+    id: string;
+    version: number;
+    displayNameKey: string;
+    descriptionKey: string;
+    canMutate: boolean;
+}
+interface ConversationSummary {
+    id: string;
+    agentId: string;
+    title: string | null;
+    status: ConversationStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+interface Conversation extends ConversationSummary {
+    agentVersion: number;
+    messages: Message[];
+    pendingApproval: ApprovalPart | null;
+}
+type ConversationStatus = 'idle' | 'running' | 'waiting-for-approval' | 'failed' | 'archived';
+interface Message {
+    id: string;
+    role: 'user' | 'assistant' | 'tool';
+    createdAt: string;
+    parts: MessagePart[];
+}
+type MessagePart = TextPart | ToolCallPart | ApprovalPart;
+interface TextPart {
+    type: 'text';
+    text: string;
+}
+type ToolCallStatus = 'running' | 'succeeded' | 'failed' | 'awaiting-approval' | 'rejected';
+interface ToolCallPart {
+    type: 'tool-call';
+    invocationId: string;
+    toolId: string;
+    toolVersion: number;
+    displayName: string;
+    status: ToolCallStatus;
+    argumentsPreview: string | null;
+    resultPreview: string | null;
+    resultCode: string | null;
+}
+type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+interface ApprovalPart {
+    type: 'approval';
+    approvalId: string;
+    proposalId: string;
+    proposalHash: string;
+    toolId: string;
+    summary: string;
+    argumentsPreview: string;
+    targets: string[];
+    expiresAt: string;
+    status: ApprovalStatus;
+}
+/** Response of `GET conversations?page=&itemsPerPage=`. */
+interface ConversationPage {
+    items: ConversationSummary[];
+    total: number;
+}
+/** Body of `POST conversations`. */
+interface CreateConversationRequest {
+    agentId: string;
+    title?: string;
+}
+/** An entity the user has open, for example `{ type: 'project', id: 'AA09027', label: 'Project AA09027' }`. */
+interface ClientContextEntity {
+    /** Dash-case, for example `order-group`. */
+    type: string;
+    /** At most 64 characters. */
+    id: string;
+    /** At most 120 characters. */
+    label?: string | null;
+}
+/**
+ * What the user has open when sending a message. Untrusted page data for the model:
+ * entity ids are search hints only and never grant access.
+ */
+interface ClientContext {
+    /** For example `/order-group/123`; at most 200 characters. */
+    route: string;
+    /** Page title; at most 120 characters. */
+    title?: string | null;
+    /** At most 5 entities. */
+    entities?: ClientContextEntity[];
+}
+/** Library name of the contract's `ClientContext`. */
+type NhAssistantClientContext = ClientContext;
+/** Body of `POST conversations/{id}/messages`. */
+interface SendMessageRequest {
+    text: string;
+    clientMessageId: string;
+    /** Page context of this message; `null` when the user left it out. */
+    clientContext?: ClientContext | null;
+}
+type ApprovalDecision = 'approve' | 'reject';
+/** Body of `POST conversations/{id}/approvals/{approvalId}/decide`. */
+interface DecideApprovalRequest {
+    decision: ApprovalDecision;
+    expectedProposalHash: string;
+    reason?: string;
+}
+
+interface TurnStartedEvent {
+    turnId: string;
+    userMessageId: string;
+    assistantMessageId: string;
+}
+interface MessageDeltaEvent {
+    messageId: string;
+    text: string;
+}
+interface ToolStartedEvent {
+    invocationId: string;
+    toolId: string;
+    toolVersion: number;
+    displayName: string;
+    argumentsPreview: string | null;
+}
+interface ToolCompletedEvent {
+    invocationId: string;
+    status: 'succeeded' | 'failed';
+    resultCode: string | null;
+    resultPreview: string | null;
+}
+type ApprovalRequiredEvent = ApprovalPart;
+type TurnCompletionStatus = 'completed' | 'waiting-for-approval' | 'cancelled' | 'failed';
+interface TurnUsage {
+    inputTokens: number;
+    outputTokens: number;
+    toolCalls: number;
+}
+interface TurnCompletedEvent {
+    turnId: string;
+    status: TurnCompletionStatus;
+    usage: TurnUsage;
+    errorCode: string | null;
+}
+interface AssistantErrorEvent {
+    code: string;
+    messageKey: string;
+}
+/** Map from SSE event name to its data payload. */
+interface NhAssistantSseEventMap {
+    'turn.started': TurnStartedEvent;
+    'message.delta': MessageDeltaEvent;
+    'tool.started': ToolStartedEvent;
+    'tool.completed': ToolCompletedEvent;
+    'approval.required': ApprovalRequiredEvent;
+    'turn.completed': TurnCompletedEvent;
+    'error': AssistantErrorEvent;
+}
+type NhAssistantSseEventType = keyof NhAssistantSseEventMap;
+/** One parsed assistant event, discriminated by its SSE event name. */
+type NhAssistantSseEvent = {
+    [K in NhAssistantSseEventType]: {
+        type: K;
+        data: NhAssistantSseEventMap[K];
+    };
+}[NhAssistantSseEventType];
+declare const NH_ASSISTANT_SSE_EVENT_TYPES: readonly NhAssistantSseEventType[];
+/**
+ * Stable client-side failure codes. The client emits these as `error` events when the
+ * transport fails before the server could send its own `error` event.
+ */
+declare const NhAssistantClientErrorCodes: {
+    readonly network: "assistant-network";
+    readonly unauthenticated: "assistant-unauthenticated";
+    readonly forbidden: "assistant-forbidden";
+    readonly notFound: "assistant-not-found";
+    readonly conversationBusy: "assistant-conversation-busy";
+    readonly validation: "assistant-validation";
+    readonly versionConflict: "assistant-version-conflict";
+    readonly invalidResponse: "assistant-invalid-response";
+    readonly streamInterrupted: "assistant-stream-interrupted";
+    readonly server: "assistant-server";
+};
+type NhAssistantClientErrorCode = typeof NhAssistantClientErrorCodes[keyof typeof NhAssistantClientErrorCodes];
+
+type AssistantStyle = 'default' | 'direct' | 'personal' | 'detailed';
+type AssistantAddressForm = 'informal' | 'formal';
+type AssistantResponseLength = 'short' | 'normal' | 'long';
+interface AssistantPreferences {
+    style: AssistantStyle;
+    addressForm: AssistantAddressForm;
+    responseLength: AssistantResponseLength;
+    /** At most 1,000 characters. Steers style only; it never overrides the fixed rules. */
+    customInstructions: string | null;
+}
+interface ApplicationContext {
+    text: string;
+    version: number;
+    hash: string;
+    updatedAt: string;
+    updatedBy: string | null;
+}
+interface ApplicationContextVersion {
+    version: number;
+    hash: string;
+    updatedAt: string;
+    updatedBy: string | null;
+}
+/** Body of `PUT admin/context`. */
+interface UpdateApplicationContextRequest {
+    text: string;
+    expectedVersion: number;
+}
+type ToolCatalogEffect = 'read-only' | 'idempotent-mutation' | 'mutation' | 'destructive';
+interface ToolCatalogEntry {
+    id: string;
+    source: 'local' | 'bridge' | 'mcp';
+    effect: ToolCatalogEffect;
+    description: string;
+}
+/** Equals `NhAiAutonomyLevel`. */
+type AssistantAutonomy = 'observe' | 'explain' | 'propose' | 'simulate' | 'execute';
+interface AdminAgentInput {
+    id: string;
+    displayName: string;
+    description: string;
+    instructions: string;
+    toolSelectors: string[];
+    mcpServerIds: string[];
+    requiredPolicy: string | null;
+    autonomy: AssistantAutonomy;
+    isEnabled: boolean;
+}
+/** Body of `PUT admin/agents/{id}`. */
+type UpdateAdminAgentRequest = AdminAgentInput & {
+    expectedVersion: number;
+};
+interface AdminAgent extends AdminAgentInput {
+    version: number;
+    source: 'code' | 'admin';
+    isOverridden: boolean;
+    instructionsHash: string;
+    updatedAt: string;
+}
+type McpAuthMode = 'none' | 'bearer' | 'api-key' | 'forward-user-token';
+interface McpServerInput {
+    id: string;
+    displayName: string;
+    url: string;
+    authMode: McpAuthMode;
+    headerName: string | null;
+    /** Write-only. Omit to keep the stored secret, `""` to clear it. */
+    secret?: string | null;
+    requiredPolicy: string | null;
+    isEnabled: boolean;
+}
+interface McpServer {
+    id: string;
+    displayName: string;
+    url: string;
+    authMode: McpAuthMode;
+    headerName: string | null;
+    hasSecret: boolean;
+    requiredPolicy: string | null;
+    isEnabled: boolean;
+    lastSyncAt: string | null;
+    lastSyncStatus: 'ok' | 'failed' | null;
+    assignedAgentIds: string[];
+}
+interface McpServerTestResult {
+    ok: boolean;
+    code: string | null;
+    toolCount: number | null;
+}
+type McpToolEffect = 'read-only' | 'mutation';
+type McpToolStatus = 'available' | 'schema-changed' | 'missing';
+interface McpTool {
+    remoteName: string;
+    localId: string;
+    description: string;
+    descriptionOverride: string | null;
+    isEnabled: boolean;
+    effect: McpToolEffect;
+    status: McpToolStatus;
+    /** Remote annotation. Untrusted: shown as a hint only, never used as a default. */
+    readOnlyHint: boolean | null;
+}
+/** Body of `PUT admin/mcp-servers/{id}/tools/{remoteName}`. */
+interface UpdateMcpToolRequest {
+    isEnabled: boolean;
+    effect: McpToolEffect;
+    descriptionOverride: string | null;
+}
+
+/** Decides whether the current user may see and use the assistant. */
+interface NhAssistantAccessPolicy {
+    canUse(): boolean | Observable<boolean>;
+}
+interface NhAssistantConfig {
+    /** Base URL of the assistant endpoints, for example `environment.api.baseUrl + '/assistant'`. */
+    apiBaseUrl: string;
+    /**
+     * Returns the caller's bearer token, or null when the request should be anonymous. It runs
+     * in the injection context of the assistant scope before every request, so it may call
+     * `inject(...)`, for example `() => inject(MyAuthService).getAuthorization()?.token ?? null`.
+     */
+    getAccessToken: () => string | null | Promise<string | null>;
+    /**
+     * Returns what the user has open, sent with each message as untrusted page context.
+     * Runs in the assistant's injection context when the panel opens and before every
+     * message, like `getAccessToken`. The library validates and truncates the result; a
+     * failing getter or an invalid shape only leaves the context out. Default: none.
+     */
+    getPageContext?: () => ClientContext | null | Promise<ClientContext | null>;
+    /** Injectable access policy. Default: always allowed. */
+    accessPolicy?: Type<NhAssistantAccessPolicy>;
+    /** Agent selected when the user has not chosen one. Default: the first agent the server lists. */
+    defaultAgentId?: string;
+    /** `'bundled'` merges the library's `en` and `nl` texts into `TranslateService`; `'host'` leaves translations to the host. Default `'bundled'`. */
+    translations?: 'bundled' | 'host';
+    /**
+     * Router link of the host's assistant administration page. The panel shows a link to it
+     * only when the server reports `canAdminister`. Default: no link.
+     */
+    adminRoute?: string | any[];
+    /** Renders assistant text as sanitized Markdown. Default `{ enabled: true }`. */
+    markdown?: {
+        enabled: boolean;
+    };
+}
+declare const NH_ASSISTANT_CONFIG: InjectionToken<NhAssistantConfig>;
+declare const NH_ASSISTANT_ACCESS_POLICY: InjectionToken<NhAssistantAccessPolicy>;
+/** The `fetch` function type the assistant client uses. */
+type NhAssistantFetch = (input: string, init: RequestInit) => Promise<Response>;
+/**
+ * Transport used by the assistant client. It is deliberately independent of the host's
+ * `HttpClient` and interceptors, because streaming responses need `fetch` and the access
+ * token comes from `NhAssistantConfig.getAccessToken`. Tests and the mock API from
+ * `@newheap/platform-ai-chat/testing` replace it.
+ */
+declare const NH_ASSISTANT_FETCH: InjectionToken<NhAssistantFetch>;
+/** Default policy: every user who can reach the host may use the assistant. */
+declare class NhAssistantAllowAllAccessPolicy implements NhAssistantAccessPolicy {
+    canUse(): boolean;
+}
+
+/**
+ * Registers the assistant client, store and panel for one application or route scope.
+ * Call it once in the root providers; a route may call it again to host an isolated
+ * assistant with its own configuration.
+ */
+declare function provideNhAssistant(config: NhAssistantConfig): EnvironmentProviders;
+
+/** The library's own translation bundles, keyed by language. All keys live under `nh-assistant.`. */
+declare const NH_ASSISTANT_TRANSLATIONS: Readonly<Record<'en' | 'nl', TranslationObject>>;
+/**
+ * Merges the bundled texts into `TranslateService` whenever the host loads or replaces a
+ * language. Host loaders never lose the library texts, the library never pre-empts the
+ * host loader, and keys the host defines under `nh-assistant.` (agent names, overrides)
+ * win over the bundle. Languages without a bundle receive the English texts.
+ */
+declare class NhAssistantTranslationMerger {
+    private readonly translate;
+    private readonly destroyRef;
+    private started;
+    start(): void;
+    private ensure;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantTranslationMerger, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<NhAssistantTranslationMerger>;
+}
+
+/** One raw server-sent event before its data is interpreted. */
+interface NhAssistantRawSseMessage {
+    event: string;
+    data: string;
+}
+/**
+ * Incremental parser for the `text/event-stream` format.
+ *
+ * Feed decoded text chunks in arrival order. Chunks may split lines, fields and line
+ * terminators anywhere. Comment lines (starting with `:`, such as the `: keep-alive`
+ * heartbeat) are ignored; `id` and `retry` fields are accepted and ignored. An event is
+ * dispatched at the empty line that terminates it. An unterminated event at the end of
+ * the stream is discarded, as the SSE specification requires.
+ */
+declare class NhAssistantSseParser {
+    private buffer;
+    private eventName;
+    private dataLines;
+    push(chunk: string): NhAssistantRawSseMessage[];
+    /** Signals the end of the stream and returns an event that a trailing CR completed. */
+    end(): NhAssistantRawSseMessage[];
+    private processLine;
+    private dispatch;
+}
+
+/** A failed JSON request of the assistant API. Carries a stable code, never response text. */
+declare class NhAssistantApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly messageKey: string;
+    constructor(status: number, code: string, messageKey: string);
+}
+/** Translation key that belongs to a failure code. */
+declare function nhAssistantErrorMessageKey(code: string): string;
+/** Maps an HTTP status of the assistant API to a stable client failure code. */
+declare function nhAssistantCodeForStatus(status: number): string;
+/** Status-specific codes that replace the generic mapping for one endpoint. */
+type NhAssistantStatusCodes = Partial<Record<number, string>>;
+
+/**
+ * Client for the assistant HTTP API. JSON endpoints return cold observables that abort
+ * their request on unsubscribe. Streaming endpoints emit every contract event and complete
+ * after `turn.completed` or `error`; transport failures become an `error` event with a
+ * client failure code instead of an observable error.
+ */
+declare class NhAssistantApiService {
+    private readonly transport;
+    status(): Observable<AssistantStatus>;
+    agents(): Observable<AgentSummary[]>;
+    listConversations(page?: number, itemsPerPage?: number): Observable<ConversationPage>;
+    createConversation(request: CreateConversationRequest): Observable<Conversation>;
+    getConversation(conversationId: string): Observable<Conversation>;
+    deleteConversation(conversationId: string): Observable<void>;
+    sendMessage(conversationId: string, request: SendMessageRequest): Observable<NhAssistantSseEvent>;
+    decideApproval(conversationId: string, approvalId: string, request: DecideApprovalRequest): Observable<NhAssistantSseEvent>;
+    cancel(conversationId: string): Observable<void>;
+    /** The caller's own assistant preferences. */
+    getPreferences(): Observable<AssistantPreferences>;
+    /** Replaces the caller's own assistant preferences and returns the stored values. */
+    updatePreferences(preferences: AssistantPreferences): Observable<AssistantPreferences>;
+    private requestStream;
+    private executeStream;
+    private readStream;
+    private emitClientError;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantApiService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<NhAssistantApiService>;
+}
+
+/**
+ * Client for the assistant administration endpoints (`admin/*`). The server requires the
+ * access policy and the admin policy; show the administration only when
+ * `NhAssistantStore.canAdminister()` is true. Failures error with `NhAssistantApiError`.
+ * Secrets are write-only: `McpServer` only reports `hasSecret`.
+ */
+declare class NhAssistantAdminApiService {
+    private readonly transport;
+    getContext(): Observable<ApplicationContext>;
+    /** Saves a new context version; fails with `assistant-version-conflict` when `expectedVersion` is stale. */
+    updateContext(request: UpdateApplicationContextRequest): Observable<ApplicationContext>;
+    getContextVersions(): Observable<ApplicationContextVersion[]>;
+    /** Local, bridge and MCP tools, for choosing tool selectors. */
+    getTools(): Observable<ToolCatalogEntry[]>;
+    getAgents(): Observable<AdminAgent[]>;
+    createAgent(input: AdminAgentInput): Observable<AdminAgent>;
+    updateAgent(agentId: string, request: UpdateAdminAgentRequest): Observable<AdminAgent>;
+    /** Restores a code agent to its definition in code. */
+    resetAgent(agentId: string): Observable<AdminAgent>;
+    /** Deletes an admin agent. Code agents cannot be deleted; disable them instead. */
+    deleteAgent(agentId: string): Observable<void>;
+    getMcpServers(): Observable<McpServer[]>;
+    createMcpServer(input: McpServerInput): Observable<McpServer>;
+    /** Omit `secret` to keep the stored secret; send `""` to clear it. */
+    updateMcpServer(serverId: string, input: McpServerInput): Observable<McpServer>;
+    deleteMcpServer(serverId: string): Observable<void>;
+    testMcpServer(serverId: string): Observable<McpServerTestResult>;
+    /** Reads the remote tool list. New tools start disabled; a changed input schema disables a tool. */
+    syncMcpServer(serverId: string): Observable<McpTool[]>;
+    getMcpTools(serverId: string): Observable<McpTool[]>;
+    updateMcpTool(serverId: string, remoteName: string, request: UpdateMcpToolRequest): Observable<McpTool>;
+    private request;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantAdminApiService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<NhAssistantAdminApiService>;
+}
+
+/**
+ * Applies one assistant event to a conversation and returns the new conversation.
+ * The input is never mutated, so the result can be stored in a signal directly.
+ *
+ * @param clientMessageId id of the optimistic user message of the current turn; its id is
+ * replaced by the server's `userMessageId` when `turn.started` arrives.
+ */
+declare function applyNhAssistantEvent(conversation: Conversation, event: NhAssistantSseEvent, clientMessageId?: string): Conversation;
+/** Records the user's approval decision locally until the server state is reloaded. */
+declare function applyNhAssistantApprovalDecision(conversation: Conversation, approvalId: string, decision: 'approve' | 'reject'): Conversation;
+
+/** Limits of the page context (contract 15.2). */
+declare const NH_ASSISTANT_PAGE_CONTEXT_LIMITS: {
+    readonly route: 200;
+    readonly title: 120;
+    readonly entities: 5;
+    readonly entityId: 64;
+    readonly entityLabel: 120;
+};
+/**
+ * Validates host-provided page context and truncates it to the contract limits.
+ * Returns null for an invalid shape (not an object or no route), so the message is sent
+ * without page context. Route, title and labels are truncated; entities beyond five are
+ * dropped, and entities with a type that is not dash-case, an empty id or an id longer
+ * than 64 characters are dropped because a truncated id would point at another entity.
+ */
+declare function normalizeNhAssistantClientContext(value: unknown): ClientContext | null;
+/** Short text for the page-context chip: the first entity's label, the title or the route. */
+declare function describeNhAssistantClientContext(context: ClientContext): string;
+
+/** A user-facing assistant failure: a stable code and a translation key, never raw server text. */
+interface NhAssistantError {
+    code: string;
+    messageKey: string;
+}
+/**
+ * Signal-based state of one assistant scope: availability, agents, the conversation list
+ * and the active conversation with its streamed turn.
+ */
+declare class NhAssistantStore {
+    private readonly api;
+    private readonly config;
+    private readonly injector;
+    private readonly accessPolicy;
+    private readonly accessGrantedState;
+    private readonly statusState;
+    private readonly statusLoadingState;
+    private readonly selectedAgentIdState;
+    private readonly conversationsState;
+    private readonly conversationsTotalState;
+    private readonly conversationsLoadingState;
+    private readonly activeConversationState;
+    private readonly conversationLoadingState;
+    private readonly streamingState;
+    private readonly decidingState;
+    private readonly errorState;
+    private readonly lastUsageState;
+    private readonly restoredDraftState;
+    private readonly pageContextState;
+    private readonly pageContextExcludedState;
+    private accessSubscription?;
+    private streamSubscription?;
+    private cancelTimer?;
+    private initialization?;
+    /** True when the access policy allows the user and the server reports the assistant as enabled. */
+    readonly enabled: _angular_core.Signal<boolean>;
+    readonly accessGranted: _angular_core.Signal<boolean | null>;
+    /** True when the assistant is enabled and the server reports that the caller passes the admin policy. */
+    readonly canAdminister: _angular_core.Signal<boolean>;
+    readonly statusLoading: _angular_core.Signal<boolean>;
+    readonly limits: _angular_core.Signal<{
+        maxMessageChars: number;
+        maxToolCallsPerTurn: number;
+    } | null>;
+    readonly agents: _angular_core.Signal<AgentSummary[]>;
+    readonly selectedAgentId: _angular_core.Signal<string | null>;
+    readonly selectedAgent: _angular_core.Signal<AgentSummary | null>;
+    readonly conversations: _angular_core.Signal<ConversationSummary[]>;
+    readonly conversationsTotal: _angular_core.Signal<number>;
+    readonly conversationsLoading: _angular_core.Signal<boolean>;
+    readonly activeConversation: _angular_core.Signal<Conversation | null>;
+    readonly conversationLoading: _angular_core.Signal<boolean>;
+    readonly streaming: _angular_core.Signal<boolean>;
+    readonly pendingApproval: _angular_core.Signal<ApprovalPart | null>;
+    readonly deciding: _angular_core.Signal<boolean>;
+    readonly error: _angular_core.Signal<NhAssistantError | null>;
+    readonly lastUsage: _angular_core.Signal<TurnUsage | null>;
+    /** Text of a message the server did not accept, so the composer can offer it again. */
+    readonly restoredDraft: _angular_core.Signal<string | null>;
+    /** Page context that the next message would send, for the transparency chip. */
+    readonly pageContext: _angular_core.Signal<ClientContext | null>;
+    /** True when the user left the page context out of the next message. */
+    readonly pageContextExcluded: _angular_core.Signal<boolean>;
+    /** True while the user can send: enabled, an agent is chosen and no turn runs or waits. */
+    readonly canSend: _angular_core.Signal<boolean>;
+    constructor();
+    /** Evaluates the access policy and loads the server status once. Safe to call repeatedly. */
+    initialize(): Promise<void>;
+    /** Reloads the server status, for example after the host changed the signed-in user. */
+    reloadStatus(): Promise<void>;
+    refreshConversations(): Promise<void>;
+    /** Chooses the agent for the next new conversation. Switching away from the active conversation's agent starts a new one. */
+    selectAgent(agentId: string): void;
+    /** Leaves the active conversation; the next message creates a new one. */
+    startNewConversation(): void;
+    openConversation(conversationId: string): Promise<void>;
+    deleteConversation(conversationId: string): Promise<void>;
+    /**
+     * Sends a user message. Creates a conversation with the selected agent when none is
+     * active, shows the message optimistically and applies the streamed events.
+     * Resolves `false` when the message was not accepted.
+     */
+    send(text: string): Promise<boolean>;
+    /** Approves or rejects the pending approval. Ignores repeated calls while a decision is in flight. */
+    decide(decision: ApprovalDecision, reason?: string): void;
+    /** Asks the server to stop the running turn or to abandon a waiting approval. */
+    cancel(): Promise<void>;
+    clearError(): void;
+    /** Reads the host's page context again so the chip shows what the next message sends. */
+    refreshPageContext(): Promise<void>;
+    /** Leaves the page context out of the next message only, or includes it again. */
+    setPageContextExcluded(excluded: boolean): void;
+    /** Returns and clears the draft of a message that was not accepted. */
+    consumeRestoredDraft(): string | null;
+    /**
+     * Page context for one message: `undefined` omits the field (no getter, getter failed or
+     * invalid shape), `null` sends an explicit "none" (no context or left out by the user).
+     */
+    private contextForMessage;
+    private readPageContext;
+    private startInitialization;
+    private createConversation;
+    private runStream;
+    private applyEvent;
+    private afterTurn;
+    private reloadActiveConversation;
+    private updateActive;
+    private removeMessage;
+    private selectInitialAgent;
+    private setError;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantStore, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<NhAssistantStore>;
+}
+
+/** Drawer width on wider screens; below the mobile breakpoint the panel fills the screen. */
+declare const NH_ASSISTANT_PANEL_WIDTH = "420px";
+declare const NH_ASSISTANT_PANEL_MOBILE_QUERY = "(max-width: 599.98px)";
+/**
+ * Opens and closes the assistant panel as a CDK overlay drawer on the right edge.
+ * `nh-assistant-panel` registers its content once; any component can then open the panel,
+ * optionally on a specific conversation. Escape closes the panel and focus returns to the
+ * element that opened it.
+ */
+declare class NhAssistantPanelService {
+    private readonly overlay;
+    private readonly store;
+    private readonly injector;
+    private readonly document;
+    private readonly breakpoints;
+    private readonly openState;
+    private overlayRef?;
+    private portal?;
+    private subscriptions;
+    private returnFocusTo;
+    readonly isOpen: Signal<boolean>;
+    constructor();
+    open(conversationId?: string): void;
+    close(): void;
+    toggle(): void;
+    /** Called by `nh-assistant-panel`; hosts should place that component once instead. */
+    registerPanel(portal: TemplatePortal): void;
+    unregisterPanel(portal: TemplatePortal): void;
+    private attach;
+    private ensureOverlay;
+    private updateSize;
+    private dispose;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantPanelService, never>;
+    static ɵprov: _angular_core.ɵɵInjectableDeclaration<NhAssistantPanelService>;
+}
+
+type NhAssistantIconName = 'assistant' | 'close' | 'send' | 'stop' | 'plus' | 'list' | 'trash' | 'tool' | 'check' | 'x' | 'warning' | 'chevron-down' | 'clock' | 'settings' | 'admin' | 'edit' | 'refresh' | 'link' | 'page';
+/**
+ * Optional icon classes of the host's icon library, for example `{ close: 'ph ph-x' }`.
+ * Icons without a class use the library's small built-in outline glyphs.
+ */
+declare const NH_ASSISTANT_ICONS: InjectionToken<Partial<Record<NhAssistantIconName, string>>>;
+/** Decorative icon. The surrounding control provides the accessible name. */
+declare class NhAssistantIconComponent {
+    private readonly icons;
+    readonly name: _angular_core.InputSignal<NhAssistantIconName>;
+    readonly iconClass: _angular_core.Signal<string | null>;
+    readonly path: _angular_core.Signal<string>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantIconComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantIconComponent, "nh-assistant-icon", never, { "name": { "alias": "name"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Header button that opens the assistant panel. It renders nothing while the assistant is
+ * disabled on the server or the access policy denies the user. A badge marks a conversation
+ * that waits for approval. Projected content replaces the default icon.
+ */
+declare class NhAssistantLauncherComponent {
+    readonly store: NhAssistantStore;
+    readonly panel: NhAssistantPanelService;
+    readonly waitingForApproval: _angular_core.Signal<boolean>;
+    readonly label: _angular_core.Signal<"nh-assistant.launcher.close" | "nh-assistant.launcher.open">;
+    constructor();
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantLauncherComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantLauncherComponent, "nh-assistant-launcher", never, {}, {}, never, ["*"], true, never>;
+}
+
+/**
+ * The assistant drawer. Place it once in the application layout; it renders nothing in
+ * place and appears as an overlay when `NhAssistantPanelService.open()` is called.
+ */
+declare class NhAssistantPanelComponent implements AfterViewInit, OnDestroy {
+    readonly store: NhAssistantStore;
+    readonly panel: NhAssistantPanelService;
+    private readonly config;
+    private readonly viewContainerRef;
+    private readonly router;
+    private readonly drawer;
+    private portal?;
+    readonly titleId: string;
+    readonly markdown: boolean;
+    readonly showConversations: _angular_core.WritableSignal<boolean>;
+    readonly showPreferences: _angular_core.WritableSignal<boolean>;
+    readonly adminRoute: string | any[] | null;
+    readonly conversation: _angular_core.Signal<Conversation | null>;
+    private readonly conversationId;
+    readonly messages: _angular_core.Signal<Message[]>;
+    readonly closed: _angular_core.Signal<boolean>;
+    readonly busy: _angular_core.Signal<boolean>;
+    readonly composerDisabled: _angular_core.Signal<boolean>;
+    readonly errorKeys: _angular_core.Signal<string[]>;
+    constructor();
+    ngAfterViewInit(): void;
+    ngOnDestroy(): void;
+    refreshPageContext(): void;
+    describeContext(context: ClientContext): string;
+    toggleConversations(): void;
+    togglePreferences(): void;
+    newConversation(): void;
+    openConversation(conversationId: string): void;
+    deleteConversation(conversationId: string): void;
+    send(text: string): void;
+    decide(decision: ApprovalDecision): void;
+    cancel(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantPanelComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantPanelComponent, "nh-assistant-panel", never, {}, {}, never, never, true, never>;
+}
+
+/** The user's conversations with loading and empty states; selecting one opens it. */
+declare class NhAssistantConversationListComponent {
+    readonly conversations: _angular_core.InputSignal<readonly ConversationSummary[]>;
+    readonly total: _angular_core.InputSignal<number>;
+    readonly activeConversationId: _angular_core.InputSignal<string | null>;
+    readonly loading: _angular_core.InputSignal<boolean>;
+    readonly disabled: _angular_core.InputSignal<boolean>;
+    readonly conversationSelect: _angular_core.OutputEmitterRef<string>;
+    readonly conversationDelete: _angular_core.OutputEmitterRef<string>;
+    readonly conversationCreate: _angular_core.OutputEmitterRef<void>;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantConversationListComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantConversationListComponent, "nh-assistant-conversation-list", never, { "conversations": { "alias": "conversations"; "required": true; "isSignal": true; }; "total": { "alias": "total"; "required": false; "isSignal": true; }; "activeConversationId": { "alias": "activeConversationId"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "conversationSelect": "conversationSelect"; "conversationDelete": "conversationDelete"; "conversationCreate": "conversationCreate"; }, never, never, true, never>;
+}
+
+/** Above this number of messages the thread renders through CDK virtual scrolling. */
+declare const NH_ASSISTANT_VIRTUAL_SCROLL_THRESHOLD = 200;
+/**
+ * The messages of a conversation as a live log. Assistant text renders as sanitized
+ * Markdown, tool calls and approvals as cards. The thread follows new content while the
+ * user is at the bottom.
+ */
+declare class NhAssistantThreadComponent {
+    private readonly injector;
+    readonly messages: _angular_core.InputSignal<readonly Message[]>;
+    readonly streaming: _angular_core.InputSignal<boolean>;
+    readonly deciding: _angular_core.InputSignal<boolean>;
+    readonly markdown: _angular_core.InputSignal<boolean>;
+    readonly approvalDecision: _angular_core.OutputEmitterRef<ApprovalDecision>;
+    readonly virtualThreshold = 200;
+    readonly virtual: _angular_core.Signal<boolean>;
+    readonly working: _angular_core.Signal<boolean>;
+    private readonly scroller;
+    private readonly viewport;
+    constructor();
+    trackMessage(_index: number, message: Message): string;
+    private scrollElement;
+    private scrollToEnd;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantThreadComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantThreadComponent, "nh-assistant-thread", never, { "messages": { "alias": "messages"; "required": true; "isSignal": true; }; "streaming": { "alias": "streaming"; "required": false; "isSignal": true; }; "deciding": { "alias": "deciding"; "required": false; "isSignal": true; }; "markdown": { "alias": "markdown"; "required": false; "isSignal": true; }; }, { "approvalDecision": "approvalDecision"; }, never, never, true, never>;
+}
+
+/**
+ * Message input. Enter sends, Shift+Enter inserts a new line. While the assistant runs
+ * the send button becomes a stop button.
+ */
+declare class NhAssistantComposerComponent {
+    /** Disables typing and sending, for example while a turn runs or waits for approval. */
+    readonly disabled: _angular_core.InputSignal<boolean>;
+    /** Shows the stop button instead of the send button. */
+    readonly busy: _angular_core.InputSignal<boolean>;
+    readonly maxLength: _angular_core.InputSignal<number | null>;
+    /** Text to put back into the input, for example a message the server did not accept. */
+    readonly restore: _angular_core.InputSignal<string | null>;
+    readonly send: _angular_core.OutputEmitterRef<string>;
+    readonly cancel: _angular_core.OutputEmitterRef<void>;
+    readonly restored: _angular_core.OutputEmitterRef<void>;
+    readonly inputId: string;
+    readonly hintId: string;
+    readonly text: _angular_core.WritableSignal<string>;
+    readonly length: _angular_core.Signal<number>;
+    readonly tooLong: _angular_core.Signal<boolean>;
+    readonly showCounter: _angular_core.Signal<boolean>;
+    readonly canSend: _angular_core.Signal<boolean>;
+    constructor();
+    onInput(event: Event): void;
+    onKeydown(event: KeyboardEvent): void;
+    submit(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantComposerComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantComposerComponent, "nh-assistant-composer", never, { "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "busy": { "alias": "busy"; "required": false; "isSignal": true; }; "maxLength": { "alias": "maxLength"; "required": false; "isSignal": true; }; "restore": { "alias": "restore"; "required": false; "isSignal": true; }; }, { "send": "send"; "cancel": "cancel"; "restored": "restored"; }, never, never, true, never>;
+}
+
+/** Shows one tool invocation with its status and expandable input and result previews. */
+declare class NhAssistantToolCallCardComponent {
+    readonly part: _angular_core.InputSignal<ToolCallPart>;
+    readonly detailsId: string;
+    readonly expanded: _angular_core.WritableSignal<boolean>;
+    readonly statusIcon: _angular_core.Signal<NhAssistantIconName>;
+    readonly hasDetails: _angular_core.Signal<boolean>;
+    toggle(): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantToolCallCardComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantToolCallCardComponent, "nh-assistant-tool-call-card", never, { "part": { "alias": "part"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/** Formats remaining milliseconds as `m:ss`, or `h:mm:ss` above one hour. */
+declare function formatNhAssistantCountdown(milliseconds: number): string;
+/**
+ * Asks the user to approve or reject a proposed mutation. Shows the summary, targets,
+ * proposed arguments and a countdown to expiry. A decision is emitted at most once until
+ * the host reports that it is no longer deciding.
+ */
+declare class NhAssistantApprovalCardComponent {
+    readonly approval: _angular_core.InputSignal<ApprovalPart>;
+    /** True while the host submits a decision; disables both buttons. */
+    readonly deciding: _angular_core.InputSignal<boolean>;
+    readonly decide: _angular_core.OutputEmitterRef<ApprovalDecision>;
+    private readonly now;
+    private readonly submitted;
+    readonly remainingMs: _angular_core.Signal<number>;
+    readonly expired: _angular_core.Signal<boolean>;
+    readonly effectiveStatus: _angular_core.Signal<ApprovalStatus>;
+    readonly actionable: _angular_core.Signal<boolean>;
+    readonly disabled: _angular_core.Signal<boolean>;
+    readonly countdown: _angular_core.Signal<string>;
+    constructor();
+    choose(decision: ApprovalDecision): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantApprovalCardComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantApprovalCardComponent, "nh-assistant-approval-card", never, { "approval": { "alias": "approval"; "required": true; "isSignal": true; }; "deciding": { "alias": "deciding"; "required": false; "isSignal": true; }; }, { "decide": "decide"; }, never, never, true, never>;
+}
+
+/**
+ * Chooses the agent for new conversations. Agent names come from the host's translation
+ * keys; agents created by an administrator carry literal text, which is shown as is.
+ */
+declare class NhAssistantAgentPickerComponent {
+    readonly agents: _angular_core.InputSignal<readonly AgentSummary[]>;
+    readonly selectedAgentId: _angular_core.InputSignal<string | null>;
+    readonly disabled: _angular_core.InputSignal<boolean>;
+    readonly agentChange: _angular_core.OutputEmitterRef<string>;
+    readonly selectId: string;
+    readonly selected: _angular_core.Signal<AgentSummary | null>;
+    onChange(event: Event): void;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantAgentPickerComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantAgentPickerComponent, "nh-assistant-agent-picker", never, { "agents": { "alias": "agents"; "required": true; "isSignal": true; }; "selectedAgentId": { "alias": "selectedAgentId"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; }, { "agentChange": "agentChange"; }, never, never, true, never>;
+}
+
+/** Maximum length of the user's own instructions. */
+declare const NH_ASSISTANT_MAX_CUSTOM_INSTRUCTIONS = 1000;
+/**
+ * The user's own assistant preferences: style, form of address, answer length and
+ * optional instructions. Preferences steer style only; the server keeps them below the
+ * application context and agent instructions.
+ */
+declare class NhAssistantPreferencesComponent {
+    private readonly api;
+    private subscription?;
+    /** Emitted when the user leaves the preferences. */
+    readonly closed: _angular_core.OutputEmitterRef<void>;
+    /** Emitted with the stored preferences after a successful save. */
+    readonly saved: _angular_core.OutputEmitterRef<AssistantPreferences>;
+    readonly id: string;
+    readonly styles: readonly AssistantStyle[];
+    readonly addressForms: readonly AssistantAddressForm[];
+    readonly responseLengths: readonly AssistantResponseLength[];
+    readonly maxInstructions = 1000;
+    readonly loading: _angular_core.WritableSignal<boolean>;
+    readonly loadFailed: _angular_core.WritableSignal<boolean>;
+    readonly saving: _angular_core.WritableSignal<boolean>;
+    readonly savedMessage: _angular_core.WritableSignal<boolean>;
+    readonly error: _angular_core.WritableSignal<NhAssistantError | null>;
+    readonly style: _angular_core.WritableSignal<AssistantStyle>;
+    readonly addressForm: _angular_core.WritableSignal<AssistantAddressForm>;
+    readonly responseLength: _angular_core.WritableSignal<AssistantResponseLength>;
+    readonly customInstructions: _angular_core.WritableSignal<string>;
+    private readonly stored;
+    readonly instructionsLength: _angular_core.Signal<number>;
+    readonly tooLong: _angular_core.Signal<boolean>;
+    readonly dirty: _angular_core.Signal<boolean>;
+    readonly canSave: _angular_core.Signal<boolean>;
+    readonly errorKeys: _angular_core.Signal<string[]>;
+    constructor();
+    load(): void;
+    onInstructionsInput(event: Event): void;
+    choose<T>(target: {
+        set(value: T): void;
+    }, value: T): void;
+    save(): void;
+    private apply;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantPreferencesComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantPreferencesComponent, "nh-assistant-preferences", never, {}, { "closed": "closed"; "saved": "saved"; }, never, never, true, never>;
+}
+
+/**
+ * Translates the first key that has a translation and otherwise returns the fallback text.
+ * Used for server-provided keys (agent names, error message keys, result codes) that the
+ * host may or may not translate.
+ */
+declare class NhAssistantTranslatePipe implements PipeTransform {
+    private readonly translate;
+    private lastKeys;
+    private lastParams;
+    private lastValue;
+    private dirty;
+    constructor();
+    transform(keys: string | readonly (string | null | undefined)[], fallback?: string, params?: Record<string, unknown>): string;
+    private resolve;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantTranslatePipe, never>;
+    static ɵpipe: _angular_core.ɵɵPipeDeclaration<NhAssistantTranslatePipe, "nhAssistantTranslate", true>;
+}
+
+/** Converts any failure into a user-facing code and translation key, never raw text. */
+declare function toNhAssistantError(error: unknown): NhAssistantError;
+/** Translation keys for an error, from the most to the least specific. */
+declare function nhAssistantErrorKeys(error: NhAssistantError | null): string[];
+/** Dash-case identifiers as the contract requires for agent and MCP server ids. */
+declare const NH_ASSISTANT_DASH_CASE: RegExp;
+
+export { NH_ASSISTANT_ACCESS_POLICY, NH_ASSISTANT_CONFIG, NH_ASSISTANT_FETCH, NH_ASSISTANT_ICONS, NH_ASSISTANT_MAX_CUSTOM_INSTRUCTIONS, NH_ASSISTANT_PAGE_CONTEXT_LIMITS, NH_ASSISTANT_PANEL_MOBILE_QUERY, NH_ASSISTANT_PANEL_WIDTH, NH_ASSISTANT_SSE_EVENT_TYPES, NH_ASSISTANT_TRANSLATIONS, NH_ASSISTANT_VIRTUAL_SCROLL_THRESHOLD, NhAssistantAdminApiService, NhAssistantAgentPickerComponent, NhAssistantAllowAllAccessPolicy, NhAssistantApiError, NhAssistantApiService, NhAssistantApprovalCardComponent, NhAssistantClientErrorCodes, NhAssistantComposerComponent, NhAssistantConversationListComponent, NhAssistantLauncherComponent, NhAssistantPanelComponent, NhAssistantPanelService, NhAssistantPreferencesComponent, NhAssistantSseParser, NhAssistantStore, NhAssistantThreadComponent, NhAssistantToolCallCardComponent, NhAssistantTranslationMerger, applyNhAssistantApprovalDecision, applyNhAssistantEvent, describeNhAssistantClientContext, formatNhAssistantCountdown, nhAssistantCodeForStatus, nhAssistantErrorMessageKey, normalizeNhAssistantClientContext, provideNhAssistant, NH_ASSISTANT_DASH_CASE as ɵNH_ASSISTANT_DASH_CASE, NhAssistantIconComponent as ɵNhAssistantIconComponent, NhAssistantTranslatePipe as ɵNhAssistantTranslatePipe, nhAssistantErrorKeys as ɵnhAssistantErrorKeys, toNhAssistantError as ɵtoNhAssistantError };
+export type { AdminAgent, AdminAgentInput, AgentSummary, ApplicationContext, ApplicationContextVersion, ApprovalDecision, ApprovalPart, ApprovalRequiredEvent, ApprovalStatus, AssistantAddressForm, AssistantAutonomy, AssistantErrorEvent, AssistantPreferences, AssistantResponseLength, AssistantStatus, AssistantStyle, ClientContext, ClientContextEntity, Conversation, ConversationPage, ConversationStatus, ConversationSummary, CreateConversationRequest, DecideApprovalRequest, McpAuthMode, McpServer, McpServerInput, McpServerTestResult, McpTool, McpToolEffect, McpToolStatus, Message, MessageDeltaEvent, MessagePart, NhAssistantAccessPolicy, NhAssistantClientContext, NhAssistantClientErrorCode, NhAssistantConfig, NhAssistantError, NhAssistantFetch, NhAssistantIconName, NhAssistantRawSseMessage, NhAssistantSseEvent, NhAssistantSseEventMap, NhAssistantSseEventType, NhAssistantStatusCodes, SendMessageRequest, TextPart, ToolCallPart, ToolCallStatus, ToolCatalogEffect, ToolCatalogEntry, ToolCompletedEvent, ToolStartedEvent, TurnCompletedEvent, TurnCompletionStatus, TurnStartedEvent, TurnUsage, UpdateAdminAgentRequest, UpdateApplicationContextRequest, UpdateMcpToolRequest };