@newheap/platform-ai-chat 0.17.0 → 0.18.0

package/package.json

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

package/testing/index.d.ts

@@ -1,4 +1,4 @@
-import { AssistantStatus, AgentSummary, Conversation, ClientContext, AssistantPreferences, ToolCatalogEntry, AdminAgentInput, CodeRunSettings, AgentRunSettingsRequest, DataSkillRequest, DataTriggerRequest, McpServerInput, McpCustomAuthMode, McpDiscovery, RunCatalog, AssistantDataClassification, AssistantAccount, AgentRunStatus, AgentTriggerReceipt, AgentRunMcpSkip, ApprovalPresentation, AgentProposalStatus, AgentProposalOrigin, AgentProposalParent, NhAssistantMcpAuthorizationWindow, NhAssistantMcpAuthorizationOutcome, NhAssistantMcpAuthorizationHandle, LiveConversationChanged, LiveConversationRead, LiveConversationRemoved, LiveConversationEvent, LiveAgentWorkChanged, FileReference, NhAssistantUploadRequest, NhAssistantLiveService, NhAssistantLiveState } from '@newheap/platform-ai-chat';
+import { AssistantStatus, AgentSummary, Conversation, ClientContext, NhAssistantConsultationLeaveRoute, AssistantPreferences, ToolCatalogEntry, AdminAgentInput, NhAssistantConsultationRoute, DataConsultationRequest, CodeRunSettings, AgentRunSettingsRequest, DataSkillRequest, DataTriggerRequest, McpServerInput, McpCustomAuthMode, McpDiscovery, RunCatalog, AssistantDataClassification, AssistantAccount, AgentRunStatus, AgentTriggerReceipt, AgentRunMcpSkip, ApprovalPresentation, AgentProposalStatus, AgentProposalOrigin, AgentProposalParent, AgentGrantSource, AgentConsultationStatus, NhAssistantMcpAuthorizationWindow, NhAssistantMcpAuthorizationOutcome, NhAssistantMcpAuthorizationHandle, LiveConversationChanged, LiveConversationRead, LiveConversationRemoved, LiveConversationEvent, LiveAgentWorkChanged, ApplicationMessageDetails, Message, FileReference, NhAssistantUploadRequest, NhAssistantLiveService, NhAssistantLiveState } from '@newheap/platform-ai-chat';
 import * as _angular_core from '@angular/core';
 import { InjectionToken, EnvironmentProviders } from '@angular/core';
 import { Observable } from 'rxjs';
