@newheap/platform-ai-chat 0.18.0 → 0.20.0

package/package.json

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

package/push/nh-assistant-push-worker.js

@@ -8,7 +8,9 @@
  * It shows a notification only when no window of the application is focused; otherwise it
  * forwards the message to the open windows, which already show the conversation live. A click
  * focuses an open window and opens the conversation there, or opens `app` with the conversation
- * in the URL fragment. Notifications carry a conversation id and short texts only.
+ * in the URL fragment. A notification about the proposals of a run also carries the run, which the
+ * click forwards, so the application can open its inbox of the run (`openRun$`). Notifications
+ * carry a conversation id, a run id and short texts only.
  */
 const settings = new URL(self.location.href).searchParams;
 const appUrl = settings.get('app') || '/';
@@ -27,12 +29,13 @@ self.addEventListener('push', event => {
   if (!payload || payload.type !== 'nh-assistant' || typeof payload.conversationId !== 'string') {
     return;
   }
+  const runId = typeof payload.runId === 'string' ? payload.runId : undefined;
 
   event.waitUntil((async () => {
     const windows = await self.clients.matchAll({ type: 'window', includeUncontrolled: true });
     if (windows.some(client => client.focused && client.visibilityState === 'visible')) {
       for (const client of windows) {
-        client.postMessage({ type: 'nh-assistant.push', kind: payload.kind, conversationId: payload.conversationId });
+        client.postMessage({ type: 'nh-assistant.push', kind: payload.kind, conversationId: payload.conversationId, runId });
       }
       return;
     }
@@ -42,29 +45,33 @@ self.addEventListener('push', event => {
       tag: String(payload.tag || `nh-assistant:${payload.conversationId}`),
       renotify: true,
       icon: iconUrl,
-      data: { conversationId: payload.conversationId }
+      data: { conversationId: payload.conversationId, runId }
     });
   })());
 });
 
 self.addEventListener('notificationclick', event => {
   event.notification.close();
-  const conversationId = event.notification.data && event.notification.data.conversationId;
+  const data = event.notification.data || {};
+  const conversationId = data.conversationId;
   if (typeof conversationId !== 'string') {
     return;
   }
+  const runId = typeof data.runId === 'string' ? data.runId : undefined;
 
   event.waitUntil((async () => {
     const windows = await self.clients.matchAll({ type: 'window', includeUncontrolled: true });
     const target = windows.find(client => client.focused) || windows[0];
     if (target) {
       await target.focus();
-      target.postMessage({ type: 'nh-assistant.open-conversation', conversationId });
+      target.postMessage({ type: 'nh-assistant.open-conversation', conversationId, runId });
       return;
     }
 
     const url = new URL(appUrl, self.location.origin);
-    url.hash = `nh-assistant-conversation=${encodeURIComponent(conversationId)}`;
+    url.hash = runId
+      ? `nh-assistant-run=${encodeURIComponent(runId)}.${encodeURIComponent(conversationId)}`
+      : `nh-assistant-conversation=${encodeURIComponent(conversationId)}`;
     await self.clients.openWindow(url.href);
   })());
 });

package/testing/index.d.ts

