🎽 fix: Hand Same-Batch Code Calls the Files a Skill Just Loaded (#16115)

* fix: give same-batch code calls the files a skill just loaded

A batch that carries a skill call next to execute_code/bash ran both
against the code-session snapshot the graph took when it planned the
batch, so the sandbox had no /mnt/data/skills/<name>/ for that turn.
Code calls in a mixed batch now wait on the skill calls and merge their
uploaded refs into their own context before dispatch.

* test: pin the spec's own file ref kind so CodeEnvFile stays assignable

---------

Co-authored-by: Lia <lia@librechat.ai>
This commit is contained in:
lia-by-librechat[bot] 2026-09-20 06:11:35 -04:00 • committed by GitHub
parent c692357dc1
commit feb8682dec
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
2 changed files with 414 additions and 0 deletions

View file

@ -2827,6 +2827,309 @@ describe('createToolExecuteHandler', () => {
});
});
describe('same-batch skill file handoff to code calls', () => {
/** Code API batch-upload response shape: one bundled file plus the
* SKILL.md the handler excludes from the artifact. */
function uploadFor(skillName: string) {
return {
storage_session_id: `session-${skillName}`,
files: [
{ fileId: `file-${skillName}`, filename: `skills/${skillName}/references/style.md` },
{ fileId: `skillmd-${skillName}`, filename: `skills/${skillName}/SKILL.md` },
],
};
}
/** The artifact ref `primeSkillFiles` derives from {@link uploadFor}. */
function primedRefFor(skillName: string) {
return {
id: `file-${skillName}`,
resource_id: `${skillName}-id`,
storage_session_id: `session-${skillName}`,
name: `skills/${skillName}/references/style.md`,
kind: 'skill',
version: 1,
};
}
/** A skill with one bundled file and every dependency the priming gate
* needs, loaded alongside real code tools so one batch carries both. */
function makeHandler(params: {
batchUploadCodeEnvFiles: jest.Mock;
tools?: unknown[];
configurable?: Record<string, unknown>;
options?: Partial<ToolExecuteOptions>;
}) {
const loadTools: ToolExecuteOptions['loadTools'] = jest.fn(async () => ({
loadedTools: (params.tools ?? []) as never[],
configurable: {
accessibleSkillIds: skillsInScope(),
codeEnvAvailable: true,
req: {
user: { id: 'user-1', tenantId: 'tenant-1' },
app: { locals: { codeApiUploadRegistry: createCodeApiUploadRegistry() } },
config: {
endpoints: {
agents: { codeApiUploadConcurrency: 2, codeApiMaxRetryWaitMs: 1_000 },
},
},
},
...(params.configurable ?? {}),
},
}));
return createToolExecuteHandler({
loadTools,
getSkillByName: jest.fn(async (name) => ({
_id: `${name}-id` as unknown as never,
name: name as string,
body: 'skill body',
fileCount: 1,
version: 1,
})) as unknown as ToolExecuteOptions['getSkillByName'],
listSkillFiles: jest.fn(async (skillId: unknown) => [
{
relativePath: 'references/style.md',
filename: 'style.md',
filepath: `/storage/${String(skillId)}/references/style.md`,
source: 's3',
bytes: 256,
},
]) as unknown as ToolExecuteOptions['listSkillFiles'],
getStrategyFunctions: jest.fn(() => ({
getDownloadStream: jest.fn(async () => Readable.from(Buffer.from(''))),
})) as unknown as ToolExecuteOptions['getStrategyFunctions'],
batchUploadCodeEnvFiles:
params.batchUploadCodeEnvFiles as unknown as ToolExecuteOptions['batchUploadCodeEnvFiles'],
...(params.options ?? {}),
});
}
it('injects the files a skill just uploaded into an execute_code call in the same batch', async () => {
const capturedConfigs: Record<string, unknown>[] = [];
const batchUploadCodeEnvFiles = jest.fn(async ({ id }: { id: string }) =>
uploadFor(id.replace(/-id$/, '')),
);
const handler = makeHandler({
batchUploadCodeEnvFiles,
tools: [createMockTool(Constants.EXECUTE_CODE, capturedConfigs)],
});
const results = await invokeHandler(handler, [
{ id: 'call_skill', name: Constants.SKILL_TOOL, args: { skillName: 'brand-kit' } },
{
id: 'call_code',
name: Constants.EXECUTE_CODE,
args: { lang: 'python', code: 'print(1)' },
},
]);
expect(results.map((result) => result.status)).toEqual(['success', 'success']);
expect(capturedConfigs).toHaveLength(1);
expect(capturedConfigs[0].session_id).toBe('session-brand-kit');
expect(capturedConfigs[0]._injected_files).toEqual([primedRefFor('brand-kit')]);
});
it('injects the files of every skill invoked in the batch', async () => {
const capturedConfigs: Record<string, unknown>[] = [];
const batchUploadCodeEnvFiles = jest.fn(async ({ id }: { id: string }) =>
uploadFor(id.replace(/-id$/, '')),
);
const handler = makeHandler({
batchUploadCodeEnvFiles,
tools: [createMockTool(Constants.EXECUTE_CODE, capturedConfigs)],
});
const results = await invokeHandler(handler, [
{ id: 'call_skill_a', name: Constants.SKILL_TOOL, args: { skillName: 'brand-kit' } },
{ id: 'call_skill_b', name: Constants.SKILL_TOOL, args: { skillName: 'chart-lib' } },
{
id: 'call_code',
name: Constants.EXECUTE_CODE,
args: { lang: 'python', code: 'print(1)' },
},
]);
expect(results.map((result) => result.status)).toEqual(['success', 'success', 'success']);
expect(capturedConfigs[0]._injected_files).toEqual(
expect.arrayContaining([primedRefFor('brand-kit'), primedRefFor('chart-lib')]),
);
expect(capturedConfigs[0]._injected_files).toHaveLength(2);
});
it('hands the files to a backgrounded code call and to a sandbox authoring call', async () => {
const capturedConfigs: Record<string, unknown>[] = [];
const batchUploadCodeEnvFiles = jest.fn(async ({ id }: { id: string }) =>
uploadFor(id.replace(/-id$/, '')),
);
const writeSandboxFile = jest.fn(async () => ({
stdout: 'WROTE 11 bytes to /mnt/data/new.txt\n',
session_id: 'sess-new',
files: [{ id: 'file-new', name: 'new.txt', storage_session_id: 'sess-new' }],
}));
const handler = makeHandler({
batchUploadCodeEnvFiles,
tools: [createMockTool(Constants.EXECUTE_CODE, capturedConfigs)],
configurable: {
backgroundToolNames: [Constants.EXECUTE_CODE],
fileAuthoringToolNames: new Set(['create_file', 'edit_file']),
},
options: {
persistBackgroundCodeResult: jest.fn(async () => ({ attachments: [] })),
readSandboxFile: jest.fn(async () => {
throw new Error('cat: /mnt/data/new.txt: No such file or directory');
}),
writeSandboxFile,
} as unknown as Partial<ToolExecuteOptions>,
});
const results = await invokeHandlerWithConfig(
handler,
[
{ id: 'call_skill', name: Constants.SKILL_TOOL, args: { skillName: 'brand-kit' } },
{
id: 'call_code_background',
name: Constants.EXECUTE_CODE,
args: { lang: 'python', code: 'print(1)', run_in_background: true },
},
{
id: 'call_create_sandbox',
name: 'create_file',
args: { path: '/mnt/data/new.txt', content: 'hello world' },
},
],
{ thread_id: 'convo-1' },
);
expect(results.map((result) => result.status)).toEqual(['success', 'success', 'success']);
/* The sandbox authoring call sends the context it cloned. */
expect(writeSandboxFile).toHaveBeenCalledWith(
expect.objectContaining({
file_path: '/mnt/data/new.txt',
session_id: 'session-brand-kit',
files: [primedRefFor('brand-kit')],
}),
);
/* The detached code invoke starts after the dispatch returns its handle. */
await new Promise((resolve) => setImmediate(resolve));
await new Promise((resolve) => setImmediate(resolve));
expect(capturedConfigs).toHaveLength(1);
expect(capturedConfigs[0]._injected_files).toEqual([primedRefFor('brand-kit')]);
});
it('runs the code call with its original files when the skill upload fails', async () => {
const capturedConfigs: Record<string, unknown>[] = [];
const batchUploadCodeEnvFiles = jest.fn(async () => {
throw new Error('Request failed with status code 500');
});
const handler = makeHandler({
batchUploadCodeEnvFiles,
tools: [createMockTool(Constants.EXECUTE_CODE, capturedConfigs)],
});
const ownFile = {
storage_session_id: 'sess-own',
id: 'own-1',
resource_id: 'user_alice',
name: 'data.parquet',
kind: 'user' as const,
};
const [skillResult, codeResult] = await invokeHandler(handler, [
{ id: 'call_skill', name: Constants.SKILL_TOOL, args: { skillName: 'brand-kit' } },
{
id: 'call_code',
name: Constants.EXECUTE_CODE,
args: { lang: 'python', code: 'print(1)' },
codeSessionContext: { session_id: 'sess-own', files: [ownFile] },
},
]);
expect(skillResult.status).toBe('success');
expect(skillResult.content).toContain('could not be loaded into the code environment');
expect(codeResult.status).toBe('success');
expect(capturedConfigs).toHaveLength(1);
expect(capturedConfigs[0].session_id).toBe('sess-own');
expect(capturedConfigs[0]._injected_files).toEqual([ownFile]);
});
it('keeps code calls concurrent when the batch has no skill call', async () => {
const order: string[] = [];
let releaseFirst: () => void = () => undefined;
const secondStarted = new Promise<void>((resolve) => {
releaseFirst = resolve;
});
const codeTool = {
name: Constants.EXECUTE_CODE,
invoke: jest.fn(async (_args: unknown, config: Record<string, unknown>) => {
const callId = (config.toolCall as { id: string }).id;
order.push(`start:${callId}`);
if (callId === 'call_code_a') {
await secondStarted;
} else {
releaseFirst();
}
order.push(`end:${callId}`);
return { content: 'ok' };
}),
};
const handler = makeHandler({
batchUploadCodeEnvFiles: jest.fn(),
tools: [codeTool],
});
const results = await invokeHandler(handler, [
{ id: 'call_code_a', name: Constants.EXECUTE_CODE, args: { lang: 'python', code: 'a()' } },
{ id: 'call_code_b', name: Constants.EXECUTE_CODE, args: { lang: 'python', code: 'b()' } },
]);
expect(results.map((result) => result.status)).toEqual(['success', 'success']);
/* The second call ran to completion while the first was still in
flight: a batch without a skill call serializes nothing. */
expect(order).toEqual([
'start:call_code_a',
'start:call_code_b',
'end:call_code_b',
'end:call_code_a',
]);
});
it('does not start the code call when the run is aborted while skill files load', async () => {
const capturedConfigs: Record<string, unknown>[] = [];
const controller = new AbortController();
const batchUploadCodeEnvFiles = jest.fn(
({ signal }: { signal?: AbortSignal }) =>
new Promise<never>((_resolve, reject) => {
signal?.addEventListener('abort', () => reject(signal.reason), { once: true });
}),
);
const codeTool = createMockTool(Constants.EXECUTE_CODE, capturedConfigs);
const handler = makeHandler({ batchUploadCodeEnvFiles, tools: [codeTool] });
const resultsPromise = new Promise<ToolExecuteResult[]>((resolve, reject) => {
handler.handle('on_tool_execute', {
toolCalls: [
{ id: 'call_skill', name: Constants.SKILL_TOOL, args: { skillName: 'brand-kit' } },
{
id: 'call_code',
name: Constants.EXECUTE_CODE,
args: { lang: 'python', code: 'print(1)' },
},
],
signal: controller.signal,
resolve,
reject,
} as ToolExecuteBatchRequest);
});
setTimeout(() => controller.abort(), 10);
const [skillResult, codeResult] = await resultsPromise;
expect(skillResult.status).toBe('error');
expect(codeResult.status).toBe('error');
expect(codeTool.invoke).not.toHaveBeenCalled();
expect(capturedConfigs).toHaveLength(0);
});
});
describe('file authoring tools for skills', () => {
const { Types } = jest.requireActual('mongoose') as typeof import('mongoose');
const SKILL_ID = new Types.ObjectId();

View file

@ -5411,6 +5411,80 @@ function buildToolCallConfig(
return toolCallConfig;
}
/**
* One-shot handoff of the files a `skill` call uploads to the code calls that
* share its batch.
*
* The graph hands every call in a batch the code-session snapshot it took when
* it planned the batch, and folds a `skill` call's artifact back into the
* session only after the whole batch settles. A code call dispatched beside a
* `skill` call therefore reads a context with none of the skill's bundled
* files: `_injected_files` omits them and the sandbox has no
* `/mnt/data/skills/<name>/` for that batch. Waiting here, then merging the
* uploaded refs into the code call's own context, is what makes the files
* visible on the turn that loaded them.
*/
interface SkillFilesHandoff {
/** Records a settled `skill` call; the last one releases every waiter. */
record(result: ToolExecuteResult): void;
/** Resolves once every `skill` call in the batch has settled, then merges
* their uploaded files into this call's own code-session context. Never
* rejects: a skill whose files failed to load contributes nothing and the
* waiting call runs with the context it already had. */
applyTo(tc: ToolCallRequest): Promise<void>;
}
function createSkillFilesHandoff(
skillToolCallIds: ReadonlySet<string>,
signal?: AbortSignal,
): SkillFilesHandoff {
const pendingSkillCallIds = new Set(skillToolCallIds);
const uploadedFiles: CodeEnvFile[] = [];
let release!: () => void;
const settled = new Promise<void>((resolve) => {
release = resolve;
});
/** A Stop ends the turn for every call in the batch, so waiters are released
* the moment it lands instead of riding out the upload's own cancellation. */
const onAbort = (): void => release();
if (signal?.aborted === true) {
release();
} else {
signal?.addEventListener('abort', onAbort, { once: true });
}
return {
record(result: ToolExecuteResult): void {
if (!pendingSkillCallIds.delete(result.toolCallId)) {
return;
}
const files =
result.status === 'success'
? (result.artifact as { files?: CodeEnvFile[] } | undefined)?.files
: undefined;
if (files && files.length > 0) {
uploadedFiles.push(...files);
}
if (pendingSkillCallIds.size === 0) {
signal?.removeEventListener('abort', onAbort);
release();
}
},
async applyTo(tc: ToolCallRequest): Promise<void> {
await settled;
/* Same call shape as the provisioned-attachment fold in the executor, so
* identity (`storage_session_id` + `id`) and destination rules stay
* consistent. Returns undefined when no skill contributed a file. */
const merged = mergeCodeFilesIntoContext(
tc.codeSessionContext as CodeSessionContext | undefined,
uploadedFiles,
);
if (merged) {
tc.codeSessionContext = merged;
}
},
};
}
export function createToolExecuteHandler(options: ToolExecuteOptions): EventHandler {
const {
runSignal: hostRunSignal,
@ -5491,10 +5565,18 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
onResult?: (result: ToolExecuteResult) => void;
}
).onResult;
/** Set only for a batch that mixes `skill` calls with code calls (see
* {@link createSkillFilesHandoff}); `undefined` leaves every other batch
* fully concurrent. */
let skillFilesHandoff: SkillFilesHandoff | undefined;
/** Reports a settled result so the agent graph can emit that call's
* completion immediately instead of waiting for the whole batch;
* `resolve` below remains the authoritative batch outcome. */
const reportResult = (result: ToolExecuteResult): ToolExecuteResult => {
/* Every per-call return in the batch funnels through here, so this is
* the one place that observes a `skill` call settling whatever path
* produced its result, including the filtered and error paths. */
skillFilesHandoff?.record(result);
try {
onResult?.(result);
} catch (callbackError) {
@ -5583,6 +5665,21 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
}
}
/* A code call in this batch reads its code-session context when it
* executes, while the `skill` call beside it is still uploading the
* files that belong in that context. Only a batch carrying both
* kinds of call waits; every other batch stays fully concurrent. */
const waitsForSkillFiles = (tc: ToolCallRequest): boolean =>
tc.name !== Constants.SKILL_TOOL &&
(isCodeSessionAwareToolCall(tc.name, mergedConfigurable) ||
(runFileSharingActive && isCodeFileToolName(tc.name)));
const skillToolCallIds = new Set(
allowedToolCalls.filter((tc) => tc.name === Constants.SKILL_TOOL).map((tc) => tc.id),
);
if (skillToolCallIds.size > 0 && allowedToolCalls.some(waitsForSkillFiles)) {
skillFilesHandoff = createSkillFilesHandoff(skillToolCallIds, runSignal);
}
const codeExecutionContext = getCodeExecutionContext(mergedConfigurable);
const runtimeSessionHint = codeExecutionContext?.runtimeSessionHint;
if (runFileSharingActive && executionContext != null) {
@ -6789,6 +6886,20 @@ export function createToolExecuteHandler(options: ToolExecuteOptions): EventHand
);
}
/* Before the background dispatch and before the sandbox
* authoring context is cloned below: both capture this call's
* code-session context, and a copy taken now would stay the
* pre-skill snapshot for the rest of the call's life. */
if (skillFilesHandoff != null && waitsForSkillFiles(tc)) {
await skillFilesHandoff.applyTo(tc);
if (runSignal?.aborted === true) {
/** The Stop landed while the skill upload held this call.
* Starting the tool now would send a request the turn has
* already abandoned. */
return reportResult(errorResult(tc, 'This operation was aborted'));
}
}
if (
backgroundToolSet.has(tc.name) &&
isBackgroundRequested(tc.args) &&