@@ -32,7 +32,10 @@ interface NhAssistantMockToolStep {
 /**
  * Pauses the turn for approval: `tool.started`, `approval.required` and
  * `turn.completed` with status `waiting-for-approval`. The decision resumes the turn with
- * the `approved` or `rejected` steps.
+ * the `approved` or `rejected` steps. With `consultation` the approval is a consulted agent's
+ * proposal that the person who asked decides in their own chat (`asker-decides`); with its
+ * `leaveRoute` the decision `leave` leaves it for the subject's approvers and resumes the turn with
+ * the `left` steps.
  */
 interface NhAssistantMockApprovalStep {
     approval: {
@@ -57,8 +60,26 @@ interface NhAssistantMockApprovalStep {
         resultPreview?: string | null;
         approved: NhAssistantMockStep[];
         rejected: NhAssistantMockStep[];
+        /** The consultation that proposed it; without it the approval is the conversation's own. */
+        consultation?: NhAssistantMockApprovalConsultation;
+        /** The steps after the person left the proposal for the subject's approvers. Default none. */
+        left?: NhAssistantMockStep[];
     };
 }
+/** Where a consulted agent's proposal of a mock turn comes from. */
+interface NhAssistantMockApprovalConsultation {
+    /** Default a generated id. */
+    consultationId?: string;
+    /** The consulted agent that proposed it. */
+    agentId: string;
+    subjectType: string;
+    subjectId: string;
+    subjectDisplayName?: string | null;
+    /** The route at the subject the person may leave it for; default none, so they only approve or reject it. */
+    leaveRoute?: NhAssistantConsultationLeaveRoute | null;
+    /** The consulted agent's answer. Default none. */
+    answer?: string | null;
+}
 /** Ends the stream with an `error` event. */
 interface NhAssistantMockErrorStep {
     error: {
@@ -137,6 +158,32 @@ interface NhAssistantMockAdminAgent extends AdminAgentInput {
     shadow?: boolean;
     /** The technical account in code, as with `ServiceAccount(actorId)`. */
     serviceAccount?: string;
+    /**
+     * The routes that the consultations of a code agent allow, with the subject types whose
+     * consultation allows each, as `AllowConsultation` in code, such as
+     * `{ 'asker-decides': ['project'], 'subject-asker-rights': ['project'] }`; a route without types is
+     * not allowed. Without it nobody can consult the agent and its state has no `consultationRoutes`.
+     */
+    consultations?: Partial<Record<NhAssistantConsultationRoute, string[]>>;
+    /**
+     * The descriptions of a code agent's consultations in code, by subject type, as `Description` in
+     * `AllowConsultation`. A type listed here and in no route of `consultations` is a consultation in
+     * code that only answers.
+     */
+    consultationDescriptions?: Record<string, string>;
+    /**
+     * The ceiling of a code agent that administrators may make consultable as data, as
+     * `ConsultableAsData` in code; it applies together with the scenario's `consultationsAsData`. `{}`
+     * allows answers only, as `ConsultableAsData()` without a configuration does. Without it a code
+     * agent gets no consultations as data.
+     */
+    consultableAsData?: NhAssistantMockConsultationCeiling;
+    /**
+     * The consultations defined as data the agent starts with, as administrators saved them. The mock
+     * saves them through its own endpoint after the agent's run configuration, so each is checked as an
+     * administrator's save is; a consultation the mock refuses fails the scenario at once.
+     */
+    dataConsultations?: NhAssistantMockDataConsultation[];
     /**
      * Whether a code agent says what it works on, as with `WorksOn`; by default it does when the
      * scenario gives `worksOnSubjectTypes`, `worksOnAllSubjects` or `worksOnApplication`.
@@ -157,6 +204,26 @@ interface NhAssistantMockAdminAgent extends AdminAgentInput {
      */
     runConfiguration?: NhAssistantMockRunConfigurationPreset;
 }
+/**
+ * A ceiling in code of consultations defined as data, as `NhAssistantConsultationCeilingBuilder`
+ * configures one: the routes data may use (none by default, which allows answers only), whether data
+ * may generate request tools and offer them to MCP clients (both off by default), and the highest
+ * limits (by default the bounds of `AllowConsultation`: 32 tool calls, 600 seconds, 32,000
+ * characters and 200 messages).
+ */
+interface NhAssistantMockConsultationCeiling {
+    routes?: NhAssistantConsultationRoute[];
+    allowRequests?: boolean;
+    allowMcp?: boolean;
+    maxToolCalls?: number;
+    maxTimeoutSeconds?: number;
+    maxAnswerChars?: number;
+    maxHistoryMessages?: number;
+}
+/** A consultation defined as data an agent of the scenario starts with. */
+interface NhAssistantMockDataConsultation extends DataConsultationRequest {
+    subjectType: string;
+}
 /**
  * The run configuration as data an agent created in the administration starts with. The mock saves it
  * through its own endpoints in order (the run settings, then each skill, then each trigger), so every
@@ -227,6 +294,13 @@ interface NhAssistantMockAdminScenario {
      * administration work per division, as an application that lists its divisions does.
      */
     runCatalog?: Partial<RunCatalog>;
+    /**
+     * Lets administrators define consultations as data within this ceiling, as `UseConsultationsAsData`
+     * in code: agents created in the administration with run settings get it, and code agents with
+     * `consultableAsData` get it together with their own. The run catalog reports it as
+     * `consultationCeiling`. Without it consultations exist in code only.
+     */
+    consultationsAsData?: NhAssistantMockConsultationCeiling;
     /**
      * The data classifications each model profile and its fallbacks permit together, by profile name.
      * An agent or skill whose classification its profile does not permit is saved with the warning
@@ -454,6 +528,12 @@ interface NhAssistantMockScenario {
      * the approval inbox, their thread and their subject's work list them, and people decide them.
      */
     proposals?: NhAssistantMockProposal[];
+    /**
+     * Consultations of agents by other assistants, as the consulted agent's thread lists them
+     * (`GET threads/{id}/consultations`), newest first. Their proposals are those of `proposals` that
+     * name them (`consultationId`), counted per route.
+     */
+    consultations?: NhAssistantMockConsultation[];
     /**
      * The application's own answer to an upload that passed the assistant's checks: `null` stores it,
      * a code refuses it as the server passes the file source's refusal on, for example
@@ -470,9 +550,27 @@ interface NhAssistantMockScenario {
      */
     scanUpload?: (upload: NhAssistantMockUpload) => 'refused' | 'failed' | null;
 }
+/** A consultation of an agent by another assistant, as the consulted agent's thread lists it. */
+interface NhAssistantMockConsultation {
+    id: string;
+    /** The consulted agent's thread. */
+    conversationId: string;
+    askerActorId: string;
+    askerDisplayName?: string | null;
+    askingAgentId?: string | null;
+    /** Default `completed`. */
+    status?: AgentConsultationStatus;
+    /** When it started, an ISO date. Default when the mock started. */
+    createdAt?: string;
+}
 /**
  * A proposal an agent left, as the mock serves it; the mock fills what it leaves out. With
  * `placedBy` a run placed it here from another subject, such as a run for the whole application.
+ * With `consultationId` another assistant consulted the agent for `initiatorActorId`, and
+ * `consultationRoute` says who decides it: an `asker-decides` proposal waits inline for the person who
+ * asked and nobody decides it here (`assistant-consult-asker-decides`); a `subject-agent-rights`
+ * proposal runs with the agent's own rights and its asker may not decide it
+ * (`assistant-four-eyes-required`).
  */
 interface NhAssistantMockProposal {
     approvalId: string;
@@ -510,6 +608,17 @@ interface NhAssistantMockProposal {
     canDecide?: boolean;
     /** Why not, when `canDecide` is `false`. Default `assistant-approval-policy-denied`. */
     reasonCode?: string | null;
+    /** The consultation that proposed it. Default none. */
+    consultationId?: string | null;
+    /** Who decides a consultation's proposal and whose rights run it. Default none. */
+    consultationRoute?: NhAssistantConsultationRoute | null;
+    /** The person who asked through the consultation, or who started the run. Default none. */
+    initiatorActorId?: string | null;
+    /**
+     * Whose rights execute it. Default `agent`, and `delegated` for a consultation's proposal that runs
+     * with the asker's rights.
+     */
+    grantSource?: AgentGrantSource;
 }
 /** One request the mock API received, for assertions in tests. */
 interface NhAssistantMockRequest {
@@ -600,6 +709,13 @@ declare class NhAssistantMockBackend {
      * answer arrive as live updates. Resolves when the turn ends.
      */
     simulateParticipantTurn(conversationId: string, person: NhAssistantMockPerson, text: string): Promise<void>;
+    /**
+     * Posts a message of the application into a conversation, as `INhAssistantConversationMessages`
+     * does on the server: it gets the next position in the conversation and reaches the people of the
+     * conversation as a live update. `trusted` marks an instruction for the assistant, as `Trusted`
+     * does on the server. Returns the stored message, or `null` for an unknown or archived conversation.
+     */
+    postApplicationMessage(conversationId: string, text: string, details?: Partial<ApplicationMessageDetails>): Message | null;
     /** Switches the simulated `NewHeap:AI:Assistant:Enabled` flag. */
     setEnabled(enabled: boolean): void;
     /** Switches whether the caller passes the admin policy (`canAdminister`, `admin/*`). */
@@ -637,6 +753,12 @@ declare class NhAssistantMockBackend {
     private list;
     private create;
     private sendMessage;
+    /**
+     * `POST conversations/{id}/approvals/{approvalId}/decide`: approves or rejects the approval the
+     * turn waits for, or leaves a consulted agent's proposal with a `leaveRoute` for the subject's
+     * approvers (`leave`). Leaving closes it here, names the proposal that now waits at the subject
+     * (`consultation.movedToApprovalId`) and resumes the turn with the step's `left` steps.
+     */
     private decide;
     private cancel;
     private playSteps;
@@ -679,6 +801,11 @@ declare class NhAssistantMockBackend {
     /** Whether the caller passes the agent's view policy, by default its required policy. */
     private readsApplicationWork;
     private decidesForApplication;
+    /**
+     * The scenario's consultations of a thread's agent, newest first, each with the proposals of the
+     * scenario that name it, counted per route; `null` when the scenario lists none there.
+     */
+    private consultationsOf;
     private nextId;
     /** An administration answer about agents with each agent's groups, as the server answers it. */
     private withGroups;
@@ -737,4 +864,4 @@ declare class NhAssistantMockLiveService implements NhAssistantLiveSurface {
 declare function provideNhAssistantMockApi(script: NhAssistantMockScenario): EnvironmentProviders;
 
 export { NH_ASSISTANT_MOCK_HUB_PATH, NH_ASSISTANT_MOCK_SCENARIO, NhAssistantMockAuthorizationWindow, NhAssistantMockBackend, NhAssistantMockLiveService, provideNhAssistantMockApi };
-export type { NhAssistantMockAdminAgent, NhAssistantMockAdminScenario, NhAssistantMockAgentGroup, NhAssistantMockApprovalStep, NhAssistantMockCollaboration, NhAssistantMockConnectionStep, NhAssistantMockDataSkill, NhAssistantMockDataTrigger, NhAssistantMockDivision, NhAssistantMockErrorStep, NhAssistantMockFailStep, NhAssistantMockLiveMessage, NhAssistantMockMcpServer, NhAssistantMockPerson, NhAssistantMockProposal, NhAssistantMockRemoteTool, NhAssistantMockRequest, NhAssistantMockRun, NhAssistantMockRunConfigurationPreset, NhAssistantMockRunNow, NhAssistantMockScenario, NhAssistantMockStep, NhAssistantMockSubject, NhAssistantMockSubjectType, NhAssistantMockTextStep, NhAssistantMockTiming, NhAssistantMockToolStep, NhAssistantMockTurn, NhAssistantMockUpload };
+export type { NhAssistantMockAdminAgent, NhAssistantMockAdminScenario, NhAssistantMockAgentGroup, NhAssistantMockApprovalConsultation, NhAssistantMockApprovalStep, NhAssistantMockCollaboration, NhAssistantMockConnectionStep, NhAssistantMockConsultation, NhAssistantMockConsultationCeiling, NhAssistantMockDataConsultation, NhAssistantMockDataSkill, NhAssistantMockDataTrigger, NhAssistantMockDivision, NhAssistantMockErrorStep, NhAssistantMockFailStep, NhAssistantMockLiveMessage, NhAssistantMockMcpServer, NhAssistantMockPerson, NhAssistantMockProposal, NhAssistantMockRemoteTool, NhAssistantMockRequest, NhAssistantMockRun, NhAssistantMockRunConfigurationPreset, NhAssistantMockRunNow, NhAssistantMockScenario, NhAssistantMockStep, NhAssistantMockSubject, NhAssistantMockSubjectType, NhAssistantMockTextStep, NhAssistantMockTiming, NhAssistantMockToolStep, NhAssistantMockTurn, NhAssistantMockUpload };