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
import {
ResourceType,
SkillsScope,
SKILL_NAME_MAX_LENGTH,
SKILL_DESCRIPTION_MAX_LENGTH,
SKILL_DESCRIPTION_SHORT_THRESHOLD as SKILL_DESCRIPTION_SHORT_THRESHOLD_SHARED,
SKILL_DISPLAY_TITLE_MAX_LENGTH,
SKILL_BODY_MAX_LENGTH,
SKILL_NAME_PATTERN as SKILL_NAME_PATTERN_SHARED,
} from 'librechat-data-provider';
import type { CodeEnvRef } from 'librechat-data-provider';
import type { Model, Types, FilterQuery } from 'mongoose';
import type {
ISkill,
ISkillDocument,
ISkillFile,
ISkillFileDocument,
ISkillSummary,
} from '~/types/skill';
import type { ISkillUploadIntentDocument } from '~/types/skillDeletion';
import type { IAgent } from '~/types/agent';
import { createSkillLifecycleMethods } from './skillLifecycle';
import { tenantSafeBulkWrite } from '~/utils/tenantBulkWrite';
import { isValidObjectIdString } from '~/utils/objectId';
import { stripYamlTrailingComment } from '~/utils/yaml';
import { escapeRegExp } from '~/utils/string';
import logger from '~/config/winston';
/** ---------- Validation helpers (pure) ---------- */
/**
* A single validation issue emitted by a skill validator. Most issues are
* errors and block the mutation; some are warnings (e.g. "description is
* awfully short, the agent may undertrigger the skill") that surface inline
* coaching without rejecting the request.
*/
export type ValidationIssue = {
field: string;
code: string;
message: string;
/**
* Defaults to `'error'` when omitted. Errors cause `createSkill` /
* `updateSkill` to throw with code `SKILL_VALIDATION_FAILED`; warnings
* are surfaced on successful responses so the UI can show inline feedback.
*/
severity?: 'error' | 'warning';
};
export type DeleteSkillCleanupStep =
| 'agent_allowlists'
| 'skill_files'
| 'permissions'
| 'upload_intents';
export type DeleteSkillResult = {
/** Whether this call removed the Skill row. */
deleted: boolean;
/** Whether the Skill row is absent after this call, including an idempotent retry. */
skillAbsent: boolean;
/** Whether every dependent database cleanup step completed. */
cleanupComplete: boolean;
failedCleanupSteps: DeleteSkillCleanupStep[];
};
type SkillFileUpsertResult = {
value: (ISkillFile & { _id: Types.ObjectId }) | null;
lastErrorObject?: {
updatedExisting?: boolean;
};
};
/** Partition an issue list into blocking errors and non-blocking warnings. */
export function partitionIssues(issues: ValidationIssue[]): {
errors: ValidationIssue[];
warnings: ValidationIssue[];
} {
const errors: ValidationIssue[] = [];
const warnings: ValidationIssue[] = [];
for (const issue of issues) {
if (issue.severity === 'warning') {
warnings.push(issue);
} else {
errors.push(issue);
}
}
return { errors, warnings };
}
const SKILL_NAME_MAX = SKILL_NAME_MAX_LENGTH;
const SKILL_DESCRIPTION_MAX = SKILL_DESCRIPTION_MAX_LENGTH;
const SKILL_DESCRIPTION_SHORT_THRESHOLD = SKILL_DESCRIPTION_SHORT_THRESHOLD_SHARED;
const SKILL_DISPLAY_TITLE_MAX = SKILL_DISPLAY_TITLE_MAX_LENGTH;
const SKILL_BODY_MAX = SKILL_BODY_MAX_LENGTH;
const SKILL_FILE_PATH_MAX = 500;
const SKILL_NAME_PATTERN = SKILL_NAME_PATTERN_SHARED;
const RELATIVE_PATH_CHARS = /^[a-zA-Z0-9._\-/]+$/;
/**
* Brand namespaces reserved for Anthropic-published skills and first-party
* bundles. Matched as prefixes, so `anthropic-helper` is rejected but
* `research-anthropic-helper` is fine.
*/
const RESERVED_NAME_PREFIXES = ['anthropic-', 'claude-'];
/**
* Slash-command names that collide with LibreChat / Claude Code CLI commands.
* A skill with one of these names would shadow a real command in any
* slash-command UI. Matched exactly (not as prefix).
*/
const RESERVED_NAME_WORDS = new Set([
'help',
'clear',
'compact',
'model',
'exit',
'quit',
'settings',
'anthropic',
'claude',
]);
export function validateSkillName(name: unknown): ValidationIssue[] {
const issues: ValidationIssue[] = [];
if (typeof name !== 'string' || name.length === 0) {
issues.push({ field: 'name', code: 'REQUIRED', message: 'Name is required' });
return issues;
}
if (name.length > SKILL_NAME_MAX) {
issues.push({
field: 'name',
code: 'TOO_LONG',
message: `Name must be ${SKILL_NAME_MAX} characters or less`,
});
}
if (!SKILL_NAME_PATTERN.test(name)) {
issues.push({
field: 'name',
code: 'INVALID_FORMAT',
message:
'Name must be kebab-case: start with a lowercase letter or digit and contain only lowercase letters, digits, and hyphens',
});
}
const lowered = name.toLowerCase();
if (RESERVED_NAME_PREFIXES.some((prefix) => lowered.startsWith(prefix))) {
issues.push({
field: 'name',
code: 'RESERVED_PREFIX',
message: `Name cannot start with ${RESERVED_NAME_PREFIXES.map((p) => `"${p}"`).join(' or ')}`,
});
}
if (RESERVED_NAME_WORDS.has(lowered)) {
issues.push({
field: 'name',
code: 'RESERVED_WORD',
message: `"${name}" is a reserved name`,
});
}
return issues;
}
export function validateSkillDescription(description: unknown): ValidationIssue[] {
const issues: ValidationIssue[] = [];
if (typeof description !== 'string' || description.trim().length === 0) {
issues.push({
field: 'description',
code: 'REQUIRED',
message: 'Description is required',
});
return issues;
}
if (description.length > SKILL_DESCRIPTION_MAX) {
issues.push({
field: 'description',
code: 'TOO_LONG',
message: `Description must be ${SKILL_DESCRIPTION_MAX} characters or less`,
});
}
if (description.trim().length < SKILL_DESCRIPTION_SHORT_THRESHOLD) {
issues.push({
field: 'description',
code: 'TOO_SHORT',
severity: 'warning',
message:
'Short descriptions may cause the agent to miss triggering opportunities — aim for a concrete "when to use this skill" sentence.',
});
}
return issues;
}
export function validateSkillBody(body: unknown): ValidationIssue[] {
const issues: ValidationIssue[] = [];
if (body !== undefined && typeof body !== 'string') {
issues.push({ field: 'body', code: 'INVALID_TYPE', message: 'Body must be a string' });
return issues;
}
if (typeof body === 'string' && body.length > SKILL_BODY_MAX) {
issues.push({
field: 'body',
code: 'TOO_LONG',
message: `Body must be ${SKILL_BODY_MAX} characters or less`,
});
}
return issues;
}
export function validateSkillDisplayTitle(displayTitle: unknown): ValidationIssue[] {
if (displayTitle === undefined || displayTitle === null) {
return [];
}
if (typeof displayTitle !== 'string') {
return [
{ field: 'displayTitle', code: 'INVALID_TYPE', message: 'Display title must be a string' },
];
}
if (displayTitle.length > SKILL_DISPLAY_TITLE_MAX) {
return [
{
field: 'displayTitle',
code: 'TOO_LONG',
message: `Display title must be ${SKILL_DISPLAY_TITLE_MAX} characters or less`,
},
];
}
return [];
}
/**
* Validate the top-level `alwaysApply` column input. Mirrors the boolean
* check on `frontmatter['always-apply']` so a loosely-typed API caller
* sending `{"alwaysApply": "false"}` (string) gets a clean 400 at the
* validation boundary instead of relying on Mongoose casting quirks to
* coerce the value.
*
* `undefined` is the only pass-through value (meaning "don't touch this
* field"). `null` is rejected: PATCH forwards any non-`undefined` value
* straight into `$set`, so a `null` payload would persist `null` in a
* boolean column, leaving the skill in a state that is neither "on" nor
* "off" while `listAlwaysApplySkills` only matches `true`.
*/
export function validateAlwaysApply(alwaysApply: unknown): ValidationIssue[] {
if (alwaysApply === undefined) {
return [];
}
if (typeof alwaysApply !== 'boolean') {
return [
{
field: 'alwaysApply',
code: 'INVALID_TYPE',
message: 'alwaysApply must be a boolean',
},
];
}
return [];
}
/**
* Known fields allowed inside a skill's YAML frontmatter. Anything else is
* reported as a warning (see `validateSkillFrontmatter`) rather than rejected:
* the frontmatter convention keeps growing, and a single unrecognized key in
* one `SKILL.md` used to fail its whole GitHub sync source. The list is derived
* from Anthropic's Agent Skills spec plus the fields LibreChat needs to pass
* through (`name`/`description` are duplicated from the top-level columns
* because real `SKILL.md` files include them in their frontmatter block).
*/
const ALLOWED_FRONTMATTER_KEYS = new Set<string>([
'name',
'description',
'when-to-use',
'allowed-tools',
'arguments',
'argument-hint',
'user-invocable',
'disable-model-invocation',
'always-apply',
'alwaysApply',
'model',
'effort',
'context',
'agent',
'paths',
'shell',
'hooks',
'version',
'license',
'compatibility',
'metadata',
'references',
]);
const CANONICAL_FRONTMATTER_KEYS = new Map(
Array.from(ALLOWED_FRONTMATTER_KEYS, (key) => [key.toLowerCase(), key]),
);
export function getCanonicalSkillFrontmatterKey(key: string): string | undefined {
return CANONICAL_FRONTMATTER_KEYS.get(key.toLowerCase());
}
export function normalizeSkillFrontmatterKeys(
frontmatter: Record<string, unknown>,
): { frontmatter: Record<string, unknown> } | { error: string } {
const normalized = Object.create(null) as Record<string, unknown>;
const recognizedKeys = new Map<string, string>();
for (const [key, value] of Object.entries(frontmatter)) {
const canonicalKey = getCanonicalSkillFrontmatterKey(key);
if (canonicalKey) {
const previousKey = recognizedKeys.get(canonicalKey);
if (previousKey) {
return {
error: `Recognized frontmatter keys "${previousKey}" and "${key}" both resolve to "${canonicalKey}"`,
};
}
recognizedKeys.set(canonicalKey, key);
}
normalized[canonicalKey ?? key] = value;
}
return { frontmatter: normalized };
}
const FRONTMATTER_MAX_STRING = 2000;
const FRONTMATTER_MAX_ARRAY = 100;
const FRONTMATTER_MAX_DEPTH = 4;
const NON_PERSISTABLE_FRONTMATTER_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
type FrontmatterKind = 'string' | 'number' | 'boolean' | 'stringArray';
const FRONTMATTER_KIND: Record<string, FrontmatterKind | FrontmatterKind[]> = {
name: 'string',
description: 'string',
'when-to-use': 'string',
'allowed-tools': ['string', 'stringArray'],
arguments: ['string', 'stringArray'],
'argument-hint': 'string',
'user-invocable': 'boolean',
'disable-model-invocation': 'boolean',
'always-apply': 'boolean',
alwaysApply: 'boolean',
model: 'string',
effort: ['string', 'number'],
context: 'string',
agent: 'string',
paths: ['string', 'stringArray'],
shell: 'string',
version: 'string',
license: 'string',
compatibility: 'string',
};
function isPlainObject(value: unknown): value is Record<string, unknown> {
if (typeof value !== 'object' || value === null || Array.isArray(value)) {
return false;
}
const prototype = Object.getPrototypeOf(value);
return prototype === Object.prototype || prototype === null;
}
function isValidFrontmatterKey(key: string): boolean {
return !key.includes('\u0000') && !NON_PERSISTABLE_FRONTMATTER_KEYS.has(key);
}
function containsInvalidFrontmatterKey(value: unknown, depth = 0): boolean {
if (depth > FRONTMATTER_MAX_DEPTH) {
return false;
}
if (Array.isArray(value)) {
return value.some((nestedValue) => containsInvalidFrontmatterKey(nestedValue, depth + 1));
}
if (!isPlainObject(value)) {
return false;
}
return Object.entries(value).some(
([key, nestedValue]) =>
!isValidFrontmatterKey(key) || containsInvalidFrontmatterKey(nestedValue, depth + 1),
);
}
function isStringArray(value: unknown): value is string[] {
return (
Array.isArray(value) &&
value.length <= FRONTMATTER_MAX_ARRAY &&
value.every((v) => typeof v === 'string' && v.length <= FRONTMATTER_MAX_STRING)
);
}
function matchesKind(value: unknown, kind: FrontmatterKind): boolean {
if (kind === 'string') {
return typeof value === 'string' && value.length <= FRONTMATTER_MAX_STRING;
}
if (kind === 'number') {
return typeof value === 'number' && Number.isFinite(value);
}
if (kind === 'boolean') {
return typeof value === 'boolean';
}
return isStringArray(value);
}
/**
* Shallow structural sanity check for `hooks`/`metadata` objects. We don't
* know their full schema yet, so we just verify they are plain objects with
* JSON-serializable leaf values up to a max depth — enough to block pathological
* payloads without constraining legitimate frontmatter extensions.
*/
function isJsonSafe(value: unknown, depth: number): boolean {
if (depth > FRONTMATTER_MAX_DEPTH) {
return false;
}
if (value === null) return true;
const t = typeof value;
if (t === 'string') return (value as string).length <= FRONTMATTER_MAX_STRING;
if (t === 'number') return Number.isFinite(value);
if (t === 'boolean') return true;
if (Array.isArray(value)) {
if (value.length > FRONTMATTER_MAX_ARRAY) return false;
return value.every((v) => isJsonSafe(v, depth + 1));
}
if (isPlainObject(value)) {
return Object.entries(value).every(
([key, nestedValue]) => isValidFrontmatterKey(key) && isJsonSafe(nestedValue, depth + 1),
);
}
return false;
}
/**
* Validate a skill's structured YAML frontmatter. Known keys are type-checked
* against `FRONTMATTER_KIND`; `hooks`, `metadata` and `references` fall back to
* a shallow JSON-safety check because their full schemas live outside this
* module. Unknown keys are reported as warnings, not errors: authors regularly
* carry keys from other tooling, and failing the skill for one of them takes
* down every other skill in the same GitHub sync source.
*/
export function validateSkillFrontmatter(frontmatter: unknown): ValidationIssue[] {
if (frontmatter === undefined || frontmatter === null) {
return [];
}
if (!isPlainObject(frontmatter)) {
return [
{
field: 'frontmatter',
code: 'INVALID_TYPE',
message: 'Frontmatter must be a plain object',
},
];
}
const normalized = normalizeSkillFrontmatterKeys(frontmatter);
if ('error' in normalized) {
return [
{
field: 'frontmatter',
code: 'DUPLICATE_KEY',
message: normalized.error,
},
];
}
const issues: ValidationIssue[] = [];
for (const [key, value] of Object.entries(normalized.frontmatter)) {
if (!isValidFrontmatterKey(key)) {
issues.push({
field: 'frontmatter',
code: 'INVALID_KEY',
message: 'Frontmatter keys must be persistable object property names',
});
continue;
}
if (containsInvalidFrontmatterKey(value)) {
issues.push({
field: `frontmatter.${key}`,
code: 'INVALID_KEY',
message: `"${key}" contains a frontmatter key that cannot be persisted`,
});
continue;
}
if (!ALLOWED_FRONTMATTER_KEYS.has(key)) {
issues.push({
field: `frontmatter.${key}`,
code: 'UNKNOWN_KEY',
severity: 'warning',
message: `"${key}" is not a recognized frontmatter key and is stored as-is`,
});
/* The key is tolerated, its value still is not: an unrecognized key is
persisted, so it stays inside the same depth, array and string bounds
every structured key is held to. */
if (!isJsonSafe(value, 0)) {
issues.push({
field: `frontmatter.${key}`,
code: 'INVALID_SHAPE',
message: `"${key}" must be a JSON-safe value (max depth ${FRONTMATTER_MAX_DEPTH}, max string ${FRONTMATTER_MAX_STRING}, max array ${FRONTMATTER_MAX_ARRAY})`,
});
}
continue;
}
if (key === 'references') {
if (!isJsonSafe(value, 0)) {
issues.push({
field: 'frontmatter.references',
code: 'INVALID_SHAPE',
message: `"references" must be a JSON-safe value (max depth ${FRONTMATTER_MAX_DEPTH}, max string ${FRONTMATTER_MAX_STRING})`,
});
}
continue;
}
if (key === 'hooks' || key === 'metadata') {
if (!isPlainObject(value) || !isJsonSafe(value, 0)) {
issues.push({
field: `frontmatter.${key}`,
code: 'INVALID_SHAPE',
message: `"${key}" must be a plain JSON-safe object (max depth ${FRONTMATTER_MAX_DEPTH}, max string ${FRONTMATTER_MAX_STRING})`,
});
}
continue;
}
const expected = FRONTMATTER_KIND[key];
if (!expected) {
continue;
}
const kinds = Array.isArray(expected) ? expected : [expected];
if (!kinds.some((kind) => matchesKind(value, kind))) {
issues.push({
field: `frontmatter.${key}`,
code: 'INVALID_TYPE',
message: `"${key}" must be ${kinds.join(' or ')}`,
});
}
}
return issues;
}
export function validateRelativePath(relativePath: unknown): ValidationIssue[] {
const issues: ValidationIssue[] = [];
if (typeof relativePath !== 'string' || relativePath.length === 0) {
issues.push({
field: 'relativePath',
code: 'REQUIRED',
message: 'Relative path is required',
});
return issues;
}
if (relativePath.length > SKILL_FILE_PATH_MAX) {
issues.push({
field: 'relativePath',
code: 'TOO_LONG',
message: `Relative path must be ${SKILL_FILE_PATH_MAX} characters or less`,
});
}
if (relativePath.startsWith('/') || relativePath.startsWith('\\')) {
issues.push({
field: 'relativePath',
code: 'ABSOLUTE_PATH',
message: 'Relative path must not start with a slash',
});
}
if (!RELATIVE_PATH_CHARS.test(relativePath)) {
issues.push({
field: 'relativePath',
code: 'INVALID_CHARS',
message: 'Relative path contains invalid characters',
});
}
const segments = relativePath.split('/');
if (segments.some((s) => s === '' || s === '.' || s === '..')) {
issues.push({
field: 'relativePath',
code: 'TRAVERSAL',
message: 'Relative path cannot contain empty segments or "." / ".."',
});
}
if (relativePath === 'SKILL.md' || segments[0] === 'SKILL.md') {
issues.push({
field: 'relativePath',
code: 'RESERVED',
message: 'SKILL.md is managed via the skill body, not file uploads',
});
}
return issues;
}
export function inferSkillFileCategory(
relativePath: string,
): 'script' | 'reference' | 'asset' | 'other' {
const [top] = relativePath.split('/');
if (top === 'scripts') return 'script';
if (top === 'references') return 'reference';
if (top === 'assets') return 'asset';
return 'other';
}
/** ---------- Method factory ---------- */
export interface SkillDeps {
/** Removes all ACL entries for a resource. Injected from PermissionService. */
removeAllPermissions: (params: { resourceType: string; resourceId: unknown }) => Promise<void>;
/** Returns resource IDs solely owned by the given user. From createAclEntryMethods. */
getSoleOwnedResourceIds: (
userObjectId: Types.ObjectId,
resourceTypes: string | string[],
) => Promise<Types.ObjectId[]>;
}
export type CreateSkillInput = {
name: string;
displayTitle?: string;
description: string;
body?: string;
frontmatter?: Record<string, unknown>;
category?: string;
/** A 24-hex string is accepted and converted to an ObjectId here. */
author: Types.ObjectId | string;
authorName: string;
source?: 'inline' | 'github' | 'notion';
sourceMetadata?: Record<string, unknown>;
/**
* When `true`, the skill is auto-primed into every turn. Callers pass this
* through alongside `frontmatter` so the boolean lands on both the indexed
* first-class column (queryable) and the raw frontmatter bag (inspectable).
*/
alwaysApply?: boolean;
tenantId?: string;
};
export type UpdateSkillInput = {
name?: string;
displayTitle?: string;
description?: string;
body?: string;
frontmatter?: Record<string, unknown>;
category?: string;
alwaysApply?: boolean;
source?: 'inline' | 'github' | 'notion';
sourceMetadata?: Record<string, unknown>;
};
export type GetAuthorSkillByNameParams = {
name: string;
author: Types.ObjectId | string;
tenantId?: string | null;
};
/**
* Maps the runtime-enforced frontmatter fields onto their first-class
* column equivalents. Returns only the keys that were explicitly set on the
* frontmatter so callers can decide whether to write `undefined` (skip the
* `$set`) versus a concrete value.
*
* `allowed-tools` accepts string or string[] per the validator; both are
* normalized to an array. Empty strings are filtered out so a stray comma
* in YAML doesn't leak through as `''`.
*/
export function deriveStructuredFrontmatterFields(
frontmatter: Record<string, unknown> | undefined,
): {
disableModelInvocation?: boolean;
userInvocable?: boolean;
allowedTools?: string[];
} {
if (!frontmatter || typeof frontmatter !== 'object') {
return {};
}
const normalized = normalizeSkillFrontmatterKeys(frontmatter);
if ('error' in normalized) {
return {};
}
frontmatter = normalized.frontmatter;
const derived: {
disableModelInvocation?: boolean;
userInvocable?: boolean;
allowedTools?: string[];
} = {};
const disableModelInvocationRaw = frontmatter['disable-model-invocation'];
if (typeof disableModelInvocationRaw === 'boolean') {
derived.disableModelInvocation = disableModelInvocationRaw;
}
const userInvocableRaw = frontmatter['user-invocable'];
if (typeof userInvocableRaw === 'boolean') {
derived.userInvocable = userInvocableRaw;
}
const allowedToolsRaw = frontmatter['allowed-tools'];
if (typeof allowedToolsRaw === 'string') {
/**
* YAML scalars like `allowed-tools: web_search` are parsed as a single
* string. Wrap into a one-element array; we deliberately do NOT split
* on commas — the validator already accepts string-array form and
* trying to "be helpful" by splitting `"web_search, file_search"`
* would silently invent semantics the spec doesn't promise.
*/
if (allowedToolsRaw.length > 0) {
derived.allowedTools = [allowedToolsRaw];
}
} else if (Array.isArray(allowedToolsRaw)) {
derived.allowedTools = allowedToolsRaw.filter(
(entry): entry is string => typeof entry === 'string' && entry.length > 0,
);
}
return derived;
}
/**
* Read-time fallback for skills authored before the structured columns
* existed: if the column is unset but the matching key is present in
* `frontmatter`, fill the column in on the returned object so downstream
* runtime checks (`skill.userInvocable === false`,
* `skill.disableModelInvocation === true`, `skill.allowedTools`) behave
* the same way they would for a freshly-created skill.
*
* Side-effect-free w.r.t. the DB (no writes), but mutates its argument
* in place and returns the same reference. Callers passing a `lean()`
* doc this is fine — the doc is a fresh JS object owned by the caller.
* When the skill is next updated, `updateSkill` re-derives and persists
* the columns naturally, so this fallback gradually becomes a no-op.
*
* Skills with the columns already populated short-circuit to no-op.
*/
export function backfillDerivedFromFrontmatter<
T extends {
frontmatter?: Record<string, unknown>;
disableModelInvocation?: boolean;
userInvocable?: boolean;
allowedTools?: string[];
},
>(skill: T | null): T | null {
if (!skill || !skill.frontmatter) {
return skill;
}
const derived = deriveStructuredFrontmatterFields(skill.frontmatter);
if (skill.disableModelInvocation === undefined && derived.disableModelInvocation !== undefined) {
skill.disableModelInvocation = derived.disableModelInvocation;
}
if (skill.userInvocable === undefined && derived.userInvocable !== undefined) {
skill.userInvocable = derived.userInvocable;
}
if (skill.allowedTools === undefined && derived.allowedTools !== undefined) {
skill.allowedTools = derived.allowedTools;
}
return skill;
}
function getAlwaysApplyFrontmatterValue(
frontmatter: Record<string, unknown> | undefined,
): boolean | undefined {
const canonical = frontmatter?.['always-apply'];
if (typeof canonical === 'boolean') {
return canonical;
}
const camelAlias = frontmatter?.alwaysApply;
if (typeof camelAlias === 'boolean') {
return camelAlias;
}
return undefined;
}
export type UpsertSkillFileInput = {
/** When supplied, replace only this stored revision; never recreate a deleted file. */
expectedFileId?: string;
/** Insert only when the path is absent, even if another writer creates it first. */
createOnly?: boolean;
/** Keep the superseded blob until a multi-step writer commits or restores this file. */
cleanupHoldOwner?: string;
skillId: Types.ObjectId | string;
relativePath: string;
file_id: string;
filename: string;
filepath: string;
storageKey?: string;
storageRegion?: string;
source: string;
sourceMetadata?: Record<string, unknown>;
mimeType: string;
bytes: number;
isExecutable?: boolean;
author: Types.ObjectId | string;
tenantId?: string;
};
export type ListSkillsByAccessParams = {
/** Trusted capability-authorized tenant scope; never accept directly from client input. */
manageTenantId?: string;
accessibleIds: Types.ObjectId[];
category?: string;
search?: string;
limit: number;
cursor?: string | null;
};
export type ListSkillsByAccessResult = {
/**
* Summary rows — `body` and `frontmatter` are intentionally omitted at the
* query projection layer to keep list payloads small. Callers that need the
* full document must fetch the detail via `getSkillById`.
*/
skills: Array<ISkillSummary & { _id: Types.ObjectId }>;
has_more: boolean;
after: string | null;
};
export type ListAlwaysApplySkillsParams = {
accessibleIds: Types.ObjectId[];
/** Max rows to return per page. The caller paginates to fill an active-state budget. */
limit: number;
/** Opaque cursor from a prior page. `null` / absent = first page. */
cursor?: string | null;
};
export type ListAlwaysApplySkillsResult = {
/**
* Rows for `alwaysApply: true` skills within `accessibleIds` on this page.
* Returns `body` eagerly — callers prime the full SKILL.md on every turn,
* so round-tripping through `getSkillById` per skill would double DB ops.
*/
skills: Array<{
_id: Types.ObjectId;
name: string;
body: string;
author: Types.ObjectId;
frontmatter?: Record<string, unknown>;
allowedTools?: string[];
version: number;
}>;
/** `true` when another page exists beyond this one. */
has_more: boolean;
/** Cursor for the next page, or `null` when `has_more` is `false`. */
after: string | null;
};
export type UpdateSkillResult =
| {
status: 'updated';
skill: ISkill & { _id: Types.ObjectId };
warnings: ValidationIssue[];
}
| { status: 'conflict'; current: ISkill & { _id: Types.ObjectId } }
| { status: 'not_found' };
export type CreateSkillResult = {
skill: ISkill & { _id: Types.ObjectId };
warnings: ValidationIssue[];
};
type BodyAlwaysApplyResult =
| { status: 'absent' }
| { status: 'valid'; value: boolean }
| { status: 'invalid' };
/**
* Extractor for the `always-apply` / `alwaysApply` flag sitting inside a SKILL.md body's
* YAML frontmatter block. The REST edit flow lets users rewrite the full
* SKILL.md text via `update.body` without a structured `frontmatter`
* object, so this is the only signal we have for "user flipped
* `always-apply:` or `alwaysApply:` inline in their editor".
*
* Returns a discriminated union so callers can tell:
* - `absent` — no always-apply key (leave column alone; could be
* "user removed the flag" or "user hasn't written it yet" — both
* resolve to no-op). An empty value (`always-apply:` with nothing
* after the colon) is also treated as absent to allow mid-edit
* placeholder states without rejecting a save.
* - `valid` — parsed cleanly as `true` / `false` (case-insensitive,
* quote-tolerant, YAML inline-comment-tolerant).
* - `invalid` — key is present with a non-empty value that isn't a
* recognizable boolean (e.g. `tru`, `yes`, `1`). Validation rejects
* this rather than silently ignoring so `always-apply: tru` typos
* surface as 400s instead of drifting the column from what the
* saved SKILL.md text says. When both forms are present, the canonical
* `always-apply` form wins because existing files may already rely on it.
*/
function extractAlwaysApplyFromBody(body: string | undefined): BodyAlwaysApplyResult {
if (typeof body !== 'string' || body.length === 0) {
return { status: 'absent' };
}
const trimmed = body.trim();
if (!trimmed.startsWith('---')) {
return { status: 'absent' };
}
const after = trimmed.slice(3);
const closingIdx = after.indexOf('\n---');
if (closingIdx === -1) {
return { status: 'absent' };
}
const block = after.slice(0, closingIdx);
let aliasResult: BodyAlwaysApplyResult | undefined;
for (const line of block.split('\n')) {
const colon = line.indexOf(':');
if (colon === -1) {
continue;
}
const key = line.slice(0, colon).trim();
const normalizedKey = key.toLowerCase();
if (normalizedKey !== 'always-apply' && normalizedKey !== 'alwaysapply') {
continue;
}
// Strip the YAML inline comment BEFORE unquoting — a line like
// `always-apply: "true" # note` has both, and if we only handled
// whole-line quoting first, the quoted branch wouldn't match and
// the comment-strip would leave `"true"` which parses as invalid.
let value = stripYamlTrailingComment(line.slice(colon + 1).trim()).trim();
if (value === '') {
const result: BodyAlwaysApplyResult = { status: 'absent' };
if (normalizedKey === 'always-apply') {
return result;
}
aliasResult = result;
continue;
}
if (
value.length >= 2 &&
((value[0] === '"' && value[value.length - 1] === '"') ||
(value[0] === "'" && value[value.length - 1] === "'"))
) {
value = value.slice(1, -1);
}
value = value.trim();
if (value === '') {
const result: BodyAlwaysApplyResult = { status: 'absent' };
if (normalizedKey === 'always-apply') {
return result;
}
aliasResult = result;
continue;
}
const lowered = value.toLowerCase();
let result: BodyAlwaysApplyResult;
if (lowered === 'true') {
result = { status: 'valid', value: true };
} else if (lowered === 'false') {
result = { status: 'valid', value: false };
} else {
result = { status: 'invalid' };
}
if (normalizedKey === 'always-apply') {
return result;
}
aliasResult = result;
}
return aliasResult ?? { status: 'absent' };
}
/**
* Resolve the effective `alwaysApply` boolean for a create/update call.
*
* The indexed `alwaysApply` column is the source of truth for auto-priming
* queries; it can also be carried inline inside the SKILL.md `body` or in
* the structured `frontmatter` bag. All three surfaces must stay in sync
* or a skill edit that flips `always-apply:` in the body would leave the
* column stale and the UI / auto-priming query would use the old value.
*
* Precedence:
* 1. An explicit top-level `alwaysApply` wins (caller overrides).
* 2. Otherwise, derive from `frontmatter['always-apply']` or the accepted
* alias `frontmatter.alwaysApply` when either is a strict boolean.
* 3. Otherwise, parse `always-apply:` / `alwaysApply:` out of the SKILL.md body
* frontmatter block (covers the UI edit flow that sends only
* `body` without a structured `frontmatter` object).
* 4. Otherwise, return `fallback` (typically `false` on create, or the
* current column value on update so an update that doesn't touch
* any of the three sources leaves the column alone).
*/
function resolveAlwaysApplyFromInput(
explicit: boolean | undefined,
frontmatter: Record<string, unknown> | undefined,
body: string | undefined,
fallback: boolean,
/* Callers that have already parsed the body (e.g. because they also
ran body-level validation) can thread the result in to avoid a
second parse. Leave undefined to let the helper parse on demand. */
precomputedBody?: BodyAlwaysApplyResult,
): boolean {
if (typeof explicit === 'boolean') {
return explicit;
}
const fromFrontmatter = getAlwaysApplyFrontmatterValue(frontmatter);
if (typeof fromFrontmatter === 'boolean') {
return fromFrontmatter;
}
const fromBody = precomputedBody ?? extractAlwaysApplyFromBody(body);
if (fromBody.status === 'valid') {
return fromBody.value;
}
return fallback;
}
/**
* Narrows candidate skill ids to those backed by an existing Skill doc or
* recognized by an injected external skill registry.
* Existence-only check (no ACL) so pruning an agent allowlist never drops
* skills the saving user merely can't view. Preserves input order, dedupes,
* and drops malformed ids — they can't reference anything. Candidates are
* lowercased before comparison: `isValidObjectIdString` accepts uppercase
* hex, but `_id.toString()` is always lowercase, and a casing mismatch
* would silently drop a valid id (and an emptied allowlist means the full
* catalog — the opposite of the configured scope).
*/
export async function filterExistingSkillIds(
mongoose: typeof import('mongoose'),
skillIds: string[],
isExternalSkillId?: (id: string) => boolean,
): Promise<string[]> {
const candidates = [
...new Set(skillIds.filter(isValidObjectIdString).map((id) => id.toLowerCase())),
];
if (candidates.length === 0) {
return [];
}
const Skill = mongoose.models.Skill as Model<ISkillDocument>;
const docs = await Skill.find(
{
_id: { $in: candidates.map((id) => new mongoose.Types.ObjectId(id)) },
deletingAt: { $exists: false },
},
{ _id: 1 },
).lean<Array<{ _id: Types.ObjectId }>>();
const existing = new Set(docs.map((doc) => doc._id.toString()));
return candidates.filter((id) => existing.has(id) || isExternalSkillId?.(id) === true);
}
export function createSkillMethods(
mongoose: typeof import('mongoose'),
deps: SkillDeps,
): {
createSkill: (data: CreateSkillInput) => Promise<CreateSkillResult>;
getSkillById: (id: string | Types.ObjectId) => Promise<(ISkill & { _id: Types.ObjectId }) | null>;
getSkillByName: (
name: string,
accessibleIds: Types.ObjectId[],
options?: {
/**
* Manual paths (`$` popover, always-apply once Phase 5 lands) set
* this so a same-name newer `userInvocable: false` duplicate can't
* shadow the older user-invocable doc the popover surfaced.
* Disable-model-invocation status is irrelevant here — manually-
* primed disabled skills are explicitly supported (iter 4).
*/
preferUserInvocable?: boolean;
/**
* Model paths (`skill` / `read_file` tool handlers) set this so a
* same-name newer `disable-model-invocation: true` duplicate can't
* shadow the cataloged model-invocable doc. User-invocability is
* irrelevant here — `userInvocable: false` skills are model-only
* and remain valid model-invocation targets.
*
* Both flags fall back to the newest match when no preferred doc
* exists, so handlers can still fire their explicit-rejection
* error paths (e.g. "cannot be invoked by the model" in the
* disabled-only case).
*/
preferModelInvocable?: boolean;
},
) => Promise<(ISkill & { _id: Types.ObjectId }) | null>;
getAuthorSkillByName: (
params: GetAuthorSkillByNameParams,
) => Promise<(ISkill & { _id: Types.ObjectId }) | null>;
listSkillsByAccess: (params: ListSkillsByAccessParams) => Promise<ListSkillsByAccessResult>;
listAlwaysApplySkills: (
params: ListAlwaysApplySkillsParams,
) => Promise<ListAlwaysApplySkillsResult>;
updateSkill: (params: {
id: string;
expectedVersion: number;
update: UpdateSkillInput;
}) => Promise<UpdateSkillResult>;
deleteSkill: (id: string) => Promise<DeleteSkillResult>;
deleteSkillFileAfterBlob: (skillId: string, fileId: string) => Promise<boolean>;
finalizeSkillDeletion: (id: string) => Promise<DeleteSkillResult>;
deleteUserSkills: (userId: Types.ObjectId | string) => Promise<number>;
findSkillBySourceIdentity: (params: {
source: 'github' | 'notion';
upstreamId: string;
tenantId?: string;
}) => Promise<(ISkill & { _id: Types.ObjectId }) | null>;
listSkillsBySource: (params: {
source: 'github' | 'notion';
sourceId: string;
}) => Promise<Array<ISkill & { _id: Types.ObjectId }>>;
listSkillFiles: (
skillId: Types.ObjectId | string,
) => Promise<Array<ISkillFile & { _id: Types.ObjectId }>>;
upsertSkillFile: (row: UpsertSkillFileInput) => Promise<ISkillFile & { _id: Types.ObjectId }>;
deleteSkillFile: (
skillId: Types.ObjectId | string,
relativePath: string,
expectedFileId?: string,
) => Promise<{ deleted: boolean }>;
getSkillFileByPath: (
skillId: Types.ObjectId | string,
relativePath: string,
) => Promise<(ISkillFile & { _id: Types.ObjectId }) | null>;
updateSkillFileContent: (
skillId: Types.ObjectId | string,
relativePath: string,
update: { content?: string; isBinary?: boolean },
expectedFileId?: string,
) => Promise<void>;
updateSkillFileCodeEnvIds: (
updates: Array<{
skillId: Types.ObjectId | string;
relativePath: string;
codeEnvRef: CodeEnvRef;
}>,
) => Promise<{ matchedCount: number; modifiedCount: number }>;
} {
const { ObjectId } = mongoose.Types;
function buildSkillFilter(
params: Pick<
ListSkillsByAccessParams,
'accessibleIds' | 'category' | 'search' | 'manageTenantId'
>,
): FilterQuery<ISkillDocument> {
const filter: FilterQuery<ISkillDocument> = params.manageTenantId
? { tenantId: params.manageTenantId, deletingAt: { $exists: false } }
: { _id: { $in: params.accessibleIds }, deletingAt: { $exists: false } };
if (params.category && params.category.length > 0) {
filter.category = params.category;
}
if (params.search && params.search.length > 0) {
const rx = new RegExp(escapeRegExp(params.search), 'i');
filter.$or = [{ name: rx }, { description: rx }, { displayTitle: rx }];
}
return filter;
}
function decodeCursor(
cursor: string | null | undefined,
): { updatedAt: Date; _id: Types.ObjectId } | null {
if (!cursor || cursor === 'undefined' || cursor === 'null') {
return null;
}
try {
const decoded = JSON.parse(Buffer.from(cursor, 'base64').toString('utf8')) as {
updatedAt?: string;
_id?: string;
};
if (
!decoded.updatedAt ||
!decoded._id ||
Number.isNaN(new Date(decoded.updatedAt).getTime()) ||
!isValidObjectIdString(decoded._id)
) {
return null;
}
return { updatedAt: new Date(decoded.updatedAt), _id: new ObjectId(decoded._id) };
} catch (error) {
logger.warn(`[skill.decodeCursor] Invalid cursor: ${(error as Error).message}`);
return null;
}
}
function encodeCursor(row: { updatedAt: Date; _id: Types.ObjectId }): string {
return Buffer.from(
JSON.stringify({ updatedAt: row.updatedAt.toISOString(), _id: row._id.toString() }),
).toString('base64');
}
async function createSkill(data: CreateSkillInput): Promise<CreateSkillResult> {
const normalizedFrontmatter = isPlainObject(data.frontmatter)
? normalizeSkillFrontmatterKeys(data.frontmatter)
: undefined;
const frontmatter =
normalizedFrontmatter && 'frontmatter' in normalizedFrontmatter
? normalizedFrontmatter.frontmatter
: data.frontmatter;
const bodyIssues = validateSkillBody(data.body);
/* Parse body's always-apply status once — reused for validation
(below) and derivation in `resolveAlwaysApplyFromInput`. Avoids
parsing the same YAML frontmatter block twice per create. */
const bodyAlwaysApply =
bodyIssues.length === 0 && data.body !== undefined
? extractAlwaysApplyFromBody(data.body)
: undefined;
const issues: ValidationIssue[] = [
...validateSkillName(data.name),
...validateSkillDescription(data.description),
...bodyIssues,
...validateSkillDisplayTitle(data.displayTitle),
...validateSkillFrontmatter(frontmatter),
...validateAlwaysApply(data.alwaysApply),
];
if (typeof data.author === 'string' && !isValidObjectIdString(data.author)) {
issues.push({
field: 'author',
code: 'INVALID_FORMAT',
message: 'Author must be a 24-character hex string',
});
}
/* Body-level `always-apply:` only needs to be well-formed when a
higher-precedence source won't override it (see
`resolveAlwaysApplyFromInput` for the cascade). A caller sending
an explicit top-level `alwaysApply` or a structured
an always-apply value in structured `frontmatter` has the body value overridden at
derivation time, so rejecting them for a typo they aren't relying
on would be user-hostile. */
if (
bodyAlwaysApply?.status === 'invalid' &&
typeof data.alwaysApply !== 'boolean' &&
getAlwaysApplyFrontmatterValue(frontmatter) === undefined
) {
issues.push({
field: 'body.frontmatter.alwaysApply',
code: 'INVALID_TYPE',
message:
'"always-apply" or "alwaysApply" in SKILL.md frontmatter must be a boolean (true or false)',
});
}
const { errors, warnings } = partitionIssues(issues);
if (errors.length > 0) {
const error = new Error('Skill validation failed');
(error as Error & { issues?: ValidationIssue[]; code?: string }).issues = errors;
(error as Error & { code?: string }).code = 'SKILL_VALIDATION_FAILED';
throw error;
}
const Skill = mongoose.models.Skill as Model<ISkillDocument>;
const author = new mongoose.Types.ObjectId(data.author);
// Application-level uniqueness check on (name, author, tenantId).
// The unique index in the schema is the persistent guarantee, but Mongoose
// creates indexes asynchronously and tests can race ahead of index creation,
// so we also enforce it here for deterministic behavior and a clean error.
const existing = await Skill.findOne({
name: data.name,
author,
tenantId: data.tenantId ?? null,
})
.select('_id')
.lean();
if (existing) {
const error = new Error(`A skill with name "${data.name}" already exists for this author`);
(error as Error & { code?: string | number }).code = 11000;
throw error;
}
const derived = deriveStructuredFrontmatterFields(frontmatter);
const doc = await Skill.create({
name: data.name,
displayTitle: data.displayTitle,
description: data.description,
body: data.body ?? '',
frontmatter: frontmatter ?? {},
category: data.category ?? '',
author,
authorName: data.authorName,
version: 1,
source: data.source ?? 'inline',
sourceMetadata: data.sourceMetadata,
fileCount: 0,
alwaysApply: resolveAlwaysApplyFromInput(
data.alwaysApply,
frontmatter,
data.body,
false,
bodyAlwaysApply,
),
tenantId: data.tenantId,
...derived,
});
return {
skill: doc.toObject() as unknown as ISkill & { _id: Types.ObjectId },
warnings,
};
}
async function getSkillById(
id: string | Types.ObjectId,
): Promise<(ISkill & { _id: Types.ObjectId }) | null> {
if (typeof id === 'string' && !isValidObjectIdString(id)) {
return null;
}
const Skill = mongoose.models.Skill as Model<ISkillDocument>;
const doc = await Skill.findOne({ _id: id, deletingAt: { $exists: false } }).lean();
return (doc as unknown as (ISkill & { _id: Types.ObjectId }) | null) ?? null;
}
async function getSkillByName(
name: string,
accessibleIds: Types.ObjectId[],
options?: {
/**
* Manual paths (`$` popover, always-apply once Phase 5 lands) set
* this so a same-name newer `userInvocable: false` duplicate can't
* shadow the older user-invocable doc the popover surfaced.
* Disable-model-invocation status is irrelevant here — manually-
* primed disabled skills are explicitly supported (iter 4).
*/
preferUserInvocable?: boolean;
/**
* Model paths (`skill` / `read_file` tool handlers) set this so a
* same-name newer `disable-model-invocation: true` duplicate can't
* shadow the cataloged model-invocable doc. User-invocability is
* irrelevant here — `userInvocable: false` skills are model-only
* and remain valid model-invocation targets.
*
* Both flags fall back to the newest match when no preferred doc
* exists, so handlers can still fire their explicit-rejection
* error paths (e.g. "cannot be invoked by the model" in the
* disabled-only case).
*/
preferModelInvocable?: boolean;
},
): Promise<(ISkill & { _id: Types.ObjectId }) | null> {
const Skill = mongoose.models.Skill as Model<ISkillDocument>;
const preferUserInvocable = options?.preferUserInvocable === true;
const preferModelInvocable = options?.preferModelInvocable === true;
/* Single-doc fast path when no preference is requested — preserves
the previous performance characteristics for callers that just
want "newest match". */
if (!preferUserInvocable && !preferModelInvocable) {
const doc = await Skill.findOne({
name,
_id: { $in: accessibleIds },
deletingAt: { $exists: false },
})
.sort({ updatedAt: -1 })
.lean();
return backfillDerivedFromFrontmatter(
(doc as unknown as (ISkill & { _id: Types.ObjectId }) | null) ?? null,
);
}
/* Multi-doc path: fetch all matching docs (typically 1, rarely 2+
across same-name duplicates) and pick the first satisfying the
caller's preference; fall back to newest. */
const docs = (await Skill.find({
name,
_id: { $in: accessibleIds },
deletingAt: { $exists: false },
})
.sort({ updatedAt: -1 })
.lean()) as unknown as Array<ISkill & { _id: Types.ObjectId }>;
if (docs.length === 0) {
return null;
}
for (const doc of docs) {
backfillDerivedFromFrontmatter(doc);
}
const preferred = docs.find((d) => {
if (preferUserInvocable && d.userInvocable === false) {
return false;
}
if (preferModelInvocable && d.disableModelInvocation === true) {
return false;
}
return true;
});
return preferred ?? docs[0];
}
async function getAuthorSkillByName(
params: GetAuthorSkillByNameParams,
): Promise<(ISkill & { _id: Types.ObjectId }) | null> {
const Skill = mongoose.models.Skill as Model<ISkillDocument>;
const doc = await Skill.findOne({
name: params.name,
author: params.author,
tenantId: params.tenantId ?? null,
deletingAt: { $exists: false },
})
.sort({ updatedAt: -1 })
.lean();
return backfillDerivedFromFrontmatter(
(doc as unknown as (ISkill & { _id: Types.ObjectId }) | null) ?? null,
);
}
async function listSkillsByAccess(
params: ListSkillsByAccessParams,
): Promise<ListSkillsByAccessResult> {
const Skill = mongoose.models.Skill as Model<ISkillDocument>;
const limit = Math.min(Math.max(1, params.limit || 20), 100);
const baseFilter = buildSkillFilter(params);
const cursor = decodeCursor(params.cursor);
let filter: FilterQuery<ISkillDocument> = baseFilter;
if (cursor) {
const cursorCondition: FilterQuery<ISkillDocument> = {
$or: [
{ updatedAt: { $lt: cursor.updatedAt } },
{ updatedAt: cursor.updatedAt, _id: { $gt: cursor._id } },
],
};
filter = { $and: [baseFilter, cursorCondition] };
}
const rows = await Skill.find(filter)
.sort({ updatedAt: -1, _id: 1 })
.limit(limit + 1)
/* `frontmatter` is deliberately NOT projected: the structured
columns (disableModelInvocation / userInvocable / allowedTools /
alwaysApply) are always populated by `createSkill` / `updateSkill`
going forward, and the branch this code ships on never shipped
to main — so no legacy rows exist that would need a frontmatter
read-time backfill on summaries. Skipping it saves ~2KB/skill ×
100/page of wire traffic. `backfillDerivedFromFrontmatter` is
still called below as defensive code; it short-circuits when
`frontmatter` is undefined. */
.select(
'name displayTitle description category author authorName version source sourceMetadata fileCount alwaysApply tenantId disableModelInvocation userInvocable allowedTools createdAt updatedAt',
)
.lean();
/* Defensive read-time fallback. With `frontmatter` excluded from the
projection, the helper short-circuits immediately; kept in the loop
so a future projection change (or legacy rows appearing via a
migration) continues to get runtime-column restoration for free. */
for (const row of rows) {
backfillDerivedFromFrontmatter(row as unknown as ISkill);
}
const has_more = rows.length > limit;
const sliced = has_more ? rows.slice(0, limit) : rows;
const last = sliced[sliced.length - 1];
const after =
has_more && last
? encodeCursor({
updatedAt: last.updatedAt as Date,
_id: last._id as Types.ObjectId,
})
: null;
return {
skills: sliced as unknown as Array<ISkillSummary & { _id: Types.ObjectId }>,
has_more,
after,
};
}
async function listAlwaysApplySkills(
params: ListAlwaysApplySkillsParams,
): Promise<ListAlwaysApplySkillsResult> {
const Skill = mongoose.models.Skill as Model<ISkillDocument>;
if (!params.accessibleIds.length) {
return { skills: [], has_more: false, after: null };
}
const limit = Math.min(Math.max(1, params.limit || 20), 100);
const baseFilter: FilterQuery<ISkillDocument> = {
_id: { $in: params.accessibleIds },
alwaysApply: true,
deletingAt: { $exists: false },
};
const cursor = decodeCursor(params.cursor);
let filter: FilterQuery<ISkillDocument> = baseFilter;
if (cursor) {
const cursorCondition: FilterQuery<ISkillDocument> = {
$or: [
{ updatedAt: { $lt: cursor.updatedAt } },
{ updatedAt: cursor.updatedAt, _id: { $gt: cursor._id } },
],
};
filter = { $and: [baseFilter, cursorCondition] };
}
const rows = await Skill.find(filter)
.sort({ updatedAt: -1, _id: 1 })
.limit(limit + 1)
.select('name body author frontmatter updatedAt allowedTools version')
.lean();
const has_more = rows.length > limit;
const sliced = has_more ? rows.slice(0, limit) : rows;
const last = sliced[sliced.length - 1];
const after =
has_more && last
? encodeCursor({
updatedAt: last.updatedAt as Date,
_id: last._id as Types.ObjectId,
})
: null;
/**
* `allowedTools` is projected alongside `name`/`body`/`author` so the
* always-apply prime pipeline (post-Phase 6) can union skill-declared
* tool allowlists into the agent's effective tool set for the turn —
* same symmetry as the manual-prime path, which reads the column off
* `getSkillByName`. Older rows predating the column show up with
* `allowedTools === undefined` (the backfill helper runs on those at
* read time elsewhere; per-turn priming is fine with undefined).
*/
const skills = sliced.map((row) => {
const result: ListAlwaysApplySkillsResult['skills'][number] = {
_id: row._id as Types.ObjectId,
name: row.name,
body: row.body ?? '',
author: row.author as Types.ObjectId,
version: row.version,
frontmatter: row.frontmatter,
};
if (row.allowedTools !== undefined) {
result.allowedTools = row.allowedTools;
}
return result;
});
return { skills, has_more, after };
}
async function updateSkill(params: {
id: string;
expectedVersion: number;
update: UpdateSkillInput;
}): Promise<UpdateSkillResult> {
const { id, expectedVersion, update } = params;
if (!isValidObjectIdString(id)) {
return { status: 'not_found' };
}
const normalizedFrontmatter = isPlainObject(update.frontmatter)
? normalizeSkillFrontmatterKeys(update.frontmatter)
: undefined;
const frontmatter =
normalizedFrontmatter && 'frontmatter' in normalizedFrontmatter
? normalizedFrontmatter.frontmatter
: update.frontmatter;
const bodyIssues = update.body !== undefined ? validateSkillBody(update.body) : [];
/* Parse body's always-apply status once — reused for validation
(precedence-aware, below) and the derivation cascade further
down. Avoids parsing the same YAML frontmatter block twice per
update. */
const bodyAlwaysApply =
bodyIssues.length === 0 && update.body !== undefined
? extractAlwaysApplyFromBody(update.body)
: undefined;
const issues: ValidationIssue[] = [];
if (update.name !== undefined) issues.push(...validateSkillName(update.name));
if (update.description !== undefined)
issues.push(...validateSkillDescription(update.description));
issues.push(...bodyIssues);
if (update.displayTitle !== undefined)
issues.push(...validateSkillDisplayTitle(update.displayTitle));
if (update.frontmatter !== undefined) issues.push(...validateSkillFrontmatter(frontmatter));
if (update.alwaysApply !== undefined) issues.push(...validateAlwaysApply(update.alwaysApply));
/* Body-level `always-apply:` only needs to be well-formed when a
higher-precedence source won't override it (see
`resolveAlwaysApplyFromInput` for precedence). Rejecting a typo
the caller is already overriding would be user-hostile, and the
body-inline derivation branch below is skipped for those
payloads anyway. */
if (
bodyAlwaysApply?.status === 'invalid' &&
update.alwaysApply === undefined &&
getAlwaysApplyFrontmatterValue(frontmatter) === undefined
) {
issues.push({
field: 'body.frontmatter.alwaysApply',
code: 'INVALID_TYPE',
message:
'"always-apply" or "alwaysApply" in SKILL.md frontmatter must be a boolean (true or false)',
});
}
const { errors, warnings } = partitionIssues(issues);
if (errors.length > 0) {
const error = new Error('Skill validation failed');
(error as Error & { issues?: ValidationIssue[]; code?: string }).issues = errors;
(error as Error & { code?: string }).code = 'SKILL_VALIDATION_FAILED';
throw error;
}
const Skill = mongoose.models.Skill as Model<ISkillDocument>;
const setPayload: Record<string, unknown> = {};
const unsetPayload: Record<string, ''> = {};
if (update.name !== undefined) setPayload.name = update.name;
if (update.displayTitle !== undefined) setPayload.displayTitle = update.displayTitle;
if (update.description !== undefined) setPayload.description = update.description;
if (update.body !== undefined) setPayload.body = update.body;
if (update.source !== undefined) setPayload.source = update.source;
if (update.sourceMetadata !== undefined) setPayload.sourceMetadata = update.sourceMetadata;
if (update.frontmatter !== undefined) {
setPayload.frontmatter = frontmatter;
/**
* Derived columns track frontmatter — when frontmatter changes, the
* derived view must follow. Fields the new frontmatter omits are
* unset (back to schema default) so removing `disable-model-invocation`
* from a SKILL.md re-enables model invocation on the next save.
*/
const derived = deriveStructuredFrontmatterFields(frontmatter);
for (const key of ['disableModelInvocation', 'userInvocable', 'allowedTools'] as const) {
if (derived[key] !== undefined) {
setPayload[key] = derived[key];
} else {
unsetPayload[key] = '';
}
}
}
if (update.category !== undefined) setPayload.category = update.category;
/**
* Keep the indexed `alwaysApply` column in sync with whatever the update
* is carrying: an explicit top-level `alwaysApply` always wins; a
* structured `frontmatter` with `always-apply: true/false` or the
* accepted `alwaysApply` alias is next; and a `body` update is scanned last for an inline `always-apply:` line
* inside the SKILL.md frontmatter block. The body path is load-bearing
* for the REST edit flow — the current UI sends `body` without a
* parallel `frontmatter` object, so inline edits to `always-apply:` / `alwaysApply:`
* would otherwise leave the column stale and auto-priming / pin
* badges would keep using the old value.
*
* When a `body` is submitted with NO `always-apply:` line (e.g. the
* user removed the line from SKILL.md), that counts as a positive
* declaration of "not always-apply" — the column flips to `false`.
* Leaving it untouched would leave a skill that was once always-apply
* silently auto-priming even after its own SKILL.md no longer
* declares the flag.
*
* Important: the gates key off the *presence of an always-apply value*
* at each level, not the presence of the parent field. An API caller
* that sends both `body` and an unrelated `frontmatter` bag (e.g.
* editing category + rewriting SKILL.md in one PATCH) still gets the
* body-inline flag respected because no structured always-apply key
* is absent in that payload.
*/
let derivedAlwaysApply: boolean | undefined;
if (update.alwaysApply !== undefined) {
derivedAlwaysApply = update.alwaysApply;
}
if (derivedAlwaysApply === undefined && update.frontmatter !== undefined) {
const fromFrontmatter = getAlwaysApplyFrontmatterValue(frontmatter);
if (typeof fromFrontmatter === 'boolean') {
derivedAlwaysApply = fromFrontmatter;
}
}
if (derivedAlwaysApply === undefined && bodyAlwaysApply !== undefined) {
if (bodyAlwaysApply.status === 'valid') {
derivedAlwaysApply = bodyAlwaysApply.value;
} else if (bodyAlwaysApply.status === 'absent') {
/* An `absent` result means the user submitted a new body that
declares no `always-apply:` key (either the key was removed or
no frontmatter block was ever there). The body is the
authoritative source for this skill's declared state: editing
it to drop the flag intends to turn auto-priming off, so flip
the column to `false`. Without this, a skill that was once
`alwaysApply: true` would keep auto-priming after the user
removed the declaration from SKILL.md — a persistent,
invisible mismatch between the file and runtime behavior.
`invalid` is rejected by the inline check above
so this branch only handles the legitimate absence case. */
derivedAlwaysApply = false;
}
}
if (derivedAlwaysApply !== undefined) {
setPayload.alwaysApply = derivedAlwaysApply;
}
const updateOps: Record<string, unknown> = {
$set: setPayload,
$inc: { version: 1 },
};
if (Object.keys(unsetPayload).length > 0) {
updateOps.$unset = unsetPayload;
}
const result = await Skill.findOneAndUpdate(
{ _id: new ObjectId(id), version: expectedVersion, deletingAt: { $exists: false } },
updateOps,
{ new: true },
).lean();
if (result) {
return {
status: 'updated',
skill: result as unknown as ISkill & { _id: Types.ObjectId },
warnings,
};
}
const current = await Skill.findOne({ _id: id, deletingAt: { $exists: false } }).lean();
if (!current) {
return { status: 'not_found' };
}
return {
status: 'conflict',
current: current as unknown as ISkill & { _id: Types.ObjectId },
};
}
/**
* Removes deleted skill ids from every agent's `skills` allowlist. A dangling
* id is invisible in the builder yet keeps the allowlist non-empty, so the
* runtime scopes the catalog to an empty intersection and the agent silently
* loses all skills. Direct `updateMany` on purpose: hygiene, not an authored
* edit — no version entry, timestamps untouched.
*
* Ids are lowercased first: allowlists store canonical `_id.toString()`
* values, and an uppercase-but-valid id would delete the Skill doc yet
* leave the dangling entry behind.
*
* Agents whose ENTIRE allowlist is being deleted fail closed instead:
* an emptied allowlist with `skills_enabled: true` means the full
* accessible catalog at runtime, so a plain `$pull` would silently widen
* a deliberately restricted agent. Disabling skills preserves the
* restriction until an author makes a new explicit choice.
*
* That inference only applies to agents with no explicit `skills_scope`.
* With a scope persisted, the field already says what an empty allowlist
* means -- `selected` resolves to no skills on its own, and `all` means the
* full catalog on purpose -- so disabling them would turn skills off behind
* the author's back.
*/
async function removeSkillsFromAgentAllowlists(skillIds: string[]): Promise<boolean> {
if (skillIds.length === 0) {
return true;
}
const ids = skillIds.map((id) => id.toLowerCase());
const Agent = mongoose.models.Agent as Model<IAgent>;
try {
await Agent.updateMany(
{
skills: { $in: ids, $not: { $elemMatch: { $nin: ids } } },
/** Only `all` and `selected` opt out: each already defines what an
* empty allowlist means. A missing field (matched here because
* `$nin` also matches absent) is the legacy shape, and an explicit
* `none` with the master flag still true is a contradictory shape
* the API accepts, which `skillDeps` would otherwise keep reading
* as permission to expose the skill-authoring tools. */
skills_scope: { $nin: [SkillsScope.all, SkillsScope.selected] },
},
{ $set: { skills: [], skills_enabled: false } },
{ timestamps: false },
);
await Agent.updateMany(
{ skills: { $in: ids } },
{ $pull: { skills: { $in: ids } } },
{ timestamps: false },
);
return true;
} catch (error) {
logger.error(
'[removeSkillsFromAgentAllowlists] Error pruning agent skill allowlists:',
error,
);
return false;
}
}
async function deleteSkill(id: string): Promise<DeleteSkillResult> {
if (!isValidObjectIdString(id)) {
return {
deleted: false,
skillAbsent: false,
cleanupComplete: false,
failedCleanupSteps: [],
};
}
// Legacy callers may still reach this data-only method. It must never
// discard the last reference to an external blob. The storage-aware API
// reconciler owns provider deletion and finalization.
const lifecycle = createSkillLifecycleMethods(mongoose);
const journal = await lifecycle.beginSkillDeletion(id);
return {
deleted: false,
skillAbsent: !journal,
cleanupComplete: !journal,
failedCleanupSteps: journal ? ['skill_files'] : [],
};
}
/** Blob deletion is idempotent; the file row remains the retry manifest until it succeeds. */
async function deleteSkillFileAfterBlob(skillId: string, fileId: string): Promise<boolean> {
const SkillFile = mongoose.models.SkillFile as Model<ISkillFileDocument>;
const result = await SkillFile.deleteOne({
skillId: new ObjectId(skillId),
file_id: fileId,
});
return result.deletedCount === 1;
}
/** Finalize only after blob rows are drained; never remove late rows without deleting blobs. */
async function finalizeSkillDeletion(id: string): Promise<DeleteSkillResult> {
const Skill = mongoose.models.Skill as Model<ISkillDocument>;
const SkillFile = mongoose.models.SkillFile as Model<ISkillFileDocument>;
const objectId = new ObjectId(id);
const skill = await Skill.findById(objectId).select('_id deletingAt').lean();
if (skill && !skill.deletingAt) {
return {
deleted: false,
skillAbsent: false,
cleanupComplete: false,
failedCleanupSteps: ['skill_files'],
};
}
if (await SkillFile.exists({ skillId: objectId })) {
return {
deleted: false,
skillAbsent: false,
cleanupComplete: false,
failedCleanupSteps: ['skill_files'],
};
}
const failedCleanupSteps: DeleteSkillCleanupStep[] = [];
if (!(await removeSkillsFromAgentAllowlists([id]))) {
failedCleanupSteps.push('agent_allowlists');
}
try {
await deps.removeAllPermissions({ resourceType: ResourceType.SKILL, resourceId: id });
} catch {
failedCleanupSteps.push('permissions');
logger.error(`[finalizeSkillDeletion] Error removing permissions for ${id}`);
}
if (failedCleanupSteps.length > 0) {
return {
deleted: false,
skillAbsent: false,
cleanupComplete: false,
failedCleanupSteps,
};
}
const result = await Skill.deleteOne({ _id: objectId, deletingAt: { $exists: true } });
return {
deleted: result.deletedCount === 1,
skillAbsent: true,
cleanupComplete: true,
failedCleanupSteps: [],
};
}
async function deleteUserSkills(userId: Types.ObjectId | string): Promise<number> {
const userObjectId = typeof userId === 'string' ? new ObjectId(userId) : userId;
const soleOwned = await deps.getSoleOwnedResourceIds(userObjectId, ResourceType.SKILL);
if (soleOwned.length === 0) {
return 0;
}
// Mark each Skill and release its public name in the same document write.
// The reconciler repairs the mark-to-journal gap and backfills file
// references outside this request.
const Skill = mongoose.models.Skill as Model<ISkillDocument>;
const deletingAt = new Date();
const result = await tenantSafeBulkWrite(
Skill,
soleOwned.map((id) => ({
updateOne: {
filter: { _id: id, deletingAt: { $exists: false } },
update: {
$set: {
name: `__deleted__${id.toString()}`,
deletingAt,
deletionNeedsJournal: true,
},
},
},
})),
{ ordered: false },
);
return result.modifiedCount;
}
async function findSkillBySourceIdentity(params: {
source: 'github' | 'notion';
upstreamId: string;
tenantId?: string;
}): Promise<(ISkill & { _id: Types.ObjectId }) | null> {
const Skill = mongoose.models.Skill as Model<ISkillDocument>;
const tenantFilter: FilterQuery<ISkillDocument> = params.tenantId
? { tenantId: params.tenantId }
: { $or: [{ tenantId: { $exists: false } }, { tenantId: null }] };
const doc = await Skill.findOne({
source: params.source,
'sourceMetadata.upstreamId': params.upstreamId,
deletingAt: { $exists: false },
...tenantFilter,
}).lean();
return (doc as unknown as (ISkill & { _id: Types.ObjectId }) | null) ?? null;
}
async function listSkillsBySource(params: {
source: 'github' | 'notion';
sourceId: string;
}): Promise<Array<ISkill & { _id: Types.ObjectId }>> {
const Skill = mongoose.models.Skill as Model<ISkillDocument>;
const rows = await Skill.find({
source: params.source,
'sourceMetadata.sourceId': params.sourceId,
deletingAt: { $exists: false },
}).lean();
return rows as unknown as Array<ISkill & { _id: Types.ObjectId }>;
}
/**
* Atomically bumps `Skill.version` and adjusts `fileCount` by `delta`.
* `delta` is `+1` when a new file is inserted, `-1` when one is deleted, and
* `0` when an existing file is replaced in place.
*
* NOTE on consistency: this runs as a **separate** MongoDB operation from
* the `upsertSkillFile` / `deleteSkillFile` that triggers it. MongoDB only
* provides multi-document ACID via transactions (which require a replica
* set), and LibreChat does not currently require that deployment shape. In
* the rare case where a SkillFile write succeeds but the subsequent
* `findByIdAndUpdate` here fails (connection drop, primary failover mid-
* request), the `fileCount` on the parent Skill will drift from the true
* row count until the next successful upsert/delete corrects it. Options if
* this ever shows up in practice:
* - wrap both ops in a transaction (requires a replica set)
* - periodic reconciliation: `fileCount = count(skill_files where skillId = ?)`
* - treat `fileCount` as advisory and recompute on read when accuracy
* matters
* For phase 1, skill files are stubbed at the upload boundary, so the risk
* window doesn't open in practice.
*/
async function bumpSkillVersionAndAdjustFileCount(
skillId: Types.ObjectId | string,
delta: number,
): Promise<void> {
const Skill = mongoose.models.Skill as Model<ISkillDocument>;
const updateOps: Record<string, Record<string, number>> = { $inc: { version: 1 } };
if (delta !== 0) {
updateOps.$inc.fileCount = delta;
}
await Skill.findByIdAndUpdate(skillId, updateOps);
}
async function listSkillFiles(
skillId: Types.ObjectId | string,
): Promise<Array<ISkillFile & { _id: Types.ObjectId }>> {
const SkillFile = mongoose.models.SkillFile as Model<ISkillFileDocument>;
const rows = await SkillFile.find({ skillId })
.select('-content')
.sort({ relativePath: 1 })
.lean();
return rows as unknown as Array<ISkillFile & { _id: Types.ObjectId }>;
}
async function upsertSkillFile(
row: UpsertSkillFileInput,
): Promise<ISkillFile & { _id: Types.ObjectId }> {
const Skill = mongoose.models.Skill as Model<ISkillDocument>;
const parent = await Skill.findOne({
_id: row.skillId,
deletingAt: { $exists: false },
})
.select('_id')
.lean();
if (!parent) {
throw Object.assign(new Error('Skill is being deleted'), { code: 'SKILL_DELETING' });
}
const issues = validateRelativePath(row.relativePath);
if (issues.length > 0) {
const error = new Error('Skill file validation failed');
(error as Error & { issues?: ValidationIssue[]; code?: string }).issues = issues;
(error as Error & { code?: string }).code = 'SKILL_FILE_VALIDATION_FAILED';
throw error;
}
const SkillFile = mongoose.models.SkillFile as Model<ISkillFileDocument>;
if (!row.createOnly) {
const previous = await SkillFile.findOne({
skillId: row.skillId,
relativePath: row.relativePath,
...(row.expectedFileId != null ? { file_id: row.expectedFileId } : {}),
})
.select('-content')
.lean();
if (
previous &&
previous.file_id === row.file_id &&
(previous.filepath !== row.filepath ||
previous.source !== row.source ||
(previous.storageKey ?? null) !== (row.storageKey ?? null) ||
(previous.storageRegion ?? null) !== (row.storageRegion ?? null))
) {
throw Object.assign(new Error('Skill file identity cannot change storage location'), {
code: 'SKILL_FILE_CONFLICT',
});
}
if (previous && previous.file_id !== row.file_id) {
// Queue the old blob before changing its only live file row. A failed
// CAS leaves the row in place, so the sweeper will retain its blob.
const SkillUploadIntent = mongoose.models
.SkillUploadIntent as Model<ISkillUploadIntentDocument>;
// A multi-step writer may roll this replacement back. Its hold and the
// sweeper's claim must contend on the same intent before the file CAS;
// an already-claimed blob is not a safe rollback candidate.
const intentFilter = row.cleanupHoldOwner
? {
fileId: previous.file_id,
state: 'committed',
cleanedAt: { $exists: false },
claimOwner: { $exists: false },
$or: [
{ cleanupHoldOwner: { $exists: false } },
{ cleanupHoldOwner: row.cleanupHoldOwner },
],
}
: { fileId: previous.file_id };
const intentUpdate = {
$setOnInsert: {
skillId: row.skillId,
fileId: previous.file_id,
source: previous.source,
storageKey: previous.storageKey ?? previous.filepath,
author: previous.author,
tenantId: previous.tenantId,
writerId: 'legacy-replacement',
state: 'committed',
},
$set: {
cleanupRequestedAt: new Date(),
...(row.cleanupHoldOwner ? { cleanupHoldOwner: row.cleanupHoldOwner } : {}),
},
$unset: { cleanedAt: '', nextCheckAt: '' },
};
try {
await SkillUploadIntent.updateOne(intentFilter, intentUpdate, { upsert: true });
} catch (error) {
// Concurrent replacements can both attempt the legacy upsert.
// The winner has already published the same cleanup reference.
if (!(error instanceof Error && 'code' in error && error.code === 11000)) throw error;
const result = await SkillUploadIntent.updateOne(intentFilter, intentUpdate);
if (row.cleanupHoldOwner && result.matchedCount !== 1) {
throw Object.assign(new Error('Skill blob cleanup is already claimed'), {
code: 'SKILL_FILE_CONFLICT',
});
}
}
}
}
const fields = {
skillId: row.skillId,
relativePath: row.relativePath,
file_id: row.file_id,
filename: row.filename,
filepath: row.filepath,
storageKey: row.storageKey,
storageRegion: row.storageRegion,
source: row.source,
sourceMetadata: row.sourceMetadata,
mimeType: row.mimeType,
bytes: row.bytes,
category: inferSkillFileCategory(row.relativePath),
isExecutable: row.isExecutable ?? false,
author: row.author,
tenantId: row.tenantId,
};
if (row.createOnly) {
if (row.expectedFileId != null) {
throw new Error('A file cannot require both an absent path and an existing revision');
}
let created: ISkillFileDocument;
try {
created = await SkillFile.create(fields);
} catch (error) {
if (error instanceof Error && 'code' in error && error.code === 11000) {
throw Object.assign(new Error('Skill file was created by another writer'), {
code: 'SKILL_FILE_CONFLICT',
});
}
throw error;
}
await bumpSkillVersionAndAdjustFileCount(row.skillId, 1);
return created.toObject() as unknown as ISkillFile & { _id: Types.ObjectId };
}
const result = (await SkillFile.findOneAndUpdate(
{
skillId: row.skillId,
relativePath: row.relativePath,
...(row.expectedFileId != null ? { file_id: row.expectedFileId } : {}),
},
{
$set: fields,
$unset: { content: '', isBinary: '', codeEnvRef: '', codeEnvRefs: '' },
},
{ new: true, upsert: row.expectedFileId == null, includeResultMetadata: true },
).lean()) as unknown as SkillFileUpsertResult;
const current = result.value;
if (!current && row.expectedFileId != null) {
throw Object.assign(new Error('Skill file changed since it was read'), {
code: 'SKILL_FILE_CONFLICT',
});
}
if (!current) {
const error = new Error('Skill file upsert failed to read the saved file row');
(error as Error & { code?: string }).code = 'SKILL_FILE_UPSERT_NOT_FOUND';
throw error;
}
const delta = result.lastErrorObject?.updatedExisting === false ? 1 : 0;
await bumpSkillVersionAndAdjustFileCount(row.skillId, delta);
return current;
}
async function deleteSkillFile(
skillId: Types.ObjectId | string,
relativePath: string,
expectedFileId?: string,
): Promise<{ deleted: boolean }> {
const Skill = mongoose.models.Skill as Model<ISkillDocument>;
const parent = await Skill.findOne({
_id: skillId,
deletingAt: { $exists: false },
})
.select('_id')
.lean();
if (!parent) {
throw Object.assign(new Error('Skill is being deleted'), { code: 'SKILL_DELETING' });
}
const SkillFile = mongoose.models.SkillFile as Model<ISkillFileDocument>;
const res = await SkillFile.deleteOne({
skillId,
relativePath,
...(expectedFileId != null ? { file_id: expectedFileId } : {}),
});
if (!res.deletedCount) {
return { deleted: false };
}
await bumpSkillVersionAndAdjustFileCount(skillId, -1);
return { deleted: true };
}
// The public surface is scoped to methods that handlers and the user
async function getSkillFileByPath(
skillId: Types.ObjectId | string,
relativePath: string,
): Promise<(ISkillFile & { _id: Types.ObjectId }) | null> {
const SkillFile = mongoose.models.SkillFile as Model<ISkillFileDocument>;
const row = await SkillFile.findOne({ skillId, relativePath }).lean();
return row as unknown as (ISkillFile & { _id: Types.ObjectId }) | null;
}
async function updateSkillFileContent(
skillId: Types.ObjectId | string,
relativePath: string,
update: { content?: string; isBinary?: boolean },
expectedFileId?: string,
): Promise<void> {
const SkillFile = mongoose.models.SkillFile as Model<ISkillFileDocument>;
await SkillFile.updateOne(
{ skillId, relativePath, ...(expectedFileId != null ? { file_id: expectedFileId } : {}) },
{ $set: update },
);
}
async function updateSkillFileCodeEnvIds(
updates: Array<{
skillId: Types.ObjectId | string;
relativePath: string;
codeEnvRef: CodeEnvRef;
}>,
): Promise<{ matchedCount: number; modifiedCount: number }> {
if (updates.length === 0) return { matchedCount: 0, modifiedCount: 0 };
const SkillFile = mongoose.models.SkillFile as Model<ISkillFileDocument>;
const ops = updates.map((u) => {
const routeKey = u.codeEnvRef.executionRouteKey ?? u.codeEnvRef.executionProfile ?? 'default';
return {
updateOne: {
filter: { skillId: u.skillId, relativePath: u.relativePath },
update: {
$set: {
codeEnvRef: u.codeEnvRef,
[`codeEnvRefs.${routeKey}`]: u.codeEnvRef,
},
},
},
};
});
/**
* The returned `{matchedCount, modifiedCount}` lets callers warn on
* partial writes — a silent miss here turns every subsequent prime
* into a fresh upload (massive egress at scale). If the wrapper's
* tenant injection ends up dropping rows, the warn log makes it
* visible instead of failing closed.
*/
const result = await tenantSafeBulkWrite(SkillFile, ops);
if (result.modifiedCount < updates.length) {
logger.warn(
`[updateSkillFileCodeEnvIds] Persisted ${result.modifiedCount}/${updates.length} codeEnvRefs (matched ${result.matchedCount}). Subsequent primes for unmatched files will re-upload.`,
);
}
return { matchedCount: result.matchedCount, modifiedCount: result.modifiedCount };
}
return {
createSkill,
getSkillById,
getSkillByName,
getAuthorSkillByName,
listSkillsByAccess,
listAlwaysApplySkills,
updateSkill,
deleteSkill,
deleteSkillFileAfterBlob,
finalizeSkillDeletion,
deleteUserSkills,
findSkillBySourceIdentity,
listSkillsBySource,
listSkillFiles,
upsertSkillFile,
deleteSkillFile,
getSkillFileByPath,
updateSkillFileContent,
updateSkillFileCodeEnvIds,
};
}
export type SkillMethods = ReturnType<typeof createSkillMethods>;