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 { InstructionsPromptErrorCode } from 'librechat-data-provider';
import type {
FiltersConfig,
AgentInstructionsPrompt,
RestrictedAgentInstructionsPrompt,
} from 'librechat-data-provider';
import type {
InstructionsPromptAccess,
InstructionsPromptAccessUser,
InstructionsPromptAccessLogger,
InstructionsPromptAccessRequest,
} from './access';
import type { InstructionsPromptLinkErrorResponse } from './errors';
import type { LinkedInstructionsConfig } from './linked';
import { getInstructionsPromptLinkError, buildInstructionsPromptError } from './errors';
import { isContentFilterError } from '~/middleware/contentFilter';
import { isValidInstructionsPromptLink } from './linked';
import { getSafeErrorMetadata } from '~/utils/errors';
export type InstructionsPromptWriteOperation = 'create' | 'update';
/**
* Returned whenever the role, ACL, or prompt-store lookup backing a write check throws
* unexpectedly (never for a recognized content-policy rejection, which `validateLinkWrite`
* already turns into its own `ok: false` result). One fixed, pre-built response — no
* detail about the failure is disclosed, and the caller logs the real cause separately
* via `getSafeErrorMetadata`.
*/
const VALIDATION_FAILED_ERROR = buildInstructionsPromptError(
500,
InstructionsPromptErrorCode.VALIDATION_FAILED,
);
/**
* Validates one create or update write of `instructionsPrompt`, owning every branch
* the write handler would otherwise carry: whether the field changed at all
* (`next === undefined` short-circuits before any permission or prompt lookup) and
* the permission/resolvability checks in `access.validateLinkWrite`. Returns `null`
* when the write may proceed; the caller only needs to map a non-null result to its
* HTTP response.
*
* Covers `'create'` and `'update'` only. A duplicate or revert carries its source
* link (the duplicated agent's, or a version snapshot's) as-is and never calls this
* function; Agent EDIT is the only authority either needs.
*
* Every branch runs inside one try/catch: an unexpected throw from the role, ACL, or
* prompt-store lookups behind `validateLinkWrite` is logged here with
* `getSafeErrorMetadata` and mapped to `VALIDATION_FAILED_ERROR` instead of reaching
* the caller, where it would otherwise surface as a raw `error.message` on the
* handler's catch-all. A recognized content-policy error is rethrown unchanged —
* `validateLinkWrite` already maps that case to its own `ok: false` result, so one
* reaching here would be an unrecognized caller bug, not a failure this function
* should mask.
*/
export async function checkInstructionsPromptWrite({
access,
operation: _operation,
user,
previous,
next,
filters,
linkedInstructions,
logger,
req,
}: {
access: Pick<InstructionsPromptAccess, 'validateLinkWrite'>;
operation: InstructionsPromptWriteOperation;
user: InstructionsPromptAccessUser;
previous: AgentInstructionsPrompt | null | undefined;
next: AgentInstructionsPrompt | null | undefined;
filters?: FiltersConfig;
linkedInstructions?: Pick<LinkedInstructionsConfig, 'langfuse'>;
logger: InstructionsPromptAccessLogger;
/** Forwarded unexamined to `access.validateLinkWrite` so its role lookup can reuse
* the caller's per-request role cache. */
req?: InstructionsPromptAccessRequest;
}): Promise<InstructionsPromptLinkErrorResponse | null> {
if (next === undefined) {
return null;
}
try {
return await getInstructionsPromptLinkError({
access,
user,
previous: previous ?? null,
next,
filters,
linkedInstructions,
req,
});
} catch (error) {
if (isContentFilterError(error)) {
throw error;
}
logger.error(
'[checkInstructionsPromptWrite] Failed to validate a linked instructions-prompt write',
getSafeErrorMetadata(error),
);
return VALIDATION_FAILED_ERROR;
}
}
/**
* Applies the create/update convention that a `null` `instructionsPrompt` in
* the update payload means "remove the link" — expressed as `$unset` because
* `removeNullishValues` drops a bare `null` before it would reach the database
* driver. Leaves `updateData` untouched when the field isn't `null` (absent,
* or a link to set). Any existing `$unset` entries on `updateData` are kept.
* Takes and returns a plain record — the `/api` update payload it operates on
* is assembled dynamically and has no single static shape.
*/
export function applyInstructionsPromptUnset(
updateData: Record<string, unknown>,
): Record<string, unknown> {
if (updateData.instructionsPrompt !== null) {
return updateData;
}
const { instructionsPrompt: _removed, $unset, ...rest } = updateData;
return {
...rest,
$unset: { ...(($unset as Record<string, unknown> | undefined) ?? {}), instructionsPrompt: 1 },
};
}
/**
* The link that will govern the agent's instructions after this write: `next`
* when the payload carries the field at all (including an explicit `null`
* removal), otherwise whatever is already stored (`previous`). A create has
* no stored link, so callers pass `undefined` for `previous` there.
*/
export function effectiveInstructionsPromptLink(
next: AgentInstructionsPrompt | RestrictedAgentInstructionsPrompt | null | undefined,
previous: AgentInstructionsPrompt | RestrictedAgentInstructionsPrompt | null | undefined,
): AgentInstructionsPrompt | RestrictedAgentInstructionsPrompt | null | undefined {
return next !== undefined ? next : previous;
}
/**
* Resolves what a save-time content scan should see for `instructions`, given the
* link that governed the agent before this write (`previous`) and the one that will
* govern it after (`effective`).
*
* Excludes `instructions` when `effective` is a real link (`isValidInstructionsPromptLink`
* — the same shape test `initializeAgent` uses): that text is dead once a link governs
* the agent, so it must not block a write that is otherwise switching to safe, linked
* content.
*
* Otherwise the agent's inline `instructions` are live text, and the payload's own
* `instructions` is scanned as-is when present. `fallbackInstructions` only fills in
* for a payload that sends none, and only when `previous` was a real link: that is
* the one case where text that was never scanned while the link stayed valid
* (`existingAgent.instructions` for an update, the reverted snapshot's own
* `instructions` for a revert) is about to go live and must be scanned before it does.
* An ordinary unlinked agent — `previous` was never a real link — keeps the base
* behavior of scanning only what the payload actually submits; `fallbackInstructions`
* is ignored for it even when supplied, so a safe partial edit that omits
* `instructions` is never rejected over stored text nothing in this write touches.
* Every other field of `data` is returned unchanged.
*/
export function excludeInstructionsWhenLinked<T extends { instructions?: unknown }>(
data: T,
{
previous,
effective,
fallbackInstructions,
}: {
previous: AgentInstructionsPrompt | RestrictedAgentInstructionsPrompt | null | undefined;
effective: AgentInstructionsPrompt | RestrictedAgentInstructionsPrompt | null | undefined;
fallbackInstructions?: unknown;
},
): T {
if (isValidInstructionsPromptLink(effective)) {
return { ...data, instructions: undefined };
}
const linkRemoved = isValidInstructionsPromptLink(previous);
if (linkRemoved && data.instructions === undefined && fallbackInstructions !== undefined) {
return { ...data, instructions: fallbackInstructions };
}
return data;
}
type InstructionsPromptLinkValue =
| AgentInstructionsPrompt
| RestrictedAgentInstructionsPrompt
| null
| undefined;
export type InstructionsContentScanOperation = 'create' | 'update' | 'duplicate' | 'revert';
/**
* Resolves what a save-time content scan should see for `instructions` on one
* agent write, dispatching `excludeInstructionsWhenLinked` with the `previous`/
* `effective`/`fallbackInstructions` a given `operation` carries:
*
* - `'create'` and `'duplicate'`: there is no stored link to remove, so `previous`
* is always `undefined` and `effective` is `data.instructionsPrompt` as submitted
* (copied verbatim from the source agent on a duplicate). No fallback applies.
* - `'update'`: `previous` is `existing.instructionsPrompt`; `effective` is
* `nextLink` when the payload carries the field at all (including an explicit
* `null` removal), otherwise `previous`. `fallbackInstructions` is
* `existing.instructions` — the text never scanned while the link stayed valid —
* so it goes live once a previously valid link is removed and the payload sends
* no `instructions` of its own.
* - `'revert'`: the snapshot's own `instructionsPrompt` restores as-is, so
* `effective` is `data.instructionsPrompt ?? null` with no permission or
* resolvability check. `previous` is `existing.instructionsPrompt ?? null`, and
* `fallbackInstructions` is `existing.instructions` — a reverted snapshot never
* unsets `instructions` for a missing field, so the agent's current stored text
* stays active and must be scanned when a valid link is being removed.
*
* Every case excludes `instructions` entirely once `effective` is a real link
* (`isValidInstructionsPromptLink`): that text is dead once a link governs the
* agent, so it must not block a write that is otherwise switching to safe, linked
* content. See `excludeInstructionsWhenLinked` for the shared exclusion/fallback
* rule this applies.
*/
export function instructionsContentForScan<
T extends { instructions?: unknown; instructionsPrompt?: unknown },
>(
operation: InstructionsContentScanOperation,
{
data,
existing,
nextLink,
}: {
data: T;
existing?: { instructions?: unknown; instructionsPrompt?: unknown } | null;
nextLink?: unknown;
},
): T {
switch (operation) {
case 'create':
case 'duplicate':
return excludeInstructionsWhenLinked(data, {
previous: undefined,
effective: data.instructionsPrompt as InstructionsPromptLinkValue,
});
case 'update': {
const previous = existing?.instructionsPrompt as InstructionsPromptLinkValue;
return excludeInstructionsWhenLinked(data, {
previous,
effective: effectiveInstructionsPromptLink(
nextLink as InstructionsPromptLinkValue,
previous,
),
fallbackInstructions: existing?.instructions,
});
}
case 'revert':
return excludeInstructionsWhenLinked(data, {
previous: (existing?.instructionsPrompt ?? null) as InstructionsPromptLinkValue,
effective: (data.instructionsPrompt ?? null) as InstructionsPromptLinkValue,
fallbackInstructions: existing?.instructions,
});
}
}