@newheap/platform-ai-chat 0.8.1 → 0.9.0

package/README.md

@@ -75,6 +75,8 @@ export const appConfig: ApplicationConfig = {
 | --- | --- | --- |
 | `apiBaseUrl` | required | Base URL of the assistant endpoints. |
 | `getAccessToken` | required | Returns the bearer token or `null`. Runs in the assistant's injection context before every request, so it may use `inject(...)`. |
+| `getRequestHeaders` | none | Returns extra headers for every request and the live connection, for example `{ 'X-NH-ActiveDivisionId': divisionId }`. The library keeps `Authorization`, `Accept`, `Accept-Language` and `Content-Type`. Browsers do not send these headers with WebSockets; see `getHubQueryParameters`. |
+| `getHubQueryParameters` | none | Returns query parameters for the live-update hub URL, for values the hub needs that WebSockets and server-sent events cannot carry as headers, for example `{ divisionId }`, which the NewHeap JWT handler copies to `X-NH-ActiveDivisionId` on `/hub` paths. Runs in the assistant's injection context when the connection starts; `access_token`, `id` and `negotiateVersion` are reserved. Never return a secret. |
 | `accessPolicy` | always allowed | Injectable class whose `canUse()` returns a boolean or an observable. |
 | `defaultAgentId` | first agent | Agent selected for new conversations. |
 | `translations` | `'bundled'` | `'bundled'` merges the library's `en` and `nl` texts into `TranslateService`; `'host'` leaves all texts to the host. |
@@ -134,9 +136,26 @@ show a localized generic explanation. Tool ids, scope targets and bounded, redac
 argument previews stay inside collapsed technical details and never become the
 authorization basis.
 
+In a chat only the person whose turn waits decides its approval. In an agent thread
+(`conversation.kind === 'thread'`) the subject's approvers decide, and several proposals
+can wait at once: the server reports in `conversation.thread.decisions` whether the
+caller may decide each one. `NhAssistantStore.approvalRights` turns that into a right per
+approval card, `decide(decision, reason, approvalId)` decides a run's proposal with its
+proposal hash through `POST approvals/{id}/decisions` and reloads the thread, and cards
+the caller may not decide say who does (`waitingFor`: an approver, or another approver
+under four-eyes). Messages a trigger wrote (`authorKind: 'trigger'`) read as an event.
+Custom layouts pass `[approvalRights]` to `nh-assistant-thread` and handle
+`(approvalChoice)`, which carries the approval id.
+
+A tool call whose agent proposal closed without running no longer waits: it ends as
+`rejected`, as `not-executed` when the proposal expired, was withdrawn or became stale, or as
+`failed` when its execution failed before it started, with the result code
+`assistant-proposal-<status>`, for example `assistant-proposal-expired`. The tool-call card and
+group show `not-executed` as a finished call that did not run, never as waiting.
+
 `NhAssistantStore` exposes the state as signals (`enabled`, `agents`,
-`conversations`, `activeConversation`, `streaming`, `pendingApproval`, `error` and
-more) and the actions `send`, `submit`, `pauseQueue`, `resumeQueue`,
+`conversations`, `activeConversation`, `streaming`, `pendingApproval`, `approvalRights`,
+`error` and more) and the actions `send`, `submit`, `pauseQueue`, `resumeQueue`,
 `updateQueuedMessage`, `removeQueuedMessage`, `steerQueuedMessage`, `decide`, `cancel`, `openConversation`,
 `startNewConversation` and `selectAgent`. The building blocks
 `nh-assistant-thread`, `nh-assistant-composer`, `nh-assistant-conversation-list`,
@@ -234,9 +253,171 @@ bundle. Route to it lazily behind the host's admin permission and pass the route
   `readOnlyHint` appear as hints only, and a changed remote input schema disables the
   tool and shows a warning.
 
+Each agent card also opens the agent's feedback report (see [Proposal feedback](#proposal-feedback)).
+
 `NhAssistantAdminApiService` (main entry) is the typed client of the `admin/*`
 endpoints. A `409` becomes the code `assistant-version-conflict`.
 
