@1mcp/agent 0.35.0-beta.4 → 0.36.0

package/build/transport/http/routes/adminRoutes.js

@@ -6,6 +6,7 @@ import { MCP_PROJECT_METADATA } from '../../../constants.js';
 import { parseTemplateConnectionKey } from '../../../core/server/templateIdentity.js';
 import { AdminConfiguredServerApplyError, AdminConfiguredServerNotFoundError, } from '../../../domains/admin/adminConfiguredServerService.js';
 import { ADMIN_SESSION_COOKIE_NAME, AdminIdentityError, } from '../../../domains/admin/adminIdentityService.js';
+import { AdminInstructionTemplateNotFoundError, } from '../../../domains/admin/adminInstructionTemplateService.js';
 import { AdminPresetConflictError, AdminPresetNotFoundError, } from '../../../domains/admin/adminPresetService.js';
 import { sensitiveOperationLimiter } from '../../../transport/http/middlewares/securityMiddleware.js';
 import { sanitizeErrorMessage } from '../../../utils/validation/sanitization.js';
@@ -40,6 +41,8 @@ const adminOAuthServiceParamsSchema = z.object({
 const backendLogSnapshotQuerySchema = z.object({
     sourceId: z.string().trim().min(1).max(256).optional(),
 });
+const configuredServerModelSchema = z.string().trim().min(1).max(64);
+const configuredToolInventoryRefreshSchema = z.object({ model: configuredServerModelSchema.optional() }).strict();
 const cliConfiguredServerMutationBodySchema = z.object({
     targetName: z.string().trim().min(1).max(256),
     dryRun: z.boolean().optional(),
@@ -53,6 +56,67 @@ const cliBackendRestartBodySchema = z
     .refine((value) => !(value.instance !== undefined && value.allInstances === true), {
     message: 'instance and allInstances are mutually exclusive',
 });
+const instructionTemplateIdentitySchema = z.string().trim().min(1).max(128);
+const instructionTemplateVariantsSchema = z.object({ initialization: z.string(), cli: z.string() }).strict();
+const instructionPreviewSelectionSchema = z.discriminatedUnion('mode', [
+    z.object({ mode: z.literal('all') }).strict(),
+    z.object({ mode: z.literal('preset'), preset: z.string().trim().min(1).max(128) }).strict(),
+    z.object({ mode: z.literal('tags'), tags: z.array(z.string().trim().min(1).max(128)).max(256) }).strict(),
+    z.object({ mode: z.literal('tag-filter'), expression: z.string().trim().min(1).max(4096) }).strict(),
+]);
+const requestContextSchema = z
+    .object({
+    project: z
+        .object({
+        path: z.string().optional(),
+        cwd: z.string().optional(),
+        name: z.string().optional(),
+        environment: z.string().optional(),
+        custom: z.record(z.string(), z.unknown()).optional(),
+        git: z
+            .object({
+            branch: z.string().optional(),
+            commit: z.string().optional(),
+            repository: z.string().optional(),
+            isRepo: z.boolean().optional(),
+        })
+            .strict()
+            .optional(),
+    })
+        .strict(),
+    user: z
+        .object({
+        name: z.string().optional(),
+        email: z.string().optional(),
+        home: z.string().optional(),
+        username: z.string().optional(),
+        uid: z.string().optional(),
+        gid: z.string().optional(),
+        shell: z.string().optional(),
+    })
+        .strict(),
+    environment: z
+        .object({
+        variables: z.record(z.string(), z.string()).optional(),
+        prefixes: z.array(z.string()).optional(),
+    })
+        .strict(),
+    timestamp: z.string().optional(),
+    sessionId: z.string().optional(),
+    version: z.string().optional(),
+    transport: z
+        .object({
+        type: z.string(),
+        url: z.string().optional(),
+        connectionId: z.string().optional(),
+        connectionTimestamp: z.string().optional(),
+        client: z.object({ name: z.string(), version: z.string(), title: z.string().optional() }).strict().optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+const configuredServerSourceSchema = z.enum(['mcpServers', 'mcpTemplates']);
 export function createAdminRoutes(options) {
     if (!options.adminEnabled) {
         options.adminService.revokeAllSessions();
@@ -421,8 +485,47 @@ export function createAdminRoutes(options) {
             ok: true,
             operationId: result.operationId,
             servers: result.result.servers,
+            configFingerprint: result.result.configFingerprint,
         });
     });
+    router.get('/api/instruction-templates', async (req, res) => {
+        const service = options.instructionTemplateService;
+        if (!service)
+            return void res.status(404).json({ error: 'admin_instruction_templates_unavailable' });
+        sendAdminOperationResult(res, await service.listTemplates({
+            context: buildAdminOperationContext(req, options, { type: 'instruction_template_collection' }),
+        }));
+    });
+    router.get('/api/instruction-templates/:identity', async (req, res) => {
+        await handleInstructionTemplateRequest(req, res, options, 'get');
+    });
+    router.post('/api/instruction-templates', async (req, res) => {
+        await handleInstructionTemplateRequest(req, res, options, 'create');
+    });
+    router.post('/api/instruction-templates/import-legacy', async (req, res) => {
+        await handleInstructionTemplateRequest(req, res, options, 'import');
+    });
+    router.post('/api/instruction-templates/:identity/clone', async (req, res) => {
+        await handleInstructionTemplateRequest(req, res, options, 'clone');
+    });
+    router.post('/api/instruction-templates/:identity/update', async (req, res) => {
+        await handleInstructionTemplateRequest(req, res, options, 'update');
+    });
+    router.post('/api/instruction-templates/:identity/validate', async (req, res) => {
+        await handleInstructionTemplateRequest(req, res, options, 'validate');
+    });
+    router.post('/api/instruction-templates/:identity/preview', async (req, res) => {
+        await handleInstructionTemplateRequest(req, res, options, 'preview');
+    });
+    router.post('/api/instruction-templates/:identity/activate', async (req, res) => {
+        await handleInstructionTemplateRequest(req, res, options, 'activate');
+    });
+    router.post('/api/instruction-templates/:identity/delete-preview', async (req, res) => {
+        await handleInstructionTemplateRequest(req, res, options, 'delete-preview');
+    });
+    router.delete('/api/instruction-templates/:identity', async (req, res) => {
+        await handleInstructionTemplateRequest(req, res, options, 'delete');
+    });
     router.get('/api/configured-servers/create-contract', async (req, res) => {
         await handleConfiguredServerCreateContract(req, res, options);
     });
@@ -432,9 +535,39 @@ export function createAdminRoutes(options) {
     router.post('/api/configured-servers', async (req, res) => {
         await handleConfiguredServerCreateApply(req, res, options);
     });
+    router.get('/api/configured-servers/:source/:name', async (req, res) => {
+        const source = configuredServerSourceSchema.safeParse(req.params.source);
+        if (!source.success)
+            return void res.status(400).json({ error: 'configured_server_source_invalid' });
+        await handleConfiguredServerDetail(req, res, options, source.data);
+    });
     router.get('/api/configured-servers/:name', async (req, res) => {
         await handleConfiguredServerDetail(req, res, options);
     });
+    router.post('/api/configured-servers/:source/:name/tool-inventory/refresh', async (req, res) => {
+        const source = configuredServerSourceSchema.safeParse(req.params.source);
+        if (!source.success)
+            return void res.status(400).json({ error: 'configured_server_source_invalid' });
+        await handleConfiguredToolInventoryRefresh(req, res, options, source.data);
+    });
+    router.post('/api/configured-servers/:source/:name/preview', async (req, res) => {
+        const source = configuredServerSourceSchema.safeParse(req.params.source);
+        if (!source.success)
+            return void res.status(400).json({ error: 'configured_server_source_invalid' });
+        await handleConfiguredServerPreview(req, res, options, source.data);
+    });
+    router.post('/api/configured-servers/:source/:name/apply', async (req, res) => {
+        const source = configuredServerSourceSchema.safeParse(req.params.source);
+        if (!source.success)
+            return void res.status(400).json({ error: 'configured_server_source_invalid' });
+        await handleConfiguredServerApply(req, res, options, source.data);
+    });
+    router.post('/api/configured-servers/mcpServers/:name/enable', async (req, res) => {
+        await handleConfiguredServerMutation(req, res, options, 'enableConfiguredServer', 'mcpServers');
+    });
+    router.post('/api/configured-servers/mcpServers/:name/disable', async (req, res) => {
+        await handleConfiguredServerMutation(req, res, options, 'disableConfiguredServer', 'mcpServers');
+    });
     router.post('/api/configured-servers/:name/preview', async (req, res) => {
         await handleConfiguredServerPreview(req, res, options);
     });
@@ -480,6 +613,113 @@ export function createAdminRoutes(options) {
     });
     return router;
 }
+async function handleInstructionTemplateRequest(req, res, options, action) {
+    const service = options.instructionTemplateService;
+    if (!service)
+        return void res.status(404).json({ error: 'admin_instruction_templates_unavailable' });
+    const body = req.body && typeof req.body === 'object' ? req.body : {};
+    const identityValue = action === 'create' || action === 'import' ? body.identity : req.params.identity;
+    const identity = instructionTemplateIdentitySchema.safeParse(identityValue);
+    if (!identity.success)
+        return void res.status(400).json({ error: 'instruction_template_identity_invalid' });
+    const context = buildAdminOperationContext(req, options, { type: 'instruction_template', id: identity.data });
+    const expectedConfigFingerprint = typeof body.expectedConfigFingerprint === 'string' ? body.expectedConfigFingerprint : '';
+    try {
+        switch (action) {
+            case 'get':
+                return sendAdminOperationResult(res, await service.getTemplate({ context, identity: identity.data }));
+            case 'create':
+            case 'update': {
+                const variants = instructionTemplateVariantsSchema.safeParse(body.variants);
+                if (!variants.success || !expectedConfigFingerprint) {
+                    return void res.status(400).json({ error: 'instruction_template_request_invalid' });
+                }
+                return sendInstructionTemplateResult(res, await (action === 'create' ? service.createTemplate : service.updateTemplate).call(service, {
+                    context,
+                    identity: identity.data,
+                    variants: variants.data,
+                    expectedConfigFingerprint,
+                }));
+            }
+            case 'clone': {
+                const destination = instructionTemplateIdentitySchema.safeParse(body.identity);
+                if (!destination.success || !expectedConfigFingerprint) {
+                    return void res.status(400).json({ error: 'instruction_template_request_invalid' });
+                }
+                return sendInstructionTemplateResult(res, await service.cloneTemplate({
+                    context,
+                    sourceIdentity: identity.data,
+                    identity: destination.data,
+                    expectedConfigFingerprint,
+                }));
+            }
+            case 'validate':
+                return sendAdminOperationResult(res, await service.validateTemplate({ context, identity: identity.data, expectedConfigFingerprint }));
+            case 'preview': {
+                const preview = z
+                    .object({
+                    surface: z.enum(['initialize', 'cli']),
+                    selection: instructionPreviewSelectionSchema,
+                    requestContext: requestContextSchema.optional(),
+                })
+                    .strict()
+                    .safeParse(body);
+                if (!preview.success)
+                    return void res.status(400).json({ error: 'instruction_template_preview_invalid' });
+                return sendAdminOperationResult(res, await service.previewTemplate({ context, identity: identity.data, ...preview.data }));
+            }
+            case 'activate':
+            case 'delete': {
+                const previewFingerprint = typeof body.previewFingerprint === 'string' ? body.previewFingerprint : '';
+                if (!expectedConfigFingerprint || !previewFingerprint) {
+                    return void res.status(400).json({ error: 'instruction_template_request_invalid' });
+                }
+                return sendInstructionTemplateResult(res, await (action === 'activate' ? service.activateTemplate : service.deleteTemplate).call(service, {
+                    context,
+                    identity: identity.data,
+                    expectedConfigFingerprint,
+                    previewFingerprint,
+                }));
+            }
+            case 'import':
+                if (!expectedConfigFingerprint) {
+                    return void res.status(400).json({ error: 'instruction_template_request_invalid' });
+                }
+                return sendInstructionTemplateResult(res, await service.importLegacyTemplate({ context, identity: identity.data, expectedConfigFingerprint }));
+            case 'delete-preview':
+                return sendAdminOperationResult(res, await service.previewDeleteTemplate({ context, identity: identity.data, expectedConfigFingerprint }));
+        }
+    }
+    catch (error) {
+        if (error instanceof AdminInstructionTemplateNotFoundError) {
+            res.status(404).json({ error: error.code });
+            return;
+        }
+        throw error;
+    }
+}
+function sendInstructionTemplateResult(res, result) {
+    if (!result.ok)
+        return sendAdminOperationResult(res, result);
+    const status = result.result?.status;
+    if (status === 'not_found')
+        return void res.status(404).json({ ok: false, error: 'instruction_template_not_found' });
+    if (status === 'invalid') {
+        return void res
+            .status(422)
+            .json({ ok: false, error: 'instruction_template_invalid', validation: result.result.validation });
+    }
+    if (status === 'legacy_unavailable') {
+        return void res.status(409).json({ ok: false, error: 'legacy_instruction_template_unavailable' });
+    }
+    if (status === 'conflict' ||
+        status === 'identity_conflict' ||
+        status === 'protected' ||
+        status === 'active_conflict') {
+        return void res.status(409).json({ ok: false, error: `instruction_template_${status}` });
+    }
+    sendAdminOperationResult(res, result);
+}
 function streamBackendLogs(req, res, broker, adminService) {
     const sessionToken = getAdminSessionCookie(req);
     let closed = false;
@@ -786,16 +1026,22 @@ function backendRestartFailure(outcome) {
             };
     }
 }
-async function handleConfiguredServerDetail(req, res, options) {
+async function handleConfiguredServerDetail(req, res, options, targetSource) {
     if (!options.configuredServerService) {
         res.status(404).json({ error: 'admin_configured_servers_unavailable' });
         return;
     }
     const targetName = req.params.name;
     try {
+        const model = configuredServerModelSchema.safeParse(req.query.model);
         const result = await options.configuredServerService.getConfiguredServerDetail({
-            context: buildAdminOperationContext(req, options, { type: 'configured_server', id: targetName }),
+            context: buildAdminOperationContext(req, options, {
+                type: 'configured_server',
+                id: `${targetSource ?? 'mcpServers'}:${targetName}`,
+            }),
             targetName,
+            ...(targetSource ? { targetSource } : {}),
+            ...(model.success ? { model: model.data } : {}),
         });
         if (!result.ok) {
             sendAdminOperationResult(res, result);
@@ -806,6 +1052,7 @@ async function handleConfiguredServerDetail(req, res, options) {
             operationId: result.operationId,
             server: result.result.server,
             editContract: result.result.editContract,
+            ...(result.result.toolInventory ? { toolInventory: result.result.toolInventory } : {}),
         });
     }
     catch (error) {
@@ -822,6 +1069,51 @@ async function handleConfiguredServerDetail(req, res, options) {
         throw error;
     }
 }
+async function handleConfiguredToolInventoryRefresh(req, res, options, targetSource) {
+    if (!options.configuredServerService?.refreshConfiguredToolInventory) {
+        res.status(404).json({ error: 'admin_configured_servers_unavailable' });
+        return;
+    }
+    const body = configuredToolInventoryRefreshSchema.safeParse(req.body ?? {});
+    if (!body.success) {
+        res.status(400).json({ error: 'configured_tool_inventory_refresh_invalid' });
+        return;
+    }
+    const targetName = req.params.name;
+    try {
+        const result = await options.configuredServerService.refreshConfiguredToolInventory({
+            context: buildAdminOperationContext(req, options, {
+                type: 'configured_server',
+                id: `${targetSource}:${targetName}`,
+            }),
+            targetName,
+            targetSource,
+            ...(body.data.model ? { model: body.data.model } : {}),
+        });
+        if (!result.ok) {
+            sendAdminOperationResult(res, result);
+            return;
+        }
+        res.status(200).json({
+            ok: true,
+            operationId: result.operationId,
+            toolInventory: result.result,
+        });
+    }
+    catch (error) {
+        if (error instanceof AdminConfiguredServerNotFoundError) {
+            res.status(404).json({
+                ok: false,
+                error: error.code,
+                code: error.code,
+                message: 'Configured server target was not found',
+                target: { type: 'configured_server', id: `${targetSource}:${targetName}` },
+            });
+            return;
+        }
+        throw error;
+    }
+}
 async function handleConfiguredServerCreateContract(req, res, options) {
     if (!options.configuredServerService) {
         res.status(404).json({ error: 'admin_configured_servers_unavailable' });
@@ -906,7 +1198,7 @@ function configuredServerCreateDraftName(draft) {
     const name = draft.name;
     return typeof name === 'string' ? name : '';
 }
-async function handleConfiguredServerPreview(req, res, options) {
+async function handleConfiguredServerPreview(req, res, options, targetSource) {
     if (!options.configuredServerService) {
         res.status(404).json({ error: 'admin_configured_servers_unavailable' });
         return;
@@ -914,11 +1206,17 @@ async function handleConfiguredServerPreview(req, res, options) {
     const targetName = req.params.name;
     const edit = getBodyValue(req.body, 'edit');
     try {
+        const model = configuredServerModelSchema.safeParse(getBodyString(req.body, 'model'));
         const result = await options.configuredServerService.previewConfiguredServerEdit({
-            context: buildAdminOperationContext(req, options, { type: 'configured_server', id: targetName }),
+            context: buildAdminOperationContext(req, options, {
+                type: 'configured_server',
+                id: `${targetSource ?? 'mcpServers'}:${targetName}`,
+            }),
             targetName,
+            ...(targetSource ? { targetSource } : {}),
             edit: edit === undefined ? {} : edit,
             connectivityCheck: getBodyString(req.body, 'connectivityCheck') === 'manual' ? 'manual' : 'auto',
+            ...(model.success ? { model: model.data } : {}),
         });
         if (!result.ok) {
             sendAdminOperationResult(res, result);
@@ -944,7 +1242,7 @@ async function handleConfiguredServerPreview(req, res, options) {
         throw error;
     }
 }
-async function handleConfiguredServerApply(req, res, options) {
+async function handleConfiguredServerApply(req, res, options, targetSource) {
     if (!options.configuredServerService) {
         res.status(404).json({ error: 'admin_configured_servers_unavailable' });
         return;
@@ -962,11 +1260,17 @@ async function handleConfiguredServerApply(req, res, options) {
     }
     const targetName = req.params.name;
     try {
+        const model = configuredServerModelSchema.safeParse(getBodyString(req.body, 'model'));
         const result = await options.configuredServerService.applyConfiguredServerEdit({
-            context: buildAdminOperationContext(req, options, { type: 'configured_server', id: targetName }),
+            context: buildAdminOperationContext(req, options, {
+                type: 'configured_server',
+                id: `${targetSource ?? 'mcpServers'}:${targetName}`,
+            }),
             targetName,
+            ...(targetSource ? { targetSource } : {}),
             edit: getBodyValue(req.body, 'edit') ?? {},
             previewFingerprint: getBodyString(req.body, 'previewFingerprint'),
+            ...(model.success ? { model: model.data } : {}),
         });
         if (!result.ok && result.status === 'mutation_failed' && isConfiguredServerApplyErrorCode(result.error)) {
             sendConfiguredServerApplyError(res, result.error);
@@ -1020,7 +1324,7 @@ function configuredServerApplyErrorMessage(code) {
             return 'The configured server edit could not be applied.';
     }
 }
-async function handleConfiguredServerMutation(req, res, options, operationName) {
+async function handleConfiguredServerMutation(req, res, options, operationName, targetSource) {
     if (!options.configuredServerService) {
         res.status(404).json({ error: 'admin_configured_servers_unavailable' });
         return;
@@ -1037,8 +1341,11 @@ async function handleConfiguredServerMutation(req, res, options, operationName)
         return;
     }
     const targetName = req.params.name;
-    const context = buildAdminOperationContext(req, options, { type: 'configured_server', id: targetName });
-    const input = { context, targetName };
+    const context = buildAdminOperationContext(req, options, {
+        type: 'configured_server',
+        id: `${targetSource ?? 'mcpServers'}:${targetName}`,
+    });
+    const input = { context, targetName, ...(targetSource ? { targetSource } : {}) };
     const result = operationName === 'enableConfiguredServer'
         ? await options.configuredServerService.enableConfiguredServer(input)
         : await options.configuredServerService.disableConfiguredServer(input);
@@ -1531,6 +1838,11 @@ function configuredServerRequestFingerprint(operationName, targetName, body) {
                 },
             }
             : {}),
+        ...(operationName.includes('InstructionTemplate') || operationName === 'applyConfiguredServerInstructionOverride'
+            ? {
+                bodyDigest: keyedRequestFingerprint(previewFingerprint || getBodyString(body, 'expectedConfigFingerprint') || operationName, 'admin-instruction-operation', stableJsonStringify(body ?? {})),
+            }
+            : {}),
     });
     if (operationName === 'applyConfiguredServerCreate') {
         return `configured_server_create_${keyedRequestFingerprint(previewFingerprint, 'configured-server-create', normalized)}`;
@@ -1621,6 +1933,30 @@ function cliOperationErrorDetails(result) {
     return details;
 }
 function operationNameForRequest(req) {
+    if (req.path.startsWith('/api/instruction-templates')) {
+        if (req.path.endsWith('/clone'))
+            return 'cloneInstructionTemplate';
+        if (req.path.endsWith('/update'))
+            return 'updateInstructionTemplate';
+        if (req.path.endsWith('/validate'))
+            return 'validateInstructionTemplate';
+        if (req.path.endsWith('/preview'))
+            return 'previewInstructionTemplate';
+        if (req.path.endsWith('/activate'))
+            return 'activateInstructionTemplate';
+        if (req.path.endsWith('/delete-preview'))
+            return 'previewDeleteInstructionTemplate';
+        if (req.path.endsWith('/import-legacy'))
+            return 'importLegacyInstructionTemplate';
+        if (req.method === 'DELETE')
+            return 'deleteInstructionTemplate';
+        if (req.method === 'POST')
+            return 'createInstructionTemplate';
+        return req.path === '/api/instruction-templates' ? 'listInstructionTemplates' : 'getInstructionTemplate';
+    }
+    if (req.path.endsWith('/instruction-override')) {
+        return 'applyConfiguredServerInstructionOverride';
+    }
     if (req.path.startsWith('/api/oauth/')) {
         return req.path.endsWith('/restart') ? 'restartBackendOAuth' : 'authorizeBackendOAuth';
     }