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 { Readable } from 'stream';
import { Constants } from '@librechat/agents';
import { logger } from '@librechat/data-schemas';
import {
getCodeEnvRefForProfile,
hasActivePiiFields,
type CodeEnvRef,
type CodeEnvRefMap,
} from 'librechat-data-provider';
import type { CodeEnvFile, ToolSessionMap, CodeSessionContext } from '@librechat/agents';
import type { Types } from 'mongoose';
import type { ServerRequest } from '~/types';
import {
extractFileContent,
extractSkillContent,
hasActiveFileFieldPolicy,
getBlockedUninspectableSkillFileField,
inspectContent,
UninspectableFileError,
} from '~/protection';
import {
createCodeApiRateLimitBudget,
getCodeApiUploadOptions,
getSafeErrorMetadata,
isAbortError,
type CodeApiRateLimitBudget,
withCodeApiUploadRecovery,
} from '~/utils';
import { seedCodeFilesIntoSessions, type CodeExecutionProfileRoute } from './codeFilesSession';
import { ContentFilterError, isContentFilterError } from '~/middleware/contentFilter';
import { getCodeExecutionRouteKey, type CodeExecutionContext } from './execution';
import { assertSkillFileContentAllowed } from '~/skills/protection';
import { createSkillContentDigest } from './compatibility';
import { getLookupConcurrency } from '~/utils/concurrency';
import { extractInvokedSkillsFromPayload } from './run';
import { resolveDownloadPath } from '~/storage/path';
import { mapWithConcurrency } from '~/utils/promise';
import { SKILL_FILE_PREFIX } from './skills';
const MAX_INSPECTABLE_SKILL_FILE_BYTES = 10 * 1024 * 1024;
/** Bounds buffered bytes in flight: at most this many files of up to the cap above. */
const SKILL_FILE_CONTENT_FIELDS = ['file_text'] as const;
const FILE_CONTENT_FIELDS = ['content', 'extracted_text'] as const;
export interface SkillFileRecord {
relativePath: string;
filename: string;
filepath: string;
source: string;
bytes: number;
codeEnvRef?: CodeEnvRef;
codeEnvRefs?: CodeEnvRefMap;
}
export interface PrimeSkillFilesParams {
skill: {
body: string;
name: string;
frontmatter?: Record<string, unknown>;
_id: Types.ObjectId | string;
/** Monotonic counter on the skill record. Bumped on every edit
* (frontmatter / body / file upsert). Threaded into `codeEnvRef.version`
* so codeapi's sessionKey scopes the cache per-revision. */
version: number;
};
skillFiles: SkillFileRecord[];
req: ServerRequest;
/** Optional operation-wide wait allowance shared by sibling skill primes. */
rateLimitBudget?: CodeApiRateLimitBudget;
/** Effective foreground cancellation signal for acquisition, waits, and transport. */
signal?: AbortSignal;
getStrategyFunctions: (source: string) => {
getDownloadStream?: (
req: ServerRequest,
filepath: string,
options?: { signal?: AbortSignal },
) => Promise<NodeJS.ReadableStream>;
[key: string]: unknown;
};
batchUploadCodeEnvFiles: (params: {
req: ServerRequest;
files: Array<{ stream: NodeJS.ReadableStream; filename: string }>;
/** Resource kind that owns the batch's storage session. Drives codeapi's
* sessionKey derivation (`<tenant>:<kind>:<id>[:v:<version>]`). */
kind: 'skill' | 'agent' | 'user';
/** Resource id (skillId / agentId / userId). */
id: string;
/** Required when `kind === 'skill'`; forbidden otherwise. */
version?: number;
/** When true, codeapi tags every file in the batch as infrastructure
* (read-only inputs that must never surface as generated artifacts,
* even if sandboxed code mutates the bytes on disk). */
read_only?: boolean;
codeApiBaseUrl?: string;
executionProfile?: CodeExecutionContext['executionProfile'];
bridgeWorkerId?: string;
signal?: AbortSignal;
}) => Promise<{
storage_session_id: string;
files: Array<{ fileId: string; filename: string }>;
}>;
/** Checks if a code env file is still active. Returns lastModified timestamp or null. */
getSessionInfo?: (
ref: CodeEnvRef,
req?: ServerRequest,
route?: {
baseUrl?: string;
executionProfile?: CodeExecutionContext['executionProfile'];
bridgeWorkerId?: string;
},
signal?: AbortSignal,
) => Promise<string | null>;
/** Trusted Code API route selected for the executing agent. */
codeExecutionContext?: Pick<
CodeExecutionContext,
'baseUrl' | 'executionProfile' | 'executionRouteKey' | 'bridgeWorkerId'
>;
/** 23-hour freshness check */
checkIfActive?: (dateString: string) => boolean;
/** Persists `codeEnvRef` on skill files after upload. Implementations
* warn-log on partial writes (matchedCount/modifiedCount mismatch)
* internally — caller can fire-and-forget without losing visibility. */
updateSkillFileCodeEnvIds?: (
updates: Array<{
skillId: Types.ObjectId | string;
relativePath: string;
codeEnvRef: CodeEnvRef;
}>,
) => Promise<{ matchedCount: number; modifiedCount: number } | void>;
}
export interface PrimeSkillFilesResult {
/** Representative storage session id (first file's). */
storage_session_id: string;
files: Array<{
/** Storage file id (the per-file uuid file_server returned at upload). */
id: string;
/** Resource id — the entity that owns the storage session. For skill
* files this is `skill._id.toString()`. Distinct from `id`; codeapi
* derives the sessionKey from `resource_id` (shared cache scope) but
* validates upload presence under `id` (per-file storage key). */
resource_id: string;
storage_session_id: string;
name: string;
kind: 'skill' | 'agent' | 'user';
version?: number;
}>;
}
const inflightPrimes = new Map<string, Promise<PrimeSkillFilesResult | null>>();
const signalIds = new WeakMap<AbortSignal, number>();
let nextSignalId = 1;
function getSignalScope(signal?: AbortSignal): string {
if (!signal) {
return 'unscoped';
}
let id = signalIds.get(signal);
if (id == null) {
id = nextSignalId++;
signalIds.set(signal, id);
}
return String(id);
}
type SkillUploadFiles = Array<{ stream: NodeJS.ReadableStream; filename: string }>;
type SkillCodeEnvRef = Extract<CodeEnvRef, { kind: 'skill' }>;
function isCurrentSkillRef(
ref: CodeEnvRef | undefined,
skillVersion: number,
): ref is SkillCodeEnvRef {
return ref?.kind === 'skill' && ref.version === skillVersion;
}
function destroySkillUploadStream(stream: NodeJS.ReadableStream): void {
try {
if (
'destroy' in stream &&
typeof (stream as NodeJS.ReadableStream & { destroy?: () => void }).destroy === 'function'
) {
(stream as NodeJS.ReadableStream & { destroy: () => void }).destroy();
}
} catch {
/* Preserve the run cancellation even if a provider stream rejects cleanup. */
}
}
/** Opens SKILL.md and bundled-file streams for one upload attempt. Called
* per attempt — a failed upload consumes the streams, so a retry must
* re-acquire them. */
async function collectSkillUploadFiles(
params: PrimeSkillFilesParams,
inspectedBuffers: ReadonlyMap<SkillFileRecord, Buffer>,
): Promise<SkillUploadFiles> {
const { skill, skillFiles, req, getStrategyFunctions, signal } = params;
signal?.throwIfAborted();
const filesToUpload: SkillUploadFiles = [];
// SKILL.md from the skill body
const bodyBuffer = Buffer.from(skill.body, 'utf-8');
filesToUpload.push({
stream: Readable.from(bodyBuffer),
filename: `${SKILL_FILE_PREFIX}${skill.name}/SKILL.md`,
});
// Bundled files from storage (parallel stream acquisition)
const streamResults = await Promise.allSettled(
skillFiles.map(async (file) => {
signal?.throwIfAborted();
const inspected = inspectedBuffers.get(file);
if (inspected != null) {
return {
stream: Readable.from(inspected),
filename: `${SKILL_FILE_PREFIX}${skill.name}/${file.relativePath}`,
};
}
const strategy = getStrategyFunctions(file.source);
if (!strategy.getDownloadStream) {
logger.warn(
`[primeSkillFiles] No download stream for "${file.relativePath}" (source: ${file.source})`,
);
return null;
}
const stream = await strategy.getDownloadStream(req, resolveDownloadPath(file), { signal });
if (signal?.aborted) {
destroySkillUploadStream(stream);
signal.throwIfAborted();
}
return { stream, filename: `${SKILL_FILE_PREFIX}${skill.name}/${file.relativePath}` };
}),
);
/* Do not let allSettled turn foreground cancellation into a skipped bundle
* member. A partial skill upload can look successful while leaving required
* files unavailable to the sandbox. */
if (signal?.aborted) {
for (const file of filesToUpload) {
destroySkillUploadStream(file.stream);
}
for (const result of streamResults) {
if (result.status === 'fulfilled' && result.value) {
destroySkillUploadStream(result.value.stream);
}
}
signal.throwIfAborted();
}
for (const result of streamResults) {
if (result.status === 'fulfilled' && result.value) {
filesToUpload.push(result.value);
} else if (result.status === 'rejected') {
logger.error('[primeSkillFiles] Failed to get stream:', getSafeErrorMetadata(result.reason));
}
}
return filesToUpload;
}
function assertStoredSkillBodyAllowed(
skill: PrimeSkillFilesParams['skill'],
req: ServerRequest,
): void {
const filters = req.config?.filters;
const skillPii = filters?.skills?.pii;
const inspectSkill = hasActivePiiFields(skillPii, ['name', 'instructions', 'frontmatter']);
const inspectFile = hasActiveFileFieldPolicy(filters, ['name', 'content', 'extracted_text']);
if (!inspectSkill && !inspectFile) {
return;
}
const finding = inspectContent(
[
...(inspectSkill
? extractSkillContent({
...(hasActivePiiFields(skillPii, ['name']) && { name: skill.name }),
...(hasActivePiiFields(skillPii, ['instructions']) && { body: skill.body }),
...(hasActivePiiFields(skillPii, ['frontmatter']) && {
frontmatter: skill.frontmatter,
}),
})
: []),
...(inspectFile
? extractFileContent({
filename: `${SKILL_FILE_PREFIX}${skill.name}/SKILL.md`,
content: skill.body,
extractedText: skill.body,
})
: []),
],
{ filters },
);
if (finding != null) {
throw new ContentFilterError(finding);
}
}
function assertStoredSkillFileAllowed(
file: SkillFileRecord,
buffer: Buffer,
req: ServerRequest,
): void {
assertSkillFileContentAllowed(req.config?.filters, {
buffer,
originalName: file.filename,
relativePath: file.relativePath,
});
}
function assertStoredSkillFileNameAllowed(file: SkillFileRecord, req: ServerRequest): void {
const filters = req.config?.filters;
const finding = inspectContent(
[
...extractSkillContent({
files: [{ name: file.filename, filename: file.relativePath }],
}),
...extractFileContent({
name: file.filename,
filename: file.relativePath,
}),
],
{ filters },
);
if (finding != null) {
throw new ContentFilterError(finding);
}
}
function shouldInspectStoredSkillFileContent(req: ServerRequest): boolean {
const filters = req.config?.filters;
const skillPii = filters?.skills?.pii;
return (
hasActivePiiFields(skillPii, SKILL_FILE_CONTENT_FIELDS) ||
hasActiveFileFieldPolicy(filters, FILE_CONTENT_FIELDS)
);
}
function shouldInspectStoredSkillFileMetadata(req: ServerRequest): boolean {
const filters = req.config?.filters;
return (
hasActivePiiFields(filters?.skills?.pii, ['file_name']) ||
hasActiveFileFieldPolicy(filters, ['name'])
);
}
function throwIfStoredSkillFileMustBeInspectable(req: ServerRequest): void {
const blockedField = getBlockedUninspectableSkillFileField(
req.config?.filters,
FILE_CONTENT_FIELDS,
);
if (blockedField != null) {
throw new UninspectableFileError(blockedField);
}
}
async function bufferSkillFileStream(
stream: NodeJS.ReadableStream,
signal?: AbortSignal,
): Promise<Buffer | null> {
const chunks: Buffer[] = [];
let bytes = 0;
for await (const chunk of stream as AsyncIterable<Uint8Array | string>) {
signal?.throwIfAborted();
const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
bytes += buffer.length;
if (bytes > MAX_INSPECTABLE_SKILL_FILE_BYTES) {
return null;
}
chunks.push(buffer);
}
signal?.throwIfAborted();
return Buffer.concat(chunks);
}
/**
* Uploads skill files to the code execution environment.
*
* Smart re-upload: if skill files have existing codeEnvIdentifiers,
* checks session freshness first. If the session is still active,
* returns cached references. Otherwise batch-uploads everything.
*
* After upload, persists new codeEnvIdentifiers on the SkillFile
* documents for future freshness checks.
*
* Rate-limit resilience: concurrent primes of the same (skill, version)
* share one flight, uploads are bounded per Code API route and principal,
* and 429 responses retry within a capped wait budget.
*/
export async function primeSkillFiles(
params: PrimeSkillFilesParams,
): Promise<PrimeSkillFilesResult | null> {
/* Single-flight per (skill, version): concurrent primes of the same cold
* skill join the in-flight upload instead of double-spending the upload
* rate budget. Skill _ids are tenant-scoped and the resulting session is
* resource-scoped (`<tenant>:skill:<id>:v:<version>`), so sharing the
* result across requests is sound. Per-process best-effort; the awaited
* codeEnvRef persist covers cross-turn and cross-node dedupe. */
const executionRouteKey = params.codeExecutionContext
? getCodeExecutionRouteKey(params.codeExecutionContext)
: 'default';
/* A flight may share cancellation only with callers from the same run.
* Cross-run sharing would let one user's Stop abort another live request. */
const flightKey = `${executionRouteKey}:${params.skill._id}:v:${params.skill.version}:run:${getSignalScope(params.signal)}`;
const inflight = inflightPrimes.get(flightKey);
if (inflight) {
return inflight;
}
const flight = executePrimeSkillFiles(params).finally(() => {
inflightPrimes.delete(flightKey);
});
inflightPrimes.set(flightKey, flight);
return flight;
}
async function executePrimeSkillFiles(
params: PrimeSkillFilesParams,
): Promise<PrimeSkillFilesResult | null> {
const {
skill,
skillFiles,
req,
getStrategyFunctions,
batchUploadCodeEnvFiles,
getSessionInfo,
checkIfActive,
updateSkillFileCodeEnvIds,
codeExecutionContext,
rateLimitBudget,
signal,
} = params;
signal?.throwIfAborted();
const executionProfile = codeExecutionContext?.executionProfile ?? 'default';
const executionRouteKey = codeExecutionContext
? getCodeExecutionRouteKey(codeExecutionContext)
: executionProfile;
const inspectStoredMetadata = shouldInspectStoredSkillFileMetadata(req);
const inspectBundledFileContent = shouldInspectStoredSkillFileContent(req);
const inspectedBuffers = new Map<SkillFileRecord, Buffer>();
assertStoredSkillBodyAllowed(skill, req);
if (inspectStoredMetadata) {
for (const file of skillFiles) {
signal?.throwIfAborted();
assertStoredSkillFileNameAllowed(file, req);
}
}
if (inspectBundledFileContent) {
await mapWithConcurrency(
skillFiles,
getLookupConcurrency(req.config, 'skillFileInspections'),
async (file) => {
signal?.throwIfAborted();
if (file.bytes > MAX_INSPECTABLE_SKILL_FILE_BYTES) {
throwIfStoredSkillFileMustBeInspectable(req);
return;
}
try {
const strategy = getStrategyFunctions(file.source);
if (!strategy.getDownloadStream) {
throwIfStoredSkillFileMustBeInspectable(req);
logger.warn('[primeSkillFiles] No download stream for stored skill file');
return;
}
const sourceStream = await strategy.getDownloadStream(req, resolveDownloadPath(file), {
signal,
});
const buffer = await bufferSkillFileStream(sourceStream, signal);
if (buffer == null) {
throwIfStoredSkillFileMustBeInspectable(req);
return;
}
assertStoredSkillFileAllowed(file, buffer, req);
inspectedBuffers.set(file, buffer);
} catch (error) {
if (isAbortError(error)) {
throw error;
}
if (isContentFilterError(error)) {
throw error;
}
throwIfStoredSkillFileMustBeInspectable(req);
logger.error('[primeSkillFiles] Failed to inspect bundled file before use');
}
},
);
}
/* Cache-hit path: every skillFile carries a `codeEnvRef` from the
* previous prime. Check freshness against codeapi for every distinct
* storage session; if all are still active, reuse without
* re-uploading. The skill version is part of the ref — when the
* skill version has been bumped (e.g. by a SKILL.md edit), stale
* refs are treated as cache misses and the files are re-uploaded
* under the new version's session key. */
if (getSessionInfo && checkIfActive && skillFiles.length > 0) {
const allHaveRefs = skillFiles.every((sf) => {
const ref = getCodeEnvRefForProfile(sf, executionRouteKey);
return isCurrentSkillRef(ref, skill.version);
});
if (allHaveRefs) {
const refsBySession = new Map<string, CodeEnvRef>();
for (const sf of skillFiles) {
const ref = getCodeEnvRefForProfile(sf, executionRouteKey);
if (ref && !refsBySession.has(ref.storage_session_id)) {
refsBySession.set(ref.storage_session_id, ref);
}
}
try {
const checkResults = await Promise.all(
Array.from(refsBySession.values()).map(async (ref) => {
const lastModified = await getSessionInfo(ref, req, codeExecutionContext, signal);
return !!(lastModified && checkIfActive(lastModified));
}),
);
signal?.throwIfAborted();
const allActive = checkResults.every(Boolean);
if (allActive) {
const files: PrimeSkillFilesResult['files'] = [];
for (const sf of skillFiles) {
const ref = getCodeEnvRefForProfile(sf, executionRouteKey);
if (!ref) continue;
/* Cache-hit refs already carry resource identity (kind / id /
* version) — pull them through so the artifact emitted by
* `handle_skill` and forwarded to `_injected_files` includes
* `resource_id`. Without this the next /exec sends
* `resource_id: undefined` and codeapi 400s. The discriminated
* union pins `version` to the skill branch only — destructure
* before the spread so TS accepts the conditional pull. */
files.push({
id: ref.file_id,
resource_id: ref.id,
storage_session_id: ref.storage_session_id,
name: `${SKILL_FILE_PREFIX}${skill.name}/${sf.relativePath}`,
kind: ref.kind,
...(ref.kind === 'skill' ? { version: ref.version } : {}),
});
}
if (files.length > 0) {
logger.debug(
`[primeSkillFiles] All ${refsBySession.size} session(s) active for skill "${skill.name}", reusing ${files.length} files`,
);
return { storage_session_id: files[0].storage_session_id, files };
}
}
} catch (error) {
if (isAbortError(error)) {
throw error;
}
// Session check failed — fall through to re-upload
}
}
}
const entityId = skill._id.toString();
try {
const uploadOptions = getCodeApiUploadOptions(req, executionRouteKey);
const uploaded = await withCodeApiUploadRecovery({
registry: req.app.locals.codeApiUploadRegistry,
scope: uploadOptions.scope,
concurrency: uploadOptions.concurrency,
label: `priming skill "${skill.name}"`,
budget: rateLimitBudget ?? createCodeApiRateLimitBudget(uploadOptions.retryWaitMs),
signal,
onWait: (waitMs) =>
logger.warn(
`[primeSkillFiles] Rate-limited priming skill "${skill.name}"; retrying in ${waitMs}ms`,
),
openSource: () => collectSkillUploadFiles(params, inspectedBuffers),
upload: async (filesToUpload) => {
if (filesToUpload.length === 0) {
return null;
}
const result = await batchUploadCodeEnvFiles({
req,
files: filesToUpload,
/* Resource identity for codeapi's sessionKey: skill files share
* cross-user-within-tenant under `<tenant>:skill:<id>:v:<version>`.
* Bumping `skill.version` on edit naturally invalidates the prior
* cache entry under the new version's sessionKey. */
kind: 'skill',
id: entityId,
version: skill.version,
/* Skill files are infrastructure: SKILL.md + bundled scripts/schemas/
* docs that the agent reads but should never edit. Tag the upload as
* read-only so codeapi seals the inputs (chmod 444 in-sandbox) and
* walker echoes the original refs as `inherited: true` even if some
* sandboxed code path mutates bytes on disk. Without this, modified
* skill files surface as ghost generated artifacts the user has no
* authority to download. */
read_only: true,
codeApiBaseUrl: codeExecutionContext?.baseUrl,
executionProfile: codeExecutionContext?.executionProfile,
bridgeWorkerId: codeExecutionContext?.bridgeWorkerId,
signal,
});
return { filesToUpload, result };
},
});
if (uploaded == null) {
return null;
}
const { filesToUpload, result } = uploaded;
// Exclude SKILL.md from the returned files array — it is uploaded to disk
// for bash access but has no codeEnvRef (cannot be cached). Omitting it
// here keeps the fresh-upload and cache-hit code paths consistent.
const files: PrimeSkillFilesResult['files'] = result.files
.filter((f) => !f.filename.endsWith('/SKILL.md'))
.map((f) => ({
id: f.fileId,
/* `resource_id` is the skill `_id` (the entity codeapi scopes
* the sessionKey on). Distinct from `id` (the per-file storage
* uuid) — both are required on the request. */
resource_id: entityId,
storage_session_id: result.storage_session_id,
name: f.filename,
kind: 'skill',
version: skill.version,
}));
// Treat partial upload failures as a priming failure — missing bundled
// files cause follow-up bash/read calls to fail at runtime with missing paths.
const expectedCount = filesToUpload.filter((f) => !f.filename.endsWith('/SKILL.md')).length;
if (files.length < expectedCount) {
logger.error('[primeSkillFiles] Partial upload failure', {
expectedCount,
uploadedCount: files.length,
});
return null;
}
/**
* Persist codeEnvRefs on skill files. Awaited (not fire-and-forget)
* so the next prime — which can start within milliseconds when
* many users hit the same skill concurrently — sees the cache
* pointer instead of racing the read against an in-flight write.
* Without the await, a fire-and-forget under concurrency stays in
* cache-miss steady-state for the duration of the burst (each
* user's prime reads stale, re-uploads, then fires its own forget
* that the next user also misses). Latency cost is ~10–50ms on
* the prime that does the upload; subsequent primes save an entire
* batch upload. Failures don't fail the prime — the file refs
* returned to the caller are still valid.
*/
if (updateSkillFileCodeEnvIds) {
/* Uploaded filenames are namespaced `skills/{skillName}/{relativePath}`
* so the sandbox mount mirrors the model-facing skill namespace. The
* persisted `relativePath` is the bare path (e.g. `references/style.md`),
* so strip the `skills/{skillName}/` prefix rather than just the first
* segment. */
const sandboxPrefix = `${SKILL_FILE_PREFIX}${skill.name}/`;
const updates = result.files
.filter((f) => !f.filename.endsWith('/SKILL.md'))
.map((f) => {
const ref: CodeEnvRef = {
kind: 'skill',
id: entityId,
storage_session_id: result.storage_session_id,
file_id: f.fileId,
version: skill.version,
executionProfile,
...(executionRouteKey !== executionProfile ? { executionRouteKey } : {}),
};
return {
skillId: skill._id,
relativePath: f.filename.startsWith(sandboxPrefix)
? f.filename.slice(sandboxPrefix.length)
: f.filename.slice(f.filename.indexOf('/') + 1),
codeEnvRef: ref,
};
});
if (updates.length > 0) {
try {
await updateSkillFileCodeEnvIds(updates);
} catch (err: unknown) {
logger.error(
'[primeSkillFiles] Failed to persist codeEnvRefs',
getSafeErrorMetadata(err),
);
}
}
}
return { storage_session_id: result.storage_session_id, files };
} catch (error) {
if (isAbortError(error)) {
throw error;
}
logger.error('[primeSkillFiles] Batch upload failed', getSafeErrorMetadata(error));
return null;
}
}
export interface PrimeInvokedSkillsDeps {
req: ServerRequest;
/** Effective cancellation signal for the historical priming operation. */
signal?: AbortSignal;
/** Raw message payload (before formatAgentMessages). Used to extract invoked skill names. */
payload?: Array<Partial<{ role: string; content: unknown }>>;
/** Explicit durable names used by a validated event-actor preflight. */
skillNames?: readonly string[];
accessibleSkillIds: Types.ObjectId[];
/** `execute_code` capability flag for the run. When false, the batch-upload
* path is skipped entirely — skill bodies still reconstruct for history
* rebuilds, but no sandbox traffic is generated. */
codeEnvAvailable: boolean;
getSkillByName: (
name: string,
accessibleIds: Types.ObjectId[],
) => Promise<{
body: string;
name: string;
frontmatter?: Record<string, unknown>;
_id: Types.ObjectId;
version: number;
fileCount: number;
} | null>;
listSkillFiles: (skillId: Types.ObjectId | string) => Promise<SkillFileRecord[]>;
getStrategyFunctions: PrimeSkillFilesParams['getStrategyFunctions'];
batchUploadCodeEnvFiles: PrimeSkillFilesParams['batchUploadCodeEnvFiles'];
getSessionInfo?: PrimeSkillFilesParams['getSessionInfo'];
checkIfActive?: PrimeSkillFilesParams['checkIfActive'];
updateSkillFileCodeEnvIds?: PrimeSkillFilesParams['updateSkillFileCodeEnvIds'];
codeExecutionContext?: PrimeSkillFilesParams['codeExecutionContext'];
rateLimitBudget?: CodeApiRateLimitBudget;
}
export interface PrimeInvokedSkillsResult {
initialSessions?: ToolSessionMap;
/** Pre-resolved skill bodies keyed by skill name. Passed to formatAgentMessages
* so it can reconstruct HumanMessages at the right position in the message sequence. */
skills?: Map<string, string>;
/** Exact records resolved under the current request's ACL. */
skillManifest?: Array<{
id: string;
name: string;
version: number;
contentDigest: string;
}>;
}
export interface PrimeInvokedSkillsForProfilesDeps
extends Omit<PrimeInvokedSkillsDeps, 'codeEnvAvailable' | 'codeExecutionContext'> {
executionProfiles: CodeExecutionProfileRoute[];
}
/**
* Extracts previously invoked skills from message history, resolves their
* bodies from DB, and re-primes their files to the code env.
*
* Returns:
* - initialSessions: seeds Graph.sessions so ToolNode injects session_id into bash/code tools
* - skills: Map of skillName → body for formatAgentMessages to reconstruct HumanMessages
*/
export async function primeInvokedSkills(
deps: PrimeInvokedSkillsDeps,
): Promise<PrimeInvokedSkillsResult> {
if ((!deps.payload?.length && !deps.skillNames?.length) || !deps.accessibleSkillIds?.length) {
return {};
}
const invokedSkills = new Set(deps.skillNames ?? []);
for (const name of extractInvokedSkillsFromPayload(deps.payload ?? [])) {
invokedSkills.add(name);
}
if (invokedSkills.size === 0) {
return {};
}
const skills = new Map<string, string>();
// Phase 1: Resolve all skills in parallel (DB lookups)
const resolveResults = await Promise.allSettled(
Array.from(invokedSkills).map(async (skillName) => {
const skill = await deps.getSkillByName(skillName, deps.accessibleSkillIds);
return skill ?? undefined;
}),
);
const resolvedSkills: Array<{
body: string;
name: string;
frontmatter?: Record<string, unknown>;
_id: Types.ObjectId;
version: number;
fileCount: number;
}> = [];
for (const r of resolveResults) {
if (r.status === 'fulfilled' && r.value) {
assertStoredSkillBodyAllowed(r.value, deps.req);
skills.set(r.value.name, r.value.body);
resolvedSkills.push(r.value);
} else if (r.status === 'rejected') {
logger.warn('[primeInvokedSkills] Skill resolution failed:', getSafeErrorMetadata(r.reason));
}
}
const skillManifest = resolvedSkills.map((skill) => ({
id: skill._id.toString(),
name: skill.name,
version: skill.version,
contentDigest: createSkillContentDigest(skill.body),
}));
// Phase 2: Single batch upload for ALL skills' files (shared session)
let sessions: ToolSessionMap | undefined;
const skillsWithFiles = resolvedSkills.filter((s) => s.fileCount > 0);
if (deps.codeEnvAvailable && skillsWithFiles.length > 0) {
const inspectStoredMetadata = shouldInspectStoredSkillFileMetadata(deps.req);
const inspectStoredSkillFileContent = shouldInspectStoredSkillFileContent(deps.req);
// Parallel file list lookups (R2 fix)
const fileListResults = await Promise.all(
skillsWithFiles.map(async (skill) => ({
skill,
files: await deps.listSkillFiles(skill._id),
})),
);
if (inspectStoredMetadata && !inspectStoredSkillFileContent) {
for (const { files } of fileListResults) {
for (const file of files) {
assertStoredSkillFileNameAllowed(file, deps.req);
}
}
}
// Session freshness check: the code env natively handles mixed sessions
// (each file carries its own session_id, fetched independently). We check
// ALL distinct sessions for freshness. If all are active, return cached
// references with zero re-uploads. If any expired, re-upload everything.
const executionProfile = deps.codeExecutionContext?.executionProfile ?? 'default';
const executionRouteKey = deps.codeExecutionContext
? getCodeExecutionRouteKey(deps.codeExecutionContext)
: executionProfile;
if (!inspectStoredSkillFileContent && deps.getSessionInfo && deps.checkIfActive) {
const allResolved = fileListResults.flatMap((r) =>
r.files.map((f) => ({
skill: r.skill,
skillName: r.skill.name,
file: f,
ref: getCodeEnvRefForProfile(f, executionRouteKey),
})),
);
const resolvedWithRef = allResolved.filter(
(entry): entry is typeof entry & { ref: SkillCodeEnvRef } =>
isCurrentSkillRef(entry.ref, entry.skill.version),
);
// Only use cache when ALL files have refs (no partial persistence)
if (resolvedWithRef.length > 0 && resolvedWithRef.length === allResolved.length) {
const refsBySession = new Map<string, CodeEnvRef>();
for (const { ref } of resolvedWithRef) {
if (ref && !refsBySession.has(ref.storage_session_id)) {
refsBySession.set(ref.storage_session_id, ref);
}
}
const checkResults = await Promise.all(
Array.from(refsBySession.values()).map(async (ref) => {
try {
const lastModified = await deps.getSessionInfo?.(
ref,
deps.req,
deps.codeExecutionContext,
deps.signal,
);
deps.signal?.throwIfAborted();
return !!(lastModified && deps.checkIfActive?.(lastModified));
} catch (error) {
if (isAbortError(error)) {
throw error;
}
return false;
}
}),
);
deps.signal?.throwIfAborted();
const allActive = checkResults.every(Boolean);
if (allActive) {
/* `id` is the STORAGE file_id (the per-file uuid the
* file_server registered the upload under); `resource_id`
* is the entity that owns the storage session — the
* skill's `_id` here. codeapi's auth layer needs both:
* `id` for the upload-existence check, `resource_id` for
* sessionKey re-derivation (`<tenant>:skill:<resource_id>:v:<version>`).
* Conflating them sent the storage nanoid through the
* sessionKey switch and 403'd every shared-kind /exec. */
const cachedFiles = resolvedWithRef.map(({ skillName, file, ref }) => ({
id: ref!.file_id,
resource_id: ref!.id,
name: `${SKILL_FILE_PREFIX}${skillName}/${file.relativePath}`,
storage_session_id: ref!.storage_session_id,
kind: ref!.kind,
...(ref!.kind === 'skill' ? { version: ref!.version } : {}),
}));
if (cachedFiles.length > 0) {
logger.debug(
`[primeInvokedSkills] All ${refsBySession.size} session(s) active, reusing ${cachedFiles.length} cached files`,
);
sessions = new Map();
/* `session_id` at the top of CodeSessionContext is the
* (representative) execution session — ToolNode reads it
* for continuity. Per-file storage is on each
* `files[i].storage_session_id`. */
sessions.set(Constants.EXECUTE_CODE, {
session_id: cachedFiles[0].storage_session_id,
files: cachedFiles,
lastUpdated: Date.now(),
} satisfies CodeSessionContext);
return {
initialSessions: sessions,
skills: skills.size > 0 ? skills : undefined,
skillManifest,
};
}
}
}
}
// Per-skill upload: each skill gets its own storage session keyed
// by `(kind: 'skill', id: skillId, version: skill.version)`.
// primeSkillFiles handles freshness caching per-skill, so only
// expired skills re-upload. Code API handles mixed
// storage_session_ids natively.
const allPrimedFiles: Array<{
id: string;
resource_id: string;
name: string;
storage_session_id: string;
kind: 'skill';
version: number;
}> = [];
const uploadOptions = getCodeApiUploadOptions(deps.req, executionRouteKey);
const rateLimitBudget =
deps.rateLimitBudget ?? createCodeApiRateLimitBudget(uploadOptions.retryWaitMs);
const primeResults = await Promise.allSettled(
fileListResults.map(async ({ skill, files }) => {
const result = await primeSkillFiles({
skill,
skillFiles: files,
req: deps.req,
getStrategyFunctions: deps.getStrategyFunctions,
batchUploadCodeEnvFiles: deps.batchUploadCodeEnvFiles,
getSessionInfo: deps.getSessionInfo,
checkIfActive: deps.checkIfActive,
updateSkillFileCodeEnvIds: deps.updateSkillFileCodeEnvIds,
codeExecutionContext: deps.codeExecutionContext,
rateLimitBudget,
signal: deps.signal,
});
return { skill, result };
}),
);
for (const r of primeResults) {
if (r.status === 'fulfilled' && r.value.result) {
for (const f of r.value.result.files) {
allPrimedFiles.push({
id: f.id,
/* `resource_id` is the skill's `_id` — drives codeapi's
* sessionKey re-derivation. See cachedFiles above for the
* full id-vs-resource_id rationale. */
resource_id: r.value.skill._id.toString(),
name: f.name,
storage_session_id: f.storage_session_id,
kind: 'skill',
version: r.value.skill.version,
});
}
} else if (r.status === 'rejected') {
if (isContentFilterError(r.reason) || isAbortError(r.reason)) {
throw r.reason;
}
logger.warn(
'[primeInvokedSkills] Failed to prime skill files:',
getSafeErrorMetadata(r.reason),
);
} else {
/* Fulfilled-null: primeSkillFiles swallowed an upload failure (429,
* partial batch). The run proceeds without this skill's files. */
logger.warn(
`[primeInvokedSkills] Priming returned no files for skill "${r.value.skill.name}"`,
);
}
}
if (allPrimedFiles.length > 0) {
sessions = new Map();
/* `session_id` at the top of CodeSessionContext is the
* (representative) execution session. Per-file storage is on
* each file's `storage_session_id`. */
sessions.set(Constants.EXECUTE_CODE, {
session_id: allPrimedFiles[0].storage_session_id,
files: allPrimedFiles,
lastUpdated: Date.now(),
} satisfies CodeSessionContext);
}
}
return {
initialSessions: sessions,
skills: skills.size > 0 ? skills : undefined,
skillManifest,
};
}
/** Primes historical skill files once per selected Code API deployment and
* seeds only the trusted session partitions that execute on that deployment. */
export async function primeInvokedSkillsForProfiles(
deps: PrimeInvokedSkillsForProfilesDeps,
): Promise<PrimeInvokedSkillsResult> {
if (deps.executionProfiles.length === 0) {
return primeInvokedSkills({ ...deps, codeEnvAvailable: false });
}
const rateLimitBudget = createCodeApiRateLimitBudget(
deps.req.config?.endpoints?.agents?.codeApiMaxRetryWaitMs,
);
const profileResults = await Promise.all(
deps.executionProfiles.map(async (profile) => ({
profile,
result: await primeInvokedSkills({
...deps,
codeEnvAvailable: true,
codeExecutionContext: profile.codeExecutionContext,
updateSkillFileCodeEnvIds: deps.updateSkillFileCodeEnvIds,
rateLimitBudget,
signal: deps.signal,
}),
})),
);
let initialSessions: ToolSessionMap | undefined;
const skills = new Map<string, string>();
const skillManifestByName = new Map<
string,
NonNullable<PrimeInvokedSkillsResult['skillManifest']>[number]
>();
for (const { profile, result } of profileResults) {
const resultManifestByName = new Map(
(result.skillManifest ?? []).map((skill) => [skill.name, skill]),
);
for (const [name, body] of result.skills ?? []) {
const identity = resultManifestByName.get(name);
if (identity == null) {
throw new Error(`Skill "${name}" resolved without a semantic identity`);
}
const existingIdentity = skillManifestByName.get(name);
const existingBody = skills.get(name);
if (
(existingIdentity != null &&
JSON.stringify(existingIdentity) !== JSON.stringify(identity)) ||
(existingBody != null && existingBody !== body)
) {
throw new Error(`Skill "${name}" changed while execution profiles were initialized`);
}
skills.set(name, body);
skillManifestByName.set(name, identity);
}
const skillFiles = result.initialSessions?.get(Constants.EXECUTE_CODE)?.files;
if (!skillFiles?.length) {
continue;
}
for (const sessionKey of profile.codeSessionKeys) {
initialSessions = seedCodeFilesIntoSessions(
skillFiles as CodeEnvFile[],
initialSessions,
sessionKey,
);
}
}
return {
initialSessions,
skills: skills.size > 0 ? skills : undefined,
skillManifest:
skillManifestByName.size > 0
? [...skillManifestByName.values()].sort((left, right) => left.id.localeCompare(right.id))
: undefined,
};
}