@newheap/platform-ai-chat 0.9.0 → 0.11.0

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, AgentProposalFeedbackCategory, AgentFeedbackSummaryRow, AgentFeedbackItem, AgentFeedbackCategoryCount, AgentProposalFeedbackGroup, McpServerTestResult, McpAuthMode, McpToolEffect, McpTool } from '@newheap/platform-ai-chat';
+import { NhAssistantStore, NhAssistantError, ApplicationContext, ApplicationContextVersion, AdminAgent, ToolCatalogEntry, McpServer, SetAgentStateRequest, AgentSkillState, AssistantAutonomy, AgentEvaluation, AgentReplay, AgentEvaluationCost, AgentProposalFeedbackCategory, AgentFeedbackSummaryRow, AgentFeedbackItem, AgentFeedbackCategoryCount, StaleKind, AgentProposalFeedbackGroup, McpServerTestResult, McpAuthMode, McpToolEffect, McpTool } from '@newheap/platform-ai-chat';
 
 type NhAssistantAdminTab = 'context' | 'agents' | 'mcp-servers';
 /**
@@ -59,10 +59,13 @@ declare class NhAssistantAdminContextComponent {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantAdminContextComponent, "nh-assistant-admin-context", never, {}, {}, never, never, true, never>;
 }
 
+type AgentStateAction = SetAgentStateRequest['state'];
 /**
- * Agent administration: code agents (override, disable, reset) and agents created here
- * (edit, disable, delete). Editing opens `nh-assistant-admin-agent-editor`; the feedback action
- * opens `nh-assistant-agent-feedback-report` for the agent.
+ * Agent administration: code agents (override, reset) and agents created here (edit, delete),
+ * and for every agent its run state with pause, stop and resume, each with an optional reason.
+ * Editing opens `nh-assistant-admin-agent-editor`; the feedback action opens
+ * `nh-assistant-agent-feedback-report` for the agent, and the evaluation action of an agent with
+ * shadow variants opens `nh-assistant-agent-evaluation`.
  */
 declare class NhAssistantAdminAgentsComponent {
     private readonly admin;
@@ -70,6 +73,7 @@ declare class NhAssistantAdminAgentsComponent {
     private readonly injector;
     private readonly host;
     private readonly backButton;
+    private readonly reasonInput;
     private subscription?;
     private actionSubscription?;
     readonly id: string;
@@ -82,11 +86,21 @@ declare class NhAssistantAdminAgentsComponent {
     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>;
+    /** The agent whose comparison with its shadow variants is shown instead of the list. */
+    readonly evaluating: _angular_core.WritableSignal<AdminAgent | null>;
     readonly confirming: _angular_core.WritableSignal<{
         agentId: string;
         action: "delete" | "reset";
     } | null>;
     readonly busyAgentId: _angular_core.WritableSignal<string | null>;
+    /** The state change whose reason is being entered, of the agent or one of its skills. */
+    readonly changingState: _angular_core.WritableSignal<{
+        agentId: string;
+        skillId?: string;
+        state: AgentStateAction;
+    } | null>;
+    readonly stateReason: _angular_core.WritableSignal<string>;
+    readonly maxReason = 500;
     readonly error: _angular_core.WritableSignal<NhAssistantError | null>;
     readonly errorKeys: _angular_core.Signal<string[]>;
     constructor();
@@ -95,10 +109,24 @@ declare class NhAssistantAdminAgentsComponent {
     edit(agent: AdminAgent): void;
     /** Shows what people said when they rejected the agent's proposals. */
     openReport(agent: AdminAgent): void;
+    /** The shadow variants of an agent, by id. */
+    variantsOf(agent: AdminAgent): string[];
+    /** Compares the agent with its shadow variants. */
+    openEvaluation(agent: AdminAgent): void;
+    /** Returns to the list and to the evaluation action of the agent whose comparison was open. */
+    closeEvaluation(): 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;
+    /** The state changes the agent allows: none for an agent that is disabled in code. */
+    stateActions(agent: AdminAgent): AgentStateAction[];
+    /** The state changes a skill allows. */
+    skillActions(skill: AgentSkillState): AgentStateAction[];
+    /** Opens the reason form of a state change of the agent or, with a skill, of that skill. */
+    askState(agent: AdminAgent, state: AgentStateAction, skill?: AgentSkillState): void;
+    isChangingState(agentId: string, state: AgentStateAction, skillId?: string): boolean;
+    applyState(agent: AdminAgent): void;
+    value(event: Event): string;
     confirm(agentId: string, action: 'delete' | 'reset'): void;
     isConfirming(agentId: string, action: 'delete' | 'reset'): boolean;
     reset(agent: AdminAgent): void;
@@ -135,7 +163,6 @@ declare class NhAssistantAdminAgentEditorComponent {
     readonly instructions: _angular_core.WritableSignal<string>;
     readonly autonomy: _angular_core.WritableSignal<AssistantAutonomy>;
     readonly requiredPolicy: _angular_core.WritableSignal<string>;
-    readonly isEnabled: _angular_core.WritableSignal<boolean>;
     readonly toolSelectors: _angular_core.WritableSignal<string[]>;
     readonly mcpServerIds: _angular_core.WritableSignal<string[]>;
     readonly newSelector: _angular_core.WritableSignal<string>;
@@ -168,11 +195,92 @@ 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 evaluation offers, in days before now; the server allows at most 92. */
+type NhAssistantEvaluationPeriod = 7 | 30 | 90;
+/** One row of the cost comparison: a measure of the live agent next to the variant's. */
+interface NhAssistantCostRow {
+    key: 'runs' | 'model-calls' | 'tokens' | 'tool-calls';
+    live: AgentEvaluationCost;
+    variant: AgentEvaluationCost;
+}
+/**
+ * Compares a shadow variant of an agent with the live agent, for the agent's administrators: the
+ * runs that handled the same events, per tool the proposals both made, only one made and what
+ * people decided about the live ones, what each cost and how each routed, with links to the threads
+ * of the differences. Small numbers mislead, so counts stand next to every share. Administrators
+ * replay the recorded runs of the period into the variant and export the comparison as JSON Lines.
+ * The report holds no messages or arguments.
+ */
+declare class NhAssistantAgentEvaluationComponent {
+    private readonly admin;
+    private readonly panel;
+    private readonly document;
+    private subscription?;
+    private replaySubscription?;
+    /** The live agent. */
+    readonly agentId: _angular_core.InputSignal<string>;
+    /** Its shadow variants; the first is compared until another is chosen. */
+    readonly variants: _angular_core.InputSignal<readonly string[]>;
+    readonly id: string;
+    readonly periods: readonly NhAssistantEvaluationPeriod[];
+    readonly maxReplayRuns = 500;
+    readonly canOpenThreads: boolean;
+    readonly variant: _angular_core.WritableSignal<string>;
+    readonly period: _angular_core.WritableSignal<NhAssistantEvaluationPeriod>;
+    readonly loading: _angular_core.WritableSignal<boolean>;
+    readonly error: _angular_core.WritableSignal<NhAssistantError | null>;
+    readonly errorKeys: _angular_core.Signal<string[]>;
+    readonly evaluation: _angular_core.WritableSignal<AgentEvaluation | null>;
+    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>;
+    readonly replays: _angular_core.WritableSignal<AgentReplay[]>;
+    readonly replayRuns: _angular_core.WritableSignal<number>;
+    readonly replaying: _angular_core.WritableSignal<boolean>;
+    readonly replayError: _angular_core.WritableSignal<NhAssistantError | null>;
+    readonly replayErrorKeys: _angular_core.Signal<string[]>;
+    readonly replayRunning: _angular_core.Signal<boolean>;
+    readonly costRows: _angular_core.Signal<NhAssistantCostRow[]>;
+    /** Routing matters only when one of the two worked in a skill. */
+    readonly showRouting: _angular_core.Signal<boolean>;
+    /** The period the last load asked for, so the report, the export and a replay agree. */
+    private range;
+    constructor();
+    /** Reloads the comparison and the variant's replays for the chosen period. */
+    load(): void;
+    loadReplays(): void;
+    onVariant(event: Event): void;
+    onPeriod(event: Event): void;
+    onReplayRuns(event: Event): void;
+    /** Replays the live agent's recorded runs of the period into the variant. */
+    replay(): void;
+    /** Downloads the paired runs of the comparison as a JSON Lines file. */
+    export(): Promise<void>;
+    /** Opens a thread of the comparison in the assistant panel, when the host has one. */
+    openThread(conversationId: string): void;
+    /** The share of a count in a total, or `null` without a total. */
+    share(count: number, total: number): number | null;
+    total(row: AgentEvaluation['tools'][number]): number;
+    categories(row: AgentEvaluation['tools'][number]): {
+        category: string;
+        count: number;
+    }[];
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantAgentEvaluationComponent, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantAgentEvaluationComponent, "nh-assistant-agent-evaluation", never, { "agentId": { "alias": "agentId"; "required": true; "isSignal": true; }; "variants": { "alias": "variants"; "required": true; "isSignal": true; }; }, {}, 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. */
+/** A summary row with its most frequent feedback categories and why open proposals closed. */
 interface NhAssistantFeedbackSummaryView extends AgentFeedbackSummaryRow {
     topCategories: AgentFeedbackCategoryCount[];
+    /** Open proposals closed before a decision, per kind, most frequent first. */
+    invalidatedKinds: {
+        kind: StaleKind;
+        count: number;
+        reasons: string;
+    }[];
 }
 /**
  * What people said when they rejected an agent's proposals, for the agent's administrators: per
@@ -365,5 +473,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, NhAssistantAgentFeedbackReportComponent, nhAssistantSelectorMatches };
-export type { NhAssistantAdminTab, NhAssistantFeedbackPeriod, NhAssistantSecretAction };
+export { NH_ASSISTANT_MAX_INSTRUCTIONS, NhAssistantAdminAgentEditorComponent, NhAssistantAdminAgentsComponent, NhAssistantAdminComponent, NhAssistantAdminContextComponent, NhAssistantAdminMcpServerEditorComponent, NhAssistantAdminMcpServersComponent, NhAssistantAdminMcpToolsComponent, NhAssistantAgentEvaluationComponent, NhAssistantAgentFeedbackReportComponent, nhAssistantSelectorMatches };
+export type { NhAssistantAdminTab, NhAssistantEvaluationPeriod, NhAssistantFeedbackPeriod, NhAssistantSecretAction };

package/agent-runs/index.d.ts

@@ -8,7 +8,9 @@ import { AgentProposal, AgentThreadLookup, AgentTriggerReceipt, NhAssistantError
  * server checks each decision against the proposal's approval policy again. After a rejection the
  * inbox asks, optionally, what was wrong, also when the rejected proposals have left the list.
  * With live updates the inbox reloads by itself when agent work changes, for example when a
- * colleague decided a proposal or a run proposed a new one.
+ * colleague decided a proposal or a run proposed a new one. A proposal that closes because it no
+ * longer fits, for example because someone did the work by hand, stays as a closed card with the
+ * reason until it is dismissed.
  */
 declare class NhAssistantAgentInboxComponent {
     private readonly api;
@@ -114,6 +116,11 @@ interface NhAssistantFeedbackRequest {
  * optionally and above the list, what was wrong; closed proposals keep a low-key action to give or
  * change that feedback later. With `decisionRights` each proposal has its own right, for example
  * from the agent work on a subject, and a pending proposal the viewer may not decide says who does.
+ * A proposal that no longer fits, for example because a person already did the work, shows why.
+ * With `holdClosedCards`, a list of open proposals keeps such a proposal, or one a newer proposal
+ * replaced, as a closed card when it closes while shown, or when an approval is refused because of
+ * it, until the person dismisses it. It reads those proposals by id with one lookup, never through
+ * their threads.
  */
 declare class NhAssistantAgentProposalsComponent {
     private readonly api;
@@ -129,6 +136,12 @@ declare class NhAssistantAgentProposalsComponent {
      */
     readonly decisionRights: _angular_core.InputSignal<ReadonlyMap<string, AgentProposalDecisionRight> | null>;
     readonly selectable: _angular_core.InputSignal<boolean>;
+    /**
+     * Keeps proposals that close as stale or are replaced while shown as closed cards with their
+     * explanation until they are dismissed. For lists of open proposals, which drop a proposal once
+     * it closes.
+     */
+    readonly holdClosedCards: _angular_core.InputSignal<boolean>;
     /** Emits after a proposal or its feedback changed, so the host reloads its list. */
     readonly changed: _angular_core.OutputEmitterRef<void>;
     readonly busy: _angular_core.WritableSignal<boolean>;
@@ -140,7 +153,30 @@ declare class NhAssistantAgentProposalsComponent {
     readonly allSelected: _angular_core.Signal<boolean>;
     /** The feedback question. It does not depend on `proposals`, which drop rejected proposals in the inbox. */
     readonly feedback: _angular_core.WritableSignal<NhAssistantFeedbackRequest | null>;
+    /** Proposals that closed as stale while shown, kept until dismissed; newest first. */
+    readonly held: _angular_core.WritableSignal<AgentProposal[]>;
+    /** The held closed cards first, then the proposals the host gave. */
+    readonly shown: _angular_core.Signal<AgentProposal[]>;
+    private readonly lookups;
     constructor();
+    /**
+     * The translation key of a proposal's status: the kind of a stale proposal, "replaced" for a
+     * superseded one, otherwise its status.
+     */
+    statusKey(proposal: AgentProposal): string;
+    /** True when the newer proposal that replaced this one is in the list. */
+    hasSuccessor(proposal: AgentProposal): boolean;
+    /** Moves focus to the newer proposal that replaced this one. */
+    showSuccessor(proposal: AgentProposal): void;
+    /** True for a closed card the list keeps until it is dismissed. */
+    isHeld(proposal: AgentProposal): boolean;
+    /** Removes a closed card. */
+    dismiss(proposal: AgentProposal): void;
+    /**
+     * Called by a host of open proposals after a live update replaced `previous` with `next`: keeps
+     * the shown pending proposals that left the list because they closed as stale or were replaced.
+     */
+    holdClosed(previous: readonly AgentProposal[], next: readonly AgentProposal[]): void;
     /** Whether the caller may decide this proposal: its own right when one was given, otherwise `canDecide`. */
     mayDecide(proposal: AgentProposal): boolean;
     /**
@@ -164,16 +200,21 @@ declare class NhAssistantAgentProposalsComponent {
     /** Closes the question; from a card, focus returns to the card's feedback action. */
     onFeedbackDismissed(): void;
     private ask;
+    /**
+     * Reads `proposals` again by id and keeps those that closed as stale or were replaced as closed
+     * cards, with their kind and explanation or their successor.
+     */
+    private holdStale;
     private run;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantAgentProposalsComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantAgentProposalsComponent, "nh-assistant-agent-proposals", never, { "proposals": { "alias": "proposals"; "required": true; "isSignal": true; }; "canDecide": { "alias": "canDecide"; "required": false; "isSignal": true; }; "decisionRights": { "alias": "decisionRights"; "required": false; "isSignal": true; }; "selectable": { "alias": "selectable"; "required": false; "isSignal": true; }; }, { "changed": "changed"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantAgentProposalsComponent, "nh-assistant-agent-proposals", never, { "proposals": { "alias": "proposals"; "required": true; "isSignal": true; }; "canDecide": { "alias": "canDecide"; "required": false; "isSignal": true; }; "decisionRights": { "alias": "decisionRights"; "required": false; "isSignal": true; }; "selectable": { "alias": "selectable"; "required": false; "isSignal": true; }; "holdClosedCards": { "alias": "holdClosedCards"; "required": false; "isSignal": true; }; }, { "changed": "changed"; }, never, never, true, never>;
 }
 
 /**
  * The runs of an agent thread, newest first: trigger, status, failure, usage, proposals and the
- * summary the next run starts from. Participants cancel an open run; approvers resume or restart
- * a failed or cancelled one. With live updates it reloads by itself when a run or proposal of the
- * thread changes.
+ * summary the next run starts from, and the agent that handed a run its work. Participants cancel
+ * an open run; approvers resume or restart a failed or cancelled one. With live updates it reloads
+ * by itself when a run or proposal of the thread changes.
  */
 declare class NhAssistantRunTimelineComponent {
     private readonly api;
@@ -183,6 +224,8 @@ declare class NhAssistantRunTimelineComponent {
     readonly role: _angular_core.InputSignal<AgentSubjectRole>;
     /** Emits after a run was cancelled or retried. */
     readonly changed: _angular_core.OutputEmitterRef<void>;
+    /** Emits the thread of the agent that handed a run its work, so the host can open it. */
+    readonly openConversation: _angular_core.OutputEmitterRef<string>;
     readonly loading: _angular_core.WritableSignal<boolean>;
     readonly loadFailed: _angular_core.WritableSignal<boolean>;
     readonly runs: _angular_core.WritableSignal<AgentRun[]>;
@@ -201,7 +244,7 @@ declare class NhAssistantRunTimelineComponent {
     /** A quiet load, after a live update, shows no loading state and keeps the runs when it fails. */
     private fetch;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<NhAssistantRunTimelineComponent, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantRunTimelineComponent, "nh-assistant-run-timeline", never, { "conversationId": { "alias": "conversationId"; "required": true; "isSignal": true; }; "role": { "alias": "role"; "required": false; "isSignal": true; }; }, { "changed": "changed"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<NhAssistantRunTimelineComponent, "nh-assistant-run-timeline", never, { "conversationId": { "alias": "conversationId"; "required": true; "isSignal": true; }; "role": { "alias": "role"; "required": false; "isSignal": true; }; }, { "changed": "changed"; "openConversation": "openConversation"; }, never, never, true, never>;
 }
 
 /**
@@ -282,8 +325,9 @@ interface NhAssistantStartedAgent {
  * decides when the viewer may not and the optional question after a rejection, and per agent the
  * conversation about the subject and, for participants, a start action. `agentId` names the agent
  * whose conversation the host offers also before it worked on the subject. With live updates the
- * view reloads by itself when agent work on its subject changes. Opening a conversation uses
- * `NhAssistantPanelService.openSubject` and emits `conversationOpened` afterwards.
+ * view reloads by itself when agent work on its subject changes; a proposal that closes because it
+ * no longer fits stays as a closed card with the reason until it is dismissed. Opening a
+ * conversation uses `NhAssistantPanelService.openSubject` and emits `conversationOpened` afterwards.
  */
 declare class NhAssistantSubjectSuggestionsComponent {
     private readonly api;