NewHeap.Platform.AI.Chat.AspNet 7.6.0

NewHeap.Platform.AI.Chat.AspNet

ASP.NET Core assistant endpoints with server-sent event streaming and approval decisions for NewHeap AI.

Registration

Register the application's AI services and AddNewHeapPlatformAIAspNet first, then the assistant, and map the endpoints:

services.AddNewHeapPlatformAIAspNet(ai => ai.AddActiveDivisionScope("app.active-division.project.view"));
services.AddNewHeapAssistant(assistant => assistant
    .UsePostgreSql(connectionString, options => { options.Schema = "nhai"; options.RunMigrations = true; })
    .UseAccessPolicy("app.assistant.access")
    .UseChatProfile("project-assistant-chat")
    .UseAdminPolicy("app.assistant.admin")
    .UseDefaultApplicationContext(applicationContextAsset)
    .UseTimeZone("Europe/Amsterdam")
    .UseTurnContextProvider<ApplicationTurnContextProvider>()
    .ConfigureMcp(mcp => mcp.AllowedHosts.Add("planning.example.com"))
    .AddAgent(agent)
    .AddToolPresenter<ApplicationAssistantToolPresenter>()
    .AddBusinessAuditSink<ApplicationAssistantAuditSink>()
    .WithLimits(limits => limits.MaxToolCallsPerTurn = 8));

endpoints.MapNewHeapAssistant("/api/assistant");

Startup fails when the ASP.NET AI integration, the access or admin policy, an agent profile or policy is missing, or when the invocation gate or a durable manager was replaced after the assistant. AddNewHeapAssistant is idempotent. The assistant relies on the registered INhAiAuthenticatedInvocationContextResolver; a replaced resolver is used as is, and no tenant claim is required.

INhAssistantToolPresenter is optional. Use it for application-localized names and approval explanations sourced from authorized server-side data. Presentation is persisted beside, but never substituted for, the exact proposal evidence. The API returns it as optional approval.presentation; clients must support null for old approvals and tools without a presenter.

Configuration

Endpoints

Administration endpoints additionally require the admin policy:

Every error of preferences and admin/* has the body { code, messageKey, errors? }. Validation errors return 400 with code assistant-validation and errors keyed by camelCase field name (values required, invalid, too-long, not-found); blocked hosts return 400 with assistant-mcp-host-blocked. A caller without the admin policy receives 403 with assistant-forbidden, unknown objects 404 with a specific *-not-found code and stale versions 409. MCP secrets are protected with ASP.NET Data Protection; persist the key ring across restarts and nodes.

clientContext is { route, title?, entities?: [{ type, id, label? }] } (route 200, title 120, five entities, dash-case type, id 64, label 120 characters). The server cuts off long text and ignores a value of the wrong shape instead of answering 400.

JSON is camelCase through one source-generated NhAssistantJsonSerializerContext. Errors outside the stream use { code, messageKey } with messageKey = nh-assistant.errors.<code>. Conversations are visible to their owner only; other callers receive 404.

Streaming

Each event is written as event: <name>, data: <json> and an empty line: turn.started, message.delta, tool.started, tool.completed, approval.required, turn.completed or error. A : keep-alive comment follows every 15 seconds without events, and the stream closes after turn.completed or error. Response buffering is disabled and X-Accel-Buffering: no is set for reverse proxies. A client disconnect cancels the turn and releases the conversation. Browser clients use fetch streaming, because EventSource cannot send an Authorization header.