@@ -1,4 +1,4 @@
-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 { AssistantStatus, AgentSummary, Conversation, ClientContext, NhAssistantConsultationLeaveRoute, AssistantPreferences, ToolCatalogEntry, AdminAgentInput, NhAssistantConsultationRoute, DataConsultationRequest, CodeRunSettings, AgentRunSettingsRequest, DataSkillRequest, DataTriggerRequest, McpServerInput, McpCustomAuthMode, McpDiscovery, RunCatalog, AssistantDataClassification, AssistantAccount, AgentPackage, 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';
@@ -80,6 +80,24 @@ interface NhAssistantMockApprovalConsultation {
     /** The consulted agent's answer. Default none. */
     answer?: string | null;
 }
+/**
+ * Asks a question with `ask_question`: `tool.started`, `question.asked` and `turn.completed` with
+ * status `waiting-for-approval`, as the server's `run.AllowQuestions()` does. Only the addressee
+ * answers, with `POST conversations/{id}/questions/{questionId}/answer`; the answer resumes the turn
+ * with the `answered` steps, or with the steps that function returns for the chosen answer.
+ */
+interface NhAssistantMockQuestionStep {
+    question: {
+        question: string;
+        /** Two to six answers. */
+        choices: string[];
+        /** The person who answers; default the person whose turn asks. */
+        addresseeActorId?: string;
+        /** Default 900 seconds, the server's default wait. */
+        expiresInSeconds?: number;
+        answered: NhAssistantMockStep[] | ((answer: string, choice: number) => NhAssistantMockStep[]);
+    };
+}
 /** Ends the stream with an `error` event. */
 interface NhAssistantMockErrorStep {
     error: {
@@ -104,7 +122,7 @@ interface NhAssistantMockConnectionStep {
         text?: string;
     };
 }
-type NhAssistantMockStep = NhAssistantMockTextStep | NhAssistantMockToolStep | NhAssistantMockApprovalStep | NhAssistantMockErrorStep | NhAssistantMockFailStep | NhAssistantMockConnectionStep;
+type NhAssistantMockStep = NhAssistantMockTextStep | NhAssistantMockToolStep | NhAssistantMockApprovalStep | NhAssistantMockQuestionStep | NhAssistantMockErrorStep | NhAssistantMockFailStep | NhAssistantMockConnectionStep;
 /** A scripted assistant turn, chosen by matching the user's message. */
 interface NhAssistantMockTurn {
     /** Case-insensitive substring, regular expression or predicate. Omit to match every message. */
@@ -136,6 +154,36 @@ interface NhAssistantMockMcpServer extends McpServerInput {
     /** A server each person connects to starts with the caller's own account connected. */
     personalConnected?: boolean;
 }
+/**
+ * An entry of agent metadata as the application registers it with `AddAgentMetadata`: its name,
+ * whether administrators may override it on agents in code, its size limit, its searchable value and
+ * its checks.
+ */
+interface NhAssistantMockAgentMetadataEntry {
+    /** The entry's dash-case name. */
+    name: string;
+    /** Administrators may override it on agents in code, as `Editable()`. */
+    editable?: boolean;
+    /** The largest value in bytes of its JSON; 4,096 by default. */
+    maxBytes?: number;
+    /** The field of the value whose text is its searchable value, as `IndexBy`. */
+    indexBy?: string;
+    /**
+     * The field of the value whose texts are its searchable values, as `IndexByEach`; an entry names
+     * `indexBy` or `indexByEach`.
+     */
+    indexByEach?: string;
+    /**
+     * The fields of the entry's type: a value with another field is refused with `value: invalid`, as
+     * the server refuses JSON that does not fit the type. Without it every field is accepted.
+     */
+    fields?: string[];
+    /**
+     * Checks a value as the application's validators do: codes by field path, `''` for the whole value,
+     * such as `{ code: ['unknown-code'] }`; `null` or an empty record accepts it.
+     */
+    validate?: (value: Record<string, unknown>) => Record<string, string[]> | null;
+}
 /**
  * A preconfigured agent. Code agents default to the scenario's chat agents. `startsOff` starts it
  * off, as `StartsOff()` in code does for an agent in code.
@@ -152,8 +200,11 @@ interface NhAssistantMockAdminAgent extends AdminAgentInput {
         shadow?: boolean;
         startsOff?: boolean;
     }[];
-    /** The live agent this code agent is a shadow variant of. */
-    shadowOf?: string;
+    /**
+     * The live agent this code agent is a shadow variant of, as `ShadowOf` in code. A data variant is
+     * created with `POST admin/agents` and `shadowOf` instead.
+     */
+    shadowOf?: string | null;
     /** The agent starts in shadow, as with `Shadow()` in code. */
     shadow?: boolean;
     /** The technical account in code, as with `ServiceAccount(actorId)`. */
@@ -171,6 +222,11 @@ interface NhAssistantMockAdminAgent extends AdminAgentInput {
      * code that only answers.
      */
     consultationDescriptions?: Record<string, string>;
+    /**
+     * The tool selections of a code agent's consultations in code, by subject type, as `Tools` in
+     * `AllowConsultation`; a type without one offers every tool of the agent.
+     */
+    consultationTools?: 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`. `{}`
@@ -203,6 +259,47 @@ interface NhAssistantMockAdminAgent extends AdminAgentInput {
      * the administration offers the guided setup.
      */
     runConfiguration?: NhAssistantMockRunConfigurationPreset;
+    /**
+     * The hand-offs a code agent accepts in code, as `AcceptHandOffs`; they cannot change in the
+     * administration, and a hand-off as data about the same type is refused.
+     */
+    codeHandOffs?: NhAssistantMockCodeHandOff[];
+}
+/** A hand-off a code agent of the scenario accepts in code. */
+interface NhAssistantMockCodeHandOff {
+    subjectType: string;
+    sources: string[];
+    description?: string;
+    notifySource?: boolean;
+    /** 5 by default, as in code. */
+    maxPerSubjectPerDay?: number;
+}
+/**
+ * The ceiling in code of hand-offs defined as data, as `UseHandOffsAsData`: per subject type the
+ * agents that may accept them as data and the agents that may hand off, and the highest daily limit
+ * (100 by default).
+ */
+interface NhAssistantMockHandOffCeiling {
+    rules: NhAssistantMockHandOffRule[];
+    maxPerSubjectPerDay?: number;
+}
+/** One connection of the ceiling, as `Allow(subjectType, rule => rule.To(...).From(...))`. */
+interface NhAssistantMockHandOffRule {
+    subjectType: string;
+    to?: string[];
+    toAgentsCreatedInAdministration?: boolean;
+    from?: string[];
+    fromAgentsCreatedInAdministration?: boolean;
+}
+/**
+ * The ceiling in code of shadow variants created as data, as `UseShadowVariantsAsData`: the live agents
+ * in code that may get them, whether agents created in the administration may too, and how many each
+ * (3 by default).
+ */
+interface NhAssistantMockShadowVariantCeiling {
+    of?: string[];
+    ofAgentsCreatedInAdministration?: boolean;
+    maxPerAgent?: number;
 }
 /**
  * A ceiling in code of consultations defined as data, as `NhAssistantConsultationCeilingBuilder`
@@ -219,6 +316,8 @@ interface NhAssistantMockConsultationCeiling {
     maxTimeoutSeconds?: number;
     maxAnswerChars?: number;
     maxHistoryMessages?: number;
+    /** Every new consultation defined as data starts off until an administrator switches it on (`StartOff()`). */
+    startsOff?: boolean;
 }
 /** A consultation defined as data an agent of the scenario starts with. */
 interface NhAssistantMockDataConsultation extends DataConsultationRequest {
@@ -294,6 +393,12 @@ interface NhAssistantMockAdminScenario {
      * administration work per division, as an application that lists its divisions does.
      */
     runCatalog?: Partial<RunCatalog>;
+    /**
+     * The entries of agent metadata the application registers in code with `AddAgentMetadata`, which
+     * the run catalog lists as `agentMetadata`; the scenario's agents give their values in
+     * `metadata`, in code for an agent in code and stored for an agent created as data. Default none.
+     */
+    agentMetadata?: NhAssistantMockAgentMetadataEntry[];
     /**
      * 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
@@ -301,6 +406,16 @@ interface NhAssistantMockAdminScenario {
      * `consultationCeiling`. Without it consultations exist in code only.
      */
     consultationsAsData?: NhAssistantMockConsultationCeiling;
+    /**
+     * Lets administrators define hand-offs as data within this ceiling, as `UseHandOffsAsData` in code.
+     * Without it hand-offs exist in code only.
+     */
+    handOffsAsData?: NhAssistantMockHandOffCeiling;
+    /**
+     * Lets administrators create shadow variants as data within this ceiling, as
+     * `UseShadowVariantsAsData` in code. Without it shadow variants exist in code only.
+     */
+    shadowVariantsAsData?: NhAssistantMockShadowVariantCeiling;
     /**
      * 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
@@ -325,6 +440,36 @@ interface NhAssistantMockAdminScenario {
      * unavailable and any id that does not start with `unknown` is accepted.
      */
     accounts?: AssistantAccount[];
+    /**
+     * The application's text assets for instructions, as its `INhAiTextAssetSource` supplies them
+     * (`UseTextAssetSource`): the run catalog reports `instructionAssets`, `GET admin/instruction-assets`
+     * lists them, and skills and agents created in the administration may name one instead of inline
+     * instructions. Without it the application offers none. Change them afterwards with
+     * `NhAssistantMockBackend.setInstructionAsset` and `removeInstructionAsset`.
+     */
+    instructionAssets?: NhAssistantMockInstructionAsset[];
+    /**
+     * Agent packages the host imported before the mock starts, in order, as `POST
+     * admin/agent-packages/import` imports them after the scenario's agents and run configurations:
+     * their parts are linked and the parts they lock show read-only. A package the import refuses fails
+     * the scenario at once.
+     */
+    agentPackages?: NhAssistantMockAgentPackage[];
+}
+/** An agent package the mock's host imported, with the options of its import. */
+interface NhAssistantMockAgentPackage {
+    package: AgentPackage;
+    /** The technical account per agent whose run settings answer to one. */
+    serviceAccounts?: Record<string, string>;
+}
+/** One version of a text asset of the mock's application. */
+interface NhAssistantMockInstructionAsset {
+    assetId: string;
+    version: number;
+    content: string;
+    /** The asset that replaces it, when the application deprecated it. */
+    replacedByAssetId?: string;
+    deprecatedAt?: string;
 }
 /** A person in the simulated organization. */
 interface NhAssistantMockPerson {
@@ -619,6 +764,20 @@ interface NhAssistantMockProposal {
      * with the asker's rights.
      */
     grantSource?: AgentGrantSource;
+    /**
+     * Whether the application executes the proposal's tool (`ExecuteInApplication` on the server).
+     * Default `false`. Approved, such a proposal waits as `awaiting-application` until its report is due,
+     * four hours later; an `execution-unknown` one is handed to the application again
+     * (`POST approvals/{id}/resolve` with `hand-to-application`) instead of running again.
+     */
+    executedByApplication?: boolean;
+    /**
+     * When the application's report is due, an ISO date, for a proposal listed as `awaiting-application`
+     * or `execution-unknown` that the application executes. Default four hours after it was made.
+     */
+    executionReportDueAt?: string | null;
+    /** The execution's result code, such as `report-overdue`. Default none. */
+    executionResultCode?: string | null;
 }
 /** One request the mock API received, for assertions in tests. */
 interface NhAssistantMockRequest {
@@ -677,6 +836,7 @@ declare class NhAssistantMockBackend {
     private readonly config;
     private readonly conversations;
     private readonly pendingApprovals;
+    private readonly pendingQuestions;
     private readonly runs;
     /** Page context of the latest message per conversation, as the server stores it. */
     private readonly pageContexts;
@@ -687,6 +847,9 @@ declare class NhAssistantMockBackend {
     private readonly subjects;
     private readonly agentRuns;
     private readonly boards;
+    private readonly agentMetadata;
+    /** Agent packages: their endpoints, and the locks and links of every other administration request. */
+    private readonly agentPackages;
     private readonly canAdministerState;
     private readonly members;
     private readonly readPositions;
@@ -734,6 +897,13 @@ declare class NhAssistantMockBackend {
      * (`reauthorization-required`) or another authorization server (`issuer-changed`).
      */
     setMcpConnectionStatus(serverId: string, status: 'reauthorization-required' | 'issuer-changed'): void;
+    /**
+     * Publishes or changes one version of a text asset of the application. A skill or agent that names
+     * this version with another hash then reports `asset-changed`, as after the server's next load.
+     */
+    setInstructionAsset(asset: NhAssistantMockInstructionAsset): void;
+    /** Removes one version of a text asset; what names it reports `asset-missing`. */
+    removeInstructionAsset(assetId: string, version: number): void;
     /** The files people uploaded, oldest first, as the application's file source stored them. */
     get uploads(): readonly {
         conversationId: string;
@@ -760,9 +930,26 @@ declare class NhAssistantMockBackend {
      * (`consultation.movedToApprovalId`) and resumes the turn with the step's `left` steps.
      */
     private decide;
+    /**
+     * `POST conversations/{id}/approvals/{approvalId}/resolve`: the person who approved a proposal in this
+     * chat resolves its uncertain hand-off (`canResolve`), as the server does: `hand-to-application` hands
+     * it to the application again with a new report deadline, `mark-resolved` confirms it. Another action
+     * is refused, as are an approval in another status and one the caller may not resolve. Returns the
+     * conversation.
+     */
+    private resolve;
+    /**
+     * `POST conversations/{id}/questions/{questionId}/answer`: the addressee answers the question the
+     * turn waits for with the index of a choice, as on the server. Anyone else is refused, as are a
+     * choice the question does not offer and a question whose wait ended, which releases the
+     * conversation. The answer resumes the turn with the step's answered steps.
+     */
+    private answer;
     private cancel;
     private playSteps;
     private pauseForApproval;
+    /** Records the `ask_question` call and posts the question; the turn then waits for its answer. */
+    private pauseForQuestion;
     private stream;
     private findTurn;
     private update;
@@ -807,6 +994,13 @@ declare class NhAssistantMockBackend {
      */
     private consultationsOf;
     private nextId;
+    /**
+     * The answer of an administration endpoint (`admin/...`) as its area gives it, with the groups of
+     * agents and the run catalog in the request's language, without the package locks and links.
+     */
+    private adminResult;
+    /** An administration request of the agent packages, as `adminResult` answers it, for a path with its query. */
+    private adminCall;
     /** An administration answer about agents with each agent's groups, as the server answers it. */
     private withGroups;
     private groupsOf;
@@ -864,4 +1058,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, 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 };
+export type { NhAssistantMockAdminAgent, NhAssistantMockAdminScenario, NhAssistantMockAgentGroup, NhAssistantMockAgentMetadataEntry, NhAssistantMockAgentPackage, NhAssistantMockApprovalConsultation, NhAssistantMockApprovalStep, NhAssistantMockCodeHandOff, NhAssistantMockCollaboration, NhAssistantMockConnectionStep, NhAssistantMockConsultation, NhAssistantMockConsultationCeiling, NhAssistantMockDataConsultation, NhAssistantMockDataSkill, NhAssistantMockDataTrigger, NhAssistantMockDivision, NhAssistantMockErrorStep, NhAssistantMockFailStep, NhAssistantMockHandOffCeiling, NhAssistantMockHandOffRule, NhAssistantMockInstructionAsset, NhAssistantMockLiveMessage, NhAssistantMockMcpServer, NhAssistantMockPerson, NhAssistantMockProposal, NhAssistantMockQuestionStep, NhAssistantMockRemoteTool, NhAssistantMockRequest, NhAssistantMockRun, NhAssistantMockRunConfigurationPreset, NhAssistantMockRunNow, NhAssistantMockScenario, NhAssistantMockShadowVariantCeiling, NhAssistantMockStep, NhAssistantMockSubject, NhAssistantMockSubjectType, NhAssistantMockTextStep, NhAssistantMockTiming, NhAssistantMockToolStep, NhAssistantMockTurn, NhAssistantMockUpload };