+## Agent runs
+
+`@newheap/platform-ai-chat/agent-runs` shows the work of agents that run on their own.
+Load it on the routes that need it; it uses `NhAssistantAgentRunApiService` from the
+`provideNhAssistant` scope.
+
+```html
+<nh-assistant-agent-inbox agentId="intake-reviewer" subjectType="project" />
+<nh-assistant-agent-thread-view
+  agentId="intake-reviewer"
+  subjectType="project"
+  [subjectId]="projectId"
+  (openConversation)="panel.open($event)" />
+```
+
+The inbox lists the proposals waiting for the signed-in person. The thread view shows
+one agent's thread on one subject: the caller's role, a start action for participants,
+and tabs with proposals, runs, working memory and files. Proposals show the
+application's presentation and keep the tool input under technical details; approve,
+reject and resolve appear only for people who may decide, and each decision takes one
+action. The proposals, run timeline, memory and files are also separate components for
+custom layouts. Opened in the panel, the thread offers its proposals to the same people.
+**Decided by** shows the name from the subject's member snapshot (`decidedByDisplayName`)
+and falls back to the actor id.
+
+With live updates the inbox, the thread view and its tabs reload by themselves when the hub
+reports `AgentWorkChanged` for work they show, debounced, and after every reconnect. The
+update names the thread, its subject (`subjectType`, `subjectId`) and whether a run, a
+proposal or feedback changed, and carries no content;
+`NhAssistantLiveService.agentWork$` exposes it as `LiveAgentWorkChanged`. These
+reloads show no loading state, keep what is shown when they fail, wait for a decision of the
+same list that is still in flight and never drop an open feedback question. The panel reloads
+an open agent thread too, so its approval cards show decisions made in the inbox or by a
+colleague. Without a connected hub nothing changes: the Refresh buttons stay.
+
+## Agent work on your own pages
+
+Show agent work where people already look, on the application's own subjects, instead of
+only in the inbox. A list shows a badge per subject; a detail page or dialog shows the
+subject's suggestions and opens the conversation with an agent about it.
+
+```html
+<!-- A list (main entry, small): every badge on the page shares one request. -->
+@for (project of projects(); track project.id) {
+  <h3>{{ project.name }}</h3>
+  <nh-assistant-subject-badge subjectType="project" [subjectId]="project.id" />
+}
+
+<!-- A detail page or dialog: load the agent-runs entry point lazily. -->
+@defer (on viewport) {
+  <nh-assistant-subject-suggestions
+    agentId="intake-reviewer"
+    subjectType="project"
+    [subjectId]="project.id"
+    (conversationOpened)="closeDialog()" />
+} @placeholder {
+  <div class="suggestions-placeholder"></div>
+}
+```
+
+`nh-assistant-subject-badge` shows nothing while the subject has no agent work, the assistant
+is disabled or the access policy denies the user. Otherwise it shows the number of proposals
+the viewer may decide in the accent color or, when they may decide none, a neutral count of
+the open proposals, plus a small indicator while an agent works on the subject. Its tooltip
+and accessible name say both counts, for example "Proposals to decide: 2 of 3 open."
+`NhAssistantSubjectSummaryService` (main entry, provided by `provideNhAssistant`) does the
+work: every `summary(subjectType, subjectId)` asked for in the same tick becomes one
+`POST subjects/{type}/summary` per subject type, in chunks of
+`NH_ASSISTANT_MAX_SUBJECT_SUMMARY` (200). Results are cached per subject and shared by everyone
+who shows it. A live `AgentWorkChanged` refetches only the subjects it names that are shown,
+batched after a short pause, and a reconnect refetches every shown subject. Call
+`refresh(subjectType, subjectIds?)` after the application changed subjects itself.
+
+`nh-assistant-subject-suggestions` (`@newheap/platform-ai-chat/agent-runs`) loads
+`GET subjects/{type}/{id}/work` and shows the open proposals of every agent on the subject in
+`nh-assistant-agent-proposals`, each with the viewer's own live decision right. A proposal the
+viewer may not decide says who does: an approver, or another approver when four-eyes keeps out
+the person who started the work. Rejecting asks the optional feedback question, also after the
+proposal left the list. Each agent with a thread on the subject, and `agentId` also before it
+worked on the subject, gets **Open conversation** and, for participants who may start it,
+**Start the agent**. Readers open only an existing conversation. The component has loading,
+empty, unavailable (no role on the subject), error and disabled states, and reloads by itself,
+debounced, when live agent work names its subject and after every reconnect.
+
+Custom layouts pass per-proposal rights to the proposals list themselves. A right overrides
+`canDecide` for its proposal:
+
+```typescript
+const work = await firstValueFrom(agentRuns.getSubjectWork('project', projectId, 'intake-reviewer'));
+const rights = new Map(work.openProposals.map(item => [item.proposal.approvalId, item]));
+```
+
+```html
+<nh-assistant-agent-proposals [proposals]="proposals" [decisionRights]="rights" (changed)="reload()" />
+```
+
+Open the conversation about a subject from your own code with
+`NhAssistantPanelService.openSubject(agentId, { type, id })`. It calls `POST threads/open`,
+which returns the agent's thread about the subject and creates it without starting a run, so
+nothing costs model time until someone types. Creating needs the participant role. The promise
+resolves with the `AgentThreadLookup` once the panel opens the conversation, and rejects with
+`NhAssistantApiError` (for example `assistant-subject-access-denied`) without opening the panel,
+so show its `messageKey` where the person asked:
+
+```typescript
+try {
+  await this.panel.openSubject('intake-reviewer', { type: 'project', id: projectId });
+} catch (error) {
+  this.error.set(error instanceof NhAssistantApiError ? error.messageKey : 'nh-assistant.errors.generic');
+}
+```
+
+The panel is a CDK overlay drawer. A host dialog on a higher layer closes when the conversation
+opens, as the suggestions' `conversationOpened` output allows, or raises the overlay container.
+`NhAssistantAgentRunApiService` offers the endpoints as `getSubjectWork`, `summarizeSubjects` and
+`openThread`. The SampleProjectManagement management portal shows badges in its project
+directory and the suggestions in its project dialog (sample case SPM-280).
+
+## Proposal feedback
+
+People who reject an agent proposal may say what was wrong. The question is optional,
+comes after the rejection and never blocks it:
+
+- After a reject, single or bulk, `nh-assistant-agent-proposals` shows
+  `nh-assistant-proposal-feedback` above the list, also when the inbox drops the rejected
+  proposals. Skip removes it; a saved answer thanks the person and emits `changed`.
+- Closed proposals with `canGiveFeedback` keep a low-key **Give feedback** action
+  (**Change feedback** once `feedback` holds the caller's own answer), and the card shows
+  that answer.
+- In the panel, the approval card of a proposal the user rejected in this session offers
+  **What was wrong?** (`NhAssistantApprovalRight.canGiveFeedback`). Chat approvals never ask.
+
+The answer is a category from `NH_ASSISTANT_FEEDBACK_CATEGORIES` (`incorrect`,
+`wrong-value`, `not-needed`, `not-now`, `already-done`, `not-allowed`, `other`) plus an
+optional text of at most 1,000 characters. `not-now` and `already-done` mean "right, but
+not now" and never count as the agent being wrong. One proposal is sent with
+`NhAssistantAgentRunApiService.giveFeedback` (`PUT approvals/{id}/feedback`), proposals
+rejected together once with `giveFeedbackMany` (`POST approvals/feedback`), stored per
+proposal as bulk feedback. Custom layouts use the component directly:
+
+```html
+<nh-assistant-proposal-feedback [approvalIds]="[approvalId]" [initial]="proposal.feedback" (saved)="reload()" (dismissed)="close()" />
+```
+
+Administrators read the answers per agent in `nh-assistant-agent-feedback-report` from
+`@newheap/platform-ai-chat/admin`, also on its own:
+
+```html
+<nh-assistant-agent-feedback-report agentId="intake-reviewer" />
+```
+
+It shows, per tool and agent version, the approved, rejected and expired proposals, the
+rejection rate, the rejections with feedback, the number of different people and the most
+frequent categories, followed by the feedback itself with its author's name
+(`authorDisplayName`, falling back to the actor id), filtered by period, tool and category,
+and an export as JSON Lines. Comparing agent versions shows whether a change to the prompt,
+tools or policy helped. `NhAssistantAdminApiService.getAgentFeedbackSummary`,
+`getAgentFeedback` and `exportAgentFeedback` are the typed client; the server requires the
+admin policy, reports only the caller's scopes and audits the export, which holds subject data.
+
 ## Theme
 
 The components define light and dark defaults and follow `prefers-color-scheme`.
@@ -325,7 +506,8 @@ providers: [
 Steps are `text`, `tool`, `approval`, `error` and `fail`. The optional `preferences`
 and `admin` parts of the scenario seed the preference and administration endpoints:
 context, tool catalog, agents, MCP servers with simulated remote tools, known
-policies and hosts that may receive the user's token. The mock answers every
+policies and hosts that may receive the user's token. Agents of the mock never run
+on their own, so their feedback report is empty. The mock answers every
 endpoint in memory and sends each turn as contract events over a chunked
 `text/event-stream` response, so the real client, parser and store run unchanged.
 Inject `NhAssistantMockBackend` to switch the simulated feature flag with

package/admin/index.d.ts

@@ -1,5 +1,5 @@
 import * as _angular_core from '@angular/core';
-import { NhAssistantStore, NhAssistantError, ApplicationContext, ApplicationContextVersion, AdminAgent, ToolCatalogEntry, McpServer, AssistantAutonomy, McpServerTestResult, McpAuthMode, McpToolEffect, McpTool } from '@newheap/platform-ai-chat';
+import { NhAssistantStore, NhAssistantError, ApplicationContext, ApplicationContextVersion, AdminAgent, ToolCatalogEntry, McpServer, AssistantAutonomy, AgentProposalFeedbackCategory, AgentFeedbackSummaryRow, AgentFeedbackItem, AgentFeedbackCategoryCount, AgentProposalFeedbackGroup, McpServerTestResult, McpAuthMode, McpToolEffect, McpTool } from '@newheap/platform-ai-chat';
 
 type NhAssistantAdminTab = 'context' | 'agents' | 'mcp-servers';
 /**
@@ -61,11 +61,15 @@ declare class NhAssistantAdminContextComponent {
 
 /**
  * Agent administration: code agents (override, disable, reset) and agents created here
- * (edit, disable, delete). Editing opens `nh-assistant-admin-agent-editor`.
+ * (edit, disable, delete). Editing opens `nh-assistant-admin-agent-editor`; the feedback action
+ * opens `nh-assistant-agent-feedback-report` for the agent.
  */
 declare class NhAssistantAdminAgentsComponent {
     private readonly admin;
     private readonly store;
+    private readonly injector;
+    private readonly host;
+    private readonly backButton;
     private subscription?;
     private actionSubscription?;
     readonly id: string;
@@ -76,6 +80,8 @@ declare class NhAssistantAdminAgentsComponent {
     readonly servers: _angular_core.WritableSignal<McpServer[]>;
     /** `undefined`: list; `null`: new agent; an agent: editing that agent. */
     readonly editing: _angular_core.WritableSignal<AdminAgent | null | undefined>;
+    /** The agent whose feedback report is shown instead of the list. */
+    readonly reporting: _angular_core.WritableSignal<AdminAgent | null>;
     readonly confirming: _angular_core.WritableSignal<{
         agentId: string;
         action: "delete" | "reset";
@@ -87,6 +93,10 @@ declare class NhAssistantAdminAgentsComponent {
     load(): void;
     create(): void;
     edit(agent: AdminAgent): void;
+    /** Shows what people said when they rejected the agent's proposals. */
+    openReport(agent: AdminAgent): void;
+    /** Returns to the list and to the feedback action of the agent whose report was open. */
+    closeReport(): void;
     onSaved(agent: AdminAgent): void;
     setEnabled(agent: AdminAgent, isEnabled: boolean): void;
     confirm(agentId: string, action: 'delete' | 'reset'): void;
@@ -158,6 +168,71 @@ declare class NhAssistantAdminAgentEditorComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantAdminAgentEditorComponent, "nh-assistant-admin-agent-editor", never, { "agent": { "alias": "agent"; "required": false; "isSignal": true; }; "tools": { "alias": "tools"; "required": false; "isSignal": true; }; "servers": { "alias": "servers"; "required": false; "isSignal": true; }; }, { "saved": "saved"; "cancelled": "cancelled"; }, never, never, true, never>;
 }
 
+/** Periods the report offers, in days before now. */
+type NhAssistantFeedbackPeriod = 7 | 30 | 90;
+/** A summary row with its most frequent feedback categories. */
+interface NhAssistantFeedbackSummaryView extends AgentFeedbackSummaryRow {
+    topCategories: AgentFeedbackCategoryCount[];
+}
+/**
+ * What people said when they rejected an agent's proposals, for the agent's administrators: per
+ * tool and agent version the decisions, the rejection rate, the share of rejections with feedback,
+ * the number of different people and the most frequent categories, followed by the feedback itself
+ * and a JSON Lines export. Comparing agent versions shows whether a change to the prompt, tools or
+ * policy helped. The server requires the assistant admin policy and reports only the caller's scopes.
+ */
+declare class NhAssistantAgentFeedbackReportComponent {
+    private readonly admin;
+    private readonly document;
+    private summarySubscription?;
+    private listSubscription?;
+    readonly agentId: _angular_core.InputSignal<string>;
+    /** Feedback per page; the server allows at most 100. */
+    readonly itemsPerPage: _angular_core.InputSignal<number>;
+    readonly id: string;
+    readonly periods: readonly NhAssistantFeedbackPeriod[];
+    readonly categories: readonly AgentProposalFeedbackCategory[];
+    readonly period: _angular_core.WritableSignal<NhAssistantFeedbackPeriod>;
+    readonly toolId: _angular_core.WritableSignal<string>;
+    readonly category: _angular_core.WritableSignal<"" | AgentProposalFeedbackCategory>;
+    readonly page: _angular_core.WritableSignal<number>;
+    readonly summaryLoading: _angular_core.WritableSignal<boolean>;
+    readonly summaryError: _angular_core.WritableSignal<NhAssistantError | null>;
+    readonly summaryErrorKeys: _angular_core.Signal<string[]>;
+    readonly rows: _angular_core.WritableSignal<AgentFeedbackSummaryRow[]>;
+    readonly listLoading: _angular_core.WritableSignal<boolean>;
+    readonly listError: _angular_core.WritableSignal<NhAssistantError | null>;
+    readonly listErrorKeys: _angular_core.Signal<string[]>;
+    readonly items: _angular_core.WritableSignal<AgentFeedbackItem[]>;
+    readonly total: _angular_core.WritableSignal<number>;
+    readonly pages: _angular_core.Signal<number>;
+    readonly exporting: _angular_core.WritableSignal<boolean>;
+    readonly exportError: _angular_core.WritableSignal<NhAssistantError | null>;
+    readonly exportErrorKeys: _angular_core.Signal<string[]>;
+    readonly canExport: _angular_core.Signal<boolean>;
+    /** Tools with proposals in the period, plus the chosen tool when the period has none of it. */
+    readonly tools: _angular_core.Signal<string[]>;
+    readonly visibleRows: _angular_core.Signal<NhAssistantFeedbackSummaryView[]>;
+    readonly filtered: _angular_core.Signal<boolean>;
+    /** The period the last load asked for, so the list, summary and export agree. */
+    private range;
+    constructor();
+    /** Reloads the summary and the first page of feedback for the chosen period. */
+    load(): void;
+    onPeriod(event: Event): void;
+    onTool(event: Event): void;
+    onCategory(event: Event): void;
+    goTo(page: number): void;
+    loadSummary(): void;
+    loadList(): void;
+    /** Downloads the feedback of the period and filters as a JSON Lines file. */
+    export(): Promise<void>;
+    /** Badge color of a feedback group: wrong and not allowed are failures, not now is a warning. */
+    groupClass(group: AgentProposalFeedbackGroup): string;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantAgentFeedbackReportComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantAgentFeedbackReportComponent, "nh-assistant-agent-feedback-report", never, { "agentId": { "alias": "agentId"; "required": true; "isSignal": true; }; "itemsPerPage": { "alias": "itemsPerPage"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
 /** Result of the latest connection test per server. */
 interface TestState {
     running: boolean;
@@ -290,5 +365,5 @@ declare class NhAssistantAdminMcpToolsComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantAdminMcpToolsComponent, "nh-assistant-admin-mcp-tools", never, { "server": { "alias": "server"; "required": true; "isSignal": true; }; }, { "closed": "closed"; "synced": "synced"; }, never, never, true, never>;
 }
 
-export { NH_ASSISTANT_MAX_INSTRUCTIONS, NhAssistantAdminAgentEditorComponent, NhAssistantAdminAgentsComponent, NhAssistantAdminComponent, NhAssistantAdminContextComponent, NhAssistantAdminMcpServerEditorComponent, NhAssistantAdminMcpServersComponent, NhAssistantAdminMcpToolsComponent, nhAssistantSelectorMatches };
-export type { NhAssistantAdminTab, NhAssistantSecretAction };
+export { NH_ASSISTANT_MAX_INSTRUCTIONS, NhAssistantAdminAgentEditorComponent, NhAssistantAdminAgentsComponent, NhAssistantAdminComponent, NhAssistantAdminContextComponent, NhAssistantAdminMcpServerEditorComponent, NhAssistantAdminMcpServersComponent, NhAssistantAdminMcpToolsComponent, NhAssistantAgentFeedbackReportComponent, nhAssistantSelectorMatches };
+export type { NhAssistantAdminTab, NhAssistantFeedbackPeriod, NhAssistantSecretAction };