@newheap/platform-ai-chat 0.18.0 → 0.19.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_UPLOAD_HEADER, ɵnhAssistantMediaTypeOf as _nhAssistantMediaTypeOf, NH_ASSISTANT_MAX_PROPOSAL_LOOKUP, NH_ASSISTANT_CONFIG, applyNhAssistantEvent, normalizeNhAssistantClientContext, applyNhAssistantApprovalDecision, NH_ASSISTANT_FETCH, NH_ASSISTANT_UPLOAD, NhAssistantLiveService, NH_ASSISTANT_MCP_AUTHORIZATION_WINDOW } from '@newheap/platform-ai-chat';
+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, NH_ASSISTANT_FETCH, NH_ASSISTANT_UPLOAD, NhAssistantLiveService, NH_ASSISTANT_MCP_AUTHORIZATION_WINDOW } from '@newheap/platform-ai-chat';
 import { Observable, Subject } from 'rxjs';
 
 /**
@@ -68,6 +68,8 @@ const statusTable = {
         'assistant-disabled',
         'assistant-conversation-not-found',
         'assistant-agent-not-found',
+        'assistant-metadata-entry-not-found',
+        'assistant-instructions-asset-not-found',
         'assistant-approval-not-found',
         'assistant-share-link-invalid',
         'assistant-participant-not-found',
@@ -84,6 +86,8 @@ const statusTable = {
         'assistant-artifact-not-found',
         'assistant-trigger-not-found',
         'assistant-consultation-not-found',
+        'assistant-handoff-not-found',
+        'assistant-package-not-linked',
         'assistant-not-found',
         'assistant-context-not-found',
         'assistant-mcp-server-not-found',
@@ -114,6 +118,9 @@ const statusTable = {
         'assistant-consult-proposal-moved',
         'assistant-consultation-in-code',
         'assistant-consultations-not-allowed',
+        'assistant-handoffs-not-allowed',
+        'assistant-handoff-in-code',
+        'assistant-shadow-variants-not-allowed',
         'assistant-skill-in-code',
         'assistant-trigger-in-code',
         'assistant-skill-in-use',
@@ -131,6 +138,10 @@ const statusTable = {
         'assistant-agent-exists',
         'assistant-code-agent-not-deletable',
         'assistant-agent-not-code',
+        'assistant-metadata-read-only',
+        'assistant-package-refused',
+        'assistant-package-locked',
+        'assistant-agent-instructions-unavailable',
         'assistant-mcp-server-exists',
         'assistant-mcp-headless-not-allowed',
         'assistant-mcp-consent-required',
@@ -144,6 +155,7 @@ const statusTable = {
     ],
     413: [
         'assistant-webhook-payload-too-large',
+        'assistant-package-too-large',
         'assistant-file-too-large'
     ],
     415: [
@@ -169,6 +181,7 @@ const statusTable = {
         'assistant-proposal-check-failed',
         'assistant-trigger-rolled-back',
         'assistant-mcp-secret-unavailable',
+        'assistant-instructions-asset-unavailable',
         'assistant-file-unavailable',
         'assistant-file-upload-failed'
     ]
@@ -215,6 +228,22 @@ function mockFailure(code, errors) {
 function mockValidationFailure(field) {
     return mockFailure('assistant-validation', field ? { [field]: ['invalid'] } : undefined);
 }
+/**
+ * Copies the stored state of a mock area: the returned function puts every map back as it was, so
+ * an agent package import that one part refuses leaves nothing behind, as the server's one
+ * transaction does, and a preview tries the import without keeping it.
+ */
+function mockSnapshot(...maps) {
+    const copies = maps.map(map => structuredClone(map));
+    return () => {
+        maps.forEach((map, index) => {
+            map.clear();
+            for (const [key, value] of copies[index]) {
+                map.set(key, value);
+            }
+        });
+    };
+}
 /** A stable, non-cryptographic fingerprint; the mock only needs change detection. */
 /**
  * The warnings of an agent or skill that classifies its model calls with `classification` on
@@ -397,8 +426,9 @@ 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: ____, ...input } of agents) {
-            const agentShadow = shadowOf !== undefined || shadow === true;
+        for (const { source, skills, shadowOf, shadow, serviceAccount, worksOnDeclared, knownSubjectTypes, consultations, consultationDescriptions, codeRunSettings: _, runConfiguration: __, consultableAsData: ___, dataConsultations: ____, consultationTools: _____, codeHandOffs: ______, ...input } of agents) {
+            const variant = typeof shadowOf === 'string';
+            const agentShadow = variant || shadow === true;
             const initial = this.toAgent(input, source, 1, false);
             this.agents.set(input.id, {
                 agent: {
@@ -407,7 +437,7 @@ class NhAssistantMockAdminAgents {
                     ...(source === 'code' ? { ...(mockWorksOnFromInput(input) ?? mockUndeclaredWorksOn), worksOnDeclared: worksOnDeclared ?? mockWorksOnFromInput(input) !== null } : {}),
                     knownSubjectTypes: knownSubjectTypes ?? [],
                     shadowOf: shadowOf ?? null,
-                    shadow: shadowState(agentShadow, shadowOf !== undefined || shadow === true, null, shadowOf !== undefined),
+                    shadow: shadowState(agentShadow, variant || shadow === true, null, variant),
                     serviceAccount: serviceAccount === undefined
                         ? null
                         : { actorId: serviceAccount, configuredActorId: serviceAccount, overridden: false, changedAt: null, changedBy: null, reason: null },
@@ -425,7 +455,7 @@ class NhAssistantMockAdminAgents {
                         dailyTokens: null,
                         cancelledRuns: 0,
                         startedRuns: 0,
-                        shadow: shadowState(agentShadow || skill.shadow === true, skill.shadow === true, null, shadowOf !== undefined)
+                        shadow: shadowState(agentShadow || skill.shadow === true, skill.shadow === true, null, variant)
                     }))
                 },
                 codeDefinition: source === 'code' ? structuredClone(input) : null,
@@ -439,6 +469,18 @@ class NhAssistantMockAdminAgents {
     find(agentId) {
         return this.agents.get(agentId)?.agent;
     }
+    /**
+     * A copy of the agents and their replays; the returned function puts it back, for an import of an
+     * agent package that fails as a whole and for its preview.
+     */
+    snapshot() {
+        return mockSnapshot(this.agents, this.replays);
+    }
+    /** The definition in code of an agent in code, as `reset` restores it; `null` for an agent created here. */
+    codeDefinition(agentId) {
+        const definition = this.agents.get(agentId)?.codeDefinition;
+        return definition ? structuredClone(definition) : null;
+    }
     has(agentId) {
         return this.agents.has(agentId);
     }
