🎣 fix: Bound Attachment Preview Matching Work (#17384)

* 🎣 fix: Bound Attachment Preview Matching Work

* test: Type the Scope Iterator and Check Concurrent Requests

* fix: Keep Attachment Candidate Selection Lint-Clean

---------

Co-authored-by: Lia <lia@librechat.ai>
This commit is contained in:
lia-by-librechat[bot] 2026-10-24 11:44:47 +02:00 • committed by GitHub
parent 0716094734
commit b69adddcd4
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
4 changed files with 349 additions and 59 deletions

View file

@ -129,11 +129,12 @@ describe('tool-call previews on the message routes', () => {
const messagesRouter = require('../messages');
app = express();
app.use(express.json({ limit: '10mb' }));
app.use(express.json({ limit: '3mb' }));
app.use((req, _res, next) => {
req.user = { id: req.headers['x-user'] ?? OWNER };
next();
});
app.get('/health', (_req, res) => res.sendStatus(200));
app.use('/api/messages', messagesRouter);
});
@ -202,6 +203,51 @@ describe('tool-call previews on the message routes', () => {
expect(message.content[0]).toEqual({ type: 'text', text: 'Building now', agentId: 'agent_a' });
});
it('previews a persisted large client-authored transcript with repeated attachment scopes', async () => {
const messageId = 'repeated-attachments';
const payload = {
messageId,
parentMessageId: 'user-1',
isCreatedByUser: false,
text: '',
content: [
{
type: 'tool_call',
tool_call: {
id: 'parent',
name: 'subagent',
output: 'done',
subagent_content: Array.from({ length: 10_000 }, () => ({
type: 'tool_call',
tool_call: { id: 'x' },
})),
},
},
],
attachments: Array.from({ length: 30_000 }, () => ({ toolCallId: 'x' })),
};
expect(Buffer.byteLength(JSON.stringify(payload))).toBeLessThan(3 * 1024 * 1024);
const saved = await request(app).post(`/api/messages/${conversationId}`).send(payload);
expect(saved.status).toBe(201);
const started = performance.now();
const [response, health] = await Promise.all([
request(app).get(`/api/messages/${conversationId}?toolPreviews=1`),
new Promise((resolve) => setTimeout(resolve, 25)).then(() => request(app).get('/health')),
]);
expect(health.status).toBe(200);
expect(response.status).toBe(200);
const preview = response.body.find((message) => message.messageId === messageId);
expect(preview.content[0].tool_call).toMatchObject({
subagentContentOmitted: true,
subagentAttachmentCalls: [{ id: 'x' }],
});
expect(preview.content[0].tool_call).not.toHaveProperty('subagent_content');
expect(performance.now() - started).toBeLessThan(3_000);
const [stored] = await mockDb.methods.getMessages({ messageId, user: OWNER });
expect(stored.content[0].tool_call.subagent_content).toHaveLength(10_000);
});
it('previews a stored long decimal without changing its numeric text or stored output', async () => {
const output = `{"n":1.${'0'.repeat(80_000)}1}`;
const messageId = 'long-decimal';

View file

@ -8,6 +8,7 @@ import {
containsToolCallPreviews,
prepareToolCallPreviews,
previewMessagesToolCalls,
previewContentToolCalls,
prepareResultToolCallPreviews,
rejectToolCallPreviewWrites,
withToolCallPreviews,
@ -49,6 +50,21 @@ const toolPart = (toolCall: TestToolCall) => ({
const longOutput = (head: string, tail: string, fill = 'x'.repeat(20_000)) =>
`${head}${fill}${tail}`;
describe('attachment matching work configuration', () => {
it('defaults to a bounded budget and accepts overrides', () => {
expect(toolCallPreviewsConfigSchema.parse({}).attachmentWorkLimit).toBe(100_000);
expect(toolCallPreviewsConfigSchema.parse({ attachmentWorkLimit: 2 }).attachmentWorkLimit).toBe(
2,
);
});
it.each([0, -1, 1.5, 1_000_001, Infinity, '100'])('rejects invalid budget %p', (value) => {
expect(toolCallPreviewsConfigSchema.safeParse({ attachmentWorkLimit: value }).success).toBe(
false,
);
});
});
describe('previewOutputText', () => {
it('keeps short output untouched', () => {
expect(previewOutputText('done', 1_024)).toBe('done');
@ -532,6 +548,92 @@ describe('previewMessagesToolCalls', () => {
expect(part.tool_call.subagentAttachmentCalls).toHaveLength(1);
});
it('deduplicates repeated attachment tuples before charging the matching budget', () => {
const subagent = toolPart({
name: 'subagent',
output: 'done',
subagent_content: Array.from({ length: 10_000 }, () => toolPart({ id: 'x' })),
});
const attachments = Array.from({ length: 30_000 }, () => ({ toolCallId: 'x' }));
const messages = [{ content: [subagent], attachments }];
expect(Buffer.byteLength(JSON.stringify(messages))).toBeLessThan(3 * 1024 * 1024);
const [message] = previewMessagesToolCalls(messages, {
...limits,
attachmentWorkLimit: 10_001,
});
expect(message.content[0].tool_call).toMatchObject({
subagentContentOmitted: true,
subagentAttachmentCalls: [{ id: 'x' }],
});
expect(subagent.tool_call.subagent_content).toHaveLength(10_000);
});
it('looks up each distinct scope once rather than scanning it for every reused child id', () => {
const scopes = Array.from({ length: 300 }, (_, i) => ({ agentId: `agent_${i}` }));
let visits = 0;
const originalIterator = scopes[Symbol.iterator].bind(scopes);
scopes[Symbol.iterator] = () => {
const iterator = originalIterator();
const next = iterator.next.bind(iterator);
iterator.next = () => {
const entry = next();
if (!entry.done && ++visits > scopes.length) {
throw new Error('Attachment scope scanned more than once');
}
return entry;
};
return iterator;
};
const subagent = toolPart({
name: 'subagent',
output: 'done',
subagent_content: Array.from({ length: 300 }, (_, i) =>
toolPart({ id: 'x', agentId: `agent_${i}` }),
),
});
const [part] = previewContentToolCalls(
[subagent],
limits,
'',
new Map([['x', scopes]]),
) as Array<{ tool_call: TestToolCall }>;
expect(part.tool_call.subagentContentOmitted).toBe(true);
expect(part.tool_call.subagentAttachmentCalls).toHaveLength(300);
expect(visits).toBe(300);
});
it('shares the work budget across parent calls and keeps incomplete transcripts in full', () => {
const parent = (id: string) =>
toolPart({
id,
name: 'subagent',
output: 'done',
subagent_content: [toolPart({ id: 'x' })],
});
const content = [parent('first'), parent('second')];
const [message] = previewMessagesToolCalls([{ content, attachments: [{ toolCallId: 'x' }] }], {
...limits,
attachmentWorkLimit: 3,
});
expect(message.content[0].tool_call.subagentContentOmitted).toBe(true);
expect(message.content[1]).toBe(content[1]);
expect(message.content[1].tool_call).not.toHaveProperty('subagentAttachmentCalls');
expect(message.content[1].tool_call.subagent_content).toHaveLength(1);
});
it('keeps the full transcript when the node budget is exhausted before a later match', () => {
const subagent = toolPart({
output: 'done',
subagent_content: [{ type: ContentTypes.TEXT, text: 'first' }, toolPart({ id: 'x' })],
});
const [message] = previewMessagesToolCalls(
[{ content: [subagent], attachments: [{ toolCallId: 'x' }] }],
{ ...limits, attachmentWorkLimit: 1 },
);
expect(message.content[0]).toBe(subagent);
expect(message.content[0].tool_call).not.toHaveProperty('subagentContentOmitted');
});
it('scopes hints to the agent a stored subagent call ran', () => {
const subagent = toolPart({
name: 'subagent',
@ -814,6 +916,45 @@ describe('findSubagentAttachmentCalls', () => {
]);
});
it('preserves first exact and first agreeing matches for every partial scope', () => {
const values = [undefined, '', 'a', 'b'];
const scopes = values.flatMap((agentId) => values.map((stepId) => ({ agentId, stepId })));
const calls = scopes.map((scope) => ({ id: 'x', ...scope }));
// Rotate traversal order so an unscoped fallback does not always precede an exact match.
for (let offset = 0; offset < calls.length; offset++) {
const ordered = [...calls.slice(offset), ...calls.slice(0, offset)];
for (const file of scopes) {
const exact = ordered.find(
(candidate) =>
(file.agentId == null || candidate.agentId === file.agentId) &&
(file.stepId == null || candidate.stepId === file.stepId),
);
const agreeing = ordered.find(
(candidate) =>
(file.agentId == null ||
candidate.agentId == null ||
candidate.agentId === file.agentId) &&
(file.stepId == null || candidate.stepId == null || candidate.stepId === file.stepId),
);
const expected = ordered.filter(
(candidate) => candidate === exact || candidate === agreeing,
);
const transcript = ordered.map(({ id, agentId, stepId }) =>
toolPart({ id, agentId, stepId }),
);
expect(
findSubagentAttachmentCalls(
[subagent('parent', transcript)],
[
{ toolCallId: 'x', ...file },
{ toolCallId: 'x', ...file },
],
),
).toEqual([{ toolCallId: 'parent', calls: expected }]);
}
}
});
it('walks nested runs and ignores calls no queried file names', () => {
const content = [
subagent('outer', [subagent('inner', [call('deep'), call('other')])]),

View file

@ -18,7 +18,18 @@ import type { AppConfig } from '@librechat/data-schemas';
import type { AppConfigUserLike, GetAppConfigOptions } from '~/app/service';
import { getAppConfigOptionsFromUser } from '~/app/service';
export type ToolCallPreviewLimits = Pick<TToolCallPreviewsConfig, 'outputChars' | 'argsChars'>;
export type ToolCallPreviewLimits = Pick<TToolCallPreviewsConfig, 'outputChars' | 'argsChars'> &
Partial<Pick<TToolCallPreviewsConfig, 'attachmentWorkLimit'>>;
type AttachmentWorkBudget = { remaining: number };
const DEFAULT_ATTACHMENT_WORK_LIMIT: number = toolCallPreviewsConfigSchema.parse(
{},
).attachmentWorkLimit;
const attachmentWorkBudget = (limits: ToolCallPreviewLimits): AttachmentWorkBudget => ({
remaining: limits.attachmentWorkLimit ?? DEFAULT_ATTACHMENT_WORK_LIMIT,
});
/** Separates the kept start and end of an output preview. */
export const TOOL_CALL_PREVIEW_ELISION = '\n…\n';
@ -175,69 +186,120 @@ type AttachmentScope = { agentId?: string; stepId?: string };
/** Each tool call id a message's attachments were saved under, with the scopes saved with it. */
type AttachmentScopes = ReadonlyMap<string, readonly AttachmentScope[]>;
/** A scope both sides carry must agree: the ownership rule the client applies. */
const scopeAgrees = (call: AttachmentScope, file: AttachmentScope): boolean =>
(call.agentId == null || file.agentId == null || call.agentId === file.agentId) &&
(call.stepId == null || file.stepId == null || call.stepId === file.stepId);
/** The agent a stored subagent call ran, from its persisted identity. */
const runAgentId = (toolCall: StoredToolCall): string | undefined => {
const identity = toolCall.subagentIdentity as { subagentAgentId?: unknown } | undefined;
return typeof identity?.subagentAgentId === 'string' ? identity.subagentAgentId : undefined;
};
/** Whether the call carries every scope the attachment does. */
const scopeMatches = (call: AttachmentScope, file: AttachmentScope): boolean =>
(file.agentId == null || call.agentId === file.agentId) &&
(file.stepId == null || call.stepId === file.stepId);
type IndexedAttachmentCall = { call: Agents.SubagentAttachmentCall; order: number };
interface AttachmentCallIndex {
first: IndexedAttachmentCall;
byAgent: Map<string | undefined, IndexedAttachmentCall>;
byStep: Map<string | undefined, IndexedAttachmentCall>;
byScope: Map<string | undefined, Map<string | undefined, IndexedAttachmentCall>>;
}
/** First call carrying every field the file scopes, with absent file fields as wildcards. */
function firstAttachmentCall(
index: AttachmentCallIndex,
scope: AttachmentScope,
): IndexedAttachmentCall | undefined {
if (scope.agentId == null) {
return scope.stepId == null ? index.first : index.byStep.get(scope.stepId);
}
return scope.stepId == null
? index.byAgent.get(scope.agentId)
: index.byScope.get(scope.agentId)?.get(scope.stepId);
}
/** First compatible call, including calls missing a field the file carries. */
function firstAgreeingAttachmentCall(
index: AttachmentCallIndex,
scope: AttachmentScope,
): IndexedAttachmentCall | undefined {
if (scope.agentId == null && scope.stepId == null) {
return index.first;
}
let candidates: Array<IndexedAttachmentCall | undefined>;
if (scope.agentId == null) {
candidates = [index.byStep.get(scope.stepId), index.byStep.get(undefined)];
} else if (scope.stepId == null) {
candidates = [index.byAgent.get(scope.agentId), index.byAgent.get(undefined)];
} else {
candidates = [
index.byScope.get(scope.agentId)?.get(scope.stepId),
index.byScope.get(undefined)?.get(scope.stepId),
index.byScope.get(scope.agentId)?.get(undefined),
index.byScope.get(undefined)?.get(undefined),
];
}
let first: IndexedAttachmentCall | undefined;
for (const candidate of candidates) {
if (candidate != null && (first == null || candidate.order < first.order)) {
first = candidate;
}
}
return first;
}
/**
* Tool calls anywhere in the parts, including inside nested subagent runs, that one of the
* message's attachments can belong to, with the agent and step scope a client checks it against.
* For each attachment scope only the first call matching it exactly and the first call agreeing
* with it are kept (the two a client can choose between), so a reused id, or an attachment with
* no scope to narrow it, does not grow the hint with the transcript.
* no scope to narrow it, does not grow the hint with the transcript. Indexing makes each scope
* a constant-time lookup rather than a scan for every child call.
*/
function nestedAttachmentCalls(
parts: unknown[],
wanted: AttachmentScopes,
ownerAgentId?: string,
): Agents.SubagentAttachmentCall[] {
const found = new Map<string, Agents.SubagentAttachmentCall>();
const exactFor = new Set<AttachmentScope>();
const agreeingFor = new Set<AttachmentScope>();
budget?: AttachmentWorkBudget,
): Agents.SubagentAttachmentCall[] | undefined {
const indexes = new Map<string, AttachmentCallIndex>();
const ordered: IndexedAttachmentCall[] = [];
/** Each level carries the agent of the run it belongs to, for parts that do not stamp one. */
const stack: Array<[unknown[], string | undefined]> = [[parts, ownerAgentId]];
while (stack.length > 0) {
const [current, levelOwner] = stack.pop() ?? [[], undefined];
for (const part of current) {
if (budget != null && budget.remaining-- <= 0) {
return undefined;
}
if (!isToolCallPart(part)) {
continue;
}
const { id, stepId, subagent_content } = part.tool_call;
const scopes = typeof id === 'string' ? wanted.get(id) : undefined;
if (scopes != null) {
/** The owner is stored on the part, on the call, or on the run that holds it. */
if (typeof id === 'string' && wanted.has(id)) {
const owner = part.agentId ?? part.tool_call.agentId ?? levelOwner;
const call: Agents.SubagentAttachmentCall = {
id: id as string,
...(typeof owner === 'string' ? { agentId: owner } : {}),
...(typeof stepId === 'string' ? { stepId } : {}),
};
let useful = false;
for (const scope of scopes) {
if (!exactFor.has(scope) && scopeMatches(call, scope)) {
exactFor.add(scope);
useful = true;
const agentId = typeof owner === 'string' ? owner : undefined;
const step = typeof stepId === 'string' ? stepId : undefined;
let index = indexes.get(id);
if (index?.byScope.get(agentId)?.has(step) !== true) {
const entry: IndexedAttachmentCall = {
call: {
id,
...(agentId != null ? { agentId } : {}),
...(step != null ? { stepId: step } : {}),
},
order: ordered.length,
};
ordered.push(entry);
if (index == null) {
index = { first: entry, byAgent: new Map(), byStep: new Map(), byScope: new Map() };
indexes.set(id, index);
}
if (!agreeingFor.has(scope) && scopeAgrees(call, scope)) {
agreeingFor.add(scope);
useful = true;
if (!index.byAgent.has(agentId)) {
index.byAgent.set(agentId, entry);
}
}
const identity = [call.id, call.agentId ?? '', call.stepId ?? ''].join('\u0000');
if (useful && !found.has(identity)) {
found.set(identity, call);
if (!index.byStep.has(step)) {
index.byStep.set(step, entry);
}
const steps = index.byScope.get(agentId) ?? new Map();
steps.set(step, entry);
index.byScope.set(agentId, steps);
}
}
if (Array.isArray(subagent_content)) {
@ -245,15 +307,40 @@ function nestedAttachmentCalls(
}
}
}
return [...found.values()];
const selected = new Set<IndexedAttachmentCall>();
for (const [id, index] of indexes) {
for (const scope of wanted.get(id) ?? []) {
if (budget != null && budget.remaining-- <= 0) {
return undefined;
}
const exact = firstAttachmentCall(index, scope);
const agreeing = firstAgreeingAttachmentCall(index, scope);
if (exact != null) {
selected.add(exact);
}
if (agreeing != null) {
selected.add(agreeing);
}
}
}
const calls: Agents.SubagentAttachmentCall[] = [];
for (const entry of ordered) {
if (selected.has(entry)) {
calls.push(entry.call);
}
}
return calls;
}
/** The tool call ids a message's attachments were saved under, with their scopes. */
function attachmentToolCallIds(message: PreviewableMessage): AttachmentScopes | undefined {
/** Deduplicates attachment scope tuples before any transcript is matched. */
function attachmentToolCallIds(message: {
attachments?: readonly unknown[] | null;
}): AttachmentScopes | undefined {
if (!Array.isArray(message.attachments) || message.attachments.length === 0) {
return undefined;
}
const scopes = new Map<string, AttachmentScope[]>();
const seen = new Map<string, Set<string>>();
for (const attachment of message.attachments) {
if (!isObject(attachment)) {
continue;
@ -266,11 +353,19 @@ function attachmentToolCallIds(message: PreviewableMessage): AttachmentScopes |
if (typeof toolCallId !== 'string' || toolCallId === '') {
continue;
}
const entries = scopes.get(toolCallId) ?? [];
entries.push({
const scope: AttachmentScope = {
...(typeof agentId === 'string' ? { agentId } : {}),
...(typeof stepId === 'string' ? { stepId } : {}),
});
};
const key = JSON.stringify([scope.agentId, scope.stepId]);
const keys = seen.get(toolCallId) ?? new Set<string>();
if (keys.has(key)) {
continue;
}
keys.add(key);
seen.set(toolCallId, keys);
const entries = scopes.get(toolCallId) ?? [];
entries.push(scope);
scopes.set(toolCallId, entries);
}
return scopes.size > 0 ? scopes : undefined;
@ -297,14 +392,9 @@ export function findSubagentAttachmentCalls(
content: unknown[],
files: ReadonlyArray<AttachmentCallQuery>,
): SubagentAttachmentCallsEntry[] {
const wanted = new Map<string, AttachmentScope[]>();
for (const { toolCallId, agentId, stepId } of files) {
const scopes = wanted.get(toolCallId) ?? [];
scopes.push({ ...(agentId != null ? { agentId } : {}), ...(stepId != null ? { stepId } : {}) });
wanted.set(toolCallId, scopes);
}
const wanted = attachmentToolCallIds({ attachments: files });
const entries: SubagentAttachmentCallsEntry[] = [];
if (wanted.size === 0) {
if (wanted == null) {
return entries;
}
for (const part of content) {
@ -320,7 +410,7 @@ export function findSubagentAttachmentCalls(
wanted,
runAgentId(part.tool_call),
);
if (calls.length === 0) {
if (calls == null || calls.length === 0) {
continue;
}
entries.push({
@ -629,6 +719,7 @@ export function previewToolCall<T extends StoredToolCall>(
limits: ToolCallPreviewLimits,
revision = '',
attachmentIds?: AttachmentScopes,
budget: AttachmentWorkBudget = attachmentWorkBudget(limits),
): T {
if (!isAgentToolCall(toolCall) || !isSettled(toolCall) || !hasIdentity(toolCall)) {
return toolCall;
@ -641,11 +732,23 @@ export function previewToolCall<T extends StoredToolCall>(
const outputPreview = previewToolCallOutput(toolCall, output, limits.outputChars);
const argsPreview = previewToolCallArgs(toolCall.args, limits.argsChars);
const subagentContent = toolCall.subagent_content;
const omitSubagentContent =
let omitSubagentContent =
Array.isArray(subagentContent) &&
subagentContent.length > 0 &&
!hasPendingApproval(subagentContent);
let childCalls: Agents.SubagentAttachmentCall[] | undefined;
if (omitSubagentContent && attachmentIds != null) {
childCalls = nestedAttachmentCalls(
subagentContent as unknown[],
attachmentIds,
runAgentId(toolCall),
budget,
);
// Never omit a transcript with incomplete attachment ownership hints.
omitSubagentContent = childCalls != null;
}
if (outputPreview === output && argsPreview == null && !omitSubagentContent) {
return toolCall;
}
@ -665,11 +768,7 @@ export function previewToolCall<T extends StoredToolCall>(
delete next.subagent_content;
next.subagentContentOmitted = true;
next.subagentContentParts = (subagentContent as unknown[]).length;
const childCalls =
attachmentIds == null
? []
: nestedAttachmentCalls(subagentContent as unknown[], attachmentIds, runAgentId(toolCall));
if (childCalls.length > 0) {
if (childCalls != null && childCalls.length > 0) {
next.subagentAttachmentCalls = childCalls;
}
}
@ -687,10 +786,11 @@ function previewToolCallSafely<T extends StoredToolCall>(
toolCall: T,
limits: ToolCallPreviewLimits,
revision: string,
attachmentIds?: AttachmentScopes,
attachmentIds: AttachmentScopes | undefined,
budget: AttachmentWorkBudget,
): T {
try {
return previewToolCall(toolCall, limits, revision, attachmentIds);
return previewToolCall(toolCall, limits, revision, attachmentIds, budget);
} catch (error) {
logger.warn('[toolCallPreviews] Sending a tool call in full; its preview failed', error);
return toolCall;
@ -704,6 +804,7 @@ export function previewContentToolCalls(
revision = '',
attachmentIds?: AttachmentScopes,
): unknown[] {
const budget = attachmentWorkBudget(limits);
let result: unknown[] | undefined;
/** First index of each identity; a repeat sends both calls whole (see `toolCallIdentity`). */
const firstIndex = new Map<string, number>();
@ -725,7 +826,7 @@ export function previewContentToolCalls(
continue;
}
firstIndex.set(identity, i);
const toolCall = previewToolCallSafely(part.tool_call, limits, revision, attachmentIds);
const toolCall = previewToolCallSafely(part.tool_call, limits, revision, attachmentIds, budget);
if (toolCall === part.tool_call) {
continue;
}

View file

@ -4279,6 +4279,8 @@ export const toolCallPreviewsConfigSchema = z.object({
/** Characters of serialized `args` kept per tool call. JSON arguments stay valid JSON with
* every field present; only the longest strings are shortened. */
argsChars: z.number().int().min(256).max(1_000_000).default(512),
/** Transcript nodes and unique scope lookups per message; exhausted calls keep their transcript. */
attachmentWorkLimit: z.number().int().min(1).max(1_000_000).default(100_000),
});
export type TToolCallPreviewsConfig = z.infer<typeof toolCallPreviewsConfigSchema>;