@newheap/platform-ai-chat 0.10.0 → 0.11.0

package/index.d.ts

@@ -12,12 +12,14 @@ import { TemplatePortal } from '@angular/cdk/portal';
 type AgentSubjectRole = 'none' | 'reader' | 'participant' | 'approver';
 type AgentRunStatus = 'queued' | 'running' | 'waiting-for-approval' | 'completed' | 'failed' | 'cancelled';
 type AgentProposalStatus = 'pending' | 'approved' | 'rejected' | 'expired' | 'withdrawn' | 'stale' | 'executing' | 'executed' | 'execution-failed' | 'execution-unknown' | 'resolved' | 'shadow';
-type AgentGrantSource = 'none' | 'delegated' | 'agent';
+type AgentGrantSource = 'none' | 'delegated' | 'agent' | 'delegated-read';
 /**
  * How a run worked: `model` through the language model, `rule` through the agent's rules without a
  * model, `rule-then-model` when the rules handed the run over to the model.
  */
 type AgentRunKind = 'model' | 'rule' | 'rule-then-model';
+/** Who chose the skill a run worked in. */
+type AgentSkillChooser = 'trigger' | 'rules' | 'triage' | 'model';
 interface AgentRun {
     id: string;
     conversationId: string;
@@ -41,6 +43,18 @@ interface AgentRun {
     backgroundOperationId: string | null;
     /** How the run worked. Missing on older servers, which only ran the model. */
     kind?: AgentRunKind;
+    /** The skill of the agent the run worked in; missing or null for the agent's own tools. */
+    skill?: string | null;
+    skillChosenBy?: AgentSkillChooser | null;
+    /** The agent that handed the run's work off; missing or null for a run no agent asked for. */
+    requestedByAgentId?: string | null;
+    /**
+     * The thread of the run that handed the work off, only in a thread's run list and only when the
+     * reader may open it.
+     */
+    requestedByConversationId?: string | null;
+    /** How many hand-offs led to the run; 0 or missing for a run no agent asked for. */
+    handOffDepth?: number;
 }
 interface AgentRunList {
     items: AgentRun[];
@@ -473,9 +487,12 @@ interface ToolCallPart {
     argumentsPreview: string | null;
     resultPreview: string | null;
     resultCode: string | null;
-    /** `delegated` or `agent` when an agent used rights beyond the caller's own. */
-    grantSource?: 'delegated' | 'agent' | null;
-    /** The result came from the agent's own grant and is shielded from this viewer. */
+    /**
+     * `delegated`, `agent` or `delegated-read` when an agent used rights beyond the caller's own:
+     * the initiator's, its own grant, or a person's through a gateway read.
+     */
+    grantSource?: 'delegated' | 'agent' | 'delegated-read' | null;
+    /** The result came from rights this viewer does not have and is shielded from them. */
     restricted?: boolean;
 }
 /**
@@ -769,18 +786,81 @@ interface AdminAgentInput {
     mcpServerIds: string[];
     requiredPolicy: string | null;
     autonomy: AssistantAutonomy;
-    isEnabled: boolean;
+    /**
+     * @deprecated Accepted and ignored by the server until the next major version: pause, stop and
+     * resume an agent with `setAgentState`. A new agent starts active.
+     */
+    isEnabled?: boolean;
 }
 /** Body of `PUT admin/agents/{id}`. */
 type UpdateAdminAgentRequest = AdminAgentInput & {
     expectedVersion: number;
 };
+/**
+ * The run state of an agent. `paused`: no new runs; events wait and run after the resume.
+ * `stopped`: active runs were cancelled and events are refused. `configured-off`: disabled in the
+ * application's code until the next deployment; it cannot be resumed here.
+ */
+type AgentRunState = 'active' | 'paused' | 'stopped' | 'configured-off';
 interface AdminAgent extends AdminAgentInput {
+    /** `false` while the agent is stopped; read `runState` for the full state. */
+    isEnabled: boolean;
     version: number;
     source: 'code' | 'admin';
     isOverridden: boolean;
     instructionsHash: string;
     updatedAt: string;
+    runState: AgentRunState;
+    stateChangedAt: string | null;
+    stateChangedBy: string | null;
+    stateReason: string | null;
+    /** Events that wait while the agent is paused. */
+    waitingInputs: number;
+    /** The agent's skills with their states and today's usage; missing or empty without skills. */
+    skills?: AgentSkillState[];
+    /** The live agent this agent is a shadow variant of; missing or null for an agent that is no variant. */
+    shadowOf?: string | null;
+}
+/** One skill of an agent with its own state and today's usage across scopes. */
+interface AgentSkillState {
+    skillId: string;
+    description: string;
+    runState: 'active' | 'paused' | 'stopped';
+    changedAt: string | null;
+    changedBy: string | null;
+    reason: string | null;
+    /** Events that wait for the skill while it is paused. */
+    waitingInputs: number;
+    toolCallsToday: number;
+    tokensToday: number;
+    /** The skill's daily budget per scope, when it has one. */
+    dailyToolCalls: number | null;
+    dailyTokens: number | null;
+    cancelledRuns: number;
+    startedRuns: number;
+}
+/** Response of `GET` and `POST admin/agents/{id}/state`. */
+interface AgentState {
+    agentId: string;
+    runState: AgentRunState;
+    /** Whether the agent works now: active, enabled in code and the assistant enabled. */
+    active: boolean;
+    changedAt: string | null;
+    changedBy: string | null;
+    reason: string | null;
+    waitingInputs: number;
+    /** The runs this change cancelled by stopping the agent. */
+    cancelledRuns: number;
+    /** The runs this change started for waiting events by resuming the agent. */
+    startedRuns: number;
+    skills?: AgentSkillState[];
+    shadowOf?: string | null;
+}
+/** Body of `POST admin/agents/{id}/state`. `active` resumes the agent. */
+interface SetAgentStateRequest {
+    state: 'active' | 'paused' | 'stopped';
+    /** Optional, at most 500 characters. */
+    reason?: string | null;
 }
 type McpAuthMode = 'none' | 'bearer' | 'api-key' | 'forward-user-token';
 interface McpServerInput {
@@ -853,6 +933,126 @@ interface AgentFeedbackListFilter extends AgentFeedbackFilter {
     itemsPerPage?: number;
 }
 /** Filter of `GET admin/agents/{id}/feedback/export`. */
+/** Query of `GET admin/agents/{id}/evaluation` and its export. */
+interface AgentEvaluationFilter {
+    /** The shadow variant to compare with the agent. */
+    variant: string;
+    /** Start of the period as an ISO 8601 date-time; seven days before `to` by default. */
+    from?: string;
+    /** End of the period, exclusive; now by default. The period spans at most 92 days. */
+    to?: string;
+}
+/**
+ * Response of `GET admin/agents/{id}/evaluation`: how a shadow variant compared with its live
+ * agent. Counts, identifiers and links only; no messages or arguments.
+ */
+interface AgentEvaluation {
+    agentId: string;
+    variantId: string;
+    from: string;
+    to: string;
+    runs: AgentEvaluationRuns;
+    tools: AgentEvaluationTool[];
+    liveCost: AgentEvaluationCost;
+    variantCost: AgentEvaluationCost;
+    routing: AgentEvaluationRouting[];
+    /** Proposals only one of the two made, with the runs and threads to read; at most 50. */
+    differences: AgentEvaluationDifference[];
+}
+interface AgentEvaluationRuns {
+    live: number;
+    variant: number;
+    /** Pairs of runs that handled the same event or that a replay repeated. */
+    paired: number;
+    /** Pairs whose variant run replayed the live run; it saw today's state of the subject. */
+    replayed: number;
+    liveUnpaired: number;
+    variantUnpaired: number;
+    /** The period held more runs than one evaluation reads; it covers the oldest. */
+    truncated: boolean;
+}
+interface AgentEvaluationTool {
+    toolId: string;
+    agreed: number;
+    liveOnly: number;
+    variantOnly: number;
+    liveDecisions: AgentEvaluationDecisions;
+    /** Live proposals people rejected that the variant did not make. */
+    rejectedLiveNotProposed: number;
+    /** Live proposals people rejected that the variant made too. */
+    rejectedLiveAlsoProposed: number;
+    /** Live proposals people approved that the variant did not make. */
+    approvedLiveMissed: number;
+}
+interface AgentEvaluationDecisions {
+    pending: number;
+    approved: number;
+    /** Executed, including failed and uncertain executions. */
+    executed: number;
+    rejected: number;
+    stale: number;
+    /** Expired and withdrawn proposals. */
+    other: number;
+    /** Feedback categories of rejected proposals and how often people chose them. */
+    rejectionCategories: Record<string, number>;
+}
+interface AgentEvaluationCost {
+    runs: number;
+    modelCalls: number;
+    tokens: number;
+    toolCalls: number;
+    averageModelCalls: number;
+    averageTokens: number;
+    averageToolCalls: number;
+    p95ModelCalls: number;
+    p95Tokens: number;
+    p95ToolCalls: number;
+}
+interface AgentEvaluationRouting {
+    /** `null` is the agent's own tools. */
+    liveSkill: string | null;
+    variantSkill: string | null;
+    runs: number;
+}
+interface AgentEvaluationDifference {
+    toolId: string;
+    kind: 'live-only' | 'variant-only';
+    /** What people decided about a live-only proposal. */
+    liveStatus: string | null;
+    liveRunId: string;
+    liveConversationId: string;
+    variantRunId: string;
+    variantConversationId: string;
+    replayed: boolean;
+}
+/** Body of `POST admin/agents/{id}/replay`. */
+interface AgentReplayRequest {
+    /** The agent whose runs to replay; the variant's live agent by default. */
+    sourceAgentId?: string | null;
+    from?: string | null;
+    to?: string | null;
+    /** 1 to 500; 100 by default. */
+    maxRuns?: number | null;
+}
+/** A replay of recorded runs into a shadow variant. */
+interface AgentReplay {
+    id: string;
+    variantAgentId: string;
+    sourceAgentId: string;
+    from: string;
+    to: string;
+    maxRuns: number;
+    status: 'running' | 'completed' | 'stopped';
+    /** Why a stopped replay stopped, such as `assistant-budget-exhausted`. */
+    stopReason: string | null;
+    runsReplayed: number;
+    runsSkipped: number;
+    createdAt: string;
+    endedAt: string | null;
+}
+interface AgentReplayList {
+    items: AgentReplay[];
+}
 interface AgentFeedbackExportFilter extends AgentFeedbackFilter {
     category?: AgentProposalFeedbackCategory;
     /** Maximum number of records; the server defaults to 10,000 and allows at most 50,000. */
@@ -1197,9 +1397,19 @@ declare class NhAssistantAdminApiService {
     getAgents(): Observable<AdminAgent[]>;
     createAgent(input: AdminAgentInput): Observable<AdminAgent>;
     updateAgent(agentId: string, request: UpdateAdminAgentRequest): Observable<AdminAgent>;
-    /** Restores a code agent to its definition in code. */
+    /** Restores a code agent to its definition in code. The run state stays as it is. */
     resetAgent(agentId: string): Observable<AdminAgent>;
-    /** Deletes an admin agent. Code agents cannot be deleted; disable them instead. */
+    getAgentState(agentId: string): Observable<AgentState>;
+    /**
+     * Pauses, stops or resumes an agent without changing its definition. A code-disabled agent
+     * cannot be resumed (`assistant-agent-configured-off`).
+     */
+    setAgentState(agentId: string, request: SetAgentStateRequest): Observable<AgentState>;
+    /**
+     * Pauses, stops or resumes one skill of an agent; its other skills keep working.
+     */
+    setSkillState(agentId: string, skillId: string, request: SetAgentStateRequest): Observable<AgentSkillState>;
+    /** Deletes an admin agent. Code agents cannot be deleted; stop them instead. */
     deleteAgent(agentId: string): Observable<void>;
     getMcpServers(): Observable<McpServer[]>;
     createMcpServer(input: McpServerInput): Observable<McpServer>;
@@ -1223,6 +1433,24 @@ declare class NhAssistantAdminApiService {
      * subject data and the server audits the export. Rejects with `NhAssistantApiError`.
      */
     exportAgentFeedback(agentId: string, filter?: AgentFeedbackExportFilter): Promise<Blob>;
+    /**
+     * Compares a shadow variant with its live agent over a period: the runs that handled the same
+     * events, the proposals per tool with what people decided about the live ones, cost and routing.
+     */
+    getAgentEvaluation(agentId: string, filter: AgentEvaluationFilter): Observable<AgentEvaluation>;
+    /**
+     * Downloads the paired runs of the comparison as JSON Lines: identifiers, statuses, usage and
+     * proposal identities, no content. The server audits the export. Rejects with `NhAssistantApiError`.
+     */
+    exportAgentEvaluation(agentId: string, filter: AgentEvaluationFilter): Promise<Blob>;
+    /**
+     * Replays the recorded runs of another agent in a period into a shadow variant, against today's
+     * state of each subject. One replay runs per variant (`assistant-replay-active`).
+     */
+    startAgentReplay(variantId: string, request: AgentReplayRequest): Observable<AgentReplay>;
+    /** The latest replays into a shadow variant, newest first. */
+    getAgentReplays(variantId: string): Observable<AgentReplayList>;
+    private download;
     private request;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantAdminApiService, never>;
     static ɵprov: _angular_core.ɵɵInjectableDeclaration<NhAssistantAdminApiService>;
@@ -2505,4 +2733,4 @@ declare function nhAssistantErrorKeys(error: NhAssistantError | null): string[];
 declare const NH_ASSISTANT_DASH_CASE: RegExp;
 
 export { NH_ASSISTANT_ACCESS_POLICY, NH_ASSISTANT_CONFIG, NH_ASSISTANT_CONVERSATION_FRAGMENT, NH_ASSISTANT_FEEDBACK_CATEGORIES, NH_ASSISTANT_FEEDBACK_GROUPS, NH_ASSISTANT_FETCH, NH_ASSISTANT_ICONS, NH_ASSISTANT_JOIN_FRAGMENT, NH_ASSISTANT_MAX_BULK_FEEDBACK, NH_ASSISTANT_MAX_CUSTOM_INSTRUCTIONS, NH_ASSISTANT_MAX_FEEDBACK_TEXT, NH_ASSISTANT_MAX_PROPOSAL_LOOKUP, NH_ASSISTANT_MAX_SUBJECT_SUMMARY, NH_ASSISTANT_NO_ANSWER_NOTICE_CODE, 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, NhAssistantActivityComponent, NhAssistantAdminApiService, NhAssistantAgentPickerComponent, NhAssistantAgentRunApiService, NhAssistantAllowAllAccessPolicy, NhAssistantApiError, NhAssistantApiService, NhAssistantApprovalCardComponent, NhAssistantClientErrorCodes, NhAssistantComposerComponent, NhAssistantConversationListComponent, NhAssistantLauncherComponent, NhAssistantLiveService, NhAssistantPanelComponent, NhAssistantPanelService, NhAssistantPreferencesComponent, NhAssistantProposalFeedbackComponent, NhAssistantPushService, NhAssistantShareComponent, NhAssistantSseParser, NhAssistantStore, NhAssistantSubjectBadgeComponent, NhAssistantSubjectSummaryService, NhAssistantThreadComponent, NhAssistantToolCallCardComponent, NhAssistantToolCallGroupComponent, NhAssistantTranslationMerger, applyNhAssistantApprovalDecision, applyNhAssistantConversationChange, applyNhAssistantEvent, applyNhAssistantLiveEvent, describeNhAssistantClientContext, formatNhAssistantCountdown, nhAssistantCodeForStatus, nhAssistantErrorMessageKey, nhAssistantIsUnread, nhAssistantLatestTurnHasText, nhAssistantShareLink, normalizeNhAssistantClientContext, provideNhAssistant, NH_ASSISTANT_DASH_CASE as ɵNH_ASSISTANT_DASH_CASE, NhAssistantIconComponent as ɵNhAssistantIconComponent, NhAssistantTranslatePipe as ɵNhAssistantTranslatePipe, nhAssistantErrorKeys as ɵnhAssistantErrorKeys, nhAssistantReloadOnAgentWork as ɵnhAssistantReloadOnAgentWork, toNhAssistantError as ɵtoNhAssistantError };
-export type { AdminAgent, AdminAgentInput, AgentArtifact, AgentConsultation, AgentConsultationList, AgentConsultationStatus, AgentDecisionOutcome, AgentExecutionResolution, AgentFeedbackCategoryCount, AgentFeedbackExportFilter, AgentFeedbackFilter, AgentFeedbackItem, AgentFeedbackList, AgentFeedbackListFilter, AgentFeedbackOutcome, AgentFeedbackSummary, AgentFeedbackSummaryRow, AgentGrantSource, AgentInbox, AgentInboxFilter, AgentInvalidationCount, AgentProposal, AgentProposalDecision, AgentProposalDecisionRight, AgentProposalFeedback, AgentProposalFeedbackCategory, AgentProposalFeedbackGroup, AgentProposalLookup, AgentProposalObject, AgentProposalStatus, AgentRun, AgentRunKind, AgentRunList, AgentRunRetryMode, AgentRunStatus, AgentSubjectRole, AgentSubjectSummary, AgentSubjectSummaryList, AgentSubjectWork, AgentSubjectWorkAgent, AgentSubjectWorkProposal, AgentSummary, AgentThread, AgentThreadLookup, AgentThreadMemory, AgentTriggerReceipt, ApplicationContext, ApplicationContextVersion, ApprovalDecision, ApprovalPart, ApprovalPresentation, ApprovalPresentationField, ApprovalRequiredEvent, ApprovalStatus, AssistantAddressForm, AssistantAutonomy, AssistantCollaboration, AssistantErrorEvent, AssistantPreferences, AssistantResponseLength, AssistantStatus, AssistantStyle, ClientContext, ClientContextEntity, Conversation, ConversationKind, ConversationMember, ConversationPage, ConversationRole, ConversationStatus, ConversationSummary, ConversationThread, ConversationThreadDecision, CreateConversationRequest, DecideApprovalRequest, DirectoryEntry, LiveAgentWorkChanged, LiveAgentWorkReason, LiveConversationChanged, LiveConversationEvent, LiveConversationRead, LiveConversationRemoved, McpAuthMode, McpServer, McpServerInput, McpServerTestResult, McpTool, McpToolEffect, McpToolStatus, Message, MessageAuthorKind, MessageDeltaEvent, MessagePart, NhAssistantAccessPolicy, NhAssistantActivity, NhAssistantApprovalChoice, NhAssistantApprovalRight, NhAssistantApprovalWaitingFor, NhAssistantClientContext, NhAssistantClientErrorCode, NhAssistantConfig, NhAssistantError, NhAssistantFetch, NhAssistantIconName, NhAssistantLiveState, NhAssistantNotice, NhAssistantProposalFeedbackSaved, NhAssistantPushConfig, NhAssistantPushState, NhAssistantQueuedMessage, NhAssistantRawSseMessage, NhAssistantSseEvent, NhAssistantSseEventMap, NhAssistantSseEventType, NhAssistantStatusCodes, NhAssistantToolCallGroupState, NotificationSettings, PushSubscriptionRequest, SendMessageRequest, ShareLink, StaleKind, StartAgentRequest, TextPart, ToolCallPart, ToolCallStatus, ToolCatalogEffect, ToolCatalogEntry, ToolCompletedEvent, ToolStartedEvent, TurnCompletedEvent, TurnCompletionStatus, TurnStartedEvent, TurnUsage, UpdateAdminAgentRequest, UpdateApplicationContextRequest, UpdateMcpToolRequest };
+export type { AdminAgent, AdminAgentInput, AgentArtifact, AgentConsultation, AgentConsultationList, AgentConsultationStatus, AgentDecisionOutcome, AgentEvaluation, AgentEvaluationCost, AgentEvaluationDecisions, AgentEvaluationDifference, AgentEvaluationFilter, AgentEvaluationRouting, AgentEvaluationRuns, AgentEvaluationTool, AgentExecutionResolution, AgentFeedbackCategoryCount, AgentFeedbackExportFilter, AgentFeedbackFilter, AgentFeedbackItem, AgentFeedbackList, AgentFeedbackListFilter, AgentFeedbackOutcome, AgentFeedbackSummary, AgentFeedbackSummaryRow, AgentGrantSource, AgentInbox, AgentInboxFilter, AgentInvalidationCount, AgentProposal, AgentProposalDecision, AgentProposalDecisionRight, AgentProposalFeedback, AgentProposalFeedbackCategory, AgentProposalFeedbackGroup, AgentProposalLookup, AgentProposalObject, AgentProposalStatus, AgentReplay, AgentReplayList, AgentReplayRequest, AgentRun, AgentRunKind, AgentRunList, AgentRunRetryMode, AgentRunState, AgentRunStatus, AgentSkillChooser, AgentSkillState, AgentState, AgentSubjectRole, AgentSubjectSummary, AgentSubjectSummaryList, AgentSubjectWork, AgentSubjectWorkAgent, AgentSubjectWorkProposal, AgentSummary, AgentThread, AgentThreadLookup, AgentThreadMemory, AgentTriggerReceipt, ApplicationContext, ApplicationContextVersion, ApprovalDecision, ApprovalPart, ApprovalPresentation, ApprovalPresentationField, ApprovalRequiredEvent, ApprovalStatus, AssistantAddressForm, AssistantAutonomy, AssistantCollaboration, AssistantErrorEvent, AssistantPreferences, AssistantResponseLength, AssistantStatus, AssistantStyle, ClientContext, ClientContextEntity, Conversation, ConversationKind, ConversationMember, ConversationPage, ConversationRole, ConversationStatus, ConversationSummary, ConversationThread, ConversationThreadDecision, CreateConversationRequest, DecideApprovalRequest, DirectoryEntry, LiveAgentWorkChanged, LiveAgentWorkReason, LiveConversationChanged, LiveConversationEvent, LiveConversationRead, LiveConversationRemoved, McpAuthMode, McpServer, McpServerInput, McpServerTestResult, McpTool, McpToolEffect, McpToolStatus, Message, MessageAuthorKind, MessageDeltaEvent, MessagePart, NhAssistantAccessPolicy, NhAssistantActivity, NhAssistantApprovalChoice, NhAssistantApprovalRight, NhAssistantApprovalWaitingFor, NhAssistantClientContext, NhAssistantClientErrorCode, NhAssistantConfig, NhAssistantError, NhAssistantFetch, NhAssistantIconName, NhAssistantLiveState, NhAssistantNotice, NhAssistantProposalFeedbackSaved, NhAssistantPushConfig, NhAssistantPushState, NhAssistantQueuedMessage, NhAssistantRawSseMessage, NhAssistantSseEvent, NhAssistantSseEventMap, NhAssistantSseEventType, NhAssistantStatusCodes, NhAssistantToolCallGroupState, NotificationSettings, PushSubscriptionRequest, SendMessageRequest, SetAgentStateRequest, ShareLink, StaleKind, StartAgentRequest, TextPart, ToolCallPart, ToolCallStatus, ToolCatalogEffect, ToolCatalogEntry, ToolCompletedEvent, ToolStartedEvent, TurnCompletedEvent, TurnCompletionStatus, TurnStartedEvent, TurnUsage, UpdateAdminAgentRequest, UpdateApplicationContextRequest, UpdateMcpToolRequest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newheap/platform-ai-chat",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "peerDependencies": {
     "@angular/cdk": "^20.2.14",
     "@angular/common": "^20.3.28",

package/testing/index.d.ts

@@ -95,6 +95,13 @@ interface NhAssistantMockMcpServer extends McpServerInput {
 /** A preconfigured agent. Code agents default to the scenario's chat agents. */
 interface NhAssistantMockAdminAgent extends AdminAgentInput {
     source: 'code' | 'admin';
+    /** The skills of a code agent, by id and description; they start active. */
+    skills?: {
+        skillId: string;
+        description: string;
+    }[];
+    /** The live agent this code agent is a shadow variant of. */
+    shadowOf?: string;
 }
 /**
  * Administration data of the mock. Hosts without an admin scenario still get working