@@ -446,6 +488,18 @@ class NhAssistantMockAdminAgents {
     all() {
         return [...this.agents.values()].map(stored => stored.agent);
     }
+    /**
+     * Makes the next version of an agent, as a change of the metadata of an agent created here does on
+     * the server; nothing else of the agent changes.
+     */
+    nextVersion(agentId) {
+        const stored = this.agents.get(agentId);
+        if (!stored) {
+            throw new Error(`The mock has no agent '${agentId}'.`);
+        }
+        stored.agent = { ...stored.agent, version: stored.agent.version + 1, updatedAt: this.now() };
+        return stored.agent;
+    }
     /** Removes a deleted MCP server from the agents it was assigned to. */
     removeServer(serverId) {
         for (const agent of this.agents.values()) {
@@ -480,7 +534,7 @@ class NhAssistantMockAdminAgents {
     agentsEndpoint(method, id, action, body, length) {
         if (id === undefined) {
             if (method === 'GET') {
-                return { status: 200, body: [...this.agents.values()].map(stored => stored.agent) };
+                return { status: 200, body: [...this.agents.values()].map(stored => this.withInstructions(stored.agent)) };
             }
             if (method !== 'POST') {
                 return { status: 405 };
@@ -493,7 +547,21 @@ class NhAssistantMockAdminAgents {
             if (this.agents.has(input.id)) {
                 return mockFailure('assistant-agent-exists');
             }
-            const agent = this.toAgent(input, 'admin', 1, false);
+            const shadowOf = typeof input.shadowOf === 'string' && input.shadowOf.trim().length > 0 ? input.shadowOf.trim() : null;
+            // Without the application's ceiling the mock creates no data variants, as the server refuses them.
+            const refused = shadowOf === null
+                ? null
+                : this.rules.shadowVariantRefusal
+                    ? this.rules.shadowVariantRefusal({ ...input, shadowOf })
+                    : mockFailure('assistant-shadow-variants-not-allowed');
+            if (refused) {
+                return refused;
+            }
+            const created = this.toAgent(input, 'admin', 1, false);
+            // A data shadow variant always works in shadow and is never offered in the chat.
+            const agent = shadowOf === null
+                ? created
+                : { ...created, shadowOf, offeredInChat: false, shadow: shadowState(true, false, null, true) };
             this.agents.set(agent.id, { agent, codeDefinition: null, consultations: noSwitches(null) });
             return { status: 201, body: agent };
         }
@@ -549,7 +617,9 @@ class NhAssistantMockAdminAgents {
                 return mockFailure('assistant-version-conflict');
             }
             const { expectedVersion, ...definition } = input;
-            stored.agent = this.toAgent(definition, stored.agent.source, stored.agent.version + 1, stored.agent.source === 'code', stored.agent);
+            const updated = this.toAgent(definition, 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 };
         }
         if (method === 'DELETE') {
@@ -966,6 +1036,22 @@ class NhAssistantMockAdminAgents {
         if (typeof input?.instructions === 'string' && input.instructions.length > mockMaxInstructions) {
             return mockFailure('assistant-instructions-too-long');
         }
+        // Only an agent created here takes its instructions from an asset, never next to inline text.
+        if (input?.instructionsAsset) {
+            const errors = {};
+            if (source !== 'admin' || !this.rules.instructionAssets) {
+                errors['instructionsAsset'] = ['not-allowed'];
+            }
+            else {
+                this.rules.instructionAssets().check(input.instructionsAsset, errors);
+            }
+            if (typeof input.instructions === 'string' && input.instructions.trim().length > 0) {
+                errors['instructions'] = ['not-allowed'];
+            }
+            if (Object.keys(errors).length > 0) {
+                return mockFailure('assistant-validation', errors);
+            }
+        }
         if (!this.validAgent(input)) {
             return mockValidationFailure();
         }
@@ -1010,8 +1096,14 @@ class NhAssistantMockAdminAgents {
      */
     toAgent(input, source, version, isOverridden, previous) {
         // Only a new agent starts off, created that way here or with StartsOff() in code.
-        const { isEnabled, startsOff, profile, dataClassification, ...definition } = structuredClone(input);
+        // Metadata is not part of the definition; its values live with the mock's agent metadata.
+        const { isEnabled, startsOff, startsInShadow, profile, dataClassification, metadata, instructionsAsset, ...definition } = structuredClone(input);
         const createdOff = previous === undefined && startsOff === true;
+        // Only a new agent created here starts in shadow, as an override that applies once it has run settings.
+        const createdInShadow = previous === undefined && source === 'admin' && startsInShadow === true;
+        // The agent shows the asset's text read-only, or none while it does not resolve.
+        const reference = source === 'admin' && instructionsAsset ? instructionsAsset : null;
+        const assetProblem = reference ? this.instructionsProblemOf(reference) : null;
         const chosenProfile = source === 'admin' && typeof profile === 'string' && profile.trim().length > 0 ? profile.trim() : null;
         const classification = chosenClassification(dataClassification);
         return this.withWarnings({
@@ -1026,7 +1118,10 @@ class NhAssistantMockAdminAgents {
             version,
             source,
             isOverridden,
-            instructionsHash: mockHashText(input.instructions),
+            instructions: reference ? this.rules.instructionAssets?.().textOf(reference) ?? '' : definition.instructions,
+            instructionsHash: reference ? reference.hash : mockHashText(input.instructions),
+            instructionsAsset: reference,
+            instructionsProblem: assetProblem,
             updatedAt: this.now(),
             runState: previous?.runState ?? (createdOff ? 'off' : 'active'),
             stateChangedAt: previous?.stateChangedAt ?? (createdOff && source === 'admin' ? this.now() : null),
@@ -1035,7 +1130,9 @@ class NhAssistantMockAdminAgents {
             waitingInputs: previous?.waitingInputs ?? 0,
             skills: previous?.skills ?? [],
             shadowOf: previous?.shadowOf ?? null,
-            shadow: previous?.shadow ?? shadowState(false, false, null, false),
+            shadow: previous?.shadow ?? (createdInShadow
+                ? { ...shadowState(true, false, true, false), changedAt: this.now(), changedBy: 'current-user' }
+                : shadowState(false, false, null, false)),
             serviceAccount: previous?.serviceAccount ?? null,
             offBeforeStop: previous?.offBeforeStop ?? false,
             // Code decides for its agents; an agent created here keeps its choice when it is omitted.
@@ -1049,6 +1146,26 @@ class NhAssistantMockAdminAgents {
             knownSubjectTypes: previous?.knownSubjectTypes ?? []
         });
     }
+    /** Why the asset an agent created here names does not resolve now, or `null` when it does. */
+    instructionsProblemOf(reference) {
+        const assets = this.rules.instructionAssets?.();
+        return assets ? assets.problemOf(reference) : 'no-asset-source';
+    }
+    /**
+     * The agent as a read finds it now: the text of the asset it names and the problem when that no
+     * longer resolves, as the server checks it at every load.
+     */
+    withInstructions(agent) {
+        if (!agent.instructionsAsset) {
+            return agent;
+        }
+        const problem = this.instructionsProblemOf(agent.instructionsAsset);
+        return {
+            ...agent,
+            instructions: problem === null ? this.rules.instructionAssets?.().textOf(agent.instructionsAsset) ?? '' : '',
+            instructionsProblem: problem
+        };
+    }
     /** The agent with the warnings the server reports for it, from its profile and classification. */
     withWarnings(agent) {
         return {
@@ -2335,6 +2452,321 @@ function kebab(value) {
         .toLowerCase();
 }
 
+const maxHandOffs = 20;
+const maxSources = 20;
+const maxDescription$3 = 500;
+const maxPerDay = 100;
+const defaultPerDay = 5;
+const defaultVariants = 3;
+/**
+ * In-memory hand-offs defined as data and shadow variants of the mock API (S9), within the scenario's
+ * `handOffsAsData` and `shadowVariantsAsData` as the ceilings in code: saving checks a hand-off as the
+ * server checks it on every save and load, and `GET` reports a stored hand-off that no longer fits,
+ * for example after its source lost its run settings, out of effect with its problem. A data variant
+ * is created with `POST admin/agents` and `shadowOf`, which `shadowVariantRefusal` checks.
+ */
+class NhAssistantMockHandOffs {
+    constructor(scenario, agents, now) {
+        this.scenario = scenario;
+        this.agents = agents;
+        this.now = now;
+        this.stored = new Map();
+    }
+    /**
+     * A copy of the hand-offs defined as data; the returned function puts it back, for an import of
+     * an agent package that fails as a whole and for its preview.
+     */
+    snapshot() {
+        return mockSnapshot(this.stored);
+    }
+    /**
+     * `GET admin/agents/{id}/hand-offs`, `PUT` and `DELETE admin/agents/{id}/hand-offs/{subjectType}`
+     * and `GET admin/agents/{id}/shadow-variants`; `segments` start after the agent id. `null` for
+     * another route.
+     */
+    handle(method, agentId, segments, body, query) {
+        const [area, subjectType] = segments;
+        if (area === 'shadow-variants' && segments.length === 1) {
+            const agent = this.agents.find(agentId);
+            if (!agent) {
+                return mockFailure('assistant-agent-not-found');
+            }
+            return method === 'GET' ? { status: 200, body: this.variantsOf(agent) } : { status: 405 };
+        }
+        if (area !== 'hand-offs' || segments.length > 2) {
+            return null;
+        }
+        const agent = this.agents.find(agentId);
+        if (!agent) {
+            return mockFailure('assistant-agent-not-found');
+        }
+        if (subjectType === undefined) {
+            return method === 'GET' ? { status: 200, body: this.handOffsOf(agent) } : { status: 405 };
+        }
+        if (method === 'PUT') {
+            return this.save(agent, subjectType, body);
+        }
+        if (method === 'DELETE') {
+            return this.remove(agent, subjectType, query);
+        }
+        return { status: 405 };
+    }
+    /** Whether the agent accepts a hand-off defined as data, which keeps its run settings in use. */
+    acceptsDataHandOffs(agentId) {
+        return [...this.stored.values()].some(handOff => handOff.agentId === agentId);
+    }
+    /**
+     * Why `input` may not create a data shadow variant, as `POST admin/agents` with `shadowOf` answers,
+     * or `null`.
+     */
+    shadowVariantRefusal(input) {
+        const liveId = input.shadowOf ?? null;
+        if (liveId === null) {
+            return null;
+        }
+        if (liveId === input.id) {
+            return mockFailure('assistant-validation', { shadowOf: ['invalid'] });
+        }
+        const live = this.agents.find(liveId);
+        if (!this.allowsVariantsOf(liveId, live)) {
+            return mockFailure('assistant-shadow-variants-not-allowed');
+        }
+        if (!live || !this.agents.isConfigured(live)) {
+            return mockFailure('assistant-validation', { shadowOf: ['not-found'] });
+        }
+        if (!isLive(live)) {
+            return mockFailure('assistant-validation', { shadowOf: ['invalid'] });
+        }
+        return this.dataVariantsOf(liveId).length >= this.maxVariants()
+            ? mockFailure('assistant-configuration-limit')
+            : null;
+    }
+    handOffsOf(agent) {
+        return {
+            agentId: agent.id,
+            codeHandOffs: this.codeHandOffsOf(agent.id),
+            dataHandOffs: [...this.stored.values()]
+                .filter(item => item.agentId === agent.id)
+                .sort((first, second) => first.subjectType.localeCompare(second.subjectType))
+                .map(({ agentId, ...item }) => {
+                const problem = this.problemOf(agent, item.subjectType, item.sources, item.maxPerSubjectPerDay);
+                return { ...item, inEffect: problem === null, problem };
+            }),
+            ceiling: this.ceilingOf(agent),
+            configured: this.agents.isConfigured(agent)
+        };
+    }
+    save(agent, subjectType, request) {
+        const ceiling = this.ceilingOf(agent);
+        if (!ceiling) {
+            return mockFailure('assistant-handoffs-not-allowed');
+        }
+        if (this.codeHandOffsOf(agent.id).some(item => item.subjectType === subjectType)) {
+            return mockFailure('assistant-handoff-in-code');
+        }
+        if (!this.agents.isConfigured(agent)) {
+            return mockFailure('assistant-agent-not-configured');
+        }
+        const sources = Array.isArray(request?.sources) ? request.sources.map(source => String(source).trim()) : [];
+        const description = typeof request?.description === 'string' && request.description.trim().length > 0 ? request.description.trim() : null;
+        const limit = request?.maxPerSubjectPerDay ?? Math.min(defaultPerDay, ceiling.maxPerSubjectPerDay);
+        const reason = typeof request?.reason === 'string' && request.reason.trim().length > 0 ? request.reason.trim() : null;
+        const errors = {};
+        if (sources.length === 0) {
+            errors['sources'] = ['required'];
+        }
+        else if (sources.length > maxSources) {
+            errors['sources'] = ['too-long'];
+        }
+        else if (sources.some(source => !mockDashCase.test(source)) || new Set(sources).size !== sources.length || sources.includes(agent.id)) {
+            errors['sources'] = ['invalid'];
+        }
+        if (description !== null && description.length > maxDescription$3) {
+            errors['description'] = ['too-long'];
+        }
+        if (!Number.isInteger(limit) || limit < 1 || limit > maxPerDay) {
+            errors['maxPerSubjectPerDay'] = ['invalid'];
+        }
+        if (reason !== null && reason.length > mockMaxStateReason) {
+            errors['reason'] = ['too-long'];
+        }
+        if (Object.keys(errors).length > 0) {
+            return mockFailure('assistant-validation', errors);
+        }
+        // The same check as every load, refused here instead of left out of effect.
+        const problem = this.problemOf(agent, subjectType, sources, limit);
+        switch (problem) {
+            case null:
+                break;
+            case 'outside-ceiling':
+                return mockFailure('assistant-validation', ceiling.subjectTypes.some(item => item.subjectType === subjectType)
+                    ? { sources: ['not-allowed'] }
+                    : { subjectType: ['not-allowed'] });
+            case 'unknown-source':
+                return mockFailure('assistant-validation', { sources: ['not-found'] });
+            case 'not-worked-on':
+                return mockFailure('assistant-validation', { subjectType: ['invalid'] });
+            case 'limit-above-ceiling':
+                return mockFailure('assistant-validation', { maxPerSubjectPerDay: ['not-allowed'] });
+            default:
+                return mockFailure('assistant-validation', { sources: ['invalid'] });
+        }
+        const key = `${agent.id}/${subjectType}`;
+        const existing = this.stored.get(key);
+        if ((existing?.version ?? null) !== (request?.expectedVersion ?? null)) {
+            return mockFailure('assistant-version-conflict');
+        }
+        if (!existing && [...this.stored.values()].filter(item => item.agentId === agent.id).length >= maxHandOffs) {
+            return mockFailure('assistant-configuration-limit');
+        }
+        const now = this.now();
+        const saved = {
+            agentId: agent.id,
+            subjectType,
+            version: (existing?.version ?? 0) + 1,
+            sources,
+            description,
+            notifySource: request?.notifySource === true,
+            maxPerSubjectPerDay: limit,
+            toolId: `assistant.handoff.${agent.id}.${subjectType}`,
+            changedAt: now,
+            changedBy: 'current-user',
+            reason,
+            inEffect: true,
+            problem: null,
+            createdAt: existing?.createdAt ?? now,
+            createdBy: existing?.createdBy ?? 'current-user'
+        };
+        this.stored.set(key, saved);
+        const { agentId, ...body } = saved;
+        return { status: 200, body };
+    }
+    remove(agent, subjectType, query) {
+        if (this.codeHandOffsOf(agent.id).some(item => item.subjectType === subjectType)) {
+            return mockFailure('assistant-handoff-in-code');
+        }
+        const key = `${agent.id}/${subjectType}`;
+        const existing = this.stored.get(key);
+        if (!existing) {
+            return mockFailure('assistant-handoff-not-found');
+        }
+        const expected = query.get('expectedVersion');
+        if (expected !== null && Number(expected) !== existing.version) {
+            return mockFailure('assistant-version-conflict');
+        }
+        this.stored.delete(key);
+        return { status: 204 };
+    }
+    /**
+     * The problem a hand-off would have, as the server checks it on save and on every load: a ceiling
+     * that connects the agent about the type, a type it works on, sources with a run configuration
+     * that the ceiling allows, and a limit within the ceiling's.
+     */
+    problemOf(agent, subjectType, sources, limit) {
+        const rules = this.rulesFor(agent, subjectType);
+        if (!this.scenario.handOffsAsData) {
+            return 'outside-ceiling';
+        }
+        if (!this.agents.isConfigured(agent)) {
+            return 'unknown-agent';
+        }
+        if (this.codeHandOffsOf(agent.id).some(item => item.subjectType === subjectType)) {
+            return 'conflicts-with-code';
+        }
+        if (!mockWorksOnCovers(agent, subjectType)) {
+            return 'not-worked-on';
+        }
+        const known = sources.map(source => this.agents.find(source));
+        if (known.some(source => !source || !this.agents.isConfigured(source))) {
+            return 'unknown-source';
+        }
+        if (known.some(source => !rules.some(rule => this.allowsSource(rule, source)))) {
+            return 'outside-ceiling';
+        }
+        return limit > this.maxPerDay() ? 'limit-above-ceiling' : null;
+    }
+    ceilingOf(agent) {
+        const rules = (this.scenario.handOffsAsData?.rules ?? []).filter(rule => this.allowsTarget(rule, agent));
+        if (rules.length === 0) {
+            return null;
+        }
+        const configured = this.agents.all().filter(candidate => candidate.id !== agent.id && this.agents.isConfigured(candidate));
+        const types = [...new Set(rules.map(rule => rule.subjectType))].sort();
+        return {
+            subjectTypes: types.map(subjectType => {
+                const forType = rules.filter(rule => rule.subjectType === subjectType);
+                return {
+                    subjectType,
+                    sources: configured.filter(candidate => forType.some(rule => this.allowsSource(rule, candidate))).map(candidate => candidate.id).sort(),
+                    sourcesCreatedInAdministration: forType.some(rule => rule.fromAgentsCreatedInAdministration === true)
+                };
+            }),
+            maxPerSubjectPerDay: this.maxPerDay(),
+            maxHandOffs,
+            maxSources,
+            maxDescriptionLength: maxDescription$3
+        };
+    }
+    rulesFor(agent, subjectType) {
+        return (this.scenario.handOffsAsData?.rules ?? []).filter(rule => rule.subjectType === subjectType && this.allowsTarget(rule, agent));
+    }
+    allowsTarget(rule, agent) {
+        return (rule.to ?? []).includes(agent.id) || (rule.toAgentsCreatedInAdministration === true && agent.source === 'admin');
+    }
+    allowsSource(rule, agent) {
+        return (rule.from ?? []).includes(agent.id) || (rule.fromAgentsCreatedInAdministration === true && agent.source === 'admin');
+    }
+    maxPerDay() {
+        return this.scenario.handOffsAsData?.maxPerSubjectPerDay ?? maxPerDay;
+    }
+    codeHandOffsOf(agentId) {
+        const agent = (this.scenario.agents ?? []).find(item => item.id === agentId && item.source === 'code');
+        return (agent?.codeHandOffs ?? []).map(item => ({
+            subjectType: item.subjectType,
+            sources: [...item.sources],
+            description: item.description ?? null,
+            notifySource: item.notifySource ?? false,
+            maxPerSubjectPerDay: item.maxPerSubjectPerDay ?? defaultPerDay,
+            toolId: `assistant.handoff.${agentId}.${item.subjectType}`
+        }));
+    }
+    variantsOf(live) {
+        const all = this.agents.all();
+        const code = all.filter(agent => agent.source === 'code' && agent.shadowOf === live.id);
+        const data = this.dataVariantsOf(live.id);
+        const allowed = this.allowsVariantsOf(live.id, live) && this.agents.isConfigured(live) && isLive(live);
+        return {
+            agentId: live.id,
+            allowsDataVariants: allowed,
+            maxDataVariants: allowed ? this.maxVariants() : 0,
+            variants: [
+                ...code.map(agent => ({ agentId: agent.id, displayName: agent.displayName, source: 'code', hasRunSettings: true, inEffect: true, problem: null })),
+                ...data.map(agent => {
+                    const hasRunSettings = this.agents.isConfigured(agent);
+                    return { agentId: agent.id, displayName: agent.displayName, source: 'data', hasRunSettings, inEffect: hasRunSettings, problem: null };
+                })
+            ]
+        };
+    }
+    dataVariantsOf(liveId) {
+        return this.agents.all()
+            .filter(agent => agent.source === 'admin' && agent.shadowOf === liveId)
+            .sort((first, second) => first.id.localeCompare(second.id));
+    }
+    allowsVariantsOf(liveId, live) {
+        const ceiling = this.scenario.shadowVariantsAsData;
+        return ceiling !== undefined
+            && ((ceiling.of ?? []).includes(liveId) || (ceiling.ofAgentsCreatedInAdministration === true && (live?.source ?? 'admin') === 'admin'));
+    }
+    maxVariants() {
+        return this.scenario.shadowVariantsAsData?.maxPerAgent ?? defaultVariants;
+    }
+}
+/** A live agent: no shadow variant and not in shadow by its code. */
+function isLive(agent) {
+    return !agent.shadowOf && !(agent.source === 'code' && agent.shadow?.configured === true);
+}
+
 /** The bounds of `AllowConsultation`, within which a ceiling may only lower the maxima. */
 const bounds = {
     toolCalls: { min: 0, max: 32, initial: 4 },
@@ -2349,14 +2781,19 @@ const roles = ['reader', 'participant', 'approver'];
 const allRoutes = ['asker-decides', 'subject-agent-rights', 'subject-asker-rights'];
 const classifications = ['public', 'internal', 'confidential', 'restricted'];
 const subjectTypePattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/** A tool id or a prefix ending in `.*`, as an agent's tool selectors are. */
+const selectorPattern = /^[a-z0-9]+(?:-[a-z0-9]+)*(?:\.[a-z0-9]+(?:-[a-z0-9]+)*)*(?:\.\*)?$/;
 /**
  * Consultations of the mock API's agents: those in code from the scenario, read-only, and those
  * defined as data, saved and removed as on the server within the ceilings in code
  * (`consultationsAsData` for the application, `consultableAsData` for an agent in code). A save
  * checks a consultation as the server does and refuses with the same codes and field errors; every
  * read checks it again, so a consultation that no longer fits, for example after the run settings
- * changed whom the agent answers to, stays with its problems. Data consultations in effect generate
- * their consult and request tools in the tool list and count for the agent's route switches.
+ * changed whom the agent answers to or the agent's own tools no longer cover its tool selection,
+ * stays with its problems. Data consultations in effect generate their consult and request tools in
+ * the tool list and count for the agent's route switches. A new consultation starts off when its
+ * request or the ceiling says so (`startsOff`); one that is off is checked as every read checks it but
+ * offers nothing until `POST .../state` switches it on.
  */
 class NhAssistantMockConsultations {
     constructor(application, agents, rules, now) {
@@ -2365,6 +2802,7 @@ class NhAssistantMockConsultations {
         this.stored = new Map();
         this.codeAllowed = new Map();
         this.codeDescriptions = new Map();
+        this.codeTools = new Map();
         this.agentCeilings = new Map();
         this.applicationCeiling = application ? ceilingOf(application) : null;
         for (const agent of agents) {
@@ -2374,6 +2812,7 @@ class NhAssistantMockConsultations {
             if (agent.consultations !== undefined || agent.consultationDescriptions !== undefined) {
                 this.codeAllowed.set(agent.id, agent.consultations ?? {});
                 this.codeDescriptions.set(agent.id, agent.consultationDescriptions ?? {});
+                this.codeTools.set(agent.id, agent.consultationTools ?? {});
             }
             if (agent.consultableAsData !== undefined) {
                 this.agentCeilings.set(agent.id, agent.consultableAsData);
@@ -2405,7 +2844,8 @@ class NhAssistantMockConsultations {
             maxToolCalls: Math.min(application.maxToolCalls, narrowed.maxToolCalls),
             maxTimeoutSeconds: Math.min(application.maxTimeoutSeconds, narrowed.maxTimeoutSeconds),
             maxAnswerChars: Math.min(application.maxAnswerChars, narrowed.maxAnswerChars),
-            maxHistoryMessages: Math.min(application.maxHistoryMessages, narrowed.maxHistoryMessages)
+            maxHistoryMessages: Math.min(application.maxHistoryMessages, narrowed.maxHistoryMessages),
+            ...(application.startsOff === true || narrowed.startsOff === true ? { startsOff: true } : {})
         };
     }
     /** The agent's consultations in code, by subject type. */
@@ -2415,6 +2855,7 @@ class NhAssistantMockConsultations {
             return [];
         }
         const descriptions = this.codeDescriptions.get(agent.id) ?? {};
+        const tools = this.codeTools.get(agent.id) ?? {};
         const types = new Set([...Object.values(allowed).flat(), ...Object.keys(descriptions)]);
         return [...types].sort().map(subjectType => {
             const consultToolId = consultToolOf(agent.id, subjectType);
@@ -2426,7 +2867,8 @@ class NhAssistantMockConsultations {
                 exposure: ['local', 'agent'],
                 consultToolId,
                 requestToolId: null,
-                askingAgents: this.askersOf(agent.id, consultToolId)
+                askingAgents: this.askersOf(agent.id, consultToolId),
+                toolSelectors: tools[subjectType] ? [...tools[subjectType]] : null
             };
         });
     }
@@ -2474,8 +2916,18 @@ class NhAssistantMockConsultations {
         }
         return tools;
     }
-    /** `PUT` and `DELETE admin/agents/{id}/consultations/{subjectType}`. */
-    handle(method, agent, subjectType, body, query) {
+    /**
+     * A copy of the consultations defined as data; the returned function puts it back, for an import
+     * of an agent package that fails as a whole and for its preview.
+     */
+    snapshot() {
+        return mockSnapshot(this.stored);
+    }
+    /** `PUT` and `DELETE admin/agents/{id}/consultations/{subjectType}`, and `POST .../state`. */
+    handle(method, agent, subjectType, body, query, action) {
+        if (action === 'state') {
+            return method === 'POST' ? this.setState(agent, subjectType, body) : { status: 405 };
+        }
         if (method === 'DELETE') {
             return this.remove(agent, subjectType, query);
         }
@@ -2483,7 +2935,7 @@ class NhAssistantMockConsultations {
     }
     save(agent, subjectType, body) {
         const request = (body ?? {});
-        const reason = text$1(request.reason);
+        const reason = text$2(request.reason);
         if (reason !== null && reason.length > mockMaxStateReason) {
             return mockFailure('assistant-validation', { reason: ['too-long'] });
         }
@@ -2498,12 +2950,16 @@ class NhAssistantMockConsultations {
             return mockFailure('assistant-consultation-in-code');
         }
         // A new consultation starts with the defaults of code, capped by the ceiling.
-        const description = text$1(request.description);
-        const instructions = text$1(request.instructions);
-        const minimumRole = (text$1(request.minimumRole) ?? 'reader');
-        const proposalRole = (text$1(request.proposalRole) ?? 'participant');
+        const description = text$2(request.description);
+        const instructions = text$2(request.instructions);
+        const minimumRole = (text$2(request.minimumRole) ?? 'reader');
+        const proposalRole = (text$2(request.proposalRole) ?? 'participant');
         const routes = (request.routes ?? []).map(route => (typeof route === 'string' ? route.trim() : ''));
-        const classification = text$1(request.dataClassification);
+        // No selection, or an empty one, offers every tool of the agent.
+        const toolSelectors = Array.isArray(request.toolSelectors) && request.toolSelectors.length > 0
+            ? request.toolSelectors.map(selector => (typeof selector === 'string' ? selector.trim() : ''))
+            : null;
+        const classification = text$2(request.dataClassification);
         const limits = {
             maxToolCalls: request.maxToolCalls ?? Math.min(bounds.toolCalls.initial, ceiling.maxToolCalls),
             timeoutSeconds: request.timeoutSeconds ?? Math.min(bounds.timeoutSeconds.initial, ceiling.maxTimeoutSeconds),
@@ -2535,6 +2991,9 @@ class NhAssistantMockConsultations {
         if (!validRoutes(routes)) {
             add('routes', 'invalid');
         }
+        if (toolSelectors !== null && !validSelectors(toolSelectors)) {
+            add('toolSelectors', 'invalid');
+        }
         if (!within(limits.maxToolCalls, bounds.toolCalls)
             || !within(limits.timeoutSeconds, bounds.timeoutSeconds)
             || !within(limits.maxAnswerChars, bounds.answerChars)
@@ -2544,6 +3003,10 @@ class NhAssistantMockConsultations {
         if (classification !== null && !classifications.includes(classification)) {
             add('dataClassification', 'invalid');
         }
+        // Only a new consultation starts off; one that exists keeps whether it is on.
+        if (request.startsOff === true && request.expectedVersion != null) {
+            add('startsOff', 'invalid');
+        }
         if (Object.keys(errors).length > 0) {
             return mockFailure('assistant-validation', errors);
         }
@@ -2556,14 +3019,16 @@ class NhAssistantMockConsultations {
             description: description,
             instructions,
             minimumRole,
-            askerPolicy: text$1(request.askerPolicy),
+            askerPolicy: text$2(request.askerPolicy),
             routes,
             proposalRole,
-            proposalPolicy: text$1(request.proposalPolicy),
+            proposalPolicy: text$2(request.proposalPolicy),
+            toolSelectors,
             ...limits,
             allowRequests: request.allowRequests === true,
             exposeToMcp: request.exposeToMcp === true,
             dataClassification: classification,
+            off: existing ? existing.off : request.startsOff === true || ceiling.startsOff === true,
             createdAt: existing?.createdAt ?? now,
             createdBy: existing?.createdBy ?? 'current-user',
             changedAt: now,
@@ -2584,6 +3049,31 @@ class NhAssistantMockConsultations {
         this.stored.set(key$2(agent.id, subjectType), row);
         return { status: 200, body: this.toConsultation(agent, row) };
     }
+    /** `POST admin/agents/{id}/consultations/{subjectType}/state`: on or off, without a new version. */
+    setState(agent, subjectType, body) {
+        const request = body;
+        if (request?.state !== 'on' && request?.state !== 'off') {
+            return mockFailure('assistant-validation', { state: [request?.state === undefined ? 'required' : 'invalid'] });
+        }
+        if (typeof request.reason === 'string' && request.reason.trim().length > mockMaxStateReason) {
+            return mockFailure('assistant-validation', { reason: ['too-long'] });
+        }
+        if (this.inCode(agent.id, subjectType)) {
+            return mockFailure('assistant-consultation-in-code');
+        }
+        const existing = this.stored.get(key$2(agent.id, subjectType));
+        if (!existing) {
+            return mockFailure('assistant-consultation-not-found');
+        }
+        const off = request.state === 'off';
+        if (existing.off !== off) {
+            existing.off = off;
+            existing.changedAt = this.now();
+            existing.changedBy = 'current-user';
+            existing.reason = typeof request.reason === 'string' && request.reason.trim().length > 0 ? request.reason.trim() : null;
+        }
+        return { status: 200, body: this.toConsultation(agent, existing) };
+    }
     remove(agent, subjectType, query) {
         const reason = query.get('reason');
         if (reason !== null && reason.trim().length > mockMaxStateReason) {
@@ -2610,7 +3100,7 @@ class NhAssistantMockConsultations {
      * no longer fit and with limits capped at the ceiling, each with a problem.
      */
     check(agent, row) {
-        const out = (problem) => ({ inEffect: false, problems: [problem], routes: [], allowRequests: false });
+        const out = (problem) => ({ inEffect: false, problems: [problem], routes: [], allowRequests: false, toolSelectors: [] });
         const ceiling = this.ceilingOf(agent);
         if (!ceiling) {
             return out('not-consultable');
@@ -2676,7 +3166,19 @@ class NhAssistantMockConsultations {
             || row.maxHistoryMessages > ceiling.maxHistoryMessages) {
             problems.push('limit-above-ceiling');
         }
-        return { inEffect: true, problems, routes: kept, allowRequests };
+        // The selection only narrows the agent's own tools; one they no longer cover drops, and a
+        // selection with none left offers no tools, never every tool of the agent.
+        let toolSelectors = null;
+        if (row.toolSelectors !== null) {
+            toolSelectors = row.toolSelectors.filter(selector => agent.toolSelectors.some(own => selectorCovers(own, selector)));
+            if (toolSelectors.length < row.toolSelectors.length) {
+                problems.push('tools-not-allowed');
+            }
+        }
+        // Off, it is checked as every read checks it, and offers nothing until it is switched on.
+        return row.off
+            ? { inEffect: false, problems, routes: [], allowRequests: false, toolSelectors: [] }
+            : { inEffect: true, problems, routes: kept, allowRequests, toolSelectors };
     }
     namesOnlyTheInitiator(policy) {
         const summary = this.rules.approvalPolicySummaries().find(item => item.name === policy);
@@ -2689,6 +3191,8 @@ class NhAssistantMockConsultations {
         return {
             ...stored,
             routes: [...row.routes],
+            toolSelectors: row.toolSelectors ? [...row.toolSelectors] : null,
+            toolSelectorsInEffect: check.toolSelectors ? [...check.toolSelectors] : null,
             instructionsHash: row.instructions === null ? null : mockHashText(row.instructions),
             inEffect: check.inEffect,
             problem: check.problems[0] ?? null,
@@ -2728,7 +3232,9 @@ function ceilingOf(ceiling) {
         maxAnswerChars: ceiling.maxAnswerChars ?? bounds.answerChars.max,
         maxHistoryMessages: ceiling.maxHistoryMessages ?? bounds.history.max,
         maxConsultations,
-        maxInstructionsLength: maxInstructions$1
+        maxInstructionsLength: maxInstructions$1,
+        // Reported only when the application lets new consultations start off, as older servers omit it.
+        ...(ceiling.startsOff === true ? { startsOff: true } : {})
     };
 }
 /** The field error of each problem a consultation would have, as the server maps them on save. */
@@ -2750,7 +3256,8 @@ function fieldFailure(problems) {
         'no-approver': ['proposalPolicy', 'invalid'],
         'limit-above-ceiling': ['limits', 'not-allowed'],
         'requests-not-allowed': ['allowRequests', 'not-allowed'],
-        'mcp-not-allowed': ['exposeToMcp', 'not-allowed']
+        'mcp-not-allowed': ['exposeToMcp', 'not-allowed'],
+        'tools-not-allowed': ['toolSelectors', 'not-allowed']
     };
     const errors = {};
     for (const problem of problems) {
@@ -2765,6 +3272,15 @@ function validRoutes(routes) {
         && new Set(routes).size === routes.length
         && !(routes.includes('subject-agent-rights') && routes.includes('subject-asker-rights'));
 }
+/** Valid selectors, each once. */
+function validSelectors(selectors) {
+    return selectors.every(selector => selector.length <= 128 && selectorPattern.test(selector))
+        && new Set(selectors).size === selectors.length;
+}
+/** The agent's selector covers a consultation's selector: the same tool, or a prefix that includes it. */
+function selectorCovers(agentSelector, selector) {
+    return agentSelector === selector || (agentSelector.endsWith('.*') && selector.startsWith(agentSelector.slice(0, -1)));
+}
 function within(value, range) {
     return Number.isInteger(value) && value >= range.min && value <= range.max;
 }
@@ -2782,11 +3298,116 @@ function covers$1(selector, toolId) {
 function key$2(agentId, subjectType) {
     return `${agentId}/${subjectType}`;
 }
-function text$1(value) {
+function text$2(value) {
     return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
 }
 
-const dashCase$4 = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/**
+ * The application's text assets of the mock API, as its `INhAiTextAssetSource` would supply them:
+ * `GET admin/instruction-assets` lists them without content and `GET admin/instruction-assets/{id}/versions/{version}`
+ * reads one. A skill version or an agent created in the administration that names one is checked as
+ * the server checks it: the asset must exist with the hash the request names. `setAsset` and
+ * `removeAsset` change the assets afterwards, so a reference that no longer resolves shows its problem
+ * (`asset-changed`, `asset-missing`), as after the server's next load. Without `instructionAssets` in
+ * the scenario the application offers none and the run catalog says so.
+ */
+class NhAssistantMockInstructionAssets {
+    constructor(assets) {
+        this.assets = new Map();
+        this.supported = assets !== undefined;
+        for (const asset of assets ?? []) {
+            this.assets.set(keyOf$1(asset.assetId, asset.version), { ...asset });
+        }
+    }
+    /** Publishes or changes one version of an asset. */
+    setAsset(asset) {
+        this.assets.set(keyOf$1(asset.assetId, asset.version), { ...asset });
+    }
+    /** Removes one version of an asset. */
+    removeAsset(assetId, version) {
+        this.assets.delete(keyOf$1(assetId, version));
+    }
+    /** `admin/instruction-assets[/{id}/versions/{version}]`; `segments` start after `instruction-assets`. */
+    handle(method, segments) {
+        if (method !== 'GET') {
+            return { status: 405 };
+        }
+        if (segments.length === 0) {
+            const list = {
+                supported: this.supported,
+                assets: [...this.assets.values()].map(asset => ({
+                    assetId: asset.assetId,
+                    version: asset.version,
+                    hash: mockHashText(asset.content),
+                    replacedByAssetId: asset.replacedByAssetId ?? null,
+                    deprecatedAt: asset.deprecatedAt ?? null
+                }))
+            };
+            return { status: 200, body: list };
+        }
+        const [assetId, versions, version] = segments;
+        const asset = segments.length === 3 && versions === 'versions' ? this.assets.get(keyOf$1(assetId, Number(version))) : undefined;
+        if (!this.supported || !asset) {
+            return mockFailure('assistant-instructions-asset-not-found');
+        }
+        const text = {
+            assetId: asset.assetId,
+            version: asset.version,
+            hash: mockHashText(asset.content),
+            content: asset.content,
+            problem: null
+        };
+        return { status: 200, body: text };
+    }
+    /**
+     * Adds the field errors of a reference a save names, as the server does: `instructionsAsset`
+     * `not-allowed` without a source, `invalid` for a malformed reference, `not-found` for a missing
+     * asset, and `instructionsAsset.hash` `invalid` for another hash.
+     */
+    check(reference, errors) {
+        if (!this.supported) {
+            errors['instructionsAsset'] = ['not-allowed'];
+            return;
+        }
+        if (typeof reference.assetId !== 'string' || !mockDashCase.test(reference.assetId) || !Number.isInteger(reference.version) || reference.version < 1) {
+            errors['instructionsAsset'] = ['invalid'];
+            return;
+        }
+        const problem = this.problemOf(reference);
+        if (problem === 'asset-missing') {
+            errors['instructionsAsset'] = ['not-found'];
+        }
+        else if (problem === 'asset-changed') {
+            errors['instructionsAsset.hash'] = ['invalid'];
+        }
+        else if (problem !== null) {
+            errors['instructionsAsset'] = ['invalid'];
+        }
+    }
+    /** Why the reference does not resolve to its hash now, or `null` when it does. */
+    problemOf(reference) {
+        if (!this.supported) {
+            return 'no-asset-source';
+        }
+        const asset = this.assets.get(keyOf$1(reference.assetId, reference.version));
+        if (!asset) {
+            return 'asset-missing';
+        }
+        if (asset.content.trim().length === 0 || asset.content.length > mockMaxInstructions) {
+            return 'asset-invalid';
+        }
+        return mockHashText(asset.content) === reference.hash ? null : 'asset-changed';
+    }
+    /** The text the reference resolves to, or `null` when it does not resolve. */
+    textOf(reference) {
+        return this.problemOf(reference) === null ? this.assets.get(keyOf$1(reference.assetId, reference.version)).content : null;
+    }
+}
+function keyOf$1(assetId, version) {
+    return `${assetId}@${version}`;
+}
+
+const dashCase$5 = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const dataClassifications = ['public', 'internal', 'confidential', 'restricted'];
 const accountabilities = ['agent', 'subject-responsible', 'service-account'];
 const conflicts = ['coalesce', 'queue', 'supersede', 'ignore'];
@@ -2811,17 +3432,22 @@ const fileLimitFields = ['maxFileBytes', 'maxFilePages', 'maxFilesPerTurn', 'max
  * checks the names against the scenario's run catalog as the server checks them against the code;
  * new skills and triggers start in shadow. A schedule without a subject set runs for the whole
  * application and fits only an agent that works on it; a stored trigger that no longer fits what its
- * agent works on stays, out of effect, with the problem `not-worked-on`. The mock runs no agents, so
- * a comparison counts nothing.
+ * agent works on stays, out of effect, with the problem `not-worked-on`. Triggers have append-only
+ * versions as skills do: a change applies at once or, with `apply` `shadow`, becomes the candidate next
+ * to the live version, which the administrator promotes or discards. The mock runs no agents, so a
+ * comparison counts nothing.
  */
 class NhAssistantMockRunConfiguration {
-    constructor(scenario, agents, now, accounts = new NhAssistantMockAccounts(scenario)) {
+    constructor(scenario, agents, now, accounts = new NhAssistantMockAccounts(scenario), instructionAssets = new NhAssistantMockInstructionAssets(scenario.instructionAssets)) {
         this.agents = agents;
         this.now = now;
         this.accounts = accounts;
+        this.instructionAssets = instructionAssets;
         this.settings = new Map();
         this.skills = new Map();
         this.triggers = new Map();
+        /** Every version of every data trigger by trigger id, live and candidate included, oldest first. */
+        this.triggerVersions = new Map();
         const approvalPolicies = scenario.runCatalog?.approvalPolicies ?? scenario.policies ?? [];
         this.consultations = new NhAssistantMockConsultations(scenario.consultationsAsData, scenario.agents ?? [], {
             find: agentId => this.agents.find(agentId),
@@ -2854,7 +3480,8 @@ class NhAssistantMockRunConfiguration {
             divisions: scenario.runCatalog?.divisions ?? false,
             // The platform's default file limits, unless the scenario's application chose its own.
             fileLimits: scenario.runCatalog?.fileLimits ?? defaultFileLimits,
-            consultationCeiling: this.consultations.applicationCeiling
+            consultationCeiling: this.consultations.applicationCeiling,
+            instructionAssets: instructionAssets.supported
         };
         this.codeTriggers = (scenario.codeTriggers ?? []).map(trigger => ({
             ...trigger,
@@ -2878,6 +3505,18 @@ class NhAssistantMockRunConfiguration {
     get profileNames() {
         return [...this.catalog.profiles];
     }
+    /**
+     * A copy of the run settings, skills, triggers and consultations; the returned function puts it
+     * back, for an import of an agent package that fails as a whole and for its preview.
+     */
+    snapshot() {
+        const restoreOwn = mockSnapshot(this.settings, this.skills, this.triggers, this.triggerVersions);
+        const restoreConsultations = this.consultations.snapshot();
+        return () => {
+            restoreOwn();
+            restoreConsultations();
+        };
+    }
     /**
      * The agent's consultations defined as data in effect with their routes in effect, which count for
      * its route switches.
@@ -2895,8 +3534,8 @@ class NhAssistantMockRunConfiguration {
     }
     /**
      * `admin/agents/{id}/configuration`, `run-settings`, `skills/{skillId}[/...]`,
-     * `triggers/{triggerId}[/shadow]` and `consultations/{subjectType}`; `segments` start after the
-     * agent id.
+     * `triggers/{triggerId}[/shadow|/versions|/candidate/...]` and `consultations/{subjectType}[/state]`;
+     * `segments` start after the agent id.
      */
     handle(method, agentId, segments, body, query) {
         const agent = this.agents.find(agentId);
@@ -2919,14 +3558,22 @@ class NhAssistantMockRunConfiguration {
             }
             return segments.length === 2 ? this.skill(method, agent, id, body, query) : null;
         }
+        if (area === 'triggers' && id !== undefined && (segments.length === 3 && action === 'versions' || segments.length === 4 && action === 'candidate')) {
+            if (!agent) {
+                return mockFailure('assistant-agent-not-found');
+            }
+            return action === 'versions'
+                ? method === 'GET' ? { status: 200, body: this.triggerHistory(agent.id, id) } : { status: 405 }
+                : this.triggerCandidate(method, agent, id, child, body);
+        }
         if (area === 'triggers' && id !== undefined && (segments.length === 2 || (segments.length === 3 && action === 'shadow'))) {
             if (!agent) {
                 return mockFailure('assistant-agent-not-found');
             }
             return action === 'shadow' ? this.triggerShadow(method, agent, id, body) : this.trigger(method, agent, id, body, query);
         }
-        if (area === 'consultations' && id !== undefined && segments.length === 2) {
-            return agent ? this.consultations.handle(method, agent, id, body, query) : mockFailure('assistant-agent-not-found');
+        if (area === 'consultations' && id !== undefined && (segments.length === 2 || (segments.length === 3 && action === 'state'))) {
+            return agent ? this.consultations.handle(method, agent, id, body, query, action) : mockFailure('assistant-agent-not-found');
         }
         return null;
     }
@@ -2937,7 +3584,9 @@ class NhAssistantMockRunConfiguration {
             .filter(trigger => this.ownerOf(trigger) === agent.id)
             .map(trigger => {
             const problem = this.triggerProblem(agent, trigger);
-            return problem ? { ...withoutOwner(trigger), inEffect: false, problem } : withoutOwner(trigger);
+            const live = problem ? { ...withoutOwner(trigger), inEffect: false, problem } : withoutOwner(trigger);
+            const candidate = this.candidateOf(trigger.triggerId);
+            return { ...live, candidate: candidate ? this.candidateDto(agent, candidate) : null };
         });
         return {
             agentId: agent.id,
@@ -2949,9 +3598,16 @@ class NhAssistantMockRunConfiguration {
             codeTriggers: this.codeTriggers.filter(trigger => trigger.agentId === agent.id).map(({ agentId, ...trigger }) => trigger),
             dataTriggers,
             problems: [
+                ...dataSkills
+                    .flatMap(skill => [{ kind: 'skill', skill }, ...(skill.candidate ? [{ kind: 'candidate', skill: skill.candidate }] : [])])
+                    .filter(entry => entry.skill.instructionsAsset && entry.skill.problem !== null)
+                    .map(entry => ({ agentId: agent.id, kind: entry.kind, id: entry.skill.skillId, code: entry.skill.problem })),
                 ...dataTriggers
                     .filter(trigger => trigger.problem !== null)
                     .map(trigger => ({ agentId: agent.id, kind: 'trigger', id: trigger.triggerId, code: trigger.problem })),
+                ...dataTriggers
+                    .filter(trigger => trigger.candidate && trigger.candidate.problem !== null)
+                    .map(trigger => ({ agentId: agent.id, kind: 'trigger-candidate', id: trigger.triggerId, code: trigger.candidate.problem })),
                 ...this.consultations.problems(agent)
             ],
             source: agent.source,
@@ -3008,7 +3664,8 @@ class NhAssistantMockRunConfiguration {
             }
             if (this.liveSkills(agent.id).length > 0
                 || [...this.triggers.values()].some(trigger => this.ownerOf(trigger) === agent.id)
-                || this.consultations.has(agent.id)) {
+                || this.consultations.has(agent.id)
+                || this.agents.acceptsDataHandOffs?.(agent.id)) {
                 return mockFailure('assistant-run-settings-in-use');
             }
             this.settings.delete(agent.id);
@@ -3018,7 +3675,7 @@ class NhAssistantMockRunConfiguration {
             return { status: 405 };
         }
         const request = (body ?? {});
-        const serviceAccount = text(request.serviceAccountActorId);
+        const serviceAccount = text$1(request.serviceAccountActorId);
         const errors = {};
         if (!accountabilities.includes(request.accountability)) {
             errors['accountability'] = [request.accountability ? 'invalid' : 'required'];
@@ -3061,18 +3718,18 @@ class NhAssistantMockRunConfiguration {
             delegateFromInitiator: request.delegateFromInitiator ?? false,
             allowGatewayReads: request.allowGatewayReads ?? false,
             elevatedReads: request.elevatedReads ?? 'restricted',
-            approvalPolicy: text(request.approvalPolicy),
+            approvalPolicy: text$1(request.approvalPolicy),
             retryCount: request.retryCount ?? 3,
             dailyToolCalls: request.dailyToolCalls ?? null,
             dailyTokens: request.dailyTokens ?? null,
             maxConcurrentRuns: request.maxConcurrentRuns ?? 4,
             maxRunsPerSubjectPerDay: request.maxRunsPerSubjectPerDay ?? 10,
             maxTokensPerRun: request.maxTokensPerRun ?? null,
-            triageProfile: text(request.triageProfile),
-            ruleHandler: text(request.ruleHandler),
+            triageProfile: text$1(request.triageProfile),
+            ruleHandler: text$1(request.ruleHandler),
             changedAt: this.now(),
             changedBy: 'current-user',
-            reason: text(request.reason),
+            reason: text$1(request.reason),
             inEffect: true,
             problem: null,
             acceptsFiles: request.acceptsFiles ?? false,
@@ -3110,9 +3767,9 @@ class NhAssistantMockRunConfiguration {
             return { status: 405 };
         }
         const request = (body ?? {});
-        const description = text(request.description);
+        const description = text$1(request.description);
         const errors = {};
-        if (!dashCase$4.test(skillId)) {
+        if (!dashCase$5.test(skillId)) {
             errors['skillId'] = ['invalid'];
         }
         if (description === null) {
@@ -3124,6 +3781,14 @@ class NhAssistantMockRunConfiguration {
         if ((request.instructions ?? '').length > maxInstructions) {
             errors['instructions'] = ['too-long'];
         }
+        // A version takes its instructions from an asset of the application or has text of its own.
+        const instructionsAsset = request.instructionsAsset ?? null;
+        if (instructionsAsset !== null) {
+            if (text$1(request.instructions) !== null) {
+                errors['instructions'] = ['not-allowed'];
+            }
+            this.instructionAssets.check(instructionsAsset, errors);
+        }
         if ((request.tools ?? []).some(tool => !agent.toolSelectors.some(selector => covers(selector, tool)))) {
             errors['tools'] = ['invalid'];
         }
@@ -3140,7 +3805,7 @@ class NhAssistantMockRunConfiguration {
         if (request.startsOff === true && (request.expectedVersion ?? null) !== null) {
             errors['startsOff'] = ['invalid'];
         }
-        const classification = text(request.dataClassification);
+        const classification = text$1(request.dataClassification);
         if (classification !== null && !dataClassifications.includes(classification)) {
             errors['dataClassification'] = ['invalid'];
         }
@@ -3163,27 +3828,30 @@ class NhAssistantMockRunConfiguration {
                 version.status = 'superseded';
             }
         }
-        const instructions = text(request.instructions);
+        const instructions = instructionsAsset === null ? text$1(request.instructions) : null;
         const saved = {
             skillId,
             version: versions.reduce((latest, version) => Math.max(latest, version.version), 0) + 1,
             status: candidate ? 'candidate' : 'live',
             description: description,
             instructions,
-            instructionsHash: instructions === null ? null : hashText(instructions),
+            instructionsHash: instructionsAsset?.hash ?? (instructions === null ? null : hashText(instructions)),
+            instructionsAsset: instructionsAsset === null
+                ? null
+                : { assetId: instructionsAsset.assetId, version: instructionsAsset.version, hash: instructionsAsset.hash },
             tools: [...new Set(request.tools ?? [])],
-            profile: text(request.profile),
+            profile: text$1(request.profile),
             dataClassification: classification,
             acceptsFiles: request.acceptsFiles ?? false,
             ...storedFileLimits(request),
-            ruleHandler: text(request.ruleHandler),
+            ruleHandler: text$1(request.ruleHandler),
             maxTokensPerRun: request.maxTokensPerRun ?? null,
             dailyToolCalls: request.dailyToolCalls ?? null,
             dailyTokens: request.dailyTokens ?? null,
-            approvalPolicy: text(request.approvalPolicy),
+            approvalPolicy: text$1(request.approvalPolicy),
             changedAt: this.now(),
             changedBy: 'current-user',
-            reason: text(request.reason),
+            reason: text$1(request.reason),
             inEffect: true,
             problem: null
         };
@@ -3248,7 +3916,8 @@ class NhAssistantMockRunConfiguration {
             instructionsHash: version.instructionsHash,
             createdAt: version.changedAt,
             createdBy: version.changedBy,
-            reason: version.reason
+            reason: version.reason,
+            instructionsAsset: version.instructionsAsset ?? null
         }));
     }
     trigger(method, agent, triggerId, body, query) {
@@ -3269,6 +3938,10 @@ class NhAssistantMockRunConfiguration {
             if (!versionMatches(query, existing.version)) {
                 return mockFailure('assistant-version-conflict');
             }
+            // Out of effect; its versions stay as history.
+            for (const version of this.triggerVersions.get(triggerId) ?? []) {
+                version.status = version.status === 'live' ? 'superseded' : version.status === 'candidate' ? 'discarded' : version.status;
+            }
             this.triggers.delete(triggerId);
             return { status: 204 };
         }
@@ -3278,7 +3951,7 @@ class NhAssistantMockRunConfiguration {
         const request = (body ?? {});
         const schedule = request.source === 'schedule';
         const errors = {};
-        if (!dashCase$4.test(triggerId)) {
+        if (!dashCase$5.test(triggerId)) {
             errors['triggerId'] = ['invalid'];
         }
         if (request.source !== 'event' && request.source !== 'schedule') {
@@ -3293,16 +3966,16 @@ class NhAssistantMockRunConfiguration {
         if (request.source === 'event') {
             this.requireKnown(errors, 'event', request.event, this.catalog.triggerEvents.map(item => item.name), true);
             // An event that names its object type up front fits only an agent that works on it.
-            const subjectType = this.catalog.triggerEvents.find(item => item.name === text(request.event))?.subjectType;
+            const subjectType = this.catalog.triggerEvents.find(item => item.name === text$1(request.event))?.subjectType;
             if (!errors['event'] && subjectType && !mockWorksOnCovers(agent, subjectType)) {
                 errors['event'] = ['invalid'];
             }
         }
         if (schedule) {
-            if ((text(request.cron) ?? '').split(' ').filter(field => field.length > 0).length < 5) {
-                errors['cron'] = [text(request.cron) === null ? 'required' : 'invalid'];
+            if ((text$1(request.cron) ?? '').split(' ').filter(field => field.length > 0).length < 5) {
+                errors['cron'] = [text$1(request.cron) === null ? 'required' : 'invalid'];
             }
-            if (text(request.subjectSet) !== null) {
+            if (text$1(request.subjectSet) !== null) {
                 this.requireKnown(errors, 'subjectSet', request.subjectSet, this.catalog.subjectSets.map(item => item.name));
             }
             else if (!mockWorksOnCovers(agent, mockSystemSubjectType)) {
@@ -3310,7 +3983,7 @@ class NhAssistantMockRunConfiguration {
                 // that works on it may do.
                 errors['subjectSet'] = ['required'];
             }
-            const message = text(request.message);
+            const message = text$1(request.message);
             if (message === null) {
                 errors['message'] = ['required'];
             }
@@ -3318,7 +3991,7 @@ class NhAssistantMockRunConfiguration {
                 errors['message'] = ['too-long'];
             }
         }
-        const skill = text(request.skill);
+        const skill = text$1(request.skill);
         if (skill !== null && !this.skillIds(agent).includes(skill)) {
             errors['skill'] = ['not-found'];
         }
@@ -3327,11 +4000,16 @@ class NhAssistantMockRunConfiguration {
         if (filters.length > maxTriggerFilters || filters.some(name => name.length > 64 || !filterName.test(name)) || (schedule && filters.length > 0)) {
             errors['filters'] = ['invalid'];
         }
+        // A new trigger has no live version to evaluate a candidate next to.
+        if ((request.apply !== undefined && request.apply !== 'live' && request.apply !== 'shadow')
+            || (request.apply === 'shadow' && (request.expectedVersion ?? null) === null)) {
+            errors['apply'] = ['invalid'];
+        }
         if (Object.keys(errors).length > 0) {
             return mockFailure('assistant-validation', errors);
         }
         if (request.source === 'event') {
-            const offered = (this.catalog.triggerEvents.find(item => item.name === text(request.event))?.filters ?? []).map(filter => filter.name);
+            const offered = (this.catalog.triggerEvents.find(item => item.name === text$1(request.event))?.filters ?? []).map(filter => filter.name);
             if (filters.some(name => !offered.includes(name))) {
                 return mockFailure('assistant-trigger-filter-not-found', { filters: ['not-found'] });
             }
@@ -3339,35 +4017,140 @@ class NhAssistantMockRunConfiguration {
         if ((request.expectedVersion ?? null) !== (existing?.version ?? null)) {
             return mockFailure('assistant-version-conflict');
         }
+        const candidate = request.apply === 'shadow';
+        const history = this.triggerVersions.get(triggerId) ?? [];
         const saved = {
             triggerId,
             skillId: skill,
             source: request.source,
-            event: schedule ? null : text(request.event),
-            cron: schedule ? text(request.cron) : null,
-            timeZone: schedule ? text(request.timeZone) : null,
-            subjectSet: schedule ? text(request.subjectSet) : null,
-            message: schedule ? text(request.message) : null,
+            event: schedule ? null : text$1(request.event),
+            cron: schedule ? text$1(request.cron) : null,
+            timeZone: schedule ? text$1(request.timeZone) : null,
+            subjectSet: schedule ? text$1(request.subjectSet) : null,
+            message: schedule ? text$1(request.message) : null,
             conflict: request.conflict ?? (schedule ? 'ignore' : 'coalesce'),
             debounceSeconds: schedule ? 0 : request.debounceSeconds ?? 120,
-            shadow: existing?.shadow ?? true,
-            version: (existing?.version ?? 0) + 1,
+            // A candidate always fires in shadow; a new version keeps the trigger's mode.
+            shadow: candidate || (existing?.shadow ?? true),
+            version: history.reduce((latest, version) => Math.max(latest, version.version), existing?.version ?? 0) + 1,
             changedAt: this.now(),
             changedBy: 'current-user',
-            reason: text(request.reason),
+            reason: text$1(request.reason),
             inEffect: true,
             problem: null,
-            filters: schedule ? [] : filters
+            filters: schedule ? [] : filters,
+            createdAt: this.now(),
+            createdBy: 'current-user'
         };
+        for (const version of history) {
+            if (version.status === 'candidate') {
+                version.status = 'discarded';
+            }
+            else if (version.status === 'live' && !candidate) {
+                version.status = 'superseded';
+            }
+        }
+        if (existing && history.length === 0) {
+            // A trigger of the scenario's preset starts its history with its live version.
+            history.push({ ...withoutOwner(existing), status: candidate ? 'live' : 'superseded', agentId: agent.id });
+        }
+        this.triggerVersions.set(triggerId, [...history, { ...withoutOwner(saved), status: candidate ? 'candidate' : 'live', agentId: agent.id }]);
+        if (candidate) {
+            return { status: 200, body: this.candidateDto(agent, this.candidateOf(triggerId)) };
+        }
         this.triggers.set(triggerId, Object.assign(saved, { [ownerKey]: agent.id }));
         return { status: 200, body: withoutOwner(saved) };
     }
-    triggerShadow(method, agent, triggerId, body) {
-        if (method !== 'POST') {
-            return { status: 405 };
-        }
-        const existing = this.triggers.get(triggerId);
-        if (!existing || this.ownerOf(existing) !== agent.id) {
+    /** `admin/agents/{id}/triggers/{triggerId}/candidate/{promote|discard|comparison}`. */
+    triggerCandidate(method, agent, triggerId, action, body) {
+        const live = this.triggers.get(triggerId);
+        const candidate = live && this.ownerOf(live) === agent.id ? this.candidateOf(triggerId) : undefined;
+        if (action === 'comparison' && method === 'GET') {
+            if (!candidate || !live) {
+                return mockFailure('assistant-trigger-candidate-not-found');
+            }
+            const comparison = {
+                agentId: agent.id,
+                triggerId,
+                from: candidate.createdAt ?? candidate.changedAt,
+                to: this.now(),
+                live: emptyStats(live.version),
+                candidate: emptyStats(candidate.version),
+                pairedEvents: 0,
+                liveOnlyEvents: 0,
+                candidateOnlyEvents: 0,
+                tools: []
+            };
+            return { status: 200, body: comparison };
+        }
+        if ((action !== 'promote' && action !== 'discard') || method !== 'POST') {
+            return { status: 405 };
+        }
+        const request = body;
+        if (typeof request?.version !== 'number') {
+            return mockFailure('assistant-validation', { version: ['required'] });
+        }
+        if (!candidate || !live) {
+            return mockFailure('assistant-trigger-candidate-not-found');
+        }
+        if (candidate.version !== request.version) {
+            return mockFailure('assistant-version-conflict');
+        }
+        if (action === 'discard') {
+            candidate.status = 'discarded';
+            return { status: 204 };
+        }
+        for (const version of this.triggerVersions.get(triggerId) ?? []) {
+            if (version.status === 'live') {
+                version.status = 'superseded';
+            }
+        }
+        candidate.status = 'live';
+        // The promoted version keeps working in the trigger's mode.
+        const { status, agentId, ...definition } = candidate;
+        const promoted = { ...definition, shadow: live.shadow, changedAt: this.now(), changedBy: 'current-user' };
+        candidate.shadow = live.shadow;
+        this.triggers.set(triggerId, Object.assign(promoted, { [ownerKey]: agent.id }));
+        return { status: 200, body: withoutOwner(promoted) };
+    }
+    /** Every version of a data trigger of the agent, newest first, with its definition. */
+    triggerHistory(agentId, triggerId) {
+        return [...(this.triggerVersions.get(triggerId) ?? [])]
+            .filter(version => version.agentId === agentId)
+            .sort((left, right) => right.version - left.version)
+            .map(version => ({
+            version: version.version,
+            status: version.status,
+            skillId: version.skillId,
+            source: version.source,
+            event: version.event,
+            filters: [...(version.filters ?? [])],
+            cron: version.cron,
+            timeZone: version.timeZone,
+            subjectSet: version.subjectSet,
+            message: version.message,
+            conflict: version.conflict,
+            debounceSeconds: version.debounceSeconds,
+            createdAt: version.createdAt ?? version.changedAt,
+            createdBy: version.createdBy ?? version.changedBy,
+            reason: version.reason
+        }));
+    }
+    candidateOf(triggerId) {
+        return (this.triggerVersions.get(triggerId) ?? []).find(version => version.status === 'candidate');
+    }
+    /** A candidate as the server shows it: always in shadow, with its own problem. */
+    candidateDto(agent, candidate) {
+        const { status, agentId, ...definition } = candidate;
+        const problem = this.triggerProblem(agent, definition);
+        return { ...definition, shadow: true, inEffect: problem === null, problem };
+    }
+    triggerShadow(method, agent, triggerId, body) {
+        if (method !== 'POST') {
+            return { status: 405 };
+        }
+        const existing = this.triggers.get(triggerId);
+        if (!existing || this.ownerOf(existing) !== agent.id) {
             return mockFailure('assistant-trigger-not-found');
         }
         const request = body;
@@ -3413,8 +4196,11 @@ class NhAssistantMockRunConfiguration {
      * that its profile, or else its agent's, does not permit.
      */
     withWarnings(agent, skill) {
+        // A version whose asset no longer resolves to its hash is out of effect, as after the server's load.
+        const assetProblem = skill.instructionsAsset ? this.instructionAssets.problemOf(skill.instructionsAsset) : null;
         return {
             ...skill,
+            ...(assetProblem !== null ? { inEffect: false, problem: assetProblem } : {}),
             warnings: mockClassificationWarnings(this.profileClassifications, skill.profile ?? agent?.profile, skill.dataClassification ?? agent?.dataClassification)
         };
     }
@@ -3422,7 +4208,7 @@ class NhAssistantMockRunConfiguration {
         return trigger[ownerKey];
     }
     requireKnown(errors, field, value, known, required = false) {
-        const name = text(value);
+        const name = text$1(value);
         if (name === null) {
             if (required) {
                 errors[field] = ['required'];
@@ -3470,7 +4256,7 @@ function withoutOwner(trigger) {
 function emptyStats(version) {
     return { version, runs: 0, completed: 0, failed: 0, proposals: 0, toolCalls: 0, tokens: 0 };
 }
-function text(value) {
+function text$1(value) {
     return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
 }
 function inRange(value, min, max) {
@@ -3527,20 +4313,29 @@ class NhAssistantMockAdmin {
         this.canAdminister = admin.canAdminister ?? true;
         this.preferences = { ...defaultPreferences, ...scenario.preferences };
         this.contextVersions.push({ version: 1, hash: mockHashText(admin.context ?? ''), updatedAt: now(), updatedBy: null, text: admin.context ?? '' });
+        this.instructionAssets = new NhAssistantMockInstructionAssets(admin.instructionAssets);
         this.agents = new NhAssistantMockAdminAgents(scenario, now, {
             hasServer: serverId => this.mcp.hasServer(serverId),
             agentPolicyNames: () => this.runConfiguration.agentPolicyNames,
             divisionsListed: () => this.runConfiguration.divisionsListed,
             profileNames: () => this.runConfiguration.profileNames,
-            dataConsultations: agentId => this.runConfiguration.consultationsInEffect(agentId)
+            dataConsultations: agentId => this.runConfiguration.consultationsInEffect(agentId),
+            shadowVariantRefusal: input => this.handOffs.shadowVariantRefusal(input),
+            instructionAssets: () => this.instructionAssets
         });
         this.accounts = new NhAssistantMockAccounts(admin);
         this.runConfiguration = new NhAssistantMockRunConfiguration(admin, {
             find: agentId => this.agents.find(agentId),
             all: () => this.agents.all(),
             knownSubjectTypes: () => [...(scenario.subjectTypes ?? []).map(type => type.id), mockSystemSubjectType],
-            setDataSkill: (agentId, skillId, description, startsOff) => this.agents.setDataSkill(agentId, skillId, description, startsOff)
-        }, now, this.accounts);
+            setDataSkill: (agentId, skillId, description, startsOff) => this.agents.setDataSkill(agentId, skillId, description, startsOff),
+            acceptsDataHandOffs: agentId => this.handOffs.acceptsDataHandOffs(agentId)
+        }, now, this.accounts, this.instructionAssets);
+        this.handOffs = new NhAssistantMockHandOffs(admin, {
+            find: agentId => this.agents.find(agentId),
+            all: () => this.agents.all(),
+            isConfigured: agent => this.runConfiguration.isConfigured(agent)
+        }, now);
         this.mcp = new NhAssistantMockAdminMcp(scenario, now, {
             agents: () => this.agents.all(),
             chatAgentIds: () => this.agents.chatAgents().map(agent => agent.id),
@@ -3593,6 +4388,30 @@ class NhAssistantMockAdmin {
     allAgents() {
         return this.agents.all();
     }
+    /** One agent of the administration, or `undefined`. */
+    findAgent(agentId) {
+        return this.agents.find(agentId);
+    }
+    /** The definition in code of an agent in code; `null` for an agent created here. */
+    codeDefinition(agentId) {
+        return this.agents.codeDefinition(agentId);
+    }
+    /**
+     * A copy of the agents and their run configuration, consultations and hand-offs; the returned
+     * function puts it back, for an import of an agent package that fails as a whole and for its preview.
+     */
+    snapshot() {
+        const restores = [this.agents.snapshot(), this.runConfiguration.snapshot(), this.handOffs.snapshot()];
+        return () => {
+            for (const restore of restores) {
+                restore();
+            }
+        };
+    }
+    /** Makes the next version of an agent, as a change of its metadata does. */
+    nextAgentVersion(agentId) {
+        return this.agents.nextVersion(agentId);
+    }
     handlePreferences(method, body) {
         if (method === 'GET') {
             return { status: 200, body: this.preferences };
@@ -3635,6 +4454,8 @@ class NhAssistantMockAdmin {
                 return method === 'GET' && segments.length === 2 ? { status: 200, body: this.toolCatalog() } : mockFailure('assistant-not-found');
             case 'run-catalog':
                 return segments.length === 2 ? this.runConfiguration.runCatalog(method) : mockFailure('assistant-not-found');
+            case 'instruction-assets':
+                return this.instructionAssets.handle(method, segments.slice(2));
             case 'accounts':
                 return segments.length === 2 ? this.accounts.search(method, query) : mockFailure('assistant-not-found');
             case 'agents':
@@ -3647,6 +4468,12 @@ class NhAssistantMockAdmin {
                 if (id !== undefined && (action === 'replay' || action === 'replays') && segments.length === 4) {
                     return this.agents.agentReplay(method, id, action, body);
                 }
+                if (id !== undefined && (action === 'hand-offs' || action === 'shadow-variants')) {
+                    const handed = this.handOffs.handle(method, id, segments.slice(3), body, query);
+                    if (handed) {
+                        return handed;
+                    }
+                }
                 if (id !== undefined && action !== undefined) {
                     const configured = this.runConfiguration.handle(method, id, segments.slice(3), body, query);
                     if (configured) {
@@ -3755,6 +4582,1329 @@ function toContext(version) {
     return { text: version.text, version: version.version, hash: version.hash, updatedAt: version.updatedAt, updatedBy: version.updatedBy };
 }
 
+/** The longest package id. */
+const maxPackageId = 128;
+/** The longest package description. */
+const maxPackageDescription = 500;
+/** The header of the export that lists the references to agents outside the selection. */
+const warningsHeader = 'X-NewHeap-Package-Warnings';
+/** The order in which an import writes the parts of its agents. */
+const phaseOrder = ['agent', 'runSettings', 'skill', 'trigger', 'consultation', 'handOff', 'metadata'];
+/** The properties of the package format each lockable field stands for. */
+const lockProperties = {
+    agent: {
+        instructions: ['instructions', 'instructionsAsset'],
+        worksOn: ['worksOnSubjectTypes', 'worksOnAllSubjects', 'worksOnApplication', 'perDivision', 'runPolicy', 'viewPolicy']
+    },
+    runSettings: {
+        dailyBudget: ['dailyToolCalls', 'dailyTokens'],
+        files: ['acceptsFiles', 'maxFileBytes', 'maxFilePages', 'maxFilesPerTurn', 'maxFileTokensPerTurn']
+    },
+    skill: {
+        instructions: ['instructions', 'instructionsAsset'],
+        dailyBudget: ['dailyToolCalls', 'dailyTokens'],
+        files: ['acceptsFiles', 'maxFileBytes', 'maxFilePages', 'maxFilesPerTurn', 'maxFileTokensPerTurn']
+    },
+    trigger: {},
+    consultation: {
+        limits: ['maxToolCalls', 'timeoutSeconds', 'maxAnswerChars', 'maxHistoryMessages']
+    },
+    handOff: {},
+    metadata: {}
+};
+/** The fields of the definition an administrator overrides on an agent in code, and its overlay carries. */
+const codeAgentFields = ['displayName', 'description', 'instructions', 'toolSelectors', 'requiredPolicy', 'autonomy'];
+/** The properties the strict format reads per object, required ones first. */
+const formatShapes = {
+    root: { required: ['format', 'formatVersion', 'package', 'agents'], optional: [] },
+    package: { required: ['id', 'version'], optional: ['description'] },
+    agent: {
+        required: ['id', 'source'],
+        optional: ['definition', 'runSettings', 'skills', 'triggers', 'consultations', 'handOffs', 'metadata', 'groups', 'locks', 'hashes']
+    },
+    definition: {
+        required: [],
+        optional: [
+            'displayName', 'description', 'instructions', 'instructionsAsset', 'toolSelectors', 'requiredPolicy', 'autonomy', 'offeredInChat',
+            'worksOnSubjectTypes', 'worksOnAllSubjects', 'worksOnApplication', 'perDivision', 'runPolicy', 'viewPolicy', 'profile',
+            'dataClassification', 'startsOff', 'startsInShadow', 'shadowOf'
+        ]
+    },
+    runSettings: {
+        required: ['accountability'],
+        optional: [
+            'delegateFromInitiator', 'allowGatewayReads', 'elevatedReads', 'approvalPolicy', 'retryCount', 'dailyToolCalls', 'dailyTokens',
+            'maxConcurrentRuns', 'maxRunsPerSubjectPerDay', 'maxTokensPerRun', 'triageProfile', 'ruleHandler', 'acceptsFiles', 'maxFileBytes',
+            'maxFilePages', 'maxFilesPerTurn', 'maxFileTokensPerTurn'
+        ]
+    },
+    skill: {
+        required: ['id', 'description'],
+        optional: [
+            'instructions', 'instructionsAsset', 'tools', 'profile', 'ruleHandler', 'maxTokensPerRun', 'dailyToolCalls', 'dailyTokens',
+            'approvalPolicy', 'dataClassification', 'acceptsFiles', 'maxFileBytes', 'maxFilePages', 'maxFilesPerTurn', 'maxFileTokensPerTurn',
+            'startsOff'
+        ]
+    },
+    trigger: {
+        required: ['id', 'source'],
+        optional: ['skill', 'event', 'filters', 'cron', 'timeZone', 'subjectSet', 'message', 'conflict', 'debounceSeconds']
+    },
+    consultation: {
+        required: ['subjectType', 'description'],
+        optional: [
+            'instructions', 'minimumRole', 'askerPolicy', 'routes', 'proposalRole', 'proposalPolicy', 'toolSelectors', 'maxToolCalls',
+            'timeoutSeconds', 'maxAnswerChars', 'maxHistoryMessages', 'allowRequests', 'exposeToMcp', 'dataClassification', 'startsOff'
+        ]
+    },
+    handOff: { required: ['subjectType', 'sources'], optional: ['description', 'notifySource', 'maxPerSubjectPerDay'] },
+    instructionsAsset: { required: ['assetId', 'version', 'hash'], optional: [] }
+};
+/**
+ * Agent packages of the mock API (S7-2), with the rules of the server: an export of exactly the chosen
+ * agents with the references to agents outside them, a preview per part (`created`, `changed`,
+ * `unchanged`, `kept-local`, `left-behind`, `refused`) after one check of the whole package against
+ * the host as it would be after the import, and an import that applies every part through the mock's
+ * own endpoints in dependency order, or nothing: a refused part answers `409 assistant-package-refused`
+ * with the plain field error `parts: invalid`, and the preview says why. Linked parts carry their link
+ * in every read; every save path refuses a change of a locked field with `{field}: locked`, and removing
+ * a locked part or deleting or resetting a linked agent answers `409 assistant-package-locked`.
+ * Unlinking makes a part local: the next upgrade keeps it as `kept-local` unless the import relinks it.
+ * An import takes over an agent the host has with a package agent's id and no package of its own when
+ * `relink` names that whole agent; otherwise the agent refuses the package (`assistant-agent-exists`).
+ * Hashes are the SHA-256 of each part's canonical JSON; a hash a package gives is not checked.
+ */
+class NhAssistantMockAgentPackages {
+    constructor(context) {
+        this.context = context;
+        this.links = new Map();
+        this.installed = new Map();
+    }
+    /**
+     * Imports the scenario's packages in order, as an administrator would; a package the import refuses
+     * fails the scenario at once.
+     */
+    importPresets(presets) {
+        for (const preset of presets) {
+            const result = this.importPackage({ package: preset.package, options: { serviceAccounts: preset.serviceAccounts ?? null } }, true);
+            if (result.status !== 200) {
+                throw new Error(`The mock refused the scenario's agent package '${preset.package?.package?.id}': ${JSON.stringify(result.body ?? null)}.`);
+            }
+        }
+    }
+    /**
+     * `POST admin/agent-packages/export`, `.../preview` and `.../import`, and `POST
+     * admin/agents/{id}/package/unlink`; `null` for another route.
+     */
+    handle(method, segments, body) {
+        if (segments[0] !== 'admin') {
+            return null;
+        }
+        if (segments[1] === 'agent-packages' && segments.length === 3) {
+            if (method !== 'POST') {
+                return { status: 405 };
+            }
+            switch (segments[2]) {
+                case 'export':
+                    return this.exportPackage(body);
+                case 'preview':
+                    return this.importPackage(body, false);
+                case 'import':
+                    return this.importPackage(body, true);
+                default:
+                    return mockFailure('assistant-not-found');
+            }
+        }
+        if (segments[1] === 'agents' && segments[3] === 'package' && segments[4] === 'unlink' && segments.length === 5) {
+            return method === 'POST' ? this.unlink(segments[2], body) : { status: 405 };
+        }
+        return null;
+    }
+    /**
+     * 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`.
+     * Removing a part with locks and deleting a linked agent answer `409 assistant-package-locked`, as
+     * does a reset that would give a locked field of the definition another value; removing a linked
+     * part without locks drops its link. Other requests run as they are.
+     */
+    guard(method, segments, run) {
+        const target = guardedPart(method, segments);
+        if (!target) {
+            return run();
+        }
+        if (target.part === null) {
+            return this.isLinked(target.agentId) ? mockFailure('assistant-package-locked') : run();
+        }
+        const reset = target.reset === true;
+        const link = this.links.get(target.agentId)?.parts.get(target.part);
+        if (!link) {
+            return run();
+        }
+        if (target.removal) {
+            if (link.lockedFields.length > 0) {
+                return mockFailure('assistant-package-locked');
+            }
+            const removed = run();
+            if (removed.status < 300) {
+                this.links.get(target.agentId)?.parts.delete(target.part);
+            }
+            return removed;
+        }
+        if (link.lockedFields.length === 0) {
+            return run();
+        }
+        const kind = kindOf(target.part);
+        const before = this.lockView(target.agentId, target.part);
+        const restore = this.context.snapshot();
+        const result = run();
+        if (result.status >= 300) {
+            return result;
+        }
+        const changed = lockedChanges(kind, link.lockedFields, before, this.lockView(target.agentId, target.part), link.view);
+        if (changed.length > 0) {
+            restore();
+            return reset ? mockFailure('assistant-package-locked') : mockFailure('assistant-validation', Object.fromEntries(changed.map(field => [field, ['locked']])));
+        }
+        return result;
+    }
+    /**
+     * Adds the package links to an administration answer: the agent's package on agents, the part's link
+     * on run settings, skills, triggers, consultations, hand-offs and metadata entries.
+     */
+    decorate(method, segments, result) {
+        if (segments[0] !== 'admin' || segments[1] !== 'agents' || result.status >= 300 || result.body === undefined || this.links.size === 0) {
+            return result;
+        }
+        const [, , agentId, area, id, action] = segments;
+        const body = result.body;
+        if (agentId === undefined) {
+            if (Array.isArray(body)) {
+                return { ...result, body: body.map(agent => this.withAgentPackage(agent)) };
+            }
+            return { ...result, body: this.withAgentPackage(body) };
+        }
+        if (area === undefined || (area === 'reset' && segments.length === 4)) {
+            return { ...result, body: this.withAgentPackage(body) };
+        }
+        if (method === 'DELETE' && area !== 'metadata') {
+            return result;
+        }
+        switch (area) {
+            case 'configuration': {
+                const configuration = body;
+                return {
+                    ...result,
+                    body: {
+                        ...configuration,
+                        runSettings: configuration.runSettings ? this.withLink(agentId, 'runSettings', configuration.runSettings) : configuration.runSettings,
+                        dataSkills: configuration.dataSkills.map(skill => this.withLink(agentId, `skill:${skill.skillId}`, skill)),
+                        dataTriggers: configuration.dataTriggers.map(trigger => this.withLink(agentId, `trigger:${trigger.triggerId}`, trigger)),
+                        dataConsultations: configuration.dataConsultations?.map(item => this.withLink(agentId, `consultation:${item.subjectType}`, item))
+                    }
+                };
+            }
+            case 'run-settings':
+                return { ...result, body: this.withLink(agentId, 'runSettings', body) };
+            case 'skills':
+                return id !== undefined && (segments.length === 5 || (action === 'candidate' && segments[6] === 'promote'))
+                    ? { ...result, body: this.withLink(agentId, `skill:${id}`, body) }
+                    : result;
+            case 'triggers':
+                return id !== undefined && (segments.length === 5 || (action === 'candidate' && segments[6] === 'promote') || action === 'shadow')
+                    ? { ...result, body: this.withLink(agentId, `trigger:${id}`, body) }
+                    : result;
+            case 'consultations':
+                return id !== undefined ? { ...result, body: this.withLink(agentId, `consultation:${id}`, body) } : result;
+            case 'hand-offs': {
+                if (id !== undefined) {
+                    return { ...result, body: this.withLink(agentId, `handOff:${id}`, body) };
+                }
+                const handOffs = body;
+                return { ...result, body: { ...handOffs, dataHandOffs: handOffs.dataHandOffs.map(item => this.withLink(agentId, `handOff:${item.subjectType}`, item)) } };
+            }
+            case 'metadata':
+                if (id !== undefined) {
+                    return { ...result, body: this.withLink(agentId, `metadata:${id}`, body) };
+                }
+                return { ...result, body: body.map(entry => this.withLink(agentId, `metadata:${entry.name}`, entry)) };
+            default:
+                return result;
+        }
+    }
+    /** A copy of the links and the imported packages; the returned function puts them back. */
+    snapshot() {
+        return mockSnapshot(this.links, this.installed);
+    }
+    /** Forgets the links of an agent that was deleted, as the server removes them with it. */
+    forget(agentId) {
+        this.links.delete(agentId);
+    }
+    exportPackage(body) {
+        const request = (body ?? {});
+        const agentIds = request.agentIds;
+        if (!Array.isArray(agentIds) || agentIds.length === 0 || !agentIds.every(id => typeof id === 'string')) {
+            return mockFailure('assistant-validation', { agentIds: ['required'] });
+        }
+        if (agentIds.length > NH_ASSISTANT_AGENT_PACKAGE_MAX_AGENTS) {
+            return mockFailure('assistant-validation', { agentIds: ['too-long'] });
+        }
+        if (new Set(agentIds).size !== agentIds.length) {
+            return mockFailure('assistant-validation', { agentIds: ['invalid'] });
+        }
+        const reads = [];
+        for (const agentId of agentIds) {
+            const read = this.read(agentId);
+            if (!read) {
+                return mockFailure('assistant-agent-not-found');
+            }
+            reads.push(read);
+        }
+        const options = request.options ?? {};
+        const errors = {};
+        const linked = this.links.get(reads[0].agent.id);
+        const packageId = text(options.packageId) ?? linked?.packageId ?? reads[0].agent.id;
+        if (!mockDashCase.test(packageId) || packageId.length > maxPackageId) {
+            errors['packageId'] = ['invalid'];
+        }
+        const installed = this.installed.get(packageId);
+        const version = options.version ?? (installed ? installed.version + 1 : 1);
+        if (!Number.isInteger(version) || version < 1) {
+            errors['version'] = ['invalid'];
+        }
+        const description = text(options.description);
+        if (description !== null && description.length > maxPackageDescription) {
+            errors['description'] = ['too-long'];
+        }
+        const agents = reads.map(read => this.packageAgentOf(read));
+        for (const [agentId, locks] of Object.entries(options.locks ?? {})) {
+            const agent = agents.find(item => item.id === agentId);
+            for (const [part, fields] of Object.entries(locks ?? {})) {
+                // A lock of an agent or part the export does not hold, or of a field its kind does not lock.
+                const problem = agent ? lockProblem(agent, part, fields) : 'not-found';
+                if (problem) {
+                    errors['locks'] = ['invalid'];
+                }
+                else if (agent && fields.length > 0) {
+                    agent.locks = { ...(agent.locks ?? {}), [part]: [...fields] };
+                }
+            }
+        }
+        if (Object.keys(errors).length > 0) {
+            return mockFailure('assistant-validation', errors);
+        }
+        for (const agent of agents) {
+            agent.hashes = Object.fromEntries([...partsOf(agent)].map(([part, value]) => [part, mockSha256(canonicalJson(value))]));
+        }
+        const agentPackage = {
+            format: NH_ASSISTANT_AGENT_PACKAGE_FORMAT,
+            formatVersion: NH_ASSISTANT_AGENT_PACKAGE_FORMAT_VERSION,
+            package: { id: packageId, version, ...(description !== null ? { description } : {}) },
+            agents
+        };
+        return {
+            status: 200,
+            text: JSON.stringify(withoutNulls(agentPackage), null, 2),
+            headers: {
+                'content-type': 'application/json',
+                'content-disposition': `attachment; filename="agent-package-${packageId}.json"`,
+                [warningsHeader]: JSON.stringify(this.warningsOf(reads))
+            }
+        };
+    }
+    /** Every reference of the exported agents to agents outside the selection. */
+    warningsOf(reads) {
+        const selected = new Set(reads.map(read => read.agent.id));
+        const everyone = this.agents();
+        const warnings = [];
+        const outside = (agentId, part, code, referencedAgentId) => {
+            if (!selected.has(referencedAgentId)) {
+                warnings.push({ agentId, part, code, referencedAgentId });
+            }
+        };
+        for (const { agent, configuration, handOffs } of reads) {
+            if (agent.shadowOf) {
+                outside(agent.id, 'agent', 'shadow-of', agent.shadowOf);
+            }
+            for (const variant of everyone.filter(item => item.shadowOf === agent.id)) {
+                outside(agent.id, 'agent', 'shadow-variant', variant.id);
+            }
+            for (const handOff of handOffs?.dataHandOffs ?? []) {
+                for (const source of handOff.sources) {
+                    outside(agent.id, `handOff:${handOff.subjectType}`, 'hand-off-source', source);
+                }
+            }
+            for (const consultation of configuration?.dataConsultations ?? []) {
+                for (const asker of consultation.askingAgents) {
+                    outside(agent.id, `consultation:${consultation.subjectType}`, 'consultation-asker', asker);
+                }
+            }
+        }
+        return warnings;
+    }
+    /**
+     * `POST admin/agent-packages/preview` (`keep` false) and `.../import`: the package read strictly, its
+     * parts applied in dependency order on a copy of the host, and, for an import without a refused part,
+     * applied for real with the links of its parts. An import with a refused part answers
+     * `assistant-package-refused` with `parts: invalid`, as the server does; the preview names each reason.
+     */
+    importPackage(body, keep) {
+        const request = (body ?? {});
+        const read = readPackage(request.package);
+        if ('status' in read) {
+            return read;
+        }
+        const agentPackage = read.package;
+        const options = request.options ?? {};
+        const apply = options.apply ?? 'live';
+        if (apply !== 'live' && apply !== 'shadow') {
+            return mockFailure('assistant-validation', { apply: ['invalid'] });
+        }
+        // The accounts and the parts to relink name agents of the package, as the server checks them.
+        const ids = new Set(agentPackage.agents.map(agent => agent.id));
+        const optionErrors = {};
+        if (Object.entries(options.serviceAccounts ?? {}).some(([agentId, actorId]) => !ids.has(agentId) || typeof actorId !== 'string' || actorId.trim().length === 0 || actorId.trim().length > 256)) {
+            optionErrors['serviceAccounts'] = ['invalid'];
+        }
+        if ((options.relink ?? []).some(item => !item || !ids.has(item.agentId)
+            || (item.part !== null && item.part !== undefined && (typeof item.part !== 'string' || !validPartKey(item.part))))) {
+            optionErrors['relink'] = ['invalid'];
+        }
+        if (Object.keys(optionErrors).length > 0) {
+            return mockFailure('assistant-validation', optionErrors);
+        }
+        // The check tries every part on a copy of the host, in live mode, and puts the host back.
+        const restoreHost = this.context.snapshot();
+        const restoreOwn = this.snapshot();
+        const planned = this.apply(agentPackage, options, 'live', null);
+        restoreHost();
+        restoreOwn();
+        const preview = {
+            packageId: agentPackage.package.id,
+            packageVersion: agentPackage.package.version,
+            installedVersion: this.installed.get(agentPackage.package.id)?.version ?? null,
+            importable: planned.every(part => part.outcome !== 'refused'),
+            parts: planned.map(publicPart)
+        };
+        if (!keep) {
+            return { status: 200, body: preview };
+        }
+        if (!preview.importable) {
+            return mockFailure('assistant-package-refused', refusedErrors);
+        }
+        // The import applies the package for real, with the chosen mode, and links its parts.
+        const restoreAll = [this.context.snapshot(), this.snapshot()];
+        const applied = this.apply(agentPackage, options, apply, planned);
+        if (applied.some(part => part.outcome === 'refused')) {
+            for (const restore of restoreAll) {
+                restore();
+            }
+            return mockFailure('assistant-package-refused', refusedErrors);
+        }
+        this.link(agentPackage, options, planned);
+        return {
+            status: 200,
+            body: {
+                packageId: agentPackage.package.id,
+                packageVersion: agentPackage.package.version,
+                hash: mockSha256(canonicalJson(agentPackage)),
+                parts: applied.map(publicPart)
+            }
+        };
+    }
+    /**
+     * Applies every agent and part of the package to the host in dependency order: agents that are no
+     * shadow variant of another agent of the package first, each phase for all of them, then the
+     * variants; reports per part what happened, `refused` with the endpoint's code or field errors.
+     * Parts an administrator unlinked stay as they are (`kept-local`) unless `relink` names them; agents
+     * and parts an earlier version of the package linked that it no longer holds are `left-behind`.
+     */
+    apply(agentPackage, options, mode, plan) {
+        const packageId = agentPackage.package.id;
+        const ids = new Set(agentPackage.agents.map(agent => agent.id));
+        const live = agentPackage.agents.filter(agent => !agent.definition?.shadowOf || !ids.has(agent.definition.shadowOf));
+        const variants = agentPackage.agents.filter(agent => !live.includes(agent));
+        const results = new Map();
+        const refusedAgents = new Set();
+        for (const group of [live, variants]) {
+            for (const kind of phaseOrder) {
+                for (const agent of group) {
+                    if (refusedAgents.has(agent.id)) {
+                        continue;
+                    }
+                    for (const [part, value] of partsOf(agent)) {
+                        if (kindOf(part) !== kind) {
+                            continue;
+                        }
+                        const planned = plan?.find(item => item.agentId === agent.id && item.part === part);
+                        // The import writes only what the check found new or changed.
+                        const outcome = planned && planned.outcome !== 'created' && planned.outcome !== 'changed'
+                            ? planned
+                            : this.applyPart(agentPackage, agent, part, value, options, mode);
+                        results.set(agent.id, [...(results.get(agent.id) ?? []), outcome]);
+                        if (kind === 'agent' && outcome.outcome === 'refused') {
+                            refusedAgents.add(agent.id);
+                        }
+                    }
+                    // Groups go with the agent: they are no part, and stay free once imported.
+                    if (kind === 'agent' && !refusedAgents.has(agent.id) && agent.groups && !agent.definition?.shadowOf) {
+                        const groups = this.context.call('PUT', `admin/agents/${encodeURIComponent(agent.id)}/groups`, { groups: agent.groups });
+                        if (groups.status >= 300) {
+                            const refusal = refusalOf(agent.id, 'agent', groups, agent.locks?.['agent'] ?? []);
+                            results.set(agent.id, [refusal, ...(results.get(agent.id) ?? []).filter(item => item.part !== 'agent')]);
+                            refusedAgents.add(agent.id);
+                        }
+                    }
+                }
+            }
+        }
+        // What an earlier version of the package linked and this one no longer holds stays, unlinked.
+        const ordered = agentPackage.agents.flatMap(agent => results.get(agent.id) ?? []);
+        for (const [agentId, link] of this.links) {
+            if (link.packageId !== packageId) {
+                continue;
+            }
+            if (!ids.has(agentId)) {
+                ordered.push(leftBehind(agentId, 'agent'));
+                continue;
+            }
+            const held = new Set(partsOf(agentPackage.agents.find(agent => agent.id === agentId)).keys());
+            for (const part of link.parts.keys()) {
+                if (!held.has(part)) {
+                    ordered.push(leftBehind(agentId, part));
+                }
+            }
+        }
+        return ordered;
+    }
+    /** Applies one part through its endpoint and reports what happened to it. */
+    applyPart(agentPackage, agent, part, value, options, mode) {
+        const lockedFields = agent.locks?.[part] ?? [];
+        const link = this.links.get(agent.id);
+        const linkedHere = link?.packageId === agentPackage.package.id;
+        const relinked = (options.relink ?? []).some(item => item.agentId === agent.id && (item.part === null || item.part === undefined || item.part === part));
+        const lockProblemCode = lockProblem(agent, part, lockedFields);
+        if (lockProblemCode) {
+            return { ...base(agent.id, part, lockedFields), outcome: 'refused', errors: { locks: [lockProblemCode] } };
+        }
+        const host = this.read(agent.id);
+        if (part === 'agent') {
+            // A relink of the whole agent lets the import take over an agent the host has with its id.
+            const takenOver = (options.relink ?? []).some(item => item.agentId === agent.id && (item.part === null || item.part === undefined));
+            const otherPackage = !!link && !linkedHere && link.parts.size > 0;
+            const refusal = agentRefusal(agent, host?.agent ?? null, linkedHere || takenOver, otherPackage);
+            if (refusal) {
+                return { ...base(agent.id, part, lockedFields), outcome: 'refused', code: refusal };
+            }
+        }
+        if (linkedHere && !relinked && (link.local.has(part) || link.local.has(NH_ASSISTANT_PACKAGE_LOCK_ALL))) {
+            return { ...base(agent.id, part, lockedFields), outcome: 'kept-local' };
+        }
+        const before = host ? this.hostHash(host, part) : null;
+        const partLink = linkedHere ? link.parts.get(part) : undefined;
+        const result = this.write(agent, part, value, host, options, mode);
+        if (result.status >= 300) {
+            return refusalOf(agent.id, part, result, lockedFields);
+        }
+        const after = this.read(agent.id);
+        const hashAfter = after ? this.hostHash(after, part) : null;
+        // In shadow a changed skill or trigger is saved as the candidate next to its live version.
+        const kind = kindOf(part);
+        const candidateVersion = mode === 'shadow' && before !== null && (kind === 'skill' || kind === 'trigger')
+            ? result.body?.version ?? null
+            : null;
+        let outcome = 'changed';
+        if (before === null) {
+            outcome = 'created';
+        }
+        else if (candidateVersion === null && before === hashAfter) {
+            outcome = 'unchanged';
+        }
+        return {
+            ...base(agent.id, part, lockedFields),
+            outcome,
+            changedLocally: !!partLink && before !== partLink.hash,
+            candidateVersion,
+            hashAfter,
+            viewAfter: this.lockView(agent.id, part)
+        };
+    }
+    /** Writes one part through the endpoint a save of it uses. */
+    write(agent, part, value, host, options, mode) {
+        const kind = kindOf(part);
+        const key = keyOf(part);
+        const agentPath = `admin/agents/${encodeURIComponent(agent.id)}`;
+        const item = value;
+        switch (kind) {
+            case 'agent':
+                return this.writeDefinition(agent, host);
+            case 'runSettings': {
+                const settings = item;
+                const account = settings.accountability === 'service-account' ? options.serviceAccounts?.[agent.id] ?? null : null;
+                return this.context.call('PUT', `${agentPath}/run-settings`, {
+                    ...settings,
+                    serviceAccountActorId: account,
+                    expectedVersion: host?.configuration?.runSettings?.version ?? null
+                });
+            }
+            case 'skill': {
+                const { id: _, startsOff, ...skill } = item;
+                const current = host?.configuration?.dataSkills.find(existing => existing.skillId === key);
+                return this.context.call('PUT', `${agentPath}/skills/${encodeURIComponent(key)}`, {
+                    ...skill,
+                    tools: skill['tools'] ?? [],
+                    expectedVersion: current?.version ?? null,
+                    ...(current ? { apply: mode } : startsOff === true ? { startsOff: true } : {})
+                });
+            }
+            case 'trigger': {
+                const { id: _, ...trigger } = item;
+                const current = host?.configuration?.dataTriggers.find(existing => existing.triggerId === key);
+                return this.context.call('PUT', `${agentPath}/triggers/${encodeURIComponent(key)}`, {
+                    ...trigger,
+                    expectedVersion: current?.version ?? null,
+                    ...(current ? { apply: mode } : {})
+                });
+            }
+            case 'consultation': {
+                const { subjectType: _, startsOff, ...consultation } = item;
+                const current = host?.configuration?.dataConsultations?.find(existing => existing.subjectType === key);
+                return this.context.call('PUT', `${agentPath}/consultations/${encodeURIComponent(key)}`, {
+                    ...consultation,
+                    routes: consultation['routes'] ?? [],
+                    expectedVersion: current?.version ?? null,
+                    ...(!current && startsOff === true ? { startsOff: true } : {})
+                });
+            }
+            case 'handOff': {
+                const { subjectType: _, ...handOff } = item;
+                const current = host?.handOffs?.dataHandOffs.find(existing => existing.subjectType === key);
+                return this.context.call('PUT', `${agentPath}/hand-offs/${encodeURIComponent(key)}`, {
+                    ...handOff,
+                    expectedVersion: current?.version ?? null
+                });
+            }
+            case 'metadata': {
+                const entry = this.read(agent.id)?.metadata.find(existing => existing.name === key);
+                return entry
+                    ? this.context.call('PUT', `${agentPath}/metadata/${encodeURIComponent(key)}`, { value, expectedVersion: entry.version })
+                    : mockFailure('assistant-metadata-entry-not-found');
+            }
+        }
+    }
+    /**
+     * Writes the definition: creates an agent created here when its id is free, or makes its next
+     * version; overrides an agent in code with the overlay, or restores its code without one.
+     */
+    writeDefinition(agent, host) {
+        const definition = agent.definition ?? {};
+        if (agent.source === 'code') {
+            const code = this.context.codeDefinition(agent.id);
+            const overlay = codeAgentFields.filter(field => definition[field] !== undefined && definition[field] !== null);
+            if (overlay.length === 0) {
+                return host?.agent.isOverridden
+                    ? this.context.call('POST', `admin/agents/${encodeURIComponent(agent.id)}/reset`)
+                    : { status: 200, body: host?.agent };
+            }
+            return this.context.call('PUT', `admin/agents/${encodeURIComponent(agent.id)}`, {
+                ...code,
+                ...Object.fromEntries(overlay.map(field => [field, definition[field]])),
+                id: agent.id,
+                mcpServerIds: host?.agent.mcpServerIds ?? [],
+                expectedVersion: host?.agent.version ?? 1
+            });
+        }
+        const worksOn = ['worksOnSubjectTypes', 'worksOnAllSubjects', 'worksOnApplication', 'perDivision', 'runPolicy', 'viewPolicy'];
+        const input = {
+            id: agent.id,
+            displayName: definition.displayName ?? '',
+            description: definition.description ?? '',
+            instructions: definition.instructions ?? '',
+            ...(definition.instructionsAsset ? { instructionsAsset: definition.instructionsAsset } : {}),
+            toolSelectors: definition.toolSelectors ?? [],
+            mcpServerIds: host?.agent.mcpServerIds ?? [],
+            requiredPolicy: definition.requiredPolicy ?? null,
+            autonomy: definition.autonomy ?? 'explain',
+            ...(definition.offeredInChat !== undefined && definition.offeredInChat !== null ? { offeredInChat: definition.offeredInChat } : {}),
+            ...(worksOn.some(field => definition[field] !== undefined && definition[field] !== null)
+                ? Object.fromEntries(worksOn.map(field => [field, definition[field] ?? null]))
+                : {}),
+            ...(definition.profile ? { profile: definition.profile } : {}),
+            ...(definition.dataClassification ? { dataClassification: definition.dataClassification } : {})
+        };
+        if (!host) {
+            return this.context.call('POST', 'admin/agents', {
+                ...input,
+                ...(definition.startsOff ? { startsOff: true } : {}),
+                ...(definition.startsInShadow ? { startsInShadow: true } : {}),
+                ...(definition.shadowOf ? { shadowOf: definition.shadowOf } : {})
+            });
+        }
+        return this.context.call('PUT', `admin/agents/${encodeURIComponent(agent.id)}`, { ...input, expectedVersion: host.agent.version });
+    }
+    /**
+     * Links the parts of an import: each part the import applied or found unchanged, with its locks and
+     * the hash of the host's part once the package's version is in effect; parts that stayed local stay
+     * so, relinked ones are linked again, and what the package left behind is unlinked.
+     */
+    link(agentPackage, options, planned) {
+        const packageId = agentPackage.package.id;
+        const version = agentPackage.package.version;
+        const now = this.context.now();
+        for (const agent of agentPackage.agents) {
+            const previous = this.links.get(agent.id);
+            const kept = previous?.packageId === packageId ? previous : undefined;
+            const relinked = (options.relink ?? []).filter(item => item.agentId === agent.id);
+            const local = new Set([...(kept?.local ?? [])].filter(part => !relinked.some(item => item.part === null || item.part === undefined || item.part === part)));
+            if (relinked.some(item => item.part === null || item.part === undefined)) {
+                local.clear();
+            }
+            const parts = new Map();
+            for (const item of planned.filter(entry => entry.agentId === agent.id)) {
+                if (item.outcome === 'kept-local' || item.outcome === 'left-behind' || item.outcome === 'refused') {
+                    continue;
+                }
+                const previousLink = kept?.parts.get(item.part);
+                parts.set(item.part, {
+                    lockedFields: [...item.lockedFields],
+                    hash: item.hashAfter ?? previousLink?.hash ?? '',
+                    view: item.viewAfter ?? previousLink?.view ?? null,
+                    packageVersion: version,
+                    linkedAt: item.outcome === 'unchanged' && previousLink ? previousLink.linkedAt : now,
+                    linkedBy: item.outcome === 'unchanged' && previousLink ? previousLink.linkedBy : 'current-user'
+                });
+            }
+            this.links.set(agent.id, { packageId, packageVersion: version, parts, local });
+        }
+        for (const item of planned.filter(entry => entry.outcome === 'left-behind' && entry.part === 'agent')) {
+            this.links.delete(item.agentId);
+        }
+        this.installed.set(packageId, { version, agents: agentPackage.agents.map(agent => agent.id) });
+    }
+    /** `POST admin/agents/{id}/package/unlink`: one part, or without one the whole agent, becomes local. */
+    unlink(agentId, body) {
+        if (!this.read(agentId)) {
+            return mockFailure('assistant-agent-not-found');
+        }
+        const request = (body ?? {});
+        const part = request.part === undefined || request.part === null ? null : request.part;
+        if (part !== null && (typeof part !== 'string' || !validPartKey(part))) {
+            return mockFailure('assistant-validation', { part: ['invalid'] });
+        }
+        if (request.reason !== undefined && request.reason !== null && (typeof request.reason !== 'string' || request.reason.length > mockMaxStateReason)) {
+            return mockFailure('assistant-validation', { reason: ['invalid'] });
+        }
+        const link = this.links.get(agentId);
+        if (!link || link.parts.size === 0 || (part !== null && !link.parts.has(part))) {
+            return mockFailure('assistant-package-not-linked');
+        }
+        const unlinked = part === null ? [...link.parts.keys()] : [part];
+        for (const key of unlinked) {
+            link.parts.delete(key);
+            link.local.add(key);
+        }
+        if (part === null) {
+            link.local.add(NH_ASSISTANT_PACKAGE_LOCK_ALL);
+        }
+        return { status: 200, body: { agentId, packageId: link.packageId, parts: unlinked.sort() } };
+    }
+    /** Whether the agent still has a linked part, so it cannot be deleted or reset. */
+    isLinked(agentId) {
+        return (this.links.get(agentId)?.parts.size ?? 0) > 0;
+    }
+    /** The agent with the package it belongs to, while a part of it is linked. */
+    withAgentPackage(agent) {
+        const link = this.links.get(agent?.id);
+        if (!link || link.parts.size === 0) {
+            return agent;
+        }
+        const read = this.read(agent.id);
+        const value = {
+            packageId: link.packageId,
+            packageVersion: link.packageVersion,
+            parts: [...link.parts.keys()].sort().map(part => this.partLinkOf(agent.id, part, link, read))
+        };
+        return { ...agent, package: value };
+    }
+    /** The item with the link of its part, or as it is when the part is not linked. */
+    withLink(agentId, part, item) {
+        const link = this.links.get(agentId);
+        const value = link ? this.partLinkOf(agentId, part, link, null) : null;
+        return value ? { ...item, package: value } : item;
+    }
+    partLinkOf(agentId, part, link, read) {
+        const partLink = link.parts.get(part);
+        if (!partLink) {
+            return null;
+        }
+        const host = read ?? this.read(agentId);
+        return {
+            part,
+            packageId: link.packageId,
+            packageVersion: partLink.packageVersion,
+            lockedFields: [...partLink.lockedFields],
+            hash: partLink.hash,
+            changedLocally: host ? this.hostHash(host, part) !== partLink.hash : false,
+            linkedAt: partLink.linkedAt,
+            linkedBy: partLink.linkedBy
+        };
+    }
+    /** What the mock has of one agent, read through its own endpoints; `null` for an unknown agent. */
+    read(agentId) {
+        const agent = this.agents().find(item => item.id === agentId);
+        if (!agent) {
+            return null;
+        }
+        const path = `admin/agents/${encodeURIComponent(agentId)}`;
+        const configuration = this.context.call('GET', `${path}/configuration`);
+        const handOffs = this.context.call('GET', `${path}/hand-offs`);
+        const metadata = this.context.call('GET', `${path}/metadata`);
+        return {
+            agent,
+            configuration: configuration.status === 200 ? configuration.body : null,
+            handOffs: handOffs.status === 200 ? handOffs.body : null,
+            metadata: metadata.status === 200 ? metadata.body : []
+        };
+    }
+    agents() {
+        const result = this.context.call('GET', 'admin/agents');
+        return result.status === 200 ? result.body : [];
+    }
+    /** The SHA-256 of the canonical JSON of the host's part as a package holds it; `null` without the part. */
+    hostHash(read, part) {
+        const value = partsOf(this.packageAgentOf(read)).get(part);
+        return value === undefined ? null : mockSha256(canonicalJson(value));
+    }
+    /**
+     * What a save may not change of a part: the agent's definition as it is in effect (for an agent in
+     * code with its code's values), or the part as a package holds it.
+     */
+    lockView(agentId, part) {
+        const read = this.read(agentId);
+        if (!read) {
+            return null;
+        }
+        if (part === 'agent') {
+            return agentDefinitionOf(read.agent);
+        }
+        const value = partsOf(this.packageAgentOf(read)).get(part);
+        return value === undefined ? null : part.startsWith('metadata:') ? { value } : value;
+    }
+    /** The agent as a package holds it, without locks and hashes. */
+    packageAgentOf(read) {
+        const { agent, configuration, handOffs, metadata } = read;
+        const inCode = agent.source === 'code';
+        const definition = inCode ? this.overlayOf(agent) : agentDefinitionOf(agent);
+        const values = metadata.filter(entry => entry.source === (inCode ? 'override' : 'data'));
+        // The projections are the format's JSON; the format's types name the same properties.
+        const packageAgent = {
+            id: agent.id,
+            source: agent.source,
+            ...(definition && Object.keys(definition).length > 0 ? { definition } : {}),
+            ...(!inCode && configuration?.runSettings ? { runSettings: runSettingsOf(configuration.runSettings) } : {}),
+            ...nonEmpty('skills', (configuration?.dataSkills ?? []).map(skillOf)),
+            ...nonEmpty('triggers', (configuration?.dataTriggers ?? []).map(triggerOf)),
+            ...nonEmpty('consultations', (configuration?.dataConsultations ?? []).map(consultationOf)),
+            ...nonEmpty('handOffs', (handOffs?.dataHandOffs ?? []).map(handOff => ({
+                subjectType: handOff.subjectType,
+                sources: [...handOff.sources],
+                description: handOff.description,
+                notifySource: handOff.notifySource,
+                maxPerSubjectPerDay: handOff.maxPerSubjectPerDay
+            })))
+        };
+        if (values.length > 0) {
+            packageAgent['metadata'] = Object.fromEntries(values.map(entry => [entry.name, entry.value]));
+        }
+        if (!agent.shadowOf && (agent.groups?.length ?? 0) > 0) {
+            packageAgent['groups'] = [...agent.groups];
+        }
+        return packageAgent;
+    }
+    /** The overrides of an agent in code: the fields of its definition that differ from its code. */
+    overlayOf(agent) {
+        const code = this.context.codeDefinition(agent.id);
+        if (!code || !agent.isOverridden) {
+            return {};
+        }
+        const definition = agent;
+        const inCode = code;
+        return Object.fromEntries(codeAgentFields
+            .filter(field => !sameValue(definition[field], inCode[field]))
+            .map(field => [field, definition[field]]));
+    }
+}
+/** The part of the administration a request saves or removes, or the whole agent it deletes or resets. */
+function guardedPart(method, segments) {
+    if (segments[0] !== 'admin' || segments[1] !== 'agents' || segments[2] === undefined) {
+        return null;
+    }
+    const [, , agentId, area, id, action, child] = segments;
+    if (segments.length === 3) {
+        return method === 'PUT' ? { agentId, part: 'agent', removal: false } : method === 'DELETE' ? { agentId, part: null, removal: true } : null;
+    }
+    // A reset restores the code's definition, which the locks keep as the package has it.
+    if (area === 'reset' && segments.length === 4) {
+        return method === 'POST' ? { agentId, part: 'agent', removal: false, reset: true } : null;
+    }
+    if (area === 'run-settings' && segments.length === 4) {
+        return method === 'PUT' || method === 'DELETE' ? { agentId, part: 'runSettings', removal: method === 'DELETE' } : null;
+    }
+    const kinds = {
+        skills: 'skill',
+        triggers: 'trigger',
+        consultations: 'consultation',
+        'hand-offs': 'handOff',
+        metadata: 'metadata'
+    };
+    const kind = area === undefined ? undefined : kinds[area];
+    if (kind === undefined || id === undefined) {
+        return null;
+    }
+    const part = `${kind}:${id}`;
+    if (segments.length === 5) {
+        return method === 'PUT' || method === 'DELETE' ? { agentId, part, removal: method === 'DELETE' } : null;
+    }
+    // Promoting a candidate makes it the live version, which the locks keep as the package has it.
+    if ((kind === 'skill' || kind === 'trigger') && action === 'candidate' && child === 'promote' && segments.length === 7 && method === 'POST') {
+        return { agentId, part, removal: false };
+    }
+    return null;
+}
+/**
+ * The locked fields a save changed to something else than the package's value: promoting the
+ * candidate an import made of the package's version is no change of a locked field.
+ */
+function lockedChanges(kind, locked, before, after, packaged) {
+    const fields = locked.includes(NH_ASSISTANT_PACKAGE_LOCK_ALL) ? NH_ASSISTANT_PACKAGE_LOCK_FIELDS[kind] : locked;
+    return fields.filter(field => {
+        const properties = lockProperties[kind][field] ?? [field];
+        const changed = properties.some(property => !sameValue(before?.[property], after?.[property]));
+        const asPackaged = packaged !== null && properties.every(property => sameValue(after?.[property], packaged[property]));
+        return changed && !asPackaged;
+    });
+}
+/** Why a lock of a package agent is invalid: `not-found` for a part it does not hold, `invalid` fields. */
+function lockProblem(agent, part, fields) {
+    if (fields.length === 0) {
+        return null;
+    }
+    if (!partsOf(agent).has(part)) {
+        return 'not-found';
+    }
+    const kind = kindOf(part);
+    const allowed = kind === 'agent' && agent.source === 'code'
+        ? NH_ASSISTANT_PACKAGE_LOCK_FIELDS.agent.slice(0, codeAgentFields.length)
+        : NH_ASSISTANT_PACKAGE_LOCK_FIELDS[kind];
+    const whole = fields.length === 1 && fields[0] === NH_ASSISTANT_PACKAGE_LOCK_ALL;
+    return whole || fields.every(field => allowed.includes(field)) ? null : 'invalid';
+}
+/**
+ * Why the agent of a package may not be imported onto the host's agent with its id, or `null`: an
+ * agent of another package, an agent in code for an agent created here, or an agent created here that
+ * the package neither linked nor takes over (`relink` naming the whole agent).
+ */
+function agentRefusal(agent, host, linkedToPackage, otherPackage) {
+    if (otherPackage) {
+        return 'assistant-agent-exists';
+    }
+    if (agent.source === 'code') {
+        if (!host) {
+            return 'assistant-agent-not-found';
+        }
+        return host.source === 'code' ? null : 'assistant-agent-not-code';
+    }
+    if (host && (host.source === 'code' || !linkedToPackage)) {
+        return 'assistant-agent-exists';
+    }
+    return null;
+}
+/** The parts of a package agent by part key, in the format's order. */
+function partsOf(agent) {
+    const parts = new Map();
+    if (agent.definition) {
+        parts.set('agent', agent.definition);
+    }
+    if (agent.runSettings) {
+        parts.set('runSettings', agent.runSettings);
+    }
+    for (const skill of agent.skills ?? []) {
+        parts.set(`skill:${skill.id}`, skill);
+    }
+    for (const trigger of agent.triggers ?? []) {
+        parts.set(`trigger:${trigger.id}`, trigger);
+    }
+    for (const consultation of agent.consultations ?? []) {
+        parts.set(`consultation:${consultation.subjectType}`, consultation);
+    }
+    for (const handOff of agent.handOffs ?? []) {
+        parts.set(`handOff:${handOff.subjectType}`, handOff);
+    }
+    for (const [name, value] of Object.entries(agent.metadata ?? {})) {
+        parts.set(`metadata:${name}`, value);
+    }
+    return parts;
+}
+function kindOf(part) {
+    const colon = part.indexOf(':');
+    return (colon < 0 ? part : part.slice(0, colon));
+}
+function keyOf(part) {
+    const colon = part.indexOf(':');
+    return colon < 0 ? '' : part.slice(colon + 1);
+}
+/** Whether a part key names a known kind, with a dash-case key for the kinds that take one. */
+function validPartKey(part) {
+    if (part === 'agent' || part === 'runSettings') {
+        return true;
+    }
+    const kind = kindOf(part);
+    return ['skill', 'trigger', 'consultation', 'handOff', 'metadata'].includes(kind) && mockDashCase.test(keyOf(part));
+}
+/** The definition of an agent as a package holds an agent created here. */
+function agentDefinitionOf(agent) {
+    return {
+        displayName: agent.displayName,
+        description: agent.description,
+        instructions: agent.instructionsAsset ? null : agent.instructions,
+        instructionsAsset: agent.instructionsAsset ?? null,
+        toolSelectors: [...agent.toolSelectors],
+        requiredPolicy: agent.requiredPolicy,
+        autonomy: agent.autonomy,
+        offeredInChat: agent.offeredInChat ?? true,
+        worksOnSubjectTypes: agent.worksOnSubjectTypes ?? null,
+        worksOnAllSubjects: agent.worksOnAllSubjects ?? null,
+        worksOnApplication: agent.worksOnApplication ?? null,
+        perDivision: agent.perDivision ?? null,
+        runPolicy: agent.runPolicy ?? null,
+        viewPolicy: agent.viewPolicy ?? null,
+        profile: agent.profile ?? null,
+        dataClassification: agent.dataClassification ?? null,
+        shadowOf: agent.shadowOf ?? null
+    };
+}
+function runSettingsOf(settings) {
+    return {
+        accountability: settings.accountability,
+        delegateFromInitiator: settings.delegateFromInitiator,
+        allowGatewayReads: settings.allowGatewayReads,
+        elevatedReads: settings.elevatedReads,
+        approvalPolicy: settings.approvalPolicy,
+        retryCount: settings.retryCount,
+        dailyToolCalls: settings.dailyToolCalls,
+        dailyTokens: settings.dailyTokens,
+        maxConcurrentRuns: settings.maxConcurrentRuns,
+        maxRunsPerSubjectPerDay: settings.maxRunsPerSubjectPerDay,
+        maxTokensPerRun: settings.maxTokensPerRun,
+        triageProfile: settings.triageProfile,
+        ruleHandler: settings.ruleHandler,
+        acceptsFiles: settings.acceptsFiles ?? false,
+        maxFileBytes: settings.maxFileBytes ?? null,
+        maxFilePages: settings.maxFilePages ?? null,
+        maxFilesPerTurn: settings.maxFilesPerTurn ?? null,
+        maxFileTokensPerTurn: settings.maxFileTokensPerTurn ?? null
+    };
+}
+function skillOf(skill) {
+    return {
+        id: skill.skillId,
+        description: skill.description,
+        instructions: skill.instructionsAsset ? null : skill.instructions,
+        instructionsAsset: skill.instructionsAsset ?? null,
+        tools: [...skill.tools],
+        profile: skill.profile,
+        ruleHandler: skill.ruleHandler,
+        maxTokensPerRun: skill.maxTokensPerRun,
+        dailyToolCalls: skill.dailyToolCalls,
+        dailyTokens: skill.dailyTokens,
+        approvalPolicy: skill.approvalPolicy,
+        dataClassification: skill.dataClassification ?? null,
+        acceptsFiles: skill.acceptsFiles ?? false,
+        maxFileBytes: skill.maxFileBytes ?? null,
+        maxFilePages: skill.maxFilePages ?? null,
+        maxFilesPerTurn: skill.maxFilesPerTurn ?? null,
+        maxFileTokensPerTurn: skill.maxFileTokensPerTurn ?? null
+    };
+}
+function triggerOf(trigger) {
+    return {
+        id: trigger.triggerId,
+        source: trigger.source,
+        skill: trigger.skillId,
+        event: trigger.event,
+        filters: [...(trigger.filters ?? [])],
+        cron: trigger.cron,
+        timeZone: trigger.timeZone,
+        subjectSet: trigger.subjectSet,
+        message: trigger.message,
+        conflict: trigger.conflict,
+        debounceSeconds: trigger.debounceSeconds
+    };
+}
+function consultationOf(consultation) {
+    return {
+        subjectType: consultation.subjectType,
+        description: consultation.description,
+        instructions: consultation.instructions,
+        minimumRole: consultation.minimumRole,
+        askerPolicy: consultation.askerPolicy,
+        routes: [...consultation.routes],
+        proposalRole: consultation.proposalRole,
+        proposalPolicy: consultation.proposalPolicy,
+        toolSelectors: consultation.toolSelectors ?? null,
+        maxToolCalls: consultation.maxToolCalls,
+        timeoutSeconds: consultation.timeoutSeconds,
+        maxAnswerChars: consultation.maxAnswerChars,
+        maxHistoryMessages: consultation.maxHistoryMessages,
+        allowRequests: consultation.allowRequests,
+        exposeToMcp: consultation.exposeToMcp,
+        dataClassification: consultation.dataClassification
+    };
+}
+/** `{ [name]: items }` for a list with items, otherwise nothing, as the format leaves empty lists out. */
+function nonEmpty(name, items) {
+    return items.length > 0 ? { [name]: items } : {};
+}
+/**
+ * Reads a package strictly, as the server does: `assistant-package-too-large` above 1 MB or 20
+ * agents; `assistant-package-format-unsupported` for another format, a newer format version, an
+ * unknown property, a missing required one or an agent id given twice.
+ */
+function readPackage(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return mockFailure('assistant-package-format-unsupported');
+    }
+    if (new TextEncoder().encode(JSON.stringify(value)).length > NH_ASSISTANT_AGENT_PACKAGE_MAX_BYTES) {
+        return mockFailure('assistant-package-too-large');
+    }
+    const root = value;
+    if (root['format'] !== NH_ASSISTANT_AGENT_PACKAGE_FORMAT
+        || typeof root['formatVersion'] !== 'number'
+        || !Number.isInteger(root['formatVersion'])
+        || root['formatVersion'] < 1
+        || root['formatVersion'] > NH_ASSISTANT_AGENT_PACKAGE_FORMAT_VERSION) {
+        return mockFailure('assistant-package-format-unsupported');
+    }
+    const agents = root['agents'];
+    if (!fits(root, 'root') || !fits(root['package'], 'package') || !Array.isArray(agents)) {
+        return mockFailure('assistant-package-format-unsupported');
+    }
+    if (agents.length > NH_ASSISTANT_AGENT_PACKAGE_MAX_AGENTS) {
+        return mockFailure('assistant-package-too-large');
+    }
+    const info = root['package'];
+    const ids = new Set();
+    for (const item of agents) {
+        if (!fitsAgent(item)) {
+            return mockFailure('assistant-package-format-unsupported');
+        }
+        const id = item['id'];
+        if (ids.has(id)) {
+            return mockFailure('assistant-package-format-unsupported');
+        }
+        ids.add(id);
+    }
+    if (agents.length === 0) {
+        return mockFailure('assistant-package-format-unsupported');
+    }
+    const errors = {};
+    if (typeof info['id'] !== 'string' || !mockDashCase.test(info['id']) || info['id'].length > maxPackageId) {
+        errors['package.id'] = ['invalid'];
+    }
+    if (typeof info['version'] !== 'number' || !Number.isInteger(info['version']) || info['version'] < 1) {
+        errors['package.version'] = ['invalid'];
+    }
+    if (info['description'] !== undefined && info['description'] !== null
+        && (typeof info['description'] !== 'string' || info['description'].length > maxPackageDescription)) {
+        errors['package.description'] = ['too-long'];
+    }
+    return Object.keys(errors).length > 0 ? mockFailure('assistant-validation', errors) : { package: structuredClone(value) };
+}
+function fitsAgent(value) {
+    if (!fits(value, 'agent')) {
+        return false;
+    }
+    const agent = value;
+    if (typeof agent['id'] !== 'string' || (agent['source'] !== 'admin' && agent['source'] !== 'code')) {
+        return false;
+    }
+    if (agent['source'] === 'admin' && (agent['definition'] === undefined || agent['definition'] === null)) {
+        return false;
+    }
+    const definition = agent['definition'];
+    if (definition !== undefined && definition !== null
+        && (!fits(definition, 'definition') || (definition['instructionsAsset'] && !fits(definition['instructionsAsset'], 'instructionsAsset')))) {
+        return false;
+    }
+    if (agent['runSettings'] !== undefined && agent['runSettings'] !== null && !fits(agent['runSettings'], 'runSettings')) {
+        return false;
+    }
+    const lists = [['skills', 'skill'], ['triggers', 'trigger'], ['consultations', 'consultation'], ['handOffs', 'handOff']];
+    for (const [list, shape] of lists) {
+        const items = agent[list];
+        if (items !== undefined && items !== null && (!Array.isArray(items) || !items.every(item => fits(item, shape)))) {
+            return false;
+        }
+    }
+    for (const map of ['metadata', 'locks', 'hashes']) {
+        const item = agent[map];
+        if (item !== undefined && item !== null && (typeof item !== 'object' || Array.isArray(item))) {
+            return false;
+        }
+    }
+    const groups = agent['groups'];
+    return groups === undefined || groups === null || (Array.isArray(groups) && groups.every(group => typeof group === 'string'));
+}
+/** Whether an object has every required property of its shape and none it does not know. */
+function fits(value, shape) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    const { required, optional } = formatShapes[shape];
+    const record = value;
+    return required.every(name => record[name] !== undefined && record[name] !== null)
+        && Object.keys(record).every(name => required.includes(name) || optional.includes(name));
+}
+function base(agentId, part, lockedFields) {
+    return {
+        agentId,
+        part,
+        outcome: 'unchanged',
+        changedLocally: false,
+        code: null,
+        errors: null,
+        lockedFields: [...lockedFields],
+        candidateVersion: null,
+        hashAfter: null,
+        viewAfter: null
+    };
+}
+function leftBehind(agentId, part) {
+    return { ...base(agentId, part, []), outcome: 'left-behind' };
+}
+/** A refused part with the endpoint's field errors, or its code without them. */
+function refusalOf(agentId, part, result, lockedFields) {
+    const body = (result.body ?? {});
+    const errors = body.errors && Object.keys(body.errors).length > 0 ? body.errors : null;
+    return {
+        ...base(agentId, part, lockedFields),
+        outcome: 'refused',
+        code: errors ? null : body.code ?? 'assistant-validation',
+        errors
+    };
+}
+/**
+ * The field errors of `assistant-package-refused`, as the server answers them: one plain field, since
+ * the preview's part outcomes say why each part was refused.
+ */
+const refusedErrors = { parts: ['invalid'] };
+function publicPart({ hashAfter: _, viewAfter: __, ...part }) {
+    return part;
+}
+/** A trimmed text, or `null` for none. */
+function text(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+/** Whether two values are the same as a package holds them: `null` and missing alike. */
+function sameValue(left, right) {
+    return canonicalJson(left ?? null) === canonicalJson(right ?? null);
+}
+/** A copy of a value without `null` and `undefined` properties, as the format writes it. */
+function withoutNulls(value) {
+    if (Array.isArray(value)) {
+        return value.map(item => withoutNulls(item));
+    }
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value)
+            .filter(([, item]) => item !== null && item !== undefined)
+            .map(([key, item]) => [key, withoutNulls(item)]));
+    }
+    return value;
+}
+/**
+ * The canonical JSON of a value, as the format hashes a part: object properties ordered by name
+ * (ordinal), properties with a `null` value left out, no white space.
+ */
+function canonicalJson(value) {
+    if (value === null || value === undefined) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(item => canonicalJson(item)).join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, item]) => item !== null && item !== undefined)
+            .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0));
+        return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+const sha256Constants = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2
+]);
+/**
+ * The SHA-256 of the UTF-8 bytes of a text, lowercase hex, computed synchronously so an import can
+ * hash its parts between two of its writes.
+ */
+function mockSha256(input) {
+    const bytes = new TextEncoder().encode(input);
+    const length = ((bytes.length + 9 + 63) >> 6) << 6;
+    const data = new Uint8Array(length);
+    data.set(bytes);
+    data[bytes.length] = 0x80;
+    const view = new DataView(data.buffer);
+    view.setUint32(length - 8, Math.floor(bytes.length / 0x20000000));
+    view.setUint32(length - 4, (bytes.length << 3) >>> 0);
+    const hash = new Uint32Array([0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19]);
+    const words = new Uint32Array(64);
+    const rotate = (value, bits) => (value >>> bits) | (value << (32 - bits));
+    for (let offset = 0; offset < length; offset += 64) {
+        for (let index = 0; index < 16; index++) {
+            words[index] = view.getUint32(offset + index * 4);
+        }
+        for (let index = 16; index < 64; index++) {
+            const low = words[index - 15];
+            const high = words[index - 2];
+            const s0 = rotate(low, 7) ^ rotate(low, 18) ^ (low >>> 3);
+            const s1 = rotate(high, 17) ^ rotate(high, 19) ^ (high >>> 10);
+            words[index] = (words[index - 16] + s0 + words[index - 7] + s1) >>> 0;
+        }
+        let [a, b, c, d, e, f, g, h] = hash;
+        for (let index = 0; index < 64; index++) {
+            const s1 = rotate(e, 6) ^ rotate(e, 11) ^ rotate(e, 25);
+            const choice = (e & f) ^ (~e & g);
+            const first = (h + s1 + choice + sha256Constants[index] + words[index]) >>> 0;
+            const s0 = rotate(a, 2) ^ rotate(a, 13) ^ rotate(a, 22);
+            const majority = (a & b) ^ (a & c) ^ (b & c);
+            const second = (s0 + majority) >>> 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + first) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (first + second) >>> 0;
+        }
+        hash[0] = (hash[0] + a) >>> 0;
+        hash[1] = (hash[1] + b) >>> 0;
+        hash[2] = (hash[2] + c) >>> 0;
+        hash[3] = (hash[3] + d) >>> 0;
+        hash[4] = (hash[4] + e) >>> 0;
+        hash[5] = (hash[5] + f) >>> 0;
+        hash[6] = (hash[6] + g) >>> 0;
+        hash[7] = (hash[7] + h) >>> 0;
+    }
+    return [...hash].map(word => word.toString(16).padStart(8, '0')).join('');
+}
+
 /** The longest file name a reference takes, as on the server. */
 const maxNameLength = 256;
 const mediaTypePattern = /^[a-z0-9][a-z0-9!#$&^_.+-]*\/[a-z0-9][a-z0-9!#$&^_.+-]*$/;
@@ -3777,7 +5927,7 @@ const binarySignatures = [
 ];
 /** How files of the platform's types start; other accepted types are the application's to check. */
 const signatures = {
-    'application/pdf': head => indexOf(head, [0x25, 0x50, 0x44, 0x46, 0x2d]) >= 0,
+    'application/pdf': head => indexOf$1(head, [0x25, 0x50, 0x44, 0x46, 0x2d]) >= 0,
     'image/png': head => startsWith(head, pngSignature),
     'image/jpeg': head => startsWith(head, jpegSignature),
     'application/vnd.openxmlformats-officedocument.wordprocessingml.document': head => startsWith(head, zipSignature),
@@ -3936,7 +6086,7 @@ function refusalCode(code) {
 function startsWith(head, signature) {
     return head.length >= signature.length && signature.every((byte, index) => head[index] === byte);
 }
-function indexOf(head, signature) {
+function indexOf$1(head, signature) {
     for (let start = 0; start + signature.length <= head.length; start++) {
         if (signature.every((byte, index) => head[start + index] === byte)) {
             return start;
@@ -3945,7 +6095,7 @@ function indexOf(head, signature) {
     return -1;
 }
 
-const dashCase$3 = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const dashCase$4 = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const minQueryLength = 2;
 const maxQueryLength = 100;
 const defaultLimit = 20;
@@ -3972,7 +6122,7 @@ class NhAssistantMockSubjects {
         this.openProposals = openProposals;
         const ids = new Set();
         for (const type of types) {
-            if (!dashCase$3.test(type.id) || type.id.length > 100) {
+            if (!dashCase$4.test(type.id) || type.id.length > 100) {
                 throw new Error(`Mock subject type '${type.id}' is not a dash-case id of at most 100 characters.`);
             }
             if (type.id.startsWith('nh-')) {
@@ -4128,7 +6278,7 @@ class NhAssistantMockSubjects {
      * subject not found.
      */
     work(typeId, subjectId, language) {
-        if (!dashCase$3.test(typeId) || typeId.length > 100 || subjectId.trim().length === 0 || subjectId.length > 200 || subjectId.trim() !== subjectId) {
+        if (!dashCase$4.test(typeId) || typeId.length > 100 || subjectId.trim().length === 0 || subjectId.length > 200 || subjectId.trim() !== subjectId) {
             return mockFailure('assistant-subject-invalid');
         }
         if (typeId === systemType$1) {
@@ -4245,7 +6395,7 @@ function isValidLinkTemplate(template) {
     return pathStart > 0 && template.indexOf(placeholder) > pathStart;
 }
 
-const dashCase$2 = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const dashCase$3 = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const maxMessage = 8_000;
 const maxSubjectId = 200;
 const maxAgentId = 128;
@@ -4963,7 +7113,7 @@ function key(agentId, subject) {
     return `${agentId}|${subject.subjectType}|${subject.subjectId}`;
 }
 function validSubject(type, id) {
-    return dashCase$2.test(type) && type.length <= 100 && id.trim().length > 0 && id.length <= maxSubjectId && id.trim() === id;
+    return dashCase$3.test(type) && type.length <= 100 && id.trim().length > 0 && id.length <= maxSubjectId && id.trim() === id;
 }
 /** The type the agent works on, and for the whole application its scope: app-wide or per division. */
 function worksOn(agent, subject) {
@@ -5033,7 +7183,7 @@ function readFilter(query, withAgent) {
         errors['agentId'] = ['invalid'];
     }
     const subjectType = query.get('subjectType');
-    if (subjectType !== null && (!dashCase$2.test(subjectType) || subjectType.length > 100)) {
+    if (subjectType !== null && (!dashCase$3.test(subjectType) || subjectType.length > 100)) {
         errors['subjectType'] = ['invalid'];
     }
     const subjectId = query.get('subjectId');
@@ -5063,7 +7213,7 @@ function readFilter(query, withAgent) {
     return { filter: { agentId, subjectType, subjectId, status, from, to, page, itemsPerPage } };
 }
 
-const dashCase$1 = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const dashCase$2 = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const language = /^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$/;
 const maxGroupId = 64;
 const maxGroups = 100;
@@ -5125,6 +7275,13 @@ class NhAssistantMockBoards {
         }
         return { agentId, groups: [...groups].sort(), codeGroups };
     }
+    /**
+     * A copy of the administrators' group choices; the returned function puts it back, for an import
+     * of an agent package that fails as a whole and for its preview.
+     */
+    snapshot() {
+        return mockSnapshot(this.choices);
+    }
     /** Forgets the choices about an agent that was deleted. */
     forget(agentId) {
         this.choices.delete(agentId);
@@ -5307,7 +7464,7 @@ function validate(groups) {
     }
     const seen = new Set();
     for (const group of groups) {
-        if (!dashCase$1.test(group.id) || group.id.length > maxGroupId) {
+        if (!dashCase$2.test(group.id) || group.id.length > maxGroupId) {
             throw new Error(`The mock agent group '${group.id}' is not a dash-case id of at most ${maxGroupId} characters.`);
         }
         if (seen.has(group.id)) {
@@ -5333,6 +7490,222 @@ function checkTexts(groupId, kind, texts, fallback, max) {
     }
 }
 
+const defaultMaxBytes = 4_096;
+const dashCase$1 = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/**
+ * Agent metadata of the mock API (MD1 to MD3), as the server serves it: `admin.agentMetadata` of the
+ * scenario are the entries registered in code, and `metadata` of each scenario agent its values, in
+ * code for an agent in code and stored at the first version for an agent created as data.
+ * `GET admin/agents/{id}/metadata`, `PUT` and `DELETE admin/agents/{id}/metadata/{name}` answer with
+ * the server's checks: an entry of an agent created here makes the agent's next version, an editable
+ * entry of an agent in code is an override with a version of its own, and a read-only one is refused.
+ * Values of `POST` and `PUT admin/agents` are not taken: the agent editor saves each entry through its
+ * slot. Values live as long as the mock.
+ */
+class NhAssistantMockAgentMetadata {
+    constructor(scenario, context, now) {
+        this.context = context;
+        this.now = now;
+        /** The values in code, by agent and entry. */
+        this.code = new Map();
+        /** The stored values, by agent and entry. */
+        this.stored = new Map();
+        this.entries = [...(scenario.admin?.agentMetadata ?? [])].sort((left, right) => left.name.localeCompare(right.name));
+        for (const entry of this.entries) {
+            if (!dashCase$1.test(entry.name) || entry.name.length > 64 || entry.name.startsWith('nh-')) {
+                throw new Error(`The mock's agent metadata entry '${entry.name}' is not a valid name.`);
+            }
+        }
+        for (const agent of scenario.admin?.agents ?? []) {
+            for (const [name, value] of Object.entries(agent.metadata ?? {})) {
+                const entry = this.entries.find(item => item.name === name);
+                // Startup refuses a value that a save would refuse.
+                const problems = entry ? this.problemsOf(entry, value) : { '': ['not-found'] };
+                if (!entry || Object.keys(problems).length > 0) {
+                    throw new Error(`The mock agent '${agent.id}' sets metadata '${name}' that the entries refuse.`);
+                }
+                if (agent.source === 'code') {
+                    this.valuesOf(this.code, agent.id).set(name, structuredClone(value));
+                }
+                else {
+                    this.valuesOf(this.stored, agent.id).set(name, {
+                        value: structuredClone(value),
+                        version: 1,
+                        changedAt: this.now(),
+                        changedBy: 'current-user'
+                    });
+                }
+            }
+        }
+    }
+    /** The run catalog's `agentMetadata`. */
+    catalog() {
+        return this.entries.map(entry => ({
+            name: entry.name,
+            editable: entry.editable === true,
+            maxBytes: entry.maxBytes ?? defaultMaxBytes,
+            indexed: entry.indexBy !== undefined
+        }));
+    }
+    /**
+     * A copy of the stored values; the returned function puts it back, for an import of an agent
+     * package that fails as a whole and for its preview.
+     */
+    snapshot() {
+        return mockSnapshot(this.stored);
+    }
+    /** Forgets the values of an agent that was deleted, as the server removes them with it. */
+    forget(agentId) {
+        this.stored.delete(agentId);
+    }
+    /** `GET admin/agents/{id}/metadata`, `PUT` and `DELETE admin/agents/{id}/metadata/{name}`. */
+    handle(method, agentId, name, query, body) {
+        if (!this.context.administers()) {
+            return mockFailure('assistant-forbidden');
+        }
+        if (name === undefined) {
+            if (method !== 'GET') {
+                return { status: 405 };
+            }
+            const agent = this.context.agent(agentId);
+            return agent
+                ? { status: 200, body: this.entries.map(entry => this.view(agent, entry)) }
+                : mockFailure('assistant-agent-not-found');
+        }
+        if (method !== 'PUT' && method !== 'DELETE') {
+            return { status: 405 };
+        }
+        const entry = this.entries.find(item => item.name === name);
+        if (!entry) {
+            return mockFailure('assistant-metadata-entry-not-found');
+        }
+        const agent = this.context.agent(agentId);
+        if (!agent) {
+            return mockFailure('assistant-agent-not-found');
+        }
+        if (agent.source === 'code' && entry.editable !== true) {
+            return mockFailure('assistant-metadata-read-only');
+        }
+        return method === 'PUT'
+            ? this.save(agent, entry, body)
+            : this.remove(agent, entry, query.get('expectedVersion'));
+    }
+    save(agent, entry, request) {
+        if (!request || typeof request !== 'object') {
+            return mockFailure('assistant-validation');
+        }
+        const errors = {};
+        for (const [field, codes] of Object.entries(this.problemsOf(entry, request.value))) {
+            errors[field === '' ? 'value' : `value.${field}`] = codes;
+        }
+        const expectedVersion = typeof request.expectedVersion === 'number' ? request.expectedVersion : null;
+        if (agent.source !== 'code' && expectedVersion === null) {
+            errors['expectedVersion'] = ['required'];
+        }
+        if (Object.keys(errors).length > 0) {
+            return mockFailure('assistant-validation', errors);
+        }
+        const values = this.valuesOf(this.stored, agent.id);
+        const current = values.get(entry.name);
+        let version;
+        if (agent.source === 'code') {
+            if (expectedVersion !== (current?.version ?? null)) {
+                return mockFailure('assistant-version-conflict');
+            }
+            version = (current?.version ?? 0) + 1;
+        }
+        else {
+            if (expectedVersion !== agent.version) {
+                return mockFailure('assistant-version-conflict');
+            }
+            version = this.context.nextVersion(agent.id).version;
+        }
+        values.set(entry.name, { value: structuredClone(request.value), version, changedAt: this.now(), changedBy: 'current-user' });
+        return { status: 200, body: this.view(this.context.agent(agent.id), entry) };
+    }
+    remove(agent, entry, expected) {
+        const values = this.valuesOf(this.stored, agent.id);
+        const current = values.get(entry.name);
+        if (!current) {
+            return { status: 200, body: this.view(agent, entry) };
+        }
+        if (expected === null || !/^\d+$/.test(expected)) {
+            return mockFailure('assistant-validation', { expectedVersion: ['required'] });
+        }
+        const expectedVersion = Number(expected);
+        if (expectedVersion !== (agent.source === 'code' ? current.version : agent.version)) {
+            return mockFailure('assistant-version-conflict');
+        }
+        if (agent.source !== 'code') {
+            this.context.nextVersion(agent.id);
+        }
+        values.delete(entry.name);
+        return { status: 200, body: this.view(this.context.agent(agent.id), entry) };
+    }
+    /** The entry of the agent in effect, as `GET admin/agents/{id}/metadata` lists it. */
+    view(agent, entry) {
+        const stored = this.stored.get(agent.id)?.get(entry.name);
+        const code = this.code.get(agent.id)?.get(entry.name);
+        const inCode = agent.source === 'code';
+        const value = stored?.value ?? (inCode ? code : undefined);
+        const source = stored
+            ? (inCode ? 'override' : 'data')
+            : (inCode && code !== undefined ? 'code' : null);
+        return {
+            name: entry.name,
+            editable: !inCode || entry.editable === true,
+            maxBytes: entry.maxBytes ?? defaultMaxBytes,
+            source,
+            value: value === undefined ? null : structuredClone(value),
+            version: inCode ? stored?.version ?? null : agent.version,
+            agentVersion: agent.version,
+            codeValue: inCode && code !== undefined ? structuredClone(code) : null,
+            indexed: entry.indexBy !== undefined,
+            indexValue: value !== undefined ? indexOf(entry, value) : null,
+            changedAt: stored?.changedAt ?? null,
+            changedBy: stored?.changedBy ?? null
+        };
+    }
+    /** The problems of a value, by field path, `''` for the whole value, as the server checks it. */
+    problemsOf(entry, value) {
+        if (value === null || value === undefined) {
+            return { '': ['required'] };
+        }
+        if (typeof value !== 'object' || Array.isArray(value)
+            || (entry.fields && Object.keys(value).some(field => !entry.fields.includes(field)))) {
+            return { '': ['invalid'] };
+        }
+        if (new TextEncoder().encode(JSON.stringify(value)).length > (entry.maxBytes ?? defaultMaxBytes)) {
+            return { '': ['too-long'] };
+        }
+        const problems = { ...(entry.validate?.(value) ?? {}) };
+        const index = indexOf(entry, value);
+        if (index !== null && index.length > 256) {
+            problems[''] = [...(problems[''] ?? []), 'too-long'];
+        }
+        return Object.fromEntries(Object.entries(problems).filter(([, codes]) => codes.length > 0));
+    }
+    valuesOf(map, agentId) {
+        let values = map.get(agentId);
+        if (!values) {
+            values = new Map();
+            map.set(agentId, values);
+        }
+        return values;
+    }
+}
+/** The searchable value of a value, trimmed and in lowercase, as the server stores it. */
+function indexOf(entry, value) {
+    if (entry.indexBy === undefined) {
+        return null;
+    }
+    const text = value[entry.indexBy];
+    const trimmed = typeof text === 'string' ? text.trim() : '';
+    return trimmed.length > 0 ? trimmed.toLowerCase() : null;
+}
+
+/** How long the application may take to report after a hand-off in the mock. */
+const reportWithinMs = 4 * 60 * 60 * 1000;
 const dashCase = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const maxReason = 500;
 const maxItemsPerPage = 100;
@@ -5357,7 +7730,10 @@ const fourEyesCode = 'assistant-four-eyes-required';
  * answers `404` and deciding it `404 assistant-approval-not-found`. A consultation's proposal that the
  * person who asked decides in their own chat (`asker-decides`) waits inline and is refused here with
  * `assistant-consult-asker-decides`; one that runs with the agent's own rights refuses its asker with
- * `assistant-four-eyes-required`.
+ * `assistant-four-eyes-required`. A proposal of a tool the application executes (`executedByApplication`)
+ * waits as `awaiting-application` once approved, and `POST approvals/{id}/resolve` resolves an
+ * `execution-unknown` proposal as the server does: `hand-to-application` for one the application
+ * executes, `re-execute` for any other, `mark-resolved` for both.
  */
 class NhAssistantMockProposals {
     constructor(scenario = [], actorId, now, mayDecideApplication = () => true, decided = () => undefined, mayWorkIn = () => true) {
@@ -5383,6 +7759,9 @@ class NhAssistantMockProposals {
             const route = item.consultationRoute ?? null;
             const refusal = consultationRefusal(route, item.initiatorActorId ?? null, actorId());
             const canDecide = item.canDecide ?? refusal === null;
+            const executedByApplication = item.executedByApplication ?? false;
+            const handedOff = executedByApplication && (item.status === 'awaiting-application' || item.status === 'execution-unknown');
+            const madeAt = item.createdAt ?? new Date(created).toISOString();
             this.proposals.set(item.approvalId, {
                 proposal: {
                     approvalId: item.approvalId,
@@ -5410,8 +7789,11 @@ class NhAssistantMockProposals {
                     initiatorActorId: item.initiatorActorId ?? null,
                     decidedByActorId: null,
                     decidedAt: null,
-                    executionResultCode: null,
+                    executionResultCode: item.executionResultCode ?? null,
                     executedAt: null,
+                    executionReportDueAt: handedOff
+                        ? item.executionReportDueAt ?? new Date(Date.parse(madeAt) + reportWithinMs).toISOString()
+                        : null,
                     rationale: item.rationale ?? null,
                     placedBy: item.placedBy ?? null,
                     parent: item.parent ?? null,
@@ -5421,7 +7803,8 @@ class NhAssistantMockProposals {
                 },
                 divisionId: item.divisionId ?? null,
                 canDecide,
-                reasonCode: canDecide ? null : item.reasonCode ?? refusal ?? 'assistant-approval-policy-denied'
+                reasonCode: canDecide ? null : item.reasonCode ?? refusal ?? 'assistant-approval-policy-denied',
+                executedByApplication
             });
         }
     }
@@ -5445,6 +7828,9 @@ class NhAssistantMockProposals {
         if (segments.length === 3 && segments[2] === 'decisions') {
             return method === 'POST' ? this.decideOne(segments[1], body) : { status: 405 };
         }
+        if (segments.length === 3 && segments[2] === 'resolve') {
+            return method === 'POST' ? this.resolve(segments[1], body) : { status: 405 };
+        }
         return null;
     }
     /** The proposals waiting in a thread, newest first; `null` when the scenario lists none there. */
@@ -5616,16 +8002,59 @@ class NhAssistantMockProposals {
             return { code: stored.reasonCode ?? 'assistant-approval-policy-denied' };
         }
         const now = this.now();
+        // A proposal the application executes is handed to it and waits for its report.
+        const handedOff = approve && stored.executedByApplication;
         stored.proposal = {
             ...stored.proposal,
-            status: approve ? 'executed' : 'rejected',
+            status: approve ? (handedOff ? 'awaiting-application' : 'executed') : 'rejected',
             decidedByActorId: this.actorId(),
             decidedAt: now,
-            executedAt: approve ? now : null
+            executedAt: approve && !handedOff ? now : null,
+            executionReportDueAt: handedOff ? new Date(Date.parse(now) + reportWithinMs).toISOString() : null
         };
         this.decided(stored.proposal);
         return { code: null };
     }
+    /**
+     * `POST approvals/{id}/resolve` as the server answers it: only an `execution-unknown` proposal, which
+     * a proposal the application executes resolves with `hand-to-application` or `mark-resolved` and
+     * every other one with `re-execute` or `mark-resolved`. Handed to the application again, it waits
+     * for its report once more; run again, it executes at once.
+     */
+    resolve(approvalId, body) {
+        const request = body;
+        const action = request?.action;
+        if (action !== 're-execute' && action !== 'hand-to-application' && action !== 'mark-resolved') {
+            return mockFailure('assistant-approval-decision-invalid');
+        }
+        const stored = this.find(approvalId);
+        if (!stored) {
+            return mockFailure('assistant-approval-not-found');
+        }
+        if (stored.proposal.status !== 'execution-unknown') {
+            return mockFailure('assistant-execution-not-uncertain');
+        }
+        if (!stored.canDecide) {
+            return mockFailure(stored.reasonCode ?? 'assistant-approval-policy-denied');
+        }
+        const handedOff = !!stored.proposal.executionReportDueAt;
+        if ((action === 'hand-to-application' && !handedOff) || (action === 're-execute' && handedOff)) {
+            return mockFailure('assistant-approval-decision-invalid');
+        }
+        const now = this.now();
+        stored.proposal = {
+            ...stored.proposal,
+            status: action === 'mark-resolved' ? 'resolved' : action === 'hand-to-application' ? 'awaiting-application' : 'executed',
+            decidedByActorId: this.actorId(),
+            executedAt: action === 're-execute' ? now : stored.proposal.executedAt,
+            executionResultCode: action === 'mark-resolved' ? 'resolved-by-approver' : null,
+            executionReportDueAt: action === 'hand-to-application'
+                ? new Date(Date.parse(now) + reportWithinMs).toISOString()
+                : stored.proposal.executionReportDueAt
+        };
+        this.decided(stored.proposal);
+        return { status: 200, body: stored.proposal };
+    }
     withRight(item) {
         const pending = item.proposal.status === 'pending';
         return {
@@ -5822,6 +8251,25 @@ class NhAssistantMockBackend {
             agents: () => this.admin.allAgents(),
             administers: () => this.admin.administers
         }, () => new Date().toISOString());
+        this.agentMetadata = new NhAssistantMockAgentMetadata(this.scenario, {
+            agent: agentId => this.admin.findAgent(agentId),
+            administers: () => this.admin.administers,
+            nextVersion: agentId => this.admin.nextAgentVersion(agentId)
+        }, () => new Date().toISOString());
+        /** Agent packages: their endpoints, and the locks and links of every other administration request. */
+        this.agentPackages = new NhAssistantMockAgentPackages({
+            call: (method, path, body) => this.adminCall(method, path, body),
+            codeDefinition: agentId => this.admin.codeDefinition(agentId),
+            snapshot: () => {
+                const restores = [this.admin.snapshot(), this.agentMetadata.snapshot(), this.boards.snapshot()];
+                return () => {
+                    for (const restore of restores) {
+                        restore();
+                    }
+                };
+            },
+            now: () => new Date().toISOString()
+        });
         this.canAdministerState = signal(this.admin.administers, ...(ngDevMode ? [{ debugName: "canAdministerState" }] : []));
         this.members = new Map();
         this.readPositions = new Map();
@@ -5896,6 +8344,8 @@ class NhAssistantMockBackend {
             this.conversations.set(copy.id, copy);
             this.readPositions.set(copy.id, lastSequence(copy));
         }
+        // The packages the host imported before, once its agents and run configurations are in place.
+        this.agentPackages.importPresets(this.scenario.admin?.agentPackages ?? []);
     }
     /**
      * Plays a scripted turn as another person in the conversation, as if a colleague with an
@@ -5990,6 +8440,17 @@ class NhAssistantMockBackend {
     setMcpConnectionStatus(serverId, status) {
         this.admin.setMcpConnectionStatus(serverId, status);
     }
+    /**
+     * 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) {
+        this.admin.instructionAssets.setAsset(asset);
+    }
+    /** Removes one version of a text asset; what names it reports `asset-missing`. */
+    removeInstructionAsset(assetId, version) {
+        this.admin.instructionAssets.removeAsset(assetId, version);
+    }
     /** The files people uploaded, oldest first, as the application's file source stored them. */
     get uploads() {
         return this.files.uploads;
@@ -6032,23 +8493,15 @@ class NhAssistantMockBackend {
         if (segments[0] === 'admin' && segments[1] === 'agents' && segments[3] === 'runs' && segments.length === 4) {
             return this.result(this.agentRuns.handleAgentRuns(method, segments[2], query, language));
         }
-        if (segments[0] === 'admin' && segments[1] === 'agents' && segments[3] === 'groups' && segments.length === 4) {
-            return this.result(this.boards.handleAdminGroups(method, segments[2], body));
-        }
         if (segments[0] === 'admin') {
-            const result = this.admin.handleAdmin(method, segments, body, query);
-            if (method === 'DELETE' && segments[1] === 'agents' && segments.length === 3 && result.status === 204) {
-                this.boards.forget(segments[2]);
-            }
-            // The run catalog lists the subject types and the groups in the request's language, as the
-            // server does; agents carry their groups.
-            if (method === 'GET' && segments.length === 2 && segments[1] === 'run-catalog' && result.status === 200) {
-                return this.result({
-                    ...result,
-                    body: { ...result.body, subjectTypes: this.subjects.catalog(language), agentGroups: this.boards.catalog(language) }
-                });
+            // Agent packages have endpoints of their own; every other save runs under their locks, and
+            // every read of the administration carries the links of the parts.
+            const packaged = this.agentPackages.handle(method, segments, body);
+            if (packaged) {
+                return this.result(packaged);
             }
-            return this.result(segments[1] === 'agents' && result.status >= 200 && result.status < 300 ? this.withGroups(result) : result);
+            const result = this.agentPackages.guard(method, segments, () => this.adminResult(method, segments, query, body, language));
+            return this.result(this.agentPackages.decorate(method, segments, result));
         }
         if (segments[0] === 'boards') {
             return this.result(this.boards.handle(method, segments, query, language) ?? { status: 404 });
@@ -6690,6 +9143,44 @@ class NhAssistantMockBackend {
         const suffix = this.sequence.toString(16).padStart(12, '0');
         return `00000000-0000-4000-8000-${suffix}`;
     }
+    /**
+     * 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.
+     */
+    adminResult(method, segments, query, body, language) {
+        if (segments[1] === 'agents' && segments[3] === 'groups' && segments.length === 4) {
+            return this.boards.handleAdminGroups(method, segments[2], body);
+        }
+        if (segments[1] === 'agents' && segments[3] === 'metadata' && segments.length <= 5) {
+            return this.agentMetadata.handle(method, segments[2], segments[4], query, body);
+        }
+        const result = this.admin.handleAdmin(method, segments, body, query);
+        if (method === 'DELETE' && segments[1] === 'agents' && segments.length === 3 && result.status === 204) {
+            this.boards.forget(segments[2]);
+            this.agentMetadata.forget(segments[2]);
+            this.agentPackages.forget(segments[2]);
+        }
+        // The run catalog lists the subject types and the groups in the request's language, as the
+        // server does; agents carry their groups.
+        if (method === 'GET' && segments.length === 2 && segments[1] === 'run-catalog' && result.status === 200) {
+            return {
+                ...result,
+                body: {
+                    ...result.body,
+                    subjectTypes: this.subjects.catalog(language),
+                    agentGroups: this.boards.catalog(language),
+                    agentMetadata: this.agentMetadata.catalog()
+                }
+            };
+        }
+        return segments[1] === 'agents' && result.status >= 200 && result.status < 300 ? this.withGroups(result) : result;
+    }
+    /** An administration request of the agent packages, as `adminResult` answers it, for a path with its query. */
+    adminCall(method, path, body) {
+        const url = new URL(path, 'http://mock.local/');
+        const segments = url.pathname.slice(1).split('/').map(segment => decodeURIComponent(segment));
+        return this.adminResult(method, segments, url.searchParams, body, null);
+    }
     /** An administration answer about agents with each agent's groups, as the server answers it. */
     withGroups(result) {
         const enrich = (item) => {
@@ -6705,6 +9196,9 @@ class NhAssistantMockBackend {
         return { groups: membership.groups, codeGroups: membership.codeGroups };
     }
     result(result) {
+        if (result.text !== undefined) {
+            return new Response(result.text, { status: result.status, headers: { 'content-type': 'application/json', ...result.headers } });
+        }
         return result.body === undefined ? this.empty(result.status) : this.json(result.status, result.body);
     }
     json(status, value) {