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 { logger } from '@librechat/data-schemas';
import {
Tools,
Constants,
ContentTypes,
TOOL_CALL_PREVIEWS_PARAM,
TOOL_CALL_PREVIEWS_VERSION,
COMMAND_RESULT_TRAILER,
hasToolCallPreview,
toolCallPreviewsConfigSchema,
} from 'librechat-data-provider';
import type {
Agents,
ToolCallPreviewMarkers,
TToolCallPreviewsConfig,
} from 'librechat-data-provider';
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'> &
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';
/** Share of a text output preview taken from the start; the rest keeps the end. */
const OUTPUT_HEAD_SHARE = 0.5;
/** Shortest a string inside a JSON preview gets before the structure is abandoned for text. */
const MIN_JSON_STRING_CHARS = 8;
/** Deepest JSON nesting a structure-preserving preview walks; deeper values fall back to text. */
const MAX_JSON_DEPTH = 64;
/** Ceiling on a kept exit-status trailer, so a malformed one cannot defeat the bound. */
const MAX_TRAILER_CHARS = 2_048;
/**
* Tools whose cards show their full record without going through a card disclosure, so a
* preview would be what the reader sees: the question-and-answer record reads both fields
* directly, and an image card's details dialog shows the prompt from its arguments.
*/
const FULL_CONTENT_TOOLS: ReadonlySet<string> = new Set([
'ask_user_question',
'image_gen_oai',
'image_edit_oai',
'gemini_image_gen',
]);
/**
* Tools whose collapsed card parses its JSON output for the row's verdict (task failures,
* partial results, warnings). When even a structure-preserving preview cannot fit, their output
* goes in full rather than as text that no longer parses.
*/
const PARSED_OUTPUT_TOOLS: ReadonlySet<string> = new Set<string>([
Constants.CHECK_BACKGROUND_TASK as string,
]);
/**
* Older web-search failures carry only this phrase, anywhere in the output, and the collapsed
* card reads it to label the search as not completed; such output goes whole.
*/
const LEGACY_SEARCH_ERROR = /error processing/i;
type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
/** The stored fields this module reads; everything else on the tool call passes through. */
interface StoredToolCall extends ToolCallPreviewMarkers {
type?: string;
id?: unknown;
stepId?: unknown;
name?: string;
executor?: string;
progress?: unknown;
runStepStatus?: unknown;
output?: unknown;
args?: unknown;
approval?: unknown;
subagent_content?: unknown;
subagentAttachmentCalls?: Agents.SubagentAttachmentCall[];
agentId?: unknown;
subagentIdentity?: unknown;
}
interface StoredToolCallPart {
type?: string;
agentId?: unknown;
tool_call?: StoredToolCall;
}
/** A message as read for a client; `content` is previewed and `attachments` only read. */
export interface PreviewableMessage {
content?: unknown[] | null;
attachments?: unknown[] | null;
/** Stamped onto each preview as `previewRevision`, so clients key fetched parts to it. */
updatedAt?: Date | string | number | null;
}
const isObject = (value: unknown): value is object => value != null && typeof value === 'object';
const isToolCallPart = (
part: unknown,
): part is StoredToolCallPart & { tool_call: StoredToolCall } =>
isObject(part) &&
(part as StoredToolCallPart).type === ContentTypes.TOOL_CALL &&
isObject((part as StoredToolCallPart).tool_call);
/** Agent tool calls only; legacy Assistants shapes keep their own nested output fields. */
const isAgentToolCall = (toolCall: StoredToolCall): boolean =>
toolCall.type == null || toolCall.type === 'tool_call';
const hasOutput = (toolCall: StoredToolCall): boolean =>
typeof toolCall.output === 'string' && toolCall.output.length > 0;
/** Only a call with an id can be fetched back by identity, so only such calls are previewed. */
const hasIdentity = (toolCall: StoredToolCall): boolean =>
typeof toolCall.id === 'string' && toolCall.id !== '';
/**
* The identity the client sends to fetch a part back: provider call id, host run-step id and
* the part's agent, matched exactly by the part endpoint. Provider ids can repeat within a
* response, so a call is previewed only when this identity is unique in its message; otherwise
* no request could name it without also naming another call.
*/
function toolCallIdentity(part: StoredToolCallPart & { tool_call: StoredToolCall }): string | null {
const { id, stepId } = part.tool_call;
if (typeof id !== 'string' || id === '') {
return null;
}
const step = typeof stepId === 'string' ? stepId : '';
const agent = typeof part.agentId === 'string' ? part.agentId : '';
return `${id}\u0000${step}\u0000${agent}`;
}
/**
* A call whose content no card still acts on: it has output, or its run step closed or reached
* full progress, and it is not waiting on an approval. A subagent can finish with no final text,
* and its transcript is as large as any other.
*/
const isSettled = (toolCall: StoredToolCall): boolean => {
if (toolCall.approval != null && !hasOutput(toolCall)) {
return false;
}
return (
hasOutput(toolCall) ||
toolCall.runStepStatus != null ||
(typeof toolCall.progress === 'number' && toolCall.progress >= 1)
);
};
/** An unresolved approval anywhere in the parts, including inside nested subagent runs. */
function hasPendingApproval(parts: unknown[]): boolean {
const stack: unknown[][] = [parts];
while (stack.length > 0) {
const current = stack.pop() ?? [];
for (const part of current) {
if (!isToolCallPart(part)) {
continue;
}
const toolCall = part.tool_call;
if (toolCall.approval != null && !hasOutput(toolCall)) {
return true;
}
if (Array.isArray(toolCall.subagent_content)) {
stack.push(toolCall.subagent_content);
}
}
}
return false;
}
/** The agent and step scope an attachment was saved with. */
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[]>;
/** 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;
};
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. Indexing makes each scope
* a constant-time lookup rather than a scan for every child call.
*/
function nestedAttachmentCalls(
parts: unknown[],
wanted: AttachmentScopes,
ownerAgentId?: string,
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;
if (typeof id === 'string' && wanted.has(id)) {
const owner = part.agentId ?? part.tool_call.agentId ?? levelOwner;
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 (!index.byAgent.has(agentId)) {
index.byAgent.set(agentId, entry);
}
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)) {
stack.push([subagent_content, runAgentId(part.tool_call)]);
}
}
}
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;
}
/** 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;
}
const { toolCallId, agentId, stepId } = attachment as {
toolCallId?: unknown;
agentId?: unknown;
stepId?: unknown;
};
if (typeof toolCallId !== 'string' || toolCallId === '') {
continue;
}
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;
}
/** A file whose owner a client is resolving: the tool call it was saved under, with its scope. */
export type AttachmentCallQuery = { toolCallId: string; agentId?: string; stepId?: string };
/** A top-level subagent call and the child calls of its stored transcript the queried files name. */
export type SubagentAttachmentCallsEntry = {
toolCallId: string;
stepId?: string;
agentId?: string;
calls: Agents.SubagentAttachmentCall[];
};
/**
* For each top-level subagent call in stored `content`, the child calls of its transcript that
* the queried files can belong to, chosen as a preview chooses `subagentAttachmentCalls`. Read
* from the transcript rather than the saved attachments, so a file that streamed before it was
* saved on the message resolves the same way.
*/
export function findSubagentAttachmentCalls(
content: unknown[],
files: ReadonlyArray<AttachmentCallQuery>,
): SubagentAttachmentCallsEntry[] {
const wanted = attachmentToolCallIds({ attachments: files });
const entries: SubagentAttachmentCallsEntry[] = [];
if (wanted == null) {
return entries;
}
for (const part of content) {
if (!isToolCallPart(part) || !Array.isArray(part.tool_call.subagent_content)) {
continue;
}
const { id, stepId } = part.tool_call;
if (typeof id !== 'string' || id === '') {
continue;
}
const calls = nestedAttachmentCalls(
part.tool_call.subagent_content,
wanted,
runAgentId(part.tool_call),
);
if (calls == null || calls.length === 0) {
continue;
}
entries.push({
toolCallId: id,
...(typeof stepId === 'string' && stepId !== '' ? { stepId } : {}),
...(typeof part.agentId === 'string' && part.agentId !== '' ? { agentId: part.agentId } : {}),
calls,
});
}
return entries;
}
/** Cuts at `end` without splitting a surrogate pair. */
function sliceStart(text: string, end: number): string {
const code = text.charCodeAt(end - 1);
return text.slice(0, code >= 0xd800 && code <= 0xdbff ? end - 1 : end);
}
/** Keeps the last `count` code units without starting inside a surrogate pair. */
function sliceEnd(text: string, count: number): string {
if (count <= 0) {
return '';
}
const start = text.length - count;
const code = text.charCodeAt(start);
return text.slice(code >= 0xdc00 && code <= 0xdfff ? start + 1 : start);
}
/**
* Keeps the start and the end. Error prefixes and first error lines live at the start;
* validation feedback, the last line of a traceback and exit-status trailers live at the end.
* `minTailChars` widens the end to keep a trailer whole.
*/
export function previewOutputText(output: string, maxChars: number, minTailChars = 0): string {
if (output.length <= maxChars) {
return output;
}
const budget = Math.max(0, maxChars - TOOL_CALL_PREVIEW_ELISION.length);
const tailChars = Math.max(budget - Math.floor(budget * OUTPUT_HEAD_SHARE), minTailChars);
const headChars = Math.max(0, budget - tailChars);
if (headChars + tailChars + TOOL_CALL_PREVIEW_ELISION.length >= output.length) {
return output;
}
return `${sliceStart(output, headChars)}${TOOL_CALL_PREVIEW_ELISION}${sliceEnd(output, tailChars)}`;
}
function capJsonStrings(value: JsonValue, maxChars: number): JsonValue {
if (typeof value === 'string') {
return value.length > maxChars ? `${sliceStart(value, maxChars)}…` : value;
}
if (Array.isArray(value)) {
return value.map((item) => capJsonStrings(item, maxChars));
}
if (value == null || typeof value !== 'object') {
return value;
}
/** Null-prototype, so a `__proto__` key stays an ordinary data key. */
const result: { [key: string]: JsonValue } = Object.create(null);
for (const key in value) {
result[key] = capJsonStrings(value[key], maxChars);
}
return result;
}
/**
* Whether the JSON could fit `maxChars` once its strings are capped: every value serializes to
* at least two characters with its separator, every string to at least `MIN_JSON_STRING_CHARS`,
* and property names are never shortened, so a structure with more values, strings or key
* characters than that allows cannot fit at any cap. The walk is iterative and counts children
* before queueing them, so its work list never outgrows the node budget; it stops as soon as any
* bound is passed and treats nesting deeper than `MAX_JSON_DEPTH` as unfit, so the cloning and
* serialization that follow only ever run on small, shallow values.
*/
function mayFitJson(value: JsonValue, maxChars: number): boolean {
const maxNodes = Math.floor(maxChars / 2);
const maxStrings = Math.floor(maxChars / MIN_JSON_STRING_CHARS);
let nodes = 0;
let strings = 0;
let keyChars = 0;
const stack: Array<[JsonValue, number]> = [[value, 0]];
while (stack.length > 0) {
const [current, depth] = stack.pop() as [JsonValue, number];
nodes++;
if (nodes > maxNodes || depth > MAX_JSON_DEPTH) {
return false;
}
if (typeof current === 'string') {
strings++;
if (strings > maxStrings) {
return false;
}
} else if (Array.isArray(current)) {
if (nodes + stack.length + current.length > maxNodes) {
return false;
}
for (const item of current) {
stack.push([item, depth + 1]);
}
} else if (current != null && typeof current === 'object') {
for (const key in current) {
keyChars += key.length + 3;
if (keyChars > maxChars || nodes + stack.length + 1 > maxNodes) {
return false;
}
stack.push([current[key], depth + 1]);
}
}
}
return true;
}
function parseJsonContainer(text: string): JsonValue | undefined {
const first = text.trimStart()[0];
if (first !== '{' && first !== '[') {
return undefined;
}
try {
return JSON.parse(text) as JsonValue;
} catch {
return undefined;
}
}
const isDigitCode = (code: number): boolean => code >= 48 && code <= 57;
/** `0-9 . e E + -`: the characters a JSON number token is made of. */
const isNumberCode = (code: number): boolean =>
isDigitCode(code) || code === 46 || code === 101 || code === 69 || code === 43 || code === 45;
/** A decimal as `[-]digits e exponent` with no leading or trailing zeros, so `1.50` and `15e-1`
* compare equal and only a change of value shows. */
function canonicalDecimal(token: string): string {
const negative = token.startsWith('-');
const unsigned = negative ? token.slice(1) : token;
const exponentAt = unsigned.search(/[eE]/);
const mantissa = exponentAt === -1 ? unsigned : unsigned.slice(0, exponentAt);
const pointAt = mantissa.indexOf('.');
const fraction = pointAt === -1 ? '' : mantissa.slice(pointAt + 1);
const digits = (pointAt === -1 ? mantissa : mantissa.slice(0, pointAt)) + fraction;
const significant = digits.replace(/^0+/, '');
if (significant === '') {
return '0';
}
let end = significant.length;
while (significant.charCodeAt(end - 1) === 48) {
end--;
}
const trimmed = significant.slice(0, end);
const exponent =
(exponentAt === -1 ? 0 : Number(unsigned.slice(exponentAt + 1))) -
fraction.length +
(significant.length - trimmed.length);
return `${negative ? '-' : ''}${trimmed}e${exponent}`;
}
/** Whether the number survives a parse and re-serialization as the same value. */
function numberRoundTrips(token: string): boolean {
const value = Number(token);
return Number.isFinite(value) && canonicalDecimal(token) === canonicalDecimal(String(value));
}
/**
* Whether every number in the (already valid) JSON text comes back as the same value once
* parsed into doubles and serialized again. An integer past 2^53, a decimal with more precision
* than a double holds, or an exponent past its range would otherwise show a different value
* (or `null`) in the preview than the tool actually produced.
*/
function numbersRoundTrip(text: string): boolean {
let i = 0;
while (i < text.length) {
const code = text.charCodeAt(i);
if (code === 34) {
i++;
while (i < text.length && text.charCodeAt(i) !== 34) {
i += text.charCodeAt(i) === 92 ? 2 : 1;
}
i++;
continue;
}
if (code !== 45 && !isDigitCode(code)) {
i++;
continue;
}
const start = i;
while (i < text.length && isNumberCode(text.charCodeAt(i))) {
i++;
}
if (!numberRoundTrips(text.slice(start, i))) {
return false;
}
}
return true;
}
/**
* The structure-preserving preview of JSON text, or `undefined` when the caller should fall
* back: the structure cannot fit, or a number in it would not survive the round trip.
*/
function shrinkJsonText(text: string, parsed: JsonValue, maxChars: number): string | undefined {
const shrunk = shrinkJsonToFit(parsed, maxChars);
return shrunk !== undefined && numbersRoundTrip(text) ? shrunk : undefined;
}
/**
* Serializes the JSON within `maxChars` by shortening only its longest strings: the largest
* per-string cap that fits wins, so short fields (a command, a path, an intent, a status) stay
* exact while a file body or log absorbs the cut. Every key, array item and scalar is kept, so
* readers that parse the value still find their fields. Returns `undefined` when even the
* shortest cap cannot fit, and the caller falls back to text.
*/
export function shrinkJsonToFit(value: JsonValue, maxChars: number): string | undefined {
if (!mayFitJson(value, maxChars)) {
return undefined;
}
const capped = capJsonStrings(value, maxChars);
let low = MIN_JSON_STRING_CHARS;
let high = maxChars;
let best: string | undefined;
while (low <= high) {
const cap = Math.floor((low + high) / 2);
const serialized = JSON.stringify(capJsonStrings(capped, cap));
if (serialized.length <= maxChars) {
best = serialized;
low = cap + 1;
} else {
high = cap - 1;
}
}
return best;
}
type ArgsPreview = { args: string | JsonValue; length: number };
export function previewToolCallArgs(args: unknown, maxChars: number): ArgsPreview | undefined {
if (typeof args === 'string') {
if (args.length <= maxChars) {
return undefined;
}
const parsed = parseJsonContainer(args);
const shrunk = parsed === undefined ? undefined : shrinkJsonText(args, parsed, maxChars);
return { args: shrunk ?? sliceStart(args, maxChars), length: args.length };
}
if (!isObject(args)) {
return undefined;
}
const serialized = JSON.stringify(args);
if (serialized.length <= maxChars) {
return undefined;
}
const shrunk = shrinkJsonToFit(args as JsonValue, maxChars);
return {
args:
shrunk === undefined ? sliceStart(serialized, maxChars) : (JSON.parse(shrunk) as JsonValue),
length: serialized.length,
};
}
/**
* Length of the exit-status trailer the attached-workspace `bash_tool` appends. Only a call the
* server stamped with that executor carries one, and its collapsed card reads the verdict there.
*/
function commandTrailerLength(toolCall: StoredToolCall, output: string): number {
if (toolCall.executor !== 'attached_workspace') {
return 0;
}
const match = COMMAND_RESULT_TRAILER.exec(output.slice(-MAX_TRAILER_CHARS));
return match == null ? 0 : match[0].length;
}
/** JSON output stays parseable (background-task results, handles); other text keeps both ends. */
export function previewToolCallOutput(
toolCall: StoredToolCall,
output: string,
maxChars: number,
): string {
if (output.length <= maxChars) {
return output;
}
const parsed = parseJsonContainer(output);
const shrunk = parsed === undefined ? undefined : shrinkJsonText(output, parsed, maxChars);
if (shrunk != null) {
return shrunk;
}
if (
parsed !== undefined &&
typeof toolCall.name === 'string' &&
PARSED_OUTPUT_TOOLS.has(toolCall.name)
) {
return output;
}
if (toolCall.name === Tools.web_search && LEGACY_SEARCH_ERROR.test(output)) {
return output;
}
return previewOutputText(output, maxChars, commandTrailerLength(toolCall, output));
}
/**
* Returns the tool call with long content replaced by previews, or the same object when nothing
* needed shortening. Only settled calls change: a call still waiting on output, approval or a
* reader's answer keeps every field, since its card acts on them. When the subagent transcript is
* left out, its tool calls that `attachmentIds` names stay on the call with their scope, so the
* files those calls saved still route to it before the transcript loads.
*/
export function previewToolCall<T extends StoredToolCall>(
toolCall: T,
limits: ToolCallPreviewLimits,
revision = '',
attachmentIds?: AttachmentScopes,
budget: AttachmentWorkBudget = attachmentWorkBudget(limits),
): T {
if (!isAgentToolCall(toolCall) || !isSettled(toolCall) || !hasIdentity(toolCall)) {
return toolCall;
}
if (typeof toolCall.name === 'string' && FULL_CONTENT_TOOLS.has(toolCall.name)) {
return toolCall;
}
const output = typeof toolCall.output === 'string' ? toolCall.output : '';
const outputPreview = previewToolCallOutput(toolCall, output, limits.outputChars);
const argsPreview = previewToolCallArgs(toolCall.args, limits.argsChars);
const subagentContent = toolCall.subagent_content;
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;
}
const next: T = { ...toolCall };
if (outputPreview !== output) {
next.output = outputPreview;
next.outputTruncated = true;
next.outputLength = output.length;
}
if (argsPreview != null) {
next.args = argsPreview.args;
next.argsTruncated = true;
next.argsLength = argsPreview.length;
}
if (omitSubagentContent) {
delete next.subagent_content;
next.subagentContentOmitted = true;
next.subagentContentParts = (subagentContent as unknown[]).length;
if (childCalls != null && childCalls.length > 0) {
next.subagentAttachmentCalls = childCalls;
}
}
if (revision !== '') {
next.previewRevision = revision;
}
return next;
}
/**
* A call that cannot be previewed is sent as stored rather than failing the whole conversation
* load; previews are an optimization, and the full value is what the client would otherwise get.
*/
function previewToolCallSafely<T extends StoredToolCall>(
toolCall: T,
limits: ToolCallPreviewLimits,
revision: string,
attachmentIds: AttachmentScopes | undefined,
budget: AttachmentWorkBudget,
): T {
try {
return previewToolCall(toolCall, limits, revision, attachmentIds, budget);
} catch (error) {
logger.warn('[toolCallPreviews] Sending a tool call in full; its preview failed', error);
return toolCall;
}
}
/** Previews every tool-call part of one content array; returns the same array when unchanged. */
export function previewContentToolCalls(
content: unknown[],
limits: ToolCallPreviewLimits,
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>();
for (let i = 0; i < content.length; i++) {
const part = content[i];
if (!isToolCallPart(part)) {
continue;
}
const identity = toolCallIdentity(part);
if (identity == null) {
continue;
}
const first = firstIndex.get(identity);
if (first != null) {
if (result != null && first >= 0) {
result[first] = content[first];
}
firstIndex.set(identity, -1);
continue;
}
firstIndex.set(identity, i);
const toolCall = previewToolCallSafely(part.tool_call, limits, revision, attachmentIds, budget);
if (toolCall === part.tool_call) {
continue;
}
result ??= content.slice();
result[i] = { ...part, tool_call: toolCall };
}
return result ?? content;
}
function messageRevision(message: PreviewableMessage): string {
const { updatedAt } = message;
if (updatedAt instanceof Date) {
return String(updatedAt.getTime());
}
return updatedAt == null ? '' : String(updatedAt);
}
/** Applies previews across messages, copying only the messages whose content changed. */
export function previewMessagesToolCalls<T extends PreviewableMessage>(
messages: T[],
limits: ToolCallPreviewLimits,
): T[] {
let result: T[] | undefined;
for (let i = 0; i < messages.length; i++) {
const message = messages[i];
if (!Array.isArray(message?.content)) {
continue;
}
const content = previewContentToolCalls(
message.content,
limits,
messageRevision(message),
attachmentToolCallIds(message),
);
if (content === message.content) {
continue;
}
result ??= messages.slice();
result[i] = { ...message, content };
}
return result ?? messages;
}
/** True when the request asked for this preview format. */
export function wantsToolCallPreviews(query: unknown): boolean {
if (!isObject(query)) {
return false;
}
return (
(query as Record<string, unknown>)[TOOL_CALL_PREVIEWS_PARAM] === TOOL_CALL_PREVIEWS_VERSION
);
}
export interface ToolCallPreviewRequest {
query?: unknown;
user?: AppConfigUserLike | null;
}
export interface ToolCallPreviewDeps {
getAppConfig: (options: GetAppConfigOptions) => Promise<AppConfig | undefined>;
}
type MessagesPreviewer = <T extends PreviewableMessage>(messages: T[]) => Promise<T[]>;
/** A response carrying the messages a fork-style route returns. */
type MessagesResult = { messages?: PreviewableMessage[] | null };
export type ResultPreviewer = <T extends MessagesResult>(result: T) => Promise<T>;
const sendInFull: MessagesPreviewer = (messages) => Promise.resolve(messages);
async function resolveLimits(
req: ToolCallPreviewRequest,
deps: ToolCallPreviewDeps,
): Promise<TToolCallPreviewsConfig> {
try {
const config = await deps.getAppConfig({
...getAppConfigOptionsFromUser(req.user),
skipRuntimeAugmentation: true,
});
return config?.toolCallPreviews ?? toolCallPreviewsConfigSchema.parse({});
} catch (error) {
logger.warn('[toolCallPreviews] Config unavailable; using default preview bounds', error);
return toolCallPreviewsConfigSchema.parse({});
}
}
/**
* Starts resolving the preview bounds for a message load, so the config read runs beside the
* message read instead of ahead of it. The returned function shapes the messages once both are
* in. A request without the preview parameter, or a deployment that turned previews off,
* receives the messages untouched.
*/
export function prepareToolCallPreviews(
req: ToolCallPreviewRequest,
deps: ToolCallPreviewDeps,
): MessagesPreviewer {
if (!wantsToolCallPreviews(req.query)) {
return sendInFull;
}
const limitsPromise = resolveLimits(req, deps);
return async (messages) => {
const limits = await limitsPromise;
if (!limits.enabled) {
return messages;
}
return previewMessagesToolCalls(messages, limits);
};
}
/**
* `prepareToolCallPreviews` for a route that returns `{ messages }` and whose `req.config` is not
* the requester's: a shared-link fork resolves the share owner's config for its content checks,
* while the forked conversation belongs to the requester, so the bounds come from the
* requester's own tenant and role.
*/
export function prepareResultToolCallPreviews(
req: ToolCallPreviewRequest,
deps: ToolCallPreviewDeps,
): ResultPreviewer {
const preview = prepareToolCallPreviews(req, deps);
return async (result) => {
if (!Array.isArray(result?.messages)) {
return result;
}
const messages = await preview(result.messages);
return messages === result.messages ? result : { ...result, messages };
};
}
/** True when any tool call in the content, nested subagent runs included, carries preview markers. */
export function containsToolCallPreviews(content: unknown): boolean {
if (!Array.isArray(content)) {
return false;
}
const stack: unknown[][] = [content];
while (stack.length > 0) {
const current = stack.pop() ?? [];
for (const part of current) {
if (!isToolCallPart(part)) {
continue;
}
if (hasToolCallPreview(part.tool_call)) {
return true;
}
if (Array.isArray(part.tool_call.subagent_content)) {
stack.push(part.tool_call.subagent_content);
}
}
}
return false;
}
interface PreviewableResultRequest {
query?: unknown;
config?: { toolCallPreviews?: TToolCallPreviewsConfig } | null;
}
/**
* Previews the messages a fork, duplicate or shared-link fork returns, so a client that asked
* for previews does not seed its conversation cache with the full history. Reads the bounds
* from the config the route already resolved.
*/
export function withToolCallPreviews<T extends MessagesResult>(
req: PreviewableResultRequest,
result: T,
): T {
if (!wantsToolCallPreviews(req.query) || !Array.isArray(result?.messages)) {
return result;
}
const limits = req.config?.toolCallPreviews ?? toolCallPreviewsConfigSchema.parse({});
if (!limits.enabled) {
return result;
}
const messages = previewMessagesToolCalls(result.messages, limits);
return messages === result.messages ? result : { ...result, messages };
}
/**
* Previews one message a mutation returns (an artifact edit's content, a branched response), so
* a client that asked for previews merges a bounded copy into its conversation cache. A response
* that leaves out the stored `attachments` passes them separately: they only decide which
* subagent child calls the preview keeps as hints, and are not added to the response.
*/
export function withMessageToolCallPreviews<T extends PreviewableMessage>(
req: PreviewableResultRequest,
message: T,
attachments?: unknown[] | null,
): T {
if (message == null || !Array.isArray(message.content)) {
return message;
}
if (attachments == null || message.attachments != null) {
return withToolCallPreviews(req, { messages: [message] }).messages[0];
}
const withAttachments = { ...message, attachments };
const previewed = withToolCallPreviews(req, { messages: [withAttachments] }).messages[0];
if (previewed === withAttachments) {
return message;
}
const { attachments: _attachments, ...rest } = previewed;
return rest as T;
}
interface MessageWriteRequest {
body?: { content?: unknown } | null;
}
interface MessageWriteResponse {
status: (code: number) => { json: (body: { error: string }) => unknown };
}
/**
* Refuses a client-authored message whose content holds tool-call previews. A preview is a
* display copy; saving it would replace the stored output, arguments or transcript with it.
*/
export function rejectToolCallPreviewWrites(
req: MessageWriteRequest,
res: MessageWriteResponse,
next: () => void,
): void {
if (containsToolCallPreviews(req.body?.content)) {
res.status(400).json({ error: 'Tool call previews cannot be saved as message content' });
return;
}
next();
}