Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
📜 feat: Add Skills Discovery and Authoring to the Management API (#15642)
Danny Avila8a85df971513
diff --git a/api/server/routes/agents/__tests__/idempotencyLimiter.spec.js b/api/server/routes/agents/__tests__/idempotencyLimiter.spec.jsindex 51c422c8df..cccbacd539 100644--- a/api/server/routes/agents/__tests__/idempotencyLimiter.spec.js+++ b/api/server/routes/agents/__tests__/idempotencyLimiter.spec.js@@ -60,6 +60,7 @@ jest.mock('~/server/routes/agents/v1', () => ({}));jest.mock('~/server/routes/agents/openai', () => require('express').Router());jest.mock('~/server/routes/agents/responses', () => require('express').Router());+jest.mock('~/server/routes/agents/skills', () => require('express').Router());jest.mock('~/server/routes/agents/management', () => {const router = require('express').Router();router.use((_req, res) => res.status(200).json({ surface: 'management' }));diff --git a/api/server/routes/agents/__tests__/management.spec.js b/api/server/routes/agents/__tests__/management.spec.jsindex 5d1e244103..3a705ef169 100644--- a/api/server/routes/agents/__tests__/management.spec.js+++ b/api/server/routes/agents/__tests__/management.spec.js@@ -85,6 +85,8 @@ const mockRequireAgentManagementAuth = jest.fn((req, res, next) => {next();});+jest.mock('../skills', () => require('express').Router());+jest.mock('../middleware', () => ({requireAgentManagementAuth: mockRequireAgentManagementAuth,}));diff --git a/api/server/routes/agents/__tests__/skills.spec.js b/api/server/routes/agents/__tests__/skills.spec.jsnew file mode 100644index 0000000000..6cca03c759--- /dev/null+++ b/api/server/routes/agents/__tests__/skills.spec.js@@ -0,0 +1,67 @@+const express = require('express');+const request = require('supertest');++const mockList = jest.fn((_req, res) => res.json({ object: 'list' }));+const mockWrite = jest.fn((_req, res) => res.json({ saved: true }));+const mockSync = jest.fn();+const mockIp = jest.fn((_req, _res, next) => next());+const mockUser = jest.fn((_req, _res, next) => next());+const mockAuth = jest.fn((_req, _res, next) => next());+let mockDeps;+jest.mock('@librechat/api', () => ({+ createSkillManagementHandlers: (deps) => {+ mockDeps = deps;+ return {+ list: mockList,+ get: mockList,+ update: mockWrite,+ listFiles: mockList,+ getFile: mockList,+ updateFile: mockWrite,+ };+ },+ mapAgentManagementError: () => ({ status: 404, body: { error: { code: 'not_found' } } }),+}));+jest.mock('../middleware', () => ({ requireAgentManagementAuth: (...args) => mockAuth(...args) }));+jest.mock('~/server/middleware', () => ({+ checkBan: (_req, _res, next) => next(),+ configMiddleware: (req, _res, next) => {+ req.config = { tenantConfig: true };+ next();+ },+}));+jest.mock('~/server/middleware/roles/capabilities', () => ({ hasCapability: jest.fn() }));+jest.mock('~/server/services/PermissionService', () => ({ checkPermission: jest.fn() }));+jest.mock('~/server/services/Skills/handlers', () => ({ getSkillsHandlers: jest.fn() }));+jest.mock('~/server/services/Skills/sync', () => ({+ maybeRunGitHubSkillSyncForRequest: (...args) => mockSync(...args),+}));+jest.mock('~/server/services/Endpoints/agents/skillDeps', () => ({+ getSkillDbMethods: () => ({}),+ getSkillToolDeps: () => ({}),+}));+jest.mock('~/models', () => ({}));+jest.mock('~/server/middleware/limiters/uploadLimiters', () => ({+ createFileLimiters: () => ({+ fileUploadIpLimiter: (...args) => mockIp(...args),+ fileUploadUserLimiter: (...args) => mockUser(...args),+ }),+}));+const app = express();+app.use(express.json());+app.use('/skills', require('../skills'));++it('wires sync and both upload limiters into the authorized management handlers', async () => {+ await mockDeps.beforeList({ config: { tenantConfig: true } });+ expect(mockSync).toHaveBeenCalledWith({ config: { tenantConfig: true } });+ expect(mockDeps.fileWriteLimiters).toHaveLength(2);+ const next = jest.fn();+ for (const limiter of mockDeps.fileWriteLimiters) limiter({}, {}, next);+ expect(mockIp).toHaveBeenCalledTimes(1);+ expect(mockUser).toHaveBeenCalledTimes(1);+});+it('keeps authentication ahead of management handlers', async () => {+ mockAuth.mockImplementationOnce((_req, res) => res.sendStatus(401));+ await request(app).get('/skills').expect(401);+ expect(mockList).not.toHaveBeenCalled();+});diff --git a/api/server/routes/agents/index.js b/api/server/routes/agents/index.jsindex f3bdd73c75..21e119362e 100644--- a/api/server/routes/agents/index.js+++ b/api/server/routes/agents/index.js@@ -55,6 +55,7 @@ const {} = require('~/server/services/Schedules');const responses = require('./responses');const management = require('./management');+const skills = require('./skills');const openai = require('./openai');const { v1 } = require('./v1');const chat = require('./chat');@@ -127,6 +128,7 @@ router.use('/v1/responses', responses);* inherit execution authentication or API-key fallback behavior.*/router.use('/v1/agents', management);+router.use('/v1/skills', skills);/*** OpenAI-compatible API routes (API key authentication handled in route file)diff --git a/api/server/routes/agents/skills.js b/api/server/routes/agents/skills.jsnew file mode 100644index 0000000000..ccace9bf8b--- /dev/null+++ b/api/server/routes/agents/skills.js@@ -0,0 +1,40 @@+const express = require('express');+const { createSkillManagementHandlers, mapAgentManagementError } = require('@librechat/api');+const { createFileLimiters } = require('~/server/middleware/limiters/uploadLimiters');+const { maybeRunGitHubSkillSyncForRequest } = require('~/server/services/Skills/sync');+const { checkBan, configMiddleware } = require('~/server/middleware');+const { hasCapability } = require('~/server/middleware/roles/capabilities');+const { checkPermission } = require('~/server/services/PermissionService');+const { getSkillsHandlers } = require('~/server/services/Skills/handlers');+const {+ getSkillDbMethods,+ getSkillToolDeps,+} = require('~/server/services/Endpoints/agents/skillDeps');+const { getRoleByName } = require('~/models');+const { requireAgentManagementAuth } = require('./middleware');++const router = express.Router();+const { fileUploadIpLimiter, fileUploadUserLimiter } = createFileLimiters();+const handlers = createSkillManagementHandlers({+ beforeList: maybeRunGitHubSkillSyncForRequest,+ fileWriteLimiters: [fileUploadIpLimiter, fileUploadUserLimiter],+ handlers: getSkillsHandlers(),+ getSkillById: getSkillDbMethods().getSkillById,+ getRoleByName,+ checkPermission,+ hasCapability,+ saveFile: getSkillToolDeps().saveSkillFileContent,+});+router.use(requireAgentManagementAuth, checkBan, configMiddleware);+router.get('/', handlers.list);+router.get('/:id', handlers.get);+router.patch('/:id', handlers.update);+router.get('/:id/files', handlers.listFiles);+router.get('/:id/files/*relativePath', handlers.getFile);+router.put('/:id/files/*relativePath', handlers.updateFile);+router.use((_req, res) => {+ const { status, body } = mapAgentManagementError('not_found');+ body.error.message = 'Skill or file not found';+ return res.status(status).json(body);+});+module.exports = router;diff --git a/api/server/routes/skills.js b/api/server/routes/skills.jsindex 2143e50f60..dd40662750 100644--- a/api/server/routes/skills.js+++ b/api/server/routes/skills.js@@ -3,7 +3,6 @@ const crypto = require('crypto');const multer = require('multer');const express = require('express');const {- createSkillsHandlers,createImportHandler,blockFilteredSkillFile,generateCheckAccess,@@ -11,7 +10,7 @@ const {resolveRequestTenantId,restoreTenantContextFromReq,} = require('@librechat/api');-const { isValidObjectIdString, logger } = require('@librechat/data-schemas');+const { logger } = require('@librechat/data-schemas');const {PermissionBits,PermissionTypes,@@ -22,30 +21,18 @@ const {const {createSkill,getSkillById,- updateSkill,deleteSkill,upsertSkillFile,- deleteSkillFile,getSkillFileByPath,getRoleByName,} = require('~/models');const { requireJwtAuth, canAccessSkillResource } = require('~/server/middleware');-const {- findAccessibleResources,- findPubliclyAccessibleResources,- hasPublicPermission,- grantPermission,-} = require('~/server/services/PermissionService');+const { grantPermission } = require('~/server/services/PermissionService');const { getStrategyFunctions } = require('~/server/services/Files/strategies');const { createFileLimiters } = require('~/server/middleware/limiters/uploadLimiters');const { maybeRunGitHubSkillSyncForRequest } = require('~/server/services/Skills/sync');const configMiddleware = require('~/server/middleware/config/app');const { getFileStrategy } = require('~/server/utils/getFileStrategy');-const {- getSkillDbMethods,- withDeploymentSkillIds,- getSkillStrategyFunctions,-} = require('~/server/services/Endpoints/agents/skillDeps');const router = express.Router();@@ -104,7 +91,6 @@ const checkSkillCreate = generateCheckAccess({// Rate limiters (reuse existing file upload limiters)// ---------------------------------------------------------------------------const { fileUploadIpLimiter, fileUploadUserLimiter } = createFileLimiters();-const skillDbMethods = getSkillDbMethods();router.use(requireJwtAuth);router.use(configMiddleware);@@ -113,33 +99,8 @@ router.use(checkSkillAccess);// ---------------------------------------------------------------------------// CRUD handlers// ----------------------------------------------------------------------------const handlers = createSkillsHandlers({- createSkill,- getSkillById: skillDbMethods.getSkillById,- listSkillsByAccess: skillDbMethods.listSkillsByAccess,- updateSkill,- deleteSkill,- listSkillFiles: skillDbMethods.listSkillFiles,- deleteSkillFile,- getSkillFileByPath: skillDbMethods.getSkillFileByPath,- updateSkillFileContent: skillDbMethods.updateSkillFileContent,- getStrategyFunctions: getSkillStrategyFunctions,- findAccessibleResources: async (params) =>- params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW- ? withDeploymentSkillIds(await findAccessibleResources(params))- : findAccessibleResources(params),- findPubliclyAccessibleResources: async (params) =>- params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW- ? withDeploymentSkillIds(await findPubliclyAccessibleResources(params))- : findPubliclyAccessibleResources(params),- hasPublicPermission: async (params) =>- params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW- ? withDeploymentSkillIds([]).some((id) => id.toString() === params.resourceId.toString()) ||- hasPublicPermission(params)- : hasPublicPermission(params),- grantPermission,- isValidObjectIdString,-});+const { getSkillsHandlers } = require('~/server/services/Skills/handlers');+const handlers = getSkillsHandlers();// ---------------------------------------------------------------------------// File storage helper: resolve the active strategy's saveBufferdiff --git a/api/server/services/Skills/handlers.js b/api/server/services/Skills/handlers.jsnew file mode 100644index 0000000000..f224cac34e--- /dev/null+++ b/api/server/services/Skills/handlers.js@@ -0,0 +1,47 @@+const { createSkillsHandlers } = require('@librechat/api');+const { isValidObjectIdString } = require('@librechat/data-schemas');+const { PermissionBits } = require('librechat-data-provider');+const { createSkill, updateSkill, deleteSkill, deleteSkillFile } = require('~/models');+const {+ findAccessibleResources,+ findPubliclyAccessibleResources,+ hasPublicPermission,+ grantPermission,+} = require('~/server/services/PermissionService');+const {+ getSkillDbMethods,+ withDeploymentSkillIds,+ getSkillStrategyFunctions,+} = require('~/server/services/Endpoints/agents/skillDeps');++function getSkillsHandlers() {+ const skillDbMethods = getSkillDbMethods();+ return createSkillsHandlers({+ createSkill,+ getSkillById: skillDbMethods.getSkillById,+ listSkillsByAccess: skillDbMethods.listSkillsByAccess,+ updateSkill,+ deleteSkill,+ listSkillFiles: skillDbMethods.listSkillFiles,+ deleteSkillFile,+ getSkillFileByPath: skillDbMethods.getSkillFileByPath,+ updateSkillFileContent: skillDbMethods.updateSkillFileContent,+ getStrategyFunctions: getSkillStrategyFunctions,+ findAccessibleResources: async (params) =>+ params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW+ ? withDeploymentSkillIds(await findAccessibleResources(params))+ : findAccessibleResources(params),+ findPubliclyAccessibleResources: async (params) =>+ params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW+ ? withDeploymentSkillIds(await findPubliclyAccessibleResources(params))+ : findPubliclyAccessibleResources(params),+ hasPublicPermission: async (params) =>+ params.resourceType === 'skill' && params.requiredPermissions === PermissionBits.VIEW+ ? withDeploymentSkillIds([]).some((id) => id.toString() === params.resourceId.toString()) ||+ hasPublicPermission(params)+ : hasPublicPermission(params),+ grantPermission,+ isValidObjectIdString,+ });+}+module.exports = { getSkillsHandlers };diff --git a/docs/skills-management-api.md b/docs/skills-management-api.mdnew file mode 100644index 0000000000..27329a59d0--- /dev/null+++ b/docs/skills-management-api.md@@ -0,0 +1,46 @@+# Skills management API++The machine-authenticated Skills surface uses the same `endpoints.agents.managementApi.auth`+configuration and client-to-principal bindings as Agent management. It is mounted before the+execution router and does not accept browser sessions or execution API keys as fallback.++| Method | Path | Operation |+| ------ | ----------------------------------------------- | --------------------------------------------- |+| GET | `/api/agents/v1/skills` | List accessible Skills (`limit` and `cursor`) |+| GET | `/api/agents/v1/skills/:id` | Read Skill metadata, body, and frontmatter |+| PATCH | `/api/agents/v1/skills/:id` | Update an inline Skill |+| GET | `/api/agents/v1/skills/:id/files` | List file metadata |+| GET | `/api/agents/v1/skills/:id/files/*relativePath` | Read a file as JSON |+| PUT | `/api/agents/v1/skills/:id/files/*relativePath` | Create or replace a text file |++Skill results expose `id`, configuration fields, `version`, `fileCount`, and ISO timestamps.+Ownership, tenant, source metadata, and storage locations are excluded. Skill lists use the Agent+management envelope: `object`, `data`, `first_id`, `last_id`, `has_more`, and `after`.+Pass returned Skill IDs in the Agent management `skills` field to assign them to an Agent.++Updates require the version returned by the latest read:++```json+{+ "expectedVersion": 1,+ "body": "Updated instructions",+ "description": "Use this skill when analyzing a new dataset."+}+```++Editable fields are `name`, `displayTitle`, `description`, `body`, `frontmatter`, `category`, and+`alwaysApply`. Existing Skills validation and content policies apply. Unknown fields are rejected.+A stale version returns HTTP 409 with `error.code: "conflict"`; retrieve the current Skill before+retrying. Skill reads require VIEW access; updates require EDIT and the Skills USE/CREATE role+permissions. Inaccessible and cross-tenant IDs return the same 404 envelope.++Text-file writes accept `{ "content": "replacement text" }`, capped at 1 MiB of UTF-8 data.+Use a relative path such as `references/guide.md`. Absolute paths, traversal, and NUL bytes are+rejected. Update `SKILL.md` through the Skill's `body` field with `expectedVersion`, not the file+endpoint. File writes use replacement semantics without a version precondition; serialize writers+to the same path. After a file write, read the Skill again before a versioned metadata/body update: file writes also+increment the parent version. Storage selection stays server-controlled. File JSON reads omit content for+binary or oversized files; raw download mode is not supported on this surface.++Git-synced and deployment-provided Skills are readable but cannot be changed through this API.+Change their upstream source instead. Browser routes keep their existing behavior.diff --git a/packages/api/src/agents/management.ts b/packages/api/src/agents/management.tsindex 51694e2dec..af834b0609 100644--- a/packages/api/src/agents/management.ts+++ b/packages/api/src/agents/management.ts@@ -77,7 +77,8 @@ export type AgentManagementErrorCode =| 'invalid_request'| 'not_found'| 'permission_denied'- | 'internal_error';+ | 'internal_error'+ | 'conflict';export type AgentManagementError = {error: {code: AgentManagementErrorCode;@@ -213,6 +214,7 @@ export const agentManagementErrorCodeSchema: z.ZodType<AgentManagementErrorCode>'not_found','permission_denied','internal_error',+ 'conflict',]);const agentManagementValidationIssueSchema = z@@ -308,6 +310,7 @@ const ERROR_STATUS: Record<AgentManagementErrorCode, number> = {not_found: 404,permission_denied: 403,internal_error: 500,+ conflict: 409,};const ERROR_MESSAGE: Record<AgentManagementErrorCode, string> = {@@ -315,6 +318,7 @@ const ERROR_MESSAGE: Record<AgentManagementErrorCode, string> = {not_found: 'Agent not found',permission_denied: 'Permission denied',internal_error: 'Internal server error',+ conflict: 'Resource conflict',};/** Map known failure classes to a stable envelope without exposing internal error messages. */diff --git a/packages/api/src/skills/handlers.ts b/packages/api/src/skills/handlers.tsindex 3d8472a55e..3a9fefc903 100644--- a/packages/api/src/skills/handlers.ts+++ b/packages/api/src/skills/handlers.ts@@ -26,6 +26,7 @@ import type {CreateSkillResult,UpdateSkillInput,ListSkillsByAccessResult,+ ListSkillsByAccessParams,UpdateSkillResult,ValidationIssue,} from '@librechat/data-schemas';@@ -34,6 +35,7 @@ import type { Types } from 'mongoose';import type { ServerRequest, StrategyFunctions } from '~/types';import { extractSkillContent, inspectContentWithTraversal } from '~/protection';import { contentFilterBlockResponse } from '~/middleware/contentFilter';+import { getDeploymentSkillIds } from './deployment';import { resolveSkillFilePathParam } from './path';import { parseSkillMarkdown } from './parse';import { isBinaryBuffer } from './binary';@@ -53,13 +55,7 @@ export interface SkillsHandlersDeps {/** Skill CRUD — from `@librechat/data-schemas` `createMethods` output. */createSkill: (data: CreateSkillInput) => Promise<CreateSkillResult>;getSkillById: (id: string | Types.ObjectId) => Promise<(ISkill & { _id: Types.ObjectId }) | null>;- listSkillsByAccess: (params: {- accessibleIds: Types.ObjectId[];- category?: string;- search?: string;- limit: number;- cursor?: string | null;- }) => Promise<ListSkillsByAccessResult>;+ listSkillsByAccess: (params: ListSkillsByAccessParams) => Promise<ListSkillsByAccessResult>;updateSkill: (params: {id: string;expectedVersion: number;@@ -303,6 +299,10 @@ function blockFilteredSkillContent(return false;}+type SkillResponseOptions = { includePublicStatus?: boolean };++type SkillListOptions = Pick<ListSkillsByAccessParams, 'manageTenantId' | 'limit' | 'cursor'>;+/*** Factory for the typed Express handlers served at `/api/skills`.* The legacy `api/server/routes/skills.js` imports this, passes in concrete@@ -310,10 +310,10 @@ function blockFilteredSkillContent(* onto the Express router.*/export function createSkillsHandlers(deps: SkillsHandlersDeps): {- list: (req: ServerRequest, res: Response) => Promise<Response>;+ list: (req: ServerRequest, res: Response, options?: SkillListOptions) => Promise<Response>;create: (req: ServerRequest, res: Response) => Promise<Response>;- get: (req: ServerRequest, res: Response) => Promise<Response>;- patch: (req: ServerRequest, res: Response) => Promise<Response>;+ get: (req: ServerRequest, res: Response, options?: SkillResponseOptions) => Promise<Response>;+ patch: (req: ServerRequest, res: Response, options?: SkillResponseOptions) => Promise<Response>;delete: (req: ServerRequest, res: Response) => Promise<Response>;listFiles: (req: ServerRequest, res: Response) => Promise<Response>;downloadFile: (req: ServerRequest, res: Response) => Promise<Response | undefined>;@@ -350,7 +350,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {}}- async function listHandler(req: ServerRequest, res: Response) {+ async function listHandler(req: ServerRequest, res: Response, options?: SkillListOptions) {try {const user = req.user;if (!user || !user.id) {@@ -364,18 +364,20 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {};const parsedLimit = parseLimit(limit);- const [accessibleIds, publicIds] = await Promise.all([- findAccessibleResources({- userId: user.id,- role: user.role,- resourceType: ResourceType.SKILL,- requiredPermissions: PermissionBits.VIEW,- }),- findPubliclyAccessibleResources({- resourceType: ResourceType.SKILL,- requiredPermissions: PermissionBits.VIEW,- }),- ]);+ const [accessibleIds, publicIds] = options?.manageTenantId+ ? [getDeploymentSkillIds(), []]+ : await Promise.all([+ findAccessibleResources({+ userId: user.id,+ role: user.role,+ resourceType: ResourceType.SKILL,+ requiredPermissions: PermissionBits.VIEW,+ }),+ findPubliclyAccessibleResources({+ resourceType: ResourceType.SKILL,+ requiredPermissions: PermissionBits.VIEW,+ }),+ ]);const mergedIds = Array.from(new Map([...accessibleIds, ...publicIds].map((id) => [id.toString(), id])).values(),@@ -385,8 +387,10 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {accessibleIds: mergedIds,category: typeof category === 'string' && category.length > 0 ? category : undefined,search: typeof search === 'string' && search.length > 0 ? search : undefined,- limit: parsedLimit,- cursor: typeof cursor === 'string' && cursor.length > 0 ? cursor : null,+ manageTenantId: options?.manageTenantId,+ limit: options?.limit ?? parsedLimit,+ cursor:+ options?.cursor ?? (typeof cursor === 'string' && cursor.length > 0 ? cursor : null),});const publicSet = new Set(publicIds.map((id) => id.toString()));@@ -487,7 +491,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {}}- async function getHandler(req: ServerRequest, res: Response) {+ async function getHandler(req: ServerRequest, res: Response, options?: SkillResponseOptions) {try {const { id } = req.params as { id: string };// The canAccessSkillResource middleware already resolved the skill via@@ -502,7 +506,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {if (!skill) {return res.status(404).json({ error: 'Skill not found' });}- const pub = await isSkillPublic(skill._id);+ const pub = options?.includePublicStatus === false ? false : await isSkillPublic(skill._id);return res.status(200).json(serializeSkill(skill, pub));} catch (error) {logger.error('[GET /skills/:id] Error fetching skill', error);@@ -510,7 +514,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {}}- async function patchHandler(req: ServerRequest, res: Response) {+ async function patchHandler(req: ServerRequest, res: Response, options?: SkillResponseOptions) {try {const { id } = req.params as { id: string };const body = (req.body ?? {}) as TUpdateSkillPayload & { expectedVersion?: number };@@ -564,7 +568,7 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {if (result.status === 'not_found') {return res.status(404).json({ error: 'Skill not found' });}- const pub = await isSkillPublic(id);+ const pub = options?.includePublicStatus === false ? false : await isSkillPublic(id);if (result.status === 'conflict') {const conflict: TSkillConflictResponse = {error: 'skill_version_conflict',@@ -655,7 +659,12 @@ export function createSkillsHandlers(deps: SkillsHandlersDeps): {// SKILL.md is the skill body itself, not a SkillFile documentif (decodedPath === 'SKILL.md') {- const skill = await getSkillById(id);+ const resolved = (+ req as ServerRequest & {+ resourceAccess?: { resourceInfo?: ISkill & { _id: Types.ObjectId } };+ }+ ).resourceAccess?.resourceInfo;+ const skill = resolved ?? (await getSkillById(id));if (!skill) {return res.status(404).json({ error: 'Skill not found' });}diff --git a/packages/api/src/skills/index.ts b/packages/api/src/skills/index.tsindex fd363b1c97..706126377b 100644--- a/packages/api/src/skills/index.ts+++ b/packages/api/src/skills/index.ts@@ -8,3 +8,4 @@ export * from './parse';export * from './skillStates';export * from './deployment';export * from './sync';+export * from './management';diff --git a/packages/api/src/skills/management.spec.ts b/packages/api/src/skills/management.spec.tsnew file mode 100644index 0000000000..685647122a--- /dev/null+++ b/packages/api/src/skills/management.spec.ts@@ -0,0 +1,466 @@+/* eslint jest/expect-expect: [warn, { assertFunctionNames: ['expect', '**.expect'] }] */+import express from 'express';+import request from 'supertest';+import mongoose, { Types } from 'mongoose';+import { MongoMemoryServer } from 'mongodb-memory-server';+import { createModels, createMethods, tenantStorage } from '@librechat/data-schemas';+import { PermissionBits, Permissions, PermissionTypes } from 'librechat-data-provider';+import type { AllMethods, IRole, IUser } from '@librechat/data-schemas';+import type { FiltersConfig } from 'librechat-data-provider';+import type { RequestHandler } from 'express';+import type { SkillManagementDeps } from './management';+import type { ServerRequest } from '~/types';+import { createSkillManagementHandlers } from './management';+import { createSkillsHandlers } from './handlers';++const tenantId = 'management-test';+const author = new Types.ObjectId();+const user = { id: author.toString(), _id: author, role: 'USER', tenantId } as IUser;+let server: MongoMemoryServer;+let db: AllMethods;+let app: express.Express;+let skillId: string;+let allowEdit: boolean;+let allowView: boolean;+let allowUse: boolean;+let canManage: boolean;+let authenticated: boolean;+let saveFile: jest.MockedFunction<SkillManagementDeps['saveFile']>;+let filters: FiltersConfig | undefined;+let readSkill: jest.SpyInstance;+let beforeList: jest.Mock;+let uploadLimiter: jest.MockedFunction<RequestHandler>;+let accessible: jest.Mock;+let publiclyAccessible: jest.Mock;+let publicStatus: jest.Mock;+let capabilityCheck: jest.Mock;+let originalStrict: string | undefined;+const inTenant = <T>(fn: () => T) => tenantStorage.run({ tenantId }, fn);++beforeAll(async () => {+ originalStrict = process.env.TENANT_ISOLATION_STRICT;+ process.env.TENANT_ISOLATION_STRICT = 'true';+ server = await MongoMemoryServer.create();+ await mongoose.connect(server.getUri());+ createModels(mongoose);+ db = createMethods(mongoose);+});+afterAll(async () => {+ await mongoose.disconnect();+ await server.stop();+ if (originalStrict == null) delete process.env.TENANT_ISOLATION_STRICT;+ else process.env.TENANT_ISOLATION_STRICT = originalStrict;+});+beforeEach(async () => {+ await mongoose.connection.dropDatabase();+ allowEdit = true;+ allowView = true;+ allowUse = true;+ canManage = false;+ authenticated = true;+ filters = undefined;+ readSkill = jest.spyOn(db, 'getSkillById');+ const { skill } = await inTenant(() =>+ db.createSkill({+ name: 'test-skill',+ description: 'Use this skill to test management operations safely.',+ body: 'Original instructions',+ author,+ authorName: 'Test',+ tenantId,+ }),+ );+ skillId = skill._id.toString();+ saveFile = jest.fn(async ({ relativePath, content }) => ({+ relativePath,+ bytes: Buffer.byteLength(content),+ }));+ beforeList = jest.fn();+ uploadLimiter = jest.fn((_req, _res, next) => next());+ accessible = jest.fn(async () => (allowView ? [new Types.ObjectId(skillId)] : []));+ publiclyAccessible = jest.fn(async () => []);+ publicStatus = jest.fn(async () => false);+ capabilityCheck = jest.fn(async () => canManage);+ const handlers = createSkillsHandlers({+ ...db,+ findAccessibleResources: accessible,+ findPubliclyAccessibleResources: publiclyAccessible,+ hasPublicPermission: publicStatus,+ grantPermission: async () => undefined,+ getStrategyFunctions: () => ({}),+ isValidObjectIdString: (id) => typeof id === 'string' && /^[a-f\d]{24}$/i.test(id),+ });+ const management = createSkillManagementHandlers({+ handlers,+ beforeList,+ fileWriteLimiters: [uploadLimiter],+ getSkillById: db.getSkillById,+ getRoleByName: async () =>+ ({+ permissions: {+ [PermissionTypes.SKILLS]: {+ [Permissions.USE]: allowUse,+ [Permissions.CREATE]: true,+ },+ },+ }) as IRole,+ checkPermission: async ({ requiredPermission }) =>+ requiredPermission === PermissionBits.EDIT ? allowEdit : allowView,+ saveFile,+ hasCapability: capabilityCheck,+ });+ app = express();+ app.use(express.json());+ app.use((req, _res, next) => {+ if (authenticated) req.user = user;+ (req as ServerRequest).config = { filters } as ServerRequest['config'];+ tenantStorage.run({ tenantId }, next);+ });+ app.get('/skills', async (req, res) => {+ await management.list(req, res);+ });+ app.get('/skills/:id', async (req, res) => {+ await management.get(req, res);+ });+ app.patch('/skills/:id', async (req, res) => {+ await management.update(req, res);+ });+ app.get('/skills/:id/files', async (req, res) => {+ await management.listFiles(req, res);+ });+ app.get('/skills/:id/files/*relativePath', async (req, res) => {+ await management.getFile(req, res);+ });+ app.put('/skills/:id/files/*relativePath', async (req, res) => {+ await management.updateFile(req, res);+ });+});++it('lists and retrieves stable representations without ownership or storage internals', async () => {+ const list = await request(app).get('/skills').expect(200);+ expect(list.body).toMatchObject({+ object: 'list',+ first_id: skillId,+ last_id: skillId,+ has_more: false,+ after: null,+ });+ expect(list.body.data[0]).toMatchObject({ id: skillId, name: 'test-skill', version: 1 });+ expect(list.body.data[0]).not.toHaveProperty('body');+ const detail = await request(app).get(`/skills/${skillId}`).expect(200);+ expect(detail.body).toMatchObject({ id: skillId, body: 'Original instructions' });+ for (const key of ['_id', 'tenantId', 'author', 'sourceMetadata', 'source']) {+ expect(detail.body).not.toHaveProperty(key);+ expect(list.body.data[0]).not.toHaveProperty(key);+ }+});+it('reuses validation and versioned persistence for partial updates', async () => {+ const updated = await request(app)+ .patch(`/skills/${skillId}`)+ .send({ expectedVersion: 1, body: 'Updated instructions' })+ .expect(200);+ expect(updated.body).toMatchObject({+ id: skillId,+ version: 2,+ body: 'Updated instructions',+ name: 'test-skill',+ });+ expect(await inTenant(() => db.getSkillById(skillId))).toMatchObject({+ version: 2,+ body: 'Updated instructions',+ });+ const conflict = await request(app)+ .patch(`/skills/${skillId}`)+ .send({ expectedVersion: 1, body: 'Stale writer' })+ .expect(409);+ expect(conflict.body).toMatchObject({ error: { code: 'conflict' } });+ expect(conflict.body).not.toHaveProperty('current');+ await request(app)+ .patch(`/skills/${skillId}`)+ .send({ expectedVersion: 2, name: 'INVALID NAME' })+ .expect(400);+});+it.each(['tenantId', 'author', 'source', 'sourceMetadata', 'user', 'permissions'])(+ 'rejects caller-controlled %s',+ async (key) => {+ await request(app)+ .patch(`/skills/${skillId}`)+ .send({ expectedVersion: 1, body: 'Updated', [key]: 'forged' })+ .expect(400);+ expect(await inTenant(() => db.getSkillById(skillId))).toMatchObject({ version: 1 });+ },+);+it.each([+ { expectedVersion: 0, body: 'x' },+ { body: 'x' },+ { expectedVersion: 1 },+ { expectedVersion: 1, body: null },+])('rejects malformed updates %j', async (body) => {+ await request(app).patch(`/skills/${skillId}`).send(body).expect(400);+});+it('hides inaccessible and cross-tenant Skills, including on file writes', async () => {+ allowView = false;+ allowEdit = false;+ await request(app).get(`/skills/${skillId}`).expect(404);+ await request(app)+ .patch(`/skills/${skillId}`)+ .send({ expectedVersion: 1, body: 'x' })+ .expect(404);+ await request(app)+ .put(`/skills/${skillId}/files/reference.md`)+ .send({ content: 'x' })+ .expect(404);+ expect(saveFile).not.toHaveBeenCalled();+ allowView = true;+ allowEdit = true;+ const { skill } = await tenantStorage.run({ tenantId: 'foreign' }, () =>+ db.createSkill({+ name: 'foreign',+ description: 'Foreign tenant skill for access isolation tests.',+ body: 'secret',+ author,+ authorName: 'Foreign',+ tenantId: 'foreign',+ }),+ );+ await request(app).get(`/skills/${skill._id}`).set('x-tenant-id', 'foreign').expect(404);+ await request(app)+ .patch(`/skills/${skill._id}`)+ .send({ expectedVersion: 1, body: 'x' })+ .expect(404);+});+it('allows viewing without allowing editing', async () => {+ allowEdit = false;+ await request(app).get(`/skills/${skillId}`).expect(200);+ await request(app)+ .patch(`/skills/${skillId}`)+ .send({ expectedVersion: 1, body: 'x' })+ .expect(404);+});+it('enforces authentication and the Skills role gate', async () => {+ authenticated = false;+ await request(app).get('/skills').expect(403);+ authenticated = true;+ allowUse = false;+ await request(app).get('/skills').expect(403);+});+it('keeps synchronized Skill content and files read-only', async () => {+ await inTenant(() =>+ db.updateSkill({ id: skillId, expectedVersion: 1, update: { source: 'github' } }),+ );+ await request(app).get(`/skills/${skillId}`).expect(200);+ await request(app)+ .patch(`/skills/${skillId}`)+ .send({ expectedVersion: 2, body: 'x' })+ .expect(403);+ await request(app)+ .put(`/skills/${skillId}/files/reference.md`)+ .send({ content: 'x' })+ .expect(403);+ expect(saveFile).not.toHaveBeenCalled();+});+it('writes nested text files through existing storage and rejects unsafe paths', async () => {+ await request(app)+ .put(`/skills/${skillId}/files/references/guide.md`)+ .send({ content: 'Guide' })+ .expect(200);+ expect(saveFile).toHaveBeenCalledWith(+ expect.objectContaining({+ skillId,+ relativePath: 'references/guide.md',+ content: 'Guide',+ mimeType: 'text/plain',+ }),+ );+ saveFile.mockClear();+ for (const path of [+ 'SKILL.md',+ 'SKILL.md/child.md',+ '..%2Fescape.md',+ 'bad%5Cpath.md',+ 'x'.repeat(1025),+ ]) {+ await request(app).put(`/skills/${skillId}/files/${path}`).send({ content: 'x' }).expect(400);+ }+ expect(saveFile).not.toHaveBeenCalled();+});+it('rejects raw downloads and malformed pagination', async () => {+ await request(app).get(`/skills/${skillId}/files/SKILL.md?raw=true`).expect(400);+ await request(app).get('/skills?limit=0').expect(400);+ await request(app).get('/skills?cursor=garbage').expect(400);+ await request(app).get('/skills?tenantId=foreign').expect(400);+});++it('preserves the resource-management capability without bypassing tenant isolation', async () => {+ allowEdit = false;+ canManage = true;+ allowView = false;+ const response = await request(app)+ .patch(`/skills/${skillId}`)+ .send({ expectedVersion: 1, body: 'Managed update' })+ .expect(200);+ expect(response.body.body).toBe('Managed update');+ const { skill } = await tenantStorage.run({ tenantId: 'foreign' }, () =>+ db.createSkill({+ name: 'foreign',+ description: 'Foreign tenant skill for capability isolation tests.',+ body: 'secret',+ author,+ authorName: 'Foreign',+ tenantId: 'foreign',+ }),+ );+ await request(app)+ .patch(`/skills/${skill._id}`)+ .send({ expectedVersion: 1, body: 'x' })+ .expect(404);+ const list = await request(app).get('/skills').expect(200);+ expect(list.body.data.map((row: { id: string }) => row.id)).toEqual([skillId]);+ canManage = false;+ const denied = await request(app).get('/skills').expect(200);+ expect(denied.body.data).toEqual([]);+});++it('reuses the authorized Skill on detail reads', async () => {+ await request(app).get(`/skills/${skillId}`).expect(200);+ expect(readSkill).toHaveBeenCalledTimes(1);+});+it('classifies content-policy blocks as invalid input and never writes the file', async () => {+ filters = {+ skills: {+ pii: {+ fields: ['file_text'],+ starterPatterns: [],+ customPatterns: [{ id: 'private', label: 'private text', regex: 'PRIVATE-TEXT' }],+ },+ },+ };+ const result = await request(app)+ .put(`/skills/${skillId}/files/notes.md`)+ .send({ content: 'PRIVATE-TEXT' })+ .expect(400);+ expect(result.body).toMatchObject({ error: { code: 'invalid_request' } });+ expect(saveFile).not.toHaveBeenCalled();+});+it('returns safe errors for storage failures', async () => {+ saveFile.mockRejectedValueOnce(new Error('secret-storage-path'));+ const result = await request(app)+ .put(`/skills/${skillId}/files/notes.md`)+ .send({ content: 'Notes' })+ .expect(500);+ expect(result.body).toEqual({+ error: { code: 'internal_error', message: 'Internal server error' },+ });+});++it('reuses the authorized Skill for SKILL.md reads', async () => {+ const response = await request(app).get(`/skills/${skillId}/files/SKILL.md`).expect(200);+ expect(response.body.content).toBe('Original instructions');+ expect(readSkill).toHaveBeenCalledTimes(1);+});+it.each(['1e2', '0x10'])('honors normalized pagination for limit=%s', async (limit) => {+ canManage = true;+ await inTenant(() =>+ db.createSkill({+ name: 'second-skill',+ description: 'Second skill for pagination validation.',+ body: 'Instructions',+ author,+ authorName: 'Test',+ tenantId,+ }),+ );+ const response = await request(app).get(`/skills?limit=${limit}`).expect(200);+ expect(response.body.data).toHaveLength(2);+});++it('authorizes and validates discovery before starting sync', async () => {+ allowUse = false;+ await request(app).get('/skills').expect(403);+ expect(beforeList).not.toHaveBeenCalled();+ allowUse = true;+ await request(app).get('/skills?limit=0').expect(400);+ expect(beforeList).not.toHaveBeenCalled();+ await request(app).get('/skills').expect(200);+ expect(beforeList).toHaveBeenCalledTimes(1);+ expect(beforeList.mock.invocationCallOrder[0]).toBeLessThan(+ accessible.mock.invocationCallOrder[0],+ );+});+it('continues discovery after a sync trigger failure', async () => {+ beforeList.mockRejectedValueOnce(new Error('sync unavailable'));+ await request(app).get('/skills').expect(200);+ expect(accessible).toHaveBeenCalledTimes(1);+});+it('does not enumerate ACLs for capability-managed lists', async () => {+ canManage = true;+ await request(app).get('/skills').expect(200);+ expect(accessible).not.toHaveBeenCalled();+ expect(publiclyAccessible).not.toHaveBeenCalled();+});+it('does not read discarded public status for details, updates, or conflicts', async () => {+ await request(app).get(`/skills/${skillId}`).expect(200);+ await request(app)+ .patch(`/skills/${skillId}`)+ .send({ expectedVersion: 1, body: 'Updated' })+ .expect(200);+ await request(app)+ .patch(`/skills/${skillId}`)+ .send({ expectedVersion: 1, body: 'Stale' })+ .expect(409);+ expect(publicStatus).not.toHaveBeenCalled();+});+it('authorizes file targets before charging upload quotas', async () => {+ allowUse = false;+ await request(app).put(`/skills/${skillId}/files/note.txt`).send({ content: 'text' }).expect(403);+ allowUse = true;+ allowEdit = false;+ await request(app).put(`/skills/${skillId}/files/note.txt`).send({ content: 'text' }).expect(404);+ allowEdit = true;+ await request(app)+ .put(`/skills/${new Types.ObjectId()}/files/note.txt`)+ .send({ content: 'text' })+ .expect(404);+ expect(uploadLimiter).not.toHaveBeenCalled();+ expect(saveFile).not.toHaveBeenCalled();+ await request(app).put(`/skills/${skillId}/files/note.txt`).send({ content: 'text' }).expect(200);+ expect(uploadLimiter).toHaveBeenCalledTimes(1);+ expect(readSkill).toHaveBeenCalledTimes(3);+});+it('stops storage writes when the upload limiter rejects', async () => {+ uploadLimiter.mockImplementationOnce((_req, res) => {+ res.sendStatus(429);+ });+ await request(app).put(`/skills/${skillId}/files/note.txt`).send({ content: 'text' }).expect(429);+ expect(saveFile).not.toHaveBeenCalled();+});+it('fails closed when the upload limiter errors', async () => {+ uploadLimiter.mockImplementationOnce((_req, _res, next) => next(new Error('limiter failure')));+ await request(app).put(`/skills/${skillId}/files/note.txt`).send({ content: 'text' }).expect(500);+ expect(saveFile).not.toHaveBeenCalled();+});++it('starts independent capability checks while waiting for the tenant-scoped Skill', async () => {+ let releaseSkill!: (value: null) => void;+ let capabilityStarted!: () => void;+ const started = new Promise<void>((resolve) => {+ capabilityStarted = resolve;+ });+ readSkill.mockImplementationOnce(+ () =>+ new Promise((resolve) => {+ releaseSkill = resolve;+ }),+ );+ capabilityCheck.mockImplementationOnce(async () => {+ capabilityStarted();+ return true;+ });+ const response = request(app)+ .get(`/skills/${skillId}`)+ .then((result) => result);+ await started;+ expect(readSkill).toHaveBeenCalledTimes(1);+ releaseSkill(null);+ expect((await response).status).toBe(404);+});diff --git a/packages/api/src/skills/management.ts b/packages/api/src/skills/management.tsnew file mode 100644index 0000000000..d33fec3506--- /dev/null+++ b/packages/api/src/skills/management.ts@@ -0,0 +1,365 @@+import { z } from 'zod';+import { logger, ResourceCapabilityMap, validateRelativePath } from '@librechat/data-schemas';+import {+ PermissionBits,+ Permissions,+ PermissionTypes,+ ResourceType,+} from 'librechat-data-provider';+import type { SkillFrontmatterValue, TSkill, TUpdateSkillPayload } from 'librechat-data-provider';+import type { Request, Response, RequestHandler } from 'express';+import type { SkillsHandlers, SkillsHandlersDeps } from './handlers';+import type { AgentManagementReadDeps } from '../agents/reads';+import type { ServerRequest } from '~/types';+import { agentManagementListSchema, mapAgentManagementError } from '../agents/management';+import { isContentFilterError } from '../middleware/contentFilter';+import { checkAccessWithRequestCache } from '../middleware/access';+import { assertSkillFileContentAllowed } from './protection';+import { getDeploymentSkillById } from './deployment';+import { resolveSkillFilePathParam } from './path';++const idSchema = z.string().regex(/^[a-f\d]{24}$/i);+const fields = {+ name: z.string(),+ displayTitle: z.string().optional(),+ description: z.string(),+ category: z.string().optional(),+ alwaysApply: z.boolean().optional(),+};+const frontmatterValue: z.ZodType<SkillFrontmatterValue> = z.lazy(() =>+ z.union([+ z.string(),+ z.number().finite(),+ z.boolean(),+ z.null(),+ z.array(frontmatterValue),+ z.record(frontmatterValue),+ ]),+);+export type SkillManagementUpdate = TUpdateSkillPayload & { expectedVersion: number };++export const skillManagementUpdateSchema: z.ZodType<SkillManagementUpdate> = z+ .object({+ name: fields.name.optional(),+ displayTitle: fields.displayTitle,+ description: fields.description.optional(),+ category: fields.category,+ alwaysApply: fields.alwaysApply,+ body: z.string().optional(),+ frontmatter: z.record(frontmatterValue).optional(),+ expectedVersion: z.number().int().positive(),+ })+ .strict()+ .refine((value) => Object.keys(value).length > 1, 'At least one update field is required');++const summarySchema = z.object({+ ...fields,+ id: idSchema,+ version: z.number().int().positive(),+ fileCount: z.number().int().nonnegative(),+ disableModelInvocation: z.boolean().optional(),+ userInvocable: z.boolean().optional(),+ allowedTools: z.array(z.string()).optional(),+ createdAt: z.string().datetime(),+ updatedAt: z.string().datetime(),+});+export type SkillManagementResponse = Pick<+ TSkill,+ | 'name'+ | 'displayTitle'+ | 'description'+ | 'category'+ | 'alwaysApply'+ | 'version'+ | 'fileCount'+ | 'disableModelInvocation'+ | 'userInvocable'+ | 'allowedTools'+ | 'createdAt'+ | 'updatedAt'+ | 'body'+ | 'frontmatter'+> & { id: string };++export const skillManagementResponseSchema: z.ZodType<SkillManagementResponse> =+ summarySchema.extend({+ body: z.string(),+ frontmatter: z.record(frontmatterValue).optional(),+ });+const fileSchema = z.object({+ relativePath: z.string(),+ filename: z.string(),+ mimeType: z.string(),+ bytes: z.number().int().nonnegative(),+});+const fileContentSchema = fileSchema.extend({+ content: z.string().optional(),+ isBinary: z.boolean(),+});+const fileUpdateSchema = z.object({ content: z.string().max(1024 * 1024) }).strict();+const listSchema = agentManagementListSchema;++type ManagementRequest = Request &+ Pick<ServerRequest, 'user' | 'config'> & {+ resourceAccess?: {+ resourceInfo: NonNullable<Awaited<ReturnType<SkillsHandlersDeps['getSkillById']>>>;+ };+ };++type SkillHandler = (req: ServerRequest, res: Response) => Promise<Response | undefined>;+type Projector = (body: unknown) => object;+export interface SkillManagementDeps {+ handlers: SkillsHandlers;+ beforeList?: (req: ServerRequest) => Promise<void>;+ fileWriteLimiters?: RequestHandler[];+ getSkillById: SkillsHandlersDeps['getSkillById'];+ getRoleByName: AgentManagementReadDeps['getRoleByName'];+ checkPermission: AgentManagementReadDeps['checkPermission'];+ hasCapability: AgentManagementReadDeps['hasCapability'];+ saveFile: (input: {+ req: ServerRequest;+ skillId: string;+ relativePath: string;+ content: string;+ mimeType: string;+ }) => Promise<{ relativePath: string; bytes: number }>;+}++function projectSkill(body: unknown, detail: boolean): object {+ const source = z.object({ _id: idSchema }).passthrough().parse(body);+ return (detail ? skillManagementResponseSchema : summarySchema).parse({+ ...source,+ id: source._id,+ });+}+function sendError(+ res: Response,+ code: Parameters<typeof mapAgentManagementError>[0],+ error?: unknown,+) {+ const mapped = mapAgentManagementError(code, error);+ if (code === 'not_found') mapped.body.error.message = 'Skill or file not found';+ return res.status(mapped.status).json(mapped.body);+}++/** Keep browser errors and persistence fields behind the versioned management contract. */+async function runHandler(+ req: ManagementRequest,+ res: Response,+ handler: SkillHandler,+ project: Projector,+) {+ let status = 200;+ let sent = false;+ const adapter = Object.create(res) as Response;+ adapter.status = (value: number) => {+ status = value;+ return adapter;+ };+ adapter.json = (body: unknown) => {+ sent = true;+ if (status >= 200 && status < 300) return res.status(status).json(project(body));+ if (status === 409) return sendError(res, 'conflict');+ if (status === 404) return sendError(res, 'not_found');+ if (status === 400) return sendError(res, 'invalid_request');+ if (status === 401 || status === 403) return sendError(res, 'permission_denied');+ return sendError(res, 'internal_error');+ };+ await handler(req as ServerRequest, adapter);+ return sent ? res : sendError(res, 'internal_error');+}++/** Wait for limiter admission or a terminal response; release listeners on every outcome. */+async function admitFileWrite(req: Request, res: Response, limiters: RequestHandler[]) {+ for (const limiter of limiters) {+ const admitted = await new Promise<boolean>((resolve, reject) => {+ const finish = () => settle(false);+ const settle = (allowed: boolean, error?: unknown) => {+ res.off('finish', finish);+ res.off('close', finish);+ if (error) reject(error);+ else resolve(allowed);+ };+ if (res.writableEnded || res.destroyed) return settle(false);+ res.once('finish', finish);+ res.once('close', finish);+ try {+ Promise.resolve(limiter(req, res, (error) => settle(!error, error))).catch((error) =>+ settle(false, error),+ );+ } catch (error) {+ settle(false, error);+ }+ });+ if (!admitted) return false;+ }+ return !res.writableEnded && !res.destroyed;+}++/** Machine API adapters reuse the browser Skills behavior after principal and resource checks. */+export function createSkillManagementHandlers(+ deps: SkillManagementDeps,+): Record<+ 'list' | 'get' | 'update' | 'listFiles' | 'getFile' | 'updateFile',+ (request: Request, res: Response) => Promise<Response>+> {+ async function canManageSkills(req: ManagementRequest): Promise<boolean> {+ if (!req.user) return false;+ const capability = ResourceCapabilityMap[ResourceType.SKILL];+ try {+ return capability != null && (await deps.hasCapability(req.user, capability));+ } catch {+ return false;+ }+ }+ function wrap(+ permission: PermissionBits | undefined,+ operation: (req: ManagementRequest, res: Response) => Promise<Response>,+ ) {+ return async (request: Request, res: Response): Promise<Response> => {+ const req = request as ManagementRequest;+ try {+ if (!req.user?.id || !req.user.tenantId) return sendError(res, 'permission_denied');+ const editing = permission === PermissionBits.EDIT;+ const allowed = await checkAccessWithRequestCache({+ req,+ user: req.user,+ permissionType: PermissionTypes.SKILLS,+ permissions: editing ? [Permissions.USE, Permissions.CREATE] : [Permissions.USE],+ getRoleByName: deps.getRoleByName,+ });+ if (!allowed) return sendError(res, 'permission_denied');+ if (permission !== undefined) {+ if (!idSchema.safeParse(req.params.id).success) return sendError(res, 'not_found');+ const [skill, canManage] = await Promise.all([+ deps.getSkillById(req.params.id),+ canManageSkills(req),+ ]);+ const deployment = getDeploymentSkillById(req.params.id);+ if (!skill || (!deployment && skill.tenantId !== req.user.tenantId))+ return sendError(res, 'not_found');+ if (+ !deployment &&+ !canManage &&+ !(await deps.checkPermission({+ userId: req.user.id,+ role: req.user.role,+ resourceType: ResourceType.SKILL,+ resourceId: skill._id,+ requiredPermission: permission,+ }))+ )+ return sendError(res, 'not_found');+ if (editing && (deployment || skill.source !== 'inline'))+ return sendError(res, 'permission_denied');+ req.resourceAccess = { resourceInfo: skill };+ }+ return await operation(req, res);+ } catch (error) {+ logger.error('[SkillManagement] Request failed', error);+ return sendError(res, 'internal_error');+ }+ };+ }+ return {+ list: wrap(undefined, async (req, res) => {+ const parsed = listSchema.safeParse(req.query);+ if (!parsed.success) return sendError(res, 'invalid_request', parsed.error);+ try {+ await deps.beforeList?.(req as ServerRequest);+ } catch (error) {+ logger.error('[SkillManagement] Failed to start request-scoped skill sync', error);+ }+ const manageTenantId = (await canManageSkills(req)) ? req.user?.tenantId : undefined;+ return runHandler(+ req,+ res,+ (request, response) =>+ deps.handlers.list(request, response, {+ ...parsed.data,+ manageTenantId,+ }),+ (body) => {+ const result = z+ .object({+ skills: z.array(z.unknown()),+ has_more: z.boolean(),+ after: z.string().nullable(),+ })+ .parse(body);+ const data = result.skills.map((skill) => projectSkill(skill, false));+ const ids = result.skills.map((skill) => z.object({ _id: idSchema }).parse(skill)._id);+ return {+ object: 'list',+ data,+ first_id: ids[0] ?? null,+ last_id: ids[ids.length - 1] ?? null,+ has_more: result.has_more,+ after: result.after,+ };+ },+ );+ }),+ get: wrap(PermissionBits.VIEW, (req, res) =>+ runHandler(+ req,+ res,+ (request, response) => deps.handlers.get(request, response, { includePublicStatus: false }),+ (body) => projectSkill(body, true),+ ),+ ),+ update: wrap(PermissionBits.EDIT, async (req, res) => {+ const parsed = skillManagementUpdateSchema.safeParse(req.body);+ if (!parsed.success) return sendError(res, 'invalid_request', parsed.error);+ req.body = parsed.data;+ return runHandler(+ req,+ res,+ (request, response) =>+ deps.handlers.patch(request, response, { includePublicStatus: false }),+ (body) => projectSkill(body, true),+ );+ }),+ listFiles: wrap(PermissionBits.VIEW, (req, res) =>+ runHandler(req, res, deps.handlers.listFiles, (body) => ({+ object: 'list',+ data: z.object({ files: z.array(fileSchema) }).parse(body).files,+ })),+ ),+ getFile: wrap(PermissionBits.VIEW, async (req, res) => {+ if (Object.keys(req.query).length > 0) return sendError(res, 'invalid_request');+ return runHandler(req, res, deps.handlers.downloadFile, (body) =>+ fileContentSchema.parse(body),+ );+ }),+ updateFile: wrap(PermissionBits.EDIT, async (req, res) => {+ const parsed = fileUpdateSchema.safeParse(req.body);+ if (!parsed.success) return sendError(res, 'invalid_request', parsed.error);+ const relativePath = resolveSkillFilePathParam(req.params.relativePath);+ if (relativePath == null || validateRelativePath(relativePath).length > 0)+ return sendError(res, 'invalid_request');+ const buffer = Buffer.from(parsed.data.content, 'utf8');+ if (buffer.length > 1024 * 1024 || buffer.includes(0))+ return sendError(res, 'invalid_request');+ try {+ assertSkillFileContentAllowed(req.config?.filters, {+ buffer,+ originalName: relativePath,+ relativePath,+ });+ } catch (error) {+ if (!isContentFilterError(error)) throw error;+ return sendError(res, 'invalid_request');+ }+ if (!(await admitFileWrite(req, res, deps.fileWriteLimiters ?? []))) return res;+ const result = await deps.saveFile({+ req: req as ServerRequest,+ skillId: req.params.id,+ relativePath,+ content: parsed.data.content,+ mimeType: 'text/plain',+ });+ return res.status(200).json({ relativePath: result.relativePath, bytes: result.bytes });+ }),+ };+}diff --git a/packages/data-schemas/src/methods/skill.ts b/packages/data-schemas/src/methods/skill.tsindex 8d03bc16c0..8c600f0892 100644--- a/packages/data-schemas/src/methods/skill.ts+++ b/packages/data-schemas/src/methods/skill.ts@@ -751,6 +751,8 @@ export type UpsertSkillFileInput = {};export type ListSkillsByAccessParams = {+ /** Trusted capability-authorized tenant scope; never accept directly from client input. */+ manageTenantId?: string;accessibleIds: Types.ObjectId[];category?: string;search?: string;@@ -1093,11 +1095,14 @@ export function createSkillMethods(const { ObjectId } = mongoose.Types;function buildSkillFilter(- params: Pick<ListSkillsByAccessParams, 'accessibleIds' | 'category' | 'search'>,+ params: Pick<+ ListSkillsByAccessParams,+ 'accessibleIds' | 'category' | 'search' | 'manageTenantId'+ >,): FilterQuery<ISkillDocument> {- const filter: FilterQuery<ISkillDocument> = {- _id: { $in: params.accessibleIds },- };+ const filter: FilterQuery<ISkillDocument> = params.manageTenantId+ ? { tenantId: params.manageTenantId }+ : { _id: { $in: params.accessibleIds } };if (params.category && params.category.length > 0) {filter.category = params.category;}