@newheap/platform-ai-chat 0.20.0 → 0.22.0

package/fesm2022/newheap-platform-ai-chat-testing.mjs

@@ -1,6 +1,6 @@
 import * as i0 from '@angular/core';
 import { InjectionToken, inject, signal, Injectable, computed, DestroyRef, makeEnvironmentProviders } from '@angular/core';
-import { NH_ASSISTANT_AGENT_PACKAGE_MAX_AGENTS, NH_ASSISTANT_AGENT_PACKAGE_FORMAT_VERSION, NH_ASSISTANT_AGENT_PACKAGE_FORMAT, NH_ASSISTANT_PACKAGE_LOCK_ALL, NH_ASSISTANT_PACKAGE_LOCK_FIELDS, NH_ASSISTANT_AGENT_PACKAGE_MAX_BYTES, NH_ASSISTANT_UPLOAD_HEADER, ɵnhAssistantMediaTypeOf as _nhAssistantMediaTypeOf, NH_ASSISTANT_MAX_PROPOSAL_LOOKUP, NH_ASSISTANT_CONFIG, applyNhAssistantEvent, normalizeNhAssistantClientContext, applyNhAssistantApprovalDecision, applyNhAssistantQuestionAnswer, NH_ASSISTANT_FETCH, NH_ASSISTANT_UPLOAD, NhAssistantLiveService, NH_ASSISTANT_MCP_AUTHORIZATION_WINDOW } from '@newheap/platform-ai-chat';
+import { NH_ASSISTANT_AGENT_PACKAGE_FORMAT_VERSION, NH_ASSISTANT_AGENT_PACKAGE_FORMAT, NH_ASSISTANT_AGENT_PACKAGE_MAX_AGENTS, NH_ASSISTANT_PACKAGE_LOCK_ALL, NH_ASSISTANT_PACKAGE_LOCK_FIELDS, NH_ASSISTANT_AGENT_PACKAGE_MAX_BYTES, NH_ASSISTANT_UPLOAD_HEADER, ɵnhAssistantMediaTypeOf as _nhAssistantMediaTypeOf, NH_ASSISTANT_MAX_PROPOSAL_LOOKUP, NH_ASSISTANT_CONFIG, applyNhAssistantEvent, normalizeNhAssistantClientContext, applyNhAssistantApprovalDecision, applyNhAssistantQuestionAnswer, NH_ASSISTANT_FETCH, NH_ASSISTANT_UPLOAD, NhAssistantLiveService, NH_ASSISTANT_MCP_AUTHORIZATION_WINDOW } from '@newheap/platform-ai-chat';
 import { Observable, Subject } from 'rxjs';
 
 /**
@@ -65,7 +65,8 @@ const statusTable = {
         'assistant-forbidden',
         'assistant-mcp-credential-mismatch',
         'assistant-mcp-initiator-only',
-        'assistant-file-forbidden'
+        'assistant-file-forbidden',
+        'assistant-not-allowed-while-impersonating'
     ],
     404: [
         'assistant-disabled',
@@ -399,6 +400,10 @@ function mockWorksOnErrors(worksOn, knownTypes, agentPolicies, divisions) {
 }
 /** Whether an agent works on subjects of the type, as the server's rule decides it. */
 function mockWorksOnCovers(agent, subjectType) {
+    // A chat-only agent (`ChatOnly()` in code) works on no subject at all.
+    if (agent.chatOnly === true) {
+        return false;
+    }
     if (subjectType === mockSystemSubjectType) {
         return agent.worksOnApplication === true;
     }
@@ -418,6 +423,8 @@ const consultationRoutes = [
 const mockChatProfile = 'chat';
 const autonomyLevels = ['observe', 'explain', 'propose', 'simulate', 'execute'];
 const dataClassifications$1 = ['public', 'internal', 'confidential', 'restricted'];
+/** The most MCP servers one agent is assigned to, as the server allows. */
+const maxServersPerAgent = 32;
 /**
  * The agents of the mock administration: agents in code and agents created as data, their state,
  * shadow modes, technical accounts, feedback, evaluation and replays. The mock runs no agents on
@@ -434,18 +441,24 @@ class NhAssistantMockAdminAgents {
         const agents = admin.agents
             ?? scenario.agents.map(agent => ({ ...codeAgentFromSummary(agent), source: 'code' }));
         // How an agent runs, in code or as data, belongs to its run configuration, not to the agent.
-        for (const { source, skills, shadowOf, shadow, serviceAccount, worksOnDeclared, knownSubjectTypes, consultations, consultationDescriptions, codeRunSettings: _, runConfiguration: __, consultableAsData: ___, dataConsultations: ____, consultationTools: _____, codeHandOffs: ______, ...input } of agents) {
+        for (const { source, skills, shadowOf, shadow, serviceAccount, worksOnDeclared, knownSubjectTypes, consultations, consultationDescriptions, chatOnly, codeRunSettings: _, runConfiguration: __, consultableAsData: ___, dataConsultations: ____, consultationTools: _____, codeHandOffs: ______, ...input } of agents) {
             const variant = typeof shadowOf === 'string';
             const agentShadow = variant || shadow === true;
+            // A chat-only agent has no shadow threads: it and its skills always work live.
+            const live = source === 'code' && chatOnly === true;
             const initial = this.toAgent(input, source, 1, false);
             this.agents.set(input.id, {
                 agent: {
                     ...initial,
                     // Code says what its agents work on; a scenario agent that says nothing works on all objects.
                     ...(source === 'code' ? { ...(mockWorksOnFromInput(input) ?? mockUndeclaredWorksOn), worksOnDeclared: worksOnDeclared ?? mockWorksOnFromInput(input) !== null } : {}),
+                    // A chat-only agent in code (`ChatOnly()`) works on nothing, said on purpose.
+                    ...(source === 'code' && chatOnly === true
+                        ? { chatOnly: true, worksOnSubjectTypes: [], worksOnAllSubjects: false, worksOnApplication: false, perDivision: false, worksOnDeclared: true }
+                        : {}),
                     knownSubjectTypes: knownSubjectTypes ?? [],
                     shadowOf: shadowOf ?? null,
-                    shadow: shadowState(agentShadow, variant || shadow === true, null, variant),
+                    shadow: shadowState(agentShadow, variant || shadow === true, null, variant || live),
                     serviceAccount: serviceAccount === undefined
                         ? null
                         : { actorId: serviceAccount, configuredActorId: serviceAccount, overridden: false, changedAt: null, changedBy: null, reason: null },
@@ -463,7 +476,7 @@ class NhAssistantMockAdminAgents {
                         dailyTokens: null,
                         cancelledRuns: 0,
                         startedRuns: 0,
-                        shadow: shadowState(agentShadow || skill.shadow === true, skill.shadow === true, null, variant)
+                        shadow: shadowState(!live && (agentShadow || skill.shadow === true), skill.shadow === true, null, variant || live)
                     }))
                 },
                 codeDefinition: source === 'code' ? structuredClone(input) : null,
@@ -543,6 +556,29 @@ class NhAssistantMockAdminAgents {
         live.agent = this.toAgent(definition, live.agent.source, live.agent.version + 1, live.agent.source === 'code', live.agent);
         return live.agent;
     }
+    /**
+     * Assigns an MCP server to an agent or removes the assignment, as `PUT` and
+     * `DELETE admin/mcp-servers/{id}/agents/{agentId}` do: only the assignment changes, never the agent's
+     * version; an agent has at most 32 servers.
+     */
+    setMcpAssignment(agentId, serverId, assign) {
+        const stored = this.agents.get(agentId);
+        if (!stored) {
+            return 'agent-not-found';
+        }
+        const assigned = stored.agent.mcpServerIds.includes(serverId);
+        if (assigned === assign) {
+            return 'unchanged';
+        }
+        if (assign && stored.agent.mcpServerIds.length >= maxServersPerAgent) {
+            return 'too-long';
+        }
+        stored.agent = {
+            ...stored.agent,
+            mcpServerIds: assign ? [...stored.agent.mcpServerIds, serverId] : stored.agent.mcpServerIds.filter(id => id !== serverId)
+        };
+        return 'changed';
+    }
     /** Removes a deleted MCP server from the agents it was assigned to. */
     removeServer(serverId) {
         for (const agent of this.agents.values()) {
@@ -600,7 +636,7 @@ class NhAssistantMockAdminAgents {
             if (refused) {
                 return refused;
             }
-            const created = this.toAgent(input, 'admin', 1, false);
+            const created = this.toAgent({ ...input, mcpServerIds: input.mcpServerIds ?? [] }, 'admin', 1, false);
             // A data shadow variant always works in shadow and is never offered in the chat.
             const agent = shadowOf === null
                 ? created
@@ -660,7 +696,8 @@ class NhAssistantMockAdminAgents {
                 return mockFailure('assistant-version-conflict');
             }
             const { expectedVersion, ...definition } = input;
-            const updated = this.toAgent(definition, stored.agent.source, stored.agent.version + 1, stored.agent.source === 'code', stored.agent);
+            // An omitted list keeps the agent's assignments; an empty list removes them.
+            const updated = this.toAgent({ ...definition, mcpServerIds: definition.mcpServerIds ?? stored.agent.mcpServerIds }, stored.agent.source, stored.agent.version + 1, stored.agent.source === 'code', stored.agent);
             // A data shadow variant keeps its live agent and stays out of the chat.
             stored.agent = stored.agent.source === 'admin' && stored.agent.shadowOf ? { ...updated, offeredInChat: false } : updated;
             return { status: 200, body: stored.agent };
@@ -714,6 +751,10 @@ class NhAssistantMockAdminAgents {
         if (request === null) {
             return mockValidationFailure();
         }
+        // The skills of a chat-only agent always work live.
+        if (stored.agent.chatOnly === true) {
+            return mockFailure('assistant-agent-does-not-work-on');
+        }
         const agentShadow = stored.agent.shadow ?? shadowState(false, false, null, false);
         if (agentShadow.locked) {
             return mockFailure('assistant-shadow-variant');
@@ -888,6 +929,10 @@ class NhAssistantMockAdminAgents {
         if (request === null) {
             return mockValidationFailure();
         }
+        // A chat-only agent has no runs that could work in shadow threads.
+        if (stored.agent.chatOnly === true) {
+            return mockFailure('assistant-agent-does-not-work-on');
+        }
         const current = stored.agent.shadow ?? shadowState(false, false, null, false);
         if (current.locked) {
             return mockFailure('assistant-shadow-variant');
@@ -1128,7 +1173,9 @@ class NhAssistantMockAdminAgents {
             typeof input.description === 'string' &&
             typeof input.instructions === 'string' && input.instructions.length <= mockMaxInstructions &&
             Array.isArray(input.toolSelectors) && input.toolSelectors.every(selector => /^[a-z0-9*][a-z0-9.*-]*$/.test(selector)) &&
-            Array.isArray(input.mcpServerIds) && input.mcpServerIds.every(serverId => this.rules.hasServer(serverId)) &&
+            // Omitted, a new agent has no servers and an update keeps them, as on the server.
+            (input.mcpServerIds === undefined || input.mcpServerIds === null ||
+                (Array.isArray(input.mcpServerIds) && input.mcpServerIds.every(serverId => this.rules.hasServer(serverId)))) &&
             (input.requiredPolicy === null || (typeof input.requiredPolicy === 'string' && (!policies || policies.includes(input.requiredPolicy)))) &&
             autonomyLevels.includes(input.autonomy) &&
             (input.isEnabled === undefined || typeof input.isEnabled === 'boolean');
@@ -1151,6 +1198,8 @@ class NhAssistantMockAdminAgents {
         const classification = chosenClassification(dataClassification);
         return this.withWarnings({
             ...definition,
+            // The callers name the servers; an omitted list keeps those of the agent, or none.
+            mcpServerIds: definition.mcpServerIds ?? previous?.mcpServerIds ?? [],
             // An agent created here keeps its profile when the input omits it; code decides for the others.
             profile: chosenProfile ?? previous?.profile ?? mockChatProfile,
             // The same for its classification; an agent in code keeps the one of its scenario.
@@ -1317,6 +1366,9 @@ const readerPriority = { min: -1000, max: 1000 };
 const classifications$1 = ['public', 'internal', 'confidential', 'restricted'];
 const mediaTypePattern$1 = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/;
 const controlCharacters = /[\u0000-\u001f\u007f]/;
+/** The longest remote tool name a sync stores, and the most tools of a server that wait for a sync. */
+const maxRemoteName = 128;
+const maxToolsAwaitingSync = 100;
 /**
  * The MCP servers of the mock administration and the caller's own connections: secrets are
  * write-only, new tools start disabled as mutations, a changed remote schema disables a tool, OAuth
@@ -1636,6 +1688,10 @@ class NhAssistantMockAdminMcp {
                     stored.organization?.status === 'issuer-changed') {
                     stored.organization = { ...stored.organization, status: 'active' };
                 }
+                if (!keepsSecret(before, input)) {
+                    // As on the server: a stored secret never follows the server to another destination.
+                    stored.secret = null;
+                }
                 if (!secretModes.includes(input.authMode)) {
                     stored.secret = null;
                     stored.server.secretReference = null;
@@ -1744,19 +1800,20 @@ class NhAssistantMockAdminMcp {
         if (length === 5 && action === 'tools' && method === 'PUT' && child !== undefined) {
             const tool = stored.tools.get(child);
             const input = body;
-            if (!tool) {
-                return mockFailure('assistant-mcp-tool-not-found');
-            }
             if (typeof input?.isEnabled !== 'boolean' || (input.effect !== 'read-only' && input.effect !== 'mutation') ||
                 (input.descriptionOverride !== null && typeof input.descriptionOverride !== 'string')) {
                 return mockValidationFailure();
             }
-            if (input.isEnabled && tool.status === 'missing') {
-                return mockValidationFailure('isEnabled');
-            }
             const override = typeof input.descriptionOverride === 'string' && input.descriptionOverride.trim().length > 0
                 ? input.descriptionOverride.slice(0, 1_000)
                 : null;
+            if (!tool) {
+                return this.reviewBeforeSync(stored, child, input.isEnabled, input.effect, override);
+            }
+            // A tool the server no longer lists cannot be enabled; one that no sync has seen yet can.
+            if (input.isEnabled && tool.status === 'missing' && !tool.awaitingSync) {
+                return mockFailure('assistant-mcp-tool-disabled');
+            }
             const updated = {
                 ...tool,
                 isEnabled: input.isEnabled,
@@ -1767,14 +1824,77 @@ class NhAssistantMockAdminMcp {
             stored.tools.set(child, updated);
             return { status: 200, body: toTool(updated) };
         }
+        if (length === 5 && action === 'agents' && child !== undefined) {
+            if (method !== 'PUT' && method !== 'DELETE') {
+                return { status: 405 };
+            }
+            // Only the assignment changes, never the agent's version, as on the server.
+            const changed = this.context.setAssignment(stored.server.id, child, method === 'PUT');
+            if (changed === 'agent-not-found') {
+                return mockFailure('assistant-agent-not-found');
+            }
+            if (changed === 'too-long') {
+                return mockFailure('assistant-validation', { mcpServerIds: ['too-long'] });
+            }
+            return { status: 200, body: this.toServer(stored) };
+        }
         return mockFailure('assistant-not-found');
     }
+    /**
+     * The reviewed settings of a tool that no sync has seen yet, as the server stores them: a missing tool
+     * without a schema that waits for its sync, with a name a sync could store and no other spelling of
+     * a stored tool's name; at most 100 per server.
+     */
+    reviewBeforeSync(stored, remoteName, isEnabled, effect, descriptionOverride) {
+        if (remoteName.trim().length === 0) {
+            return mockFailure('assistant-validation', { remoteName: ['required'] });
+        }
+        if (remoteName.length > maxRemoteName) {
+            return mockFailure('assistant-validation', { remoteName: ['too-long'] });
+        }
+        const lower = remoteName.toLowerCase();
+        if (controlCharacters.test(remoteName) || [...stored.tools.keys()].some(name => name.toLowerCase() === lower)) {
+            return mockFailure('assistant-validation', { remoteName: ['invalid'] });
+        }
+        if ([...stored.tools.values()].filter(tool => tool.awaitingSync).length >= maxToolsAwaitingSync) {
+            return mockFailure('assistant-configuration-limit');
+        }
+        const tool = {
+            remoteName,
+            localId: `mcp.${stored.server.id}.${kebab(remoteName)}`,
+            description: '',
+            descriptionOverride,
+            isEnabled,
+            effect,
+            status: 'missing',
+            readOnlyHint: null,
+            awaitingSync: true,
+            inputSchemaHash: ''
+        };
+        stored.tools.set(remoteName, tool);
+        return { status: 200, body: toTool(tool) };
+    }
     sync(stored) {
         const seen = new Set();
         for (const remote of stored.remoteTools) {
             seen.add(remote.remoteName);
-            const existing = stored.tools.get(remote.remoteName);
+            const existing = stored.tools.get(remote.remoteName) ?? this.reviewedInOtherSpelling(stored, remote.remoteName);
             const description = remote.description.slice(0, 1_000);
+            if (existing?.awaitingSync) {
+                // The first sync that sees a reviewed tool keeps its settings and takes the server's spelling.
+                stored.tools.delete(existing.remoteName);
+                stored.tools.set(remote.remoteName, {
+                    ...existing,
+                    remoteName: remote.remoteName,
+                    localId: `mcp.${stored.server.id}.${kebab(remote.remoteName)}`,
+                    description,
+                    status: 'available',
+                    readOnlyHint: remote.readOnlyHint ?? null,
+                    awaitingSync: false,
+                    inputSchemaHash: remote.inputSchemaHash
+                });
+                continue;
+            }
             if (!existing) {
                 stored.tools.set(remote.remoteName, {
                     remoteName: remote.remoteName,
@@ -1800,11 +1920,19 @@ class NhAssistantMockAdminMcp {
             });
         }
         for (const [name, tool] of stored.tools) {
-            if (!seen.has(name)) {
+            // A reviewed tool that this sync does not see keeps waiting with its settings.
+            if (!seen.has(name) && !tool.awaitingSync) {
                 stored.tools.set(name, { ...tool, isEnabled: false, status: 'missing' });
             }
         }
     }
+    /** A reviewed tool that waits for its sync under another spelling of a name no remote tool has. */
+    reviewedInOtherSpelling(stored, remoteName) {
+        const lower = remoteName.toLowerCase();
+        const names = new Set(stored.remoteTools.map(remote => remote.remoteName));
+        return [...stored.tools.values()]
+            .find(tool => tool.awaitingSync && !names.has(tool.remoteName) && tool.remoteName.toLowerCase() === lower);
+    }
     /**
      * The field errors of a server change, as the server reports them in one refusal: the fields
      * themselves, the credential and the OAuth settings. Empty when the change is valid.
@@ -2124,17 +2252,20 @@ class NhAssistantMockAdminMcp {
         if (input.secret && input.secretReference) {
             add('secretReference', 'invalid');
         }
+        // As on the server: a stored secret and reference serve only the destination they were given for.
+        const keeps = keepsSecret(stored?.server, input);
         const reference = input.secretReference === undefined || input.secretReference === null
-            ? (input.secret ? null : stored?.server.secretReference ?? null)
+            ? (input.secret || !keeps ? null : stored?.server.secretReference ?? null)
             : input.secretReference || null;
         if (reference !== null && (!secretReference.test(reference) || reference.includes('..'))) {
             add('secretReference', 'invalid');
         }
         if (secretModes.includes(input.authMode)) {
             // As on the server: bearer, api-key and basic need a stored secret or a reference. A new stored
-            // secret replaces a reference, a new reference a stored secret.
+            // secret replaces a reference, a new reference a stored secret, and another destination needs
+            // either again.
             const storedSecret = input.secret === undefined || input.secret === null
-                ? !!stored?.secret && !input.secretReference
+                ? keeps && !!stored?.secret && !input.secretReference
                 : input.secret.length > 0;
             if (!storedSecret && (reference === null || !!input.secret)) {
                 add('secret', 'required');
@@ -2208,10 +2339,32 @@ class NhAssistantMockAdminMcp {
         };
     }
 }
+/**
+ * Whether a stored secret and reference stay with the server after the input, as on the server: the
+ * URL keeps its origin (scheme, host and port), and the authentication mode and the `api-key` header,
+ * in any letter case, stay the same.
+ */
+function keepsSecret(stored, input) {
+    const before = stored ? originOf(stored.url) : null;
+    if (!stored || before === null || stored.authMode !== input.authMode || before !== originOf(input.url)) {
+        return false;
+    }
+    return input.authMode !== 'api-key'
+        || (stored.headerName || 'X-Api-Key').toLowerCase() === (input.headerName || 'X-Api-Key').toLowerCase();
+}
+/** The origin of an absolute URL in lowercase, or `null` for an invalid one. */
+function originOf(url) {
+    try {
+        return new URL(url.trim()).origin.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
 function toServerFields(input, stored) {
     const usesSecret = secretModes.includes(input.authMode);
     const reference = input.secretReference === undefined || input.secretReference === null
-        ? (input.secret ? null : stored?.secretReference ?? null)
+        ? (input.secret || !keepsSecret(stored, input) ? null : stored?.secretReference ?? null)
         : input.secretReference || null;
     const certificate = input.clientCertificateReference === undefined || input.clientCertificateReference === null
         ? stored?.clientCertificateReference ?? null
@@ -2482,7 +2635,7 @@ function allowedServerUrl(value) {
     }
 }
 function toTool({ inputSchemaHash, ...tool }) {
-    return tool;
+    return { ...tool, awaitingSync: tool.awaitingSync === true };
 }
 function toTools(stored) {
     return [...stored.tools.values()].map(toTool);
@@ -2789,7 +2942,9 @@ class NhAssistantMockHandOffs {
                 ...data.map(agent => {
                     const hasRunSettings = this.agents.isConfigured(agent);
                     return {
-                        agentId: agent.id, displayName: agent.displayName, source: 'data', hasRunSettings, inEffect: hasRunSettings, problem: null, version: agent.version
+                        agentId: agent.id, displayName: agent.displayName, source: 'data', hasRunSettings, inEffect: hasRunSettings, problem: null, version: agent.version,
+                        packageId: null,
+                        packageVersion: null
                     };
                 })
             ]
@@ -4435,6 +4590,7 @@ class NhAssistantMockAdmin {
             agents: () => this.agents.all(),
             chatAgentIds: () => this.agents.chatAgents().map(agent => agent.id),
             removeServer: serverId => this.agents.removeServer(serverId),
+            setAssignment: (serverId, agentId, assign) => this.agents.setMcpAssignment(agentId, serverId, assign),
             canAdminister: () => this.canAdminister
         });
         this.presetRunConfigurations(admin.agents ?? []);
@@ -4866,8 +5022,139 @@ class NhAssistantMockAgentPackages {
         if (segments[1] === 'agents' && segments[3] === 'package' && segments[4] === 'unlink' && segments.length === 5) {
             return method === 'POST' ? this.unlink(segments[2], body) : { status: 405 };
         }
+        // A promotion as the package's version is an import of the variant's parts onto its live agent.
+        if (segments[1] === 'agents' && segments[3] === 'promote' && segments.length === 4
+            && body?.asPackageVersion === true) {
+            return method === 'POST' ? this.promoteAsPackageVersion(segments[2], body) : { status: 405 };
+        }
         return null;
     }
+    /**
+     * `POST admin/agents/{id}/promote` with `asPackageVersion` (FB11): a data shadow variant whose every
+     * part is linked to one package becomes that package's next version of its live agent. Its parts,
+     * as an export reads them, are imported onto the live agent with the import's rules and relinked;
+     * the live agent keeps its name and chat offer, an agent in code its run settings in code. The
+     * variant leaves first, with its links, so its trigger ids are free, and the live agent leaves the
+     * package it belonged to; a refused part puts everything back and answers the import's
+     * `409 assistant-package-refused`. A part without a link answers `404 assistant-package-not-linked`.
+     */
+    promoteAsPackageVersion(variantId, body) {
+        const listed = this.context.call('GET', 'admin/agents');
+        if (listed.status !== 200) {
+            return listed;
+        }
+        const request = (body ?? {});
+        if (typeof request.expectedVersion !== 'number') {
+            return mockFailure('assistant-validation', { expectedVersion: ['required'] });
+        }
+        if (request.moveSkills === true) {
+            return mockFailure('assistant-validation', { moveSkills: ['not-allowed'] });
+        }
+        const variantRead = this.read(variantId);
+        if (!variantRead) {
+            return mockFailure('assistant-agent-not-found');
+        }
+        const variant = variantRead.agent;
+        if (variant.source !== 'admin' || !variant.shadowOf) {
+            return mockFailure('assistant-not-shadow-variant');
+        }
+        const liveRead = this.read(variant.shadowOf);
+        if (!liveRead) {
+            return mockFailure('assistant-agent-not-found');
+        }
+        const live = liveRead.agent;
+        if (request.expectedVersion !== live.version
+            || (typeof request.expectedVariantVersion === 'number' && request.expectedVariantVersion !== variant.version)) {
+            return mockFailure('assistant-version-conflict');
+        }
+        // Every part of the variant is linked to its package.
+        const link = this.links.get(variantId);
+        const parts = this.packageAgentOf(variantRead);
+        if (!link || [...partsOf(parts).keys()].some(part => !link.parts.has(part))) {
+            return mockFailure('assistant-package-not-linked');
+        }
+        const inCode = live.source === 'code';
+        const carried = parts.definition;
+        const definition = !carried
+            ? null
+            : inCode
+                ? {
+                    description: carried.description,
+                    instructions: carried.instructions,
+                    toolSelectors: carried.toolSelectors,
+                    requiredPolicy: carried.requiredPolicy,
+                    autonomy: carried.autonomy
+                }
+                : { ...carried, displayName: live.displayName, offeredInChat: live.offeredInChat !== false, shadowOf: null, startsOff: null, startsInShadow: null };
+        const locks = Object.fromEntries([...link.parts]
+            .filter(([part, partLink]) => partLink.lockedFields.length > 0 && (part !== 'runSettings' || !inCode))
+            .map(([part, partLink]) => [part, [...partLink.lockedFields]]));
+        const agent = withoutNulls({
+            ...parts,
+            id: live.id,
+            source: live.source,
+            definition,
+            runSettings: inCode ? null : parts.runSettings,
+            groups: null,
+            hashes: null,
+            locks: Object.keys(locks).length > 0 ? locks : null
+        });
+        const agentPackage = {
+            format: NH_ASSISTANT_AGENT_PACKAGE_FORMAT,
+            formatVersion: NH_ASSISTANT_AGENT_PACKAGE_FORMAT_VERSION,
+            package: { id: link.packageId, version: link.packageVersion },
+            agents: [agent]
+        };
+        // The live agent's technical account stays; without one it takes the variant's.
+        const account = liveRead.configuration?.runSettings?.serviceAccountActorId
+            ?? variantRead.configuration?.runSettings?.serviceAccountActorId
+            ?? null;
+        // All of it or nothing: the variant leaves first, and the package's other agents stay linked.
+        const restore = [this.context.snapshot(), this.snapshot()];
+        const others = [...this.links].filter(([agentId, item]) => item.packageId === link.packageId && agentId !== variantId);
+        this.links.delete(variantId);
+        const deleted = this.context.call('DELETE', `admin/agents/${encodeURIComponent(variantId)}`);
+        if (deleted.status >= 300) {
+            restore.forEach(put => put());
+            return deleted;
+        }
+        for (const [agentId] of others) {
+            this.links.delete(agentId);
+        }
+        this.links.delete(live.id);
+        for (const installed of this.installed.values()) {
+            installed.agents = installed.agents.filter(agentId => agentId !== live.id && agentId !== variantId);
+        }
+        const imported = this.importPackage({
+            package: agentPackage,
+            options: { relink: [{ agentId: live.id }], serviceAccounts: account ? { [live.id]: account } : null }
+        }, true);
+        if (imported.status !== 200) {
+            restore.forEach(put => put());
+            return imported;
+        }
+        for (const [agentId, item] of others) {
+            this.links.set(agentId, item);
+        }
+        this.installed.set(link.packageId, {
+            version: link.packageVersion,
+            agents: [...others.map(([agentId]) => agentId), live.id].sort()
+        });
+        const result = imported.body;
+        const promoted = this.read(live.id).agent;
+        return {
+            status: 200,
+            body: {
+                agent: this.withAgentPackage(promoted),
+                variantId,
+                movedSkills: result.parts
+                    .filter(part => part.part.startsWith('skill:') && part.outcome !== 'refused' && part.outcome !== 'left-behind' && part.outcome !== 'kept-local')
+                    .map(part => part.part.slice('skill:'.length))
+                    .sort(),
+                package: result
+            }
+        };
+    }
     /**
      * Runs a save of the administration under the package locks: a save may keep a locked field's value
      * or take the package's, never another; such a change is undone and refused with `{field}: locked`.
@@ -4975,6 +5262,22 @@ class NhAssistantMockAgentPackages {
                     return { ...result, body: this.withLink(agentId, `metadata:${id}`, body) };
                 }
                 return { ...result, body: body.map(entry => this.withLink(agentId, `metadata:${entry.name}`, entry)) };
+            case 'shadow-variants': {
+                // A data variant names the package its parts are linked to.
+                const listing = body;
+                return {
+                    ...result,
+                    body: {
+                        ...listing,
+                        variants: listing.variants.map(variant => {
+                            const link = this.links.get(variant.agentId);
+                            return variant.source === 'data' && link && link.parts.size > 0
+                                ? { ...variant, packageId: link.packageId, packageVersion: link.packageVersion }
+                                : variant;
+                        })
+                    }
+                };
+            }
             default:
                 return result;
         }
@@ -6951,8 +7254,9 @@ class NhAssistantMockAgentRuns {
     }
     /**
      * `POST runs/{id}/retry`: resumes a failed or cancelled run (`queued`), or restarts the agent in the
-     * same thread like a start by hand; needs the approver role on the thread. The mock's resumed
-     * attempt ends at once as the scenario's `runNow` says.
+     * same thread like a start by hand; needs the approver role on the thread, and a restart also passes
+     * the start checks of `POST threads/start`. The mock's resumed attempt ends at once as the
+     * scenario's `runNow` says.
      */
     retry(runId, body, language) {
         const mode = body?.mode ?? 'resume';
@@ -6978,7 +7282,17 @@ class NhAssistantMockAgentRuns {
             return mockFailure('assistant-agent-not-found');
         }
         if (mode === 'restart') {
-            return this.startNow(agent, found.thread.subject);
+            // A restart starts the agent again for the caller: the rule of a start by hand decides, with the
+            // caller's live role.
+            const subject = this.subjects.describe(found.thread.subject.subjectType, found.thread.subject.subjectId, language, this.context.administers());
+            if (!subject) {
+                return mockFailure('assistant-subject-access-denied');
+            }
+            const refusal = this.refusal(agent, subject);
+            if (refusal) {
+                return mockFailure(refusal);
+            }
+            return this.startNow(agent, subject);
         }
         const runNow = this.scenario.runNow?.[agent.id] ?? {};
         const status = runNow.status ?? 'completed';
@@ -7964,7 +8278,8 @@ class NhAssistantMockProposals {
                     parent: item.parent ?? null,
                     canGiveFeedback: false,
                     consultationId: item.consultationId ?? null,
-                    consultationRoute: route
+                    consultationRoute: route,
+                    ...(item.supersededByApprovalId ? { supersededByApprovalId: item.supersededByApprovalId } : {})
                 },
                 divisionId: item.divisionId ?? null,
                 canDecide,
@@ -8830,7 +9145,10 @@ class NhAssistantMockBackend {
         if (filesCode) {
             return this.error(filesCode);
         }
-        if (!acceptsMessage(conversation.status)) {
+        // Like the server: a question or an approval that passed its lifetime closes as expired, and the
+        // message starts its turn (CS9).
+        this.closeExpiredWait(conversation);
+        if (!acceptsMessage(this.conversations.get(conversation.id)?.status ?? conversation.status)) {
             return this.empty(409);
         }
         // Like the server: an invalid page context is dropped, never a 400.
@@ -9005,6 +9323,28 @@ class NhAssistantMockBackend {
             await this.playSteps(conversation.id, assistantMessageId, steps, emit);
         });
     }
+    /**
+     * Closes the question or the approval a chat waits for once its lifetime passed, as a late answer or
+     * decision closes it on the server; one that is still valid keeps the chat busy. Agent threads keep
+     * their own rules.
+     */
+    closeExpiredWait(conversation) {
+        if (conversation.status !== 'waiting-for-approval' || conversation.kind === 'thread') {
+            return;
+        }
+        const now = Date.now();
+        const question = this.pendingQuestions.get(conversation.id);
+        if (question && Date.parse(question.question.expiresAt) <= now) {
+            this.pendingQuestions.delete(conversation.id);
+            this.update(conversation.id, current => withClosedQuestion(current, question.question.questionId, 'expired'));
+            return;
+        }
+        const pending = this.pendingApprovals.get(conversation.id);
+        if (pending && Date.parse(pending.approval.expiresAt) <= now) {
+            this.pendingApprovals.delete(conversation.id);
+            this.update(conversation.id, current => withExpiredApproval(current, pending.approval.approvalId, pending.invocationId));
+        }
+    }
     cancel(conversation) {
         const run = this.runs.get(conversation.id);
         if (run) {
@@ -9589,6 +9929,27 @@ function withClosedQuestion(conversation, questionId, status) {
         messages: conversation.messages.map(message => ({ ...message, parts: message.parts.map(closed) }))
     };
 }
+/**
+ * An approval that passed its lifetime, as the server closes it when the next message arrives: it
+ * expired, its call failed with `assistant-approval-expired`, and the conversation takes the message.
+ */
+function withExpiredApproval(conversation, approvalId, invocationId) {
+    const expired = (part) => {
+        if (part.type === 'approval' && part.approvalId === approvalId) {
+            return { ...part, status: 'expired' };
+        }
+        if (part.type === 'tool-call' && part.invocationId === invocationId) {
+            return { ...part, status: 'failed', resultCode: 'assistant-approval-expired' };
+        }
+        return part;
+    };
+    return {
+        ...conversation,
+        status: 'idle',
+        pendingApproval: null,
+        messages: conversation.messages.map(message => ({ ...message, parts: message.parts.map(expired) }))
+    };
+}
 /** Like the server: a new message starts in an idle conversation or after a failed turn. */
 function acceptsMessage(status) {
     return status === 'idle' || status === 'failed';