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
/**
* `@librechat/agents` may ship without the skill-flavored tool definitions on
* older installed versions. Stub them so `registerCodeExecutionTools` (which
* consumes only the three exports below) can be exercised deterministically.
* Mirrors the same pattern used in `__tests__/skills.test.ts`.
*/
jest.mock('@librechat/agents', () => ({
CODE_EXECUTION_TOOLS: new Set(['execute_code', 'bash_tool']),
Constants: { READ_FILE: 'read_file', WRITE_FILE: 'write_file' },
ReadFileToolDefinition: {
name: 'read_file',
description: 'read skill files using {skillName}/{filePath} and SKILL.md',
parameters: {
type: 'object',
properties: {
intent: { type: 'string', description: 'SDK read intent' },
path: {
type: 'string',
description: 'For skill files: "{skillName}/{path}".',
},
},
required: ['path'],
},
responseFormat: 'content',
},
SkillToolDefinition: {
name: 'skill',
description: `Invoke a skill from the user's library.
CONSTRAINTS:
- Do not invoke a skill that is already active in this conversation.
- Skill names come from the catalog only. Do not guess names.`,
parameters: {
type: 'object',
properties: {
intent: { type: 'string', description: 'intent' },
skillName: {
type: 'string',
description: 'Must match a name from the "Available Skills" section.',
},
args: { type: 'string', description: 'Optional freeform arguments string.' },
},
required: ['skillName'],
},
},
BashExecutionToolDefinition: {
name: 'bash_tool',
description: 'bash',
schema: {
type: 'object',
properties: {
command: { type: 'string' },
args: { type: 'array', items: { type: 'string' } },
},
required: ['command'],
},
},
BashToolOutputReferencesGuide: '{{tool<idx>turn<turn>}}',
/**
* Deterministic stub mirroring the SDK's `buildBashExecutionToolDescription`:
* appends an LLM-facing reference-syntax marker only when
* `enableToolOutputReferences` is true.
*/
buildBashExecutionToolDescription: ({
enableToolOutputReferences,
}: {
enableToolOutputReferences?: boolean;
} = {}): string =>
enableToolOutputReferences === true ? 'bash {{tool<idx>turn<turn>}}' : 'bash',
}));
import fs from 'fs';
import path from 'path';
import { CODE_EXECUTION_TOOLS, ReadFileToolDefinition } from '@librechat/agents';
import type { LCTool, LCToolRegistry } from '@librechat/agents';
import { CODE_WORKSPACE_OPERATIONS, Constants } from 'librechat-data-provider';
import {
buildToolSet,
buildRunToolSet,
buildHistoricalToolNames,
BuildToolSetConfig,
registerCodeExecutionTools,
registerFileAuthoringTools,
FILE_AUTHORING_TOOL_NAMES,
isFileAuthoringToolDefinition,
isCodeSessionToolName,
isSkillToolAvailable,
getSkillToolDefinition,
buildAuthoringSkillToolDescription,
buildAuthoringSkillToolParameters,
} from './tools';
/** Portable ceiling for OpenAI-compatible tool description validators. */
const TOOL_DESCRIPTION_ADVISORY_MAX_LENGTH = 1024;
const ATTACHED_SKILL_FILE_SENTENCE =
'Skill files are not on the attached machine, so bash_tool cannot run them by path; to run a skill script there, read it and write it into the workspace first.';
function filePathDescription(tool?: LCTool): string {
const parameters = tool?.parameters as
| { properties?: { path?: { description?: string } } }
| undefined;
return parameters?.properties?.path?.description ?? '';
}
function maxToolDescriptionLength(definitions: LCTool[]): number {
return definitions.reduce((max, definition) => {
const length = definition.description?.length ?? Number.POSITIVE_INFINITY;
return Math.max(max, length);
}, 0);
}
describe('buildToolSet', () => {
describe('event-driven mode (toolDefinitions)', () => {
it('builds toolSet from toolDefinitions when available', () => {
const agentConfig: BuildToolSetConfig = {
toolDefinitions: [
{ name: 'tool_search', description: 'Search for tools' },
{ name: 'list_commits_mcp_github', description: 'List commits' },
{ name: 'calculator', description: 'Calculate' },
],
tools: [],
};
const toolSet = buildToolSet(agentConfig);
expect(toolSet.size).toBe(3);
expect(toolSet.has('tool_search')).toBe(true);
expect(toolSet.has('list_commits_mcp_github')).toBe(true);
expect(toolSet.has('calculator')).toBe(true);
});
it('includes tool_search in toolSet for deferred tools workflow', () => {
const agentConfig: BuildToolSetConfig = {
toolDefinitions: [
{ name: 'tool_search', description: 'Search for deferred tools' },
{ name: 'deferred_tool_1', description: 'A deferred tool', defer_loading: true },
{ name: 'deferred_tool_2', description: 'Another deferred tool', defer_loading: true },
],
};
const toolSet = buildToolSet(agentConfig);
expect(toolSet.has('tool_search')).toBe(true);
expect(toolSet.has('deferred_tool_1')).toBe(true);
expect(toolSet.has('deferred_tool_2')).toBe(true);
});
it('prefers toolDefinitions over tools when both are present', () => {
const agentConfig: BuildToolSetConfig = {
toolDefinitions: [{ name: 'from_definitions' }],
tools: [{ name: 'from_tools' }],
};
const toolSet = buildToolSet(agentConfig);
expect(toolSet.size).toBe(1);
expect(toolSet.has('from_definitions')).toBe(true);
expect(toolSet.has('from_tools')).toBe(false);
});
});
describe('legacy mode (tools)', () => {
it('falls back to tools when toolDefinitions is empty', () => {
const agentConfig: BuildToolSetConfig = {
toolDefinitions: [],
tools: [{ name: 'web_search' }, { name: 'calculator' }],
};
const toolSet = buildToolSet(agentConfig);
expect(toolSet.size).toBe(2);
expect(toolSet.has('web_search')).toBe(true);
expect(toolSet.has('calculator')).toBe(true);
});
it('falls back to tools when toolDefinitions is undefined', () => {
const agentConfig: BuildToolSetConfig = {
tools: [{ name: 'tool_a' }, { name: 'tool_b' }],
};
const toolSet = buildToolSet(agentConfig);
expect(toolSet.size).toBe(2);
expect(toolSet.has('tool_a')).toBe(true);
expect(toolSet.has('tool_b')).toBe(true);
});
});
describe('edge cases', () => {
it('includes names retained on unresolved lazy agent descriptors', () => {
const toolSet = buildToolSet({
historicalToolNames: ['lazy_search', 'lazy_calculator'],
});
expect(toolSet).toEqual(new Set(['lazy_search', 'lazy_calculator']));
});
it('returns empty set when agentConfig is null', () => {
const toolSet = buildToolSet(null);
expect(toolSet.size).toBe(0);
});
it('returns empty set when agentConfig is undefined', () => {
const toolSet = buildToolSet(undefined);
expect(toolSet.size).toBe(0);
});
it('returns empty set when both toolDefinitions and tools are empty', () => {
const agentConfig: BuildToolSetConfig = {
toolDefinitions: [],
tools: [],
};
const toolSet = buildToolSet(agentConfig);
expect(toolSet.size).toBe(0);
});
it('filters out null/undefined tool entries', () => {
const agentConfig: BuildToolSetConfig = {
tools: [{ name: 'valid_tool' }, null, undefined, { name: 'another_valid' }],
};
const toolSet = buildToolSet(agentConfig);
expect(toolSet.size).toBe(2);
expect(toolSet.has('valid_tool')).toBe(true);
expect(toolSet.has('another_valid')).toBe(true);
});
it('filters out empty string tool names', () => {
const agentConfig: BuildToolSetConfig = {
toolDefinitions: [{ name: 'valid' }, { name: '' }, { name: 'also_valid' }],
};
const toolSet = buildToolSet(agentConfig);
expect(toolSet.size).toBe(2);
expect(toolSet.has('valid')).toBe(true);
expect(toolSet.has('also_valid')).toBe(true);
expect(toolSet.has('')).toBe(false);
});
});
});
describe('buildRunToolSet', () => {
const agent = (id: string, ...toolNames: string[]) => ({
id,
toolDefinitions: toolNames.map((name) => ({ name })),
});
it('returns an empty set without a primary or additional agent', () => {
expect(buildRunToolSet(null)).toEqual(new Set());
});
it('collects tools recursively across every reachable agent shape', () => {
const eager = agent('eager', 'eager_tool');
const lazy = {
id: 'lazy',
historicalToolNames: ['lazy_tool'],
};
const metadata = agent('metadata', 'metadata_tool');
const graphMember = agent('graph-member', 'graph_tool');
const primary = {
...agent('primary', 'primary_tool'),
subagentAgentConfigs: [eager],
lazySubagentConfigs: [lazy],
subagentGraphMemberMetadata: [metadata],
subagentGraphConfigs: [{ memberConfigs: [graphMember] }],
};
expect(buildRunToolSet(primary)).toEqual(
new Set([
'subagent',
'conditional_transfer',
'primary_tool',
'eager_tool',
'lazy_tool',
'metadata_tool',
'graph_tool',
]),
);
});
it('adds only effective handoff destinations as transfer tools', () => {
const primary = {
...agent('primary', 'primary_tool'),
edges: [
{ from: 'primary', to: 'writer', edgeType: 'handoff' as const },
{ from: 'writer', to: ['reviewer', 'publisher'] },
{ from: 'publisher', to: 'archive', edgeType: 'direct' as const },
],
};
const toolSet = buildRunToolSet(primary, [agent('disconnected', 'disconnected_tool')]);
expect(toolSet).toEqual(
new Set([
'subagent',
'conditional_transfer',
'primary_tool',
'disconnected_tool',
'lc_transfer_to_writer',
'lc_transfer_to_reviewer',
'lc_transfer_to_publisher',
]),
);
});
it('includes host-generated controls supplied by the run', () => {
expect(buildRunToolSet(agent('primary'), null, ['check_background_task'])).toEqual(
new Set(['subagent', 'conditional_transfer', 'check_background_task']),
);
});
});
describe('buildHistoricalToolNames', () => {
it('normalizes MCP names and expands toolkits and deferred search', () => {
expect(
buildHistoricalToolNames({
configuredToolNames: ['search_mcp_Connector: Company', 'image_gen_oai'],
toolOptions: {
'search_mcp_Connector: Company': { defer_loading: true },
},
rawMcpServerNames: ['Connector: Company'],
deferredToolsAvailable: true,
}),
).toEqual(
new Set(['search_mcp_Connector__Company', 'image_gen_oai', 'image_edit_oai', 'tool_search']),
);
});
it('expands code, memory, skill, programmatic, and background controls', () => {
expect(
buildHistoricalToolNames({
configuredToolNames: ['execute_code', 'memory', 'lookup'],
alwaysApplyToolNames: ['skill_allowed_tool'],
toolOptions: { lookup: { allowed_callers: ['code_execution'], run_in_background: true } },
codeExecutionAvailable: true,
memoryAvailable: true,
skillsAvailable: true,
skillAuthoringAvailable: true,
programmaticToolsAvailable: true,
backgroundToolsAvailable: true,
}),
).toEqual(
new Set([
'execute_code',
'memory',
'lookup',
'skill_allowed_tool',
'bash_tool',
'read_file',
'create_file',
'edit_file',
'search_workspace',
'list_workspace_files',
'set_memory',
'delete_memory',
'skill',
'run_tools_with_bash',
'check_background_task',
]),
);
});
it('keeps skill file access without exposing the skill invocation tool', () => {
expect(
buildHistoricalToolNames({
skillsAvailable: false,
skillFileAccessAvailable: true,
}),
).toEqual(new Set(['read_file']));
});
it('exposes the skill invocation tool on an authoring run with an empty catalog', () => {
expect(
buildHistoricalToolNames({
skillsAvailable: false,
skillFileAccessAvailable: false,
skillAuthoringAvailable: true,
}),
).toEqual(new Set(['skill', 'read_file', 'create_file', 'edit_file']));
});
it('normalizes Action names and their options', () => {
expect(
buildHistoricalToolNames({
configuredToolNames: [
`${Constants.mcp_all}${Constants.mcp_delimiter}warehouse`,
'lookup_action_api---example---com',
],
toolOptions: {
'lookup_action_api---example---com': { defer_loading: true },
},
deferredToolsAvailable: true,
}),
).toEqual(
new Set([
`${Constants.mcp_all}${Constants.mcp_delimiter}warehouse`,
'lookup_action_api_example_com',
'tool_search',
]),
);
});
it('accepts only historical calls covered by an MCP wildcard server suffix', () => {
const primary = {
id: 'primary',
accessibleMcpServerNames: ['bar', 'foo_mcp_bar', 'Connector: Company'],
toolDefinitions: [
{ name: `${Constants.mcp_all}${Constants.mcp_delimiter}bar` },
{ name: `${Constants.mcp_all}${Constants.mcp_delimiter}Connector: Company` },
],
};
const messages = [
{
content: [
{ tool_call: { name: 'search_mcp_Connector__Company' } },
{ tool_call: { name: 'search_mcp_attacker' } },
{
tool_call: {
name: 'subagent',
subagent_content: [{ tool_call: { name: 'run_query_mcp_bar' } }],
},
},
],
},
{
tool_calls: [{ name: 'lookup_mcp_Connector__Company' }],
additional_kwargs: {
tool_calls: [{ function: { name: 'legacy_mcp_Connector__Company' } }],
},
},
{ tool_calls: [{ name: 'lookup_mcp_foo_mcp_bar' }] },
{
tool_calls: [{ name: 'gitlab-get_mcp_server_version_mcp_bar', mcpServerName: 'bar' }],
},
{ tool_calls: [{ name: 'legacy_mcp_tool_mcp_bar' }] },
];
expect(buildRunToolSet(primary, null, null, messages)).toEqual(
new Set([
'subagent',
'conditional_transfer',
`${Constants.mcp_all}${Constants.mcp_delimiter}bar`,
`${Constants.mcp_all}${Constants.mcp_delimiter}Connector: Company`,
'search_mcp_Connector__Company',
'run_query_mcp_bar',
'lookup_mcp_Connector__Company',
'legacy_mcp_Connector__Company',
'gitlab-get_mcp_server_version_mcp_bar',
]),
);
expect(buildRunToolSet(primary, null, null, messages, true)).toContain(
'legacy_mcp_tool_mcp_bar',
);
});
it('does not inspect history when the run has no MCP wildcard', () => {
const message = {};
Object.defineProperty(message, 'content', {
get: () => {
throw new Error('history should not be inspected');
},
});
expect(() =>
buildRunToolSet({ toolDefinitions: [{ name: 'web' }] }, null, null, [message]),
).not.toThrow();
});
});
describe('isSkillToolAvailable', () => {
it('registers for a visible catalog, for an authoring run, and for neither', () => {
expect(isSkillToolAvailable({ modelInvocableSkillsAvailable: true })).toBe(true);
expect(isSkillToolAvailable({ skillAuthoringAvailable: true })).toBe(true);
expect(
isSkillToolAvailable({ modelInvocableSkillsAvailable: true, skillAuthoringAvailable: true }),
).toBe(true);
expect(
isSkillToolAvailable({
modelInvocableSkillsAvailable: false,
skillAuthoringAvailable: false,
}),
).toBe(false);
expect(isSkillToolAvailable({})).toBe(false);
});
});
describe('getSkillToolDefinition', () => {
function skillNameDescription(definition: LCTool): string {
const parameters = definition.parameters as
| { properties?: { skillName?: { description?: string } } }
| undefined;
return parameters?.properties?.skillName?.description ?? '';
}
it('keeps the catalog-only guidance when the run cannot author skills', () => {
const definition = getSkillToolDefinition(false);
expect(definition.name).toBe('skill');
expect(definition.description).toContain('Skill names come from the catalog only');
expect(skillNameDescription(definition)).toBe(
'Must match a name from the "Available Skills" section.',
);
});
it('accepts a skill authored during the run when the run can author skills', () => {
const definition = getSkillToolDefinition(true);
expect(definition.description).not.toContain('Skill names come from the catalog only');
expect(definition.description).toContain('a skill you created in this conversation');
expect(definition.description).toContain('Creating a skill does not load it');
expect(definition.description).toContain(
'Do not invoke a skill that is already active in this conversation.',
);
expect(skillNameDescription(definition)).toContain(
'the name of a skill you created in this conversation',
);
});
it('leaves the rest of the schema and the non-authoring definition untouched', () => {
const authoring = getSkillToolDefinition(true);
const parameters = authoring.parameters as {
type?: string;
required?: string[];
properties?: Record<string, { description?: string }>;
};
expect(parameters.type).toBe('object');
expect(parameters.required).toEqual(['skillName']);
expect(Object.keys(parameters.properties ?? {})).toEqual(['intent', 'skillName', 'args']);
expect(parameters.properties?.args?.description).toBe('Optional freeform arguments string.');
expect(skillNameDescription(getSkillToolDefinition(false))).toBe(
'Must match a name from the "Available Skills" section.',
);
expect(getSkillToolDefinition(true)).toBe(authoring);
});
});
describe('buildAuthoringSkillToolDescription', () => {
it('rewrites the catalog-only constraint in place, keeping every other one', () => {
const base = [
'Invoke a skill.',
'',
'CONSTRAINTS:',
'- Do not invoke a skill that is already active in this conversation.',
'- Skill names come from the catalog only. Do not guess names.',
].join('\n');
const result = buildAuthoringSkillToolDescription(base);
expect(result).not.toContain('Skill names come from the catalog only');
expect(result).toContain(
'- Do not invoke a skill that is already active in this conversation.',
);
expect(result).toContain('a skill you created in this conversation');
/* Rewritten in place, so the guidance stays inside CONSTRAINTS rather than
trailing after it. */
expect(
result.endsWith(
'Creating a skill does not load it. Invoke it here when you want to follow its instructions.',
),
).toBe(true);
});
it('appends the guidance when the SDK no longer carries that sentence', () => {
/* Drift branch: the sentence was reworded or dropped upstream. The authored
-skill guidance must still reach the model, appended rather than lost. */
const drifted = [
'Invoke a skill.',
'',
'CONSTRAINTS:',
'- Do not invoke a skill that is already active in this conversation.',
].join('\n');
const result = buildAuthoringSkillToolDescription(drifted);
expect(result.startsWith(drifted)).toBe(true);
expect(result).toContain('a skill you created in this conversation');
expect(result).toContain('Creating a skill does not load it');
});
});
describe('buildAuthoringSkillToolParameters', () => {
it('retargets skillName guidance while preserving the rest of the schema', () => {
const base = {
type: 'object',
properties: {
intent: { type: 'string', description: 'intent' },
skillName: { type: 'string', description: 'catalog only' },
},
required: ['skillName'],
} as unknown as LCTool['parameters'];
const result = buildAuthoringSkillToolParameters(base) as unknown as {
type?: string;
required?: string[];
properties?: Record<string, { type?: string; description?: string }>;
};
expect(result.properties?.skillName?.description).toContain(
'a skill you created in this conversation',
);
/* The property keeps its own non-description fields, and its siblings are
untouched. */
expect(result.properties?.skillName?.type).toBe('string');
expect(result.properties?.intent?.description).toBe('intent');
expect(result.type).toBe('object');
expect(result.required).toEqual(['skillName']);
});
it('returns the schema unchanged when the SDK has no skillName property', () => {
/* Drift branch: the installed package disagrees with the types it shipped.
Losing the authored-skill hint beats failing the packages/api import,
which is what an unguarded dereference at module load would do. */
const base = {
type: 'object',
properties: { intent: { type: 'string' } },
} as unknown as LCTool['parameters'];
expect(buildAuthoringSkillToolParameters(base)).toBe(base);
});
});
describe('installed @librechat/agents skill tool canary', () => {
/**
* The two things the authoring variant reads off the real SDK export. This
* suite mocks `@librechat/agents`, so these assertions deliberately reach
* past the mock to the installed package.
*
* When either fails, do not "fix" the test: the authoring variant is silently
* degraded against that version. A moved sentence leaves the reworded
* catalog-only constraint standing beside guidance that contradicts it (the
* append branch above), and a moved `skillName` property drops the authored
* -skill wording from the parameter. Re-point `CATALOG_ONLY_SKILL_CONSTRAINT`
* in `tools.ts` at the new text instead.
*/
it('still ships the constraint sentence and skillName property the variant rewrites', () => {
const { SkillToolDefinition } = jest.requireActual('@librechat/agents') as {
SkillToolDefinition: {
description: string;
parameters: { properties?: Record<string, { description?: string } | undefined> };
};
};
expect(SkillToolDefinition.description).toContain(
'- Skill names come from the catalog only. Do not guess names.',
);
expect(SkillToolDefinition.parameters.properties?.skillName).toBeDefined();
});
});
describe('e2e skill assertion harness agreement', () => {
/**
* `e2e/setup/fake-model.js` tells an authoring run apart from a skills-off run
* by grepping the advertised `skill` description for one sentence. Both runs
* can reach the model with nothing in the catalog, and only that sentence
* separates them, so the harness reports `authoring-only` for one and `none`
* for the other. Reword the description without this test and the harness
* silently calls every authoring run skills-off, which reads as an
* `agent-skills.spec.ts` failure with no mention of the rewording.
*
* The literal is read from the harness rather than repeated here: a copy
* would keep passing after the harness changed.
*/
const guidance = (() => {
const harness = fs.readFileSync(
path.resolve(__dirname, '../../../../e2e/setup/fake-model.js'),
'utf8',
);
const match = /const AUTHORED_SKILL_GUIDANCE = '([^']+)';/.exec(harness);
if (!match) {
throw new Error('AUTHORED_SKILL_GUIDANCE was not found in e2e/setup/fake-model.js');
}
return match[1];
})();
it('ships the sentence the harness greps for, only on the authoring variant', () => {
const { SkillToolDefinition } = jest.requireActual('@librechat/agents') as {
SkillToolDefinition: { description: string };
};
expect(buildAuthoringSkillToolDescription(SkillToolDefinition.description)).toContain(guidance);
expect(SkillToolDefinition.description).not.toContain(guidance);
});
});
describe('registerCodeExecutionTools', () => {
it('advertises selected named actions to the model', () => {
const result = registerCodeExecutionTools({
toolRegistry: undefined,
toolDefinitions: [],
includeBash: true,
workspaceTools: true,
workspaceOperations: new Set(['execute_command']),
workspaceEnvironment: {
fingerprint: 'a'.repeat(64),
repo: 'owner/app',
ref: 'main',
actions: ['check'],
},
});
const bash = result.toolDefinitions.find((def) => def.name === 'bash_tool');
expect(bash?.parameters).toMatchObject({
required: [],
properties: { environmentAction: { enum: ['check'] } },
});
expect(bash?.description).toContain('owner/app');
});
it('tells the model to route worktree commands through cwd only when lanes are available', () => {
const cwdDescription = (workspaceLinkedWorktrees: boolean): string | undefined => {
const bash = registerCodeExecutionTools({
toolRegistry: undefined,
toolDefinitions: [],
includeBash: true,
workspaceTools: true,
workspaceOperations: new Set(['execute_command']),
workspaceLinkedWorktrees,
}).toolDefinitions.find((def) => def.name === 'bash_tool');
return (bash?.parameters as { properties?: { cwd?: { description?: string } } })?.properties
?.cwd?.description;
};
expect(cwdDescription(true)).toContain('.worktrees/<name>');
expect(cwdDescription(true)).toContain('Any other call, with or without cwd, is checkout-wide');
expect(cwdDescription(false)).not.toContain('.worktrees');
expect(cwdDescription(false)).not.toContain('checkout-wide');
for (const lanes of [true, false]) {
expect(cwdDescription(lanes)).toContain('The command starts there; do not also cd into it.');
}
});
it('describes the read-only native sandbox filesystem only when the worker advertises it', () => {
const bashDescription = (workspaceNativeSandbox?: boolean): string | undefined =>
registerCodeExecutionTools({
toolRegistry: undefined,
toolDefinitions: [],
includeBash: true,
workspaceTools: true,
workspaceOperations: new Set(['execute_command']),
workspaceNativeSandbox,
}).toolDefinitions.find((def) => def.name === 'bash_tool')?.description;
const scratch =
'/ and /tmp are read-only; write scratch files to $TMPDIR or the workspace. Programs that hardcode /tmp fail.';
expect(bashDescription(true)).toContain(scratch);
expect(bashDescription(false)).not.toContain(scratch);
expect(bashDescription()).not.toContain(scratch);
expect(bashDescription(false)).toContain(
'temp files, and background processes are not durable',
);
});
it.each([
{
operations: ['read_file', 'execute_command'],
includeBash: true,
lines: undefined,
warns: true,
},
{ operations: ['read_file', 'execute_command'], includeBash: true, lines: 50, warns: true },
{ operations: ['execute_command'], includeBash: true, lines: undefined, warns: true },
{
operations: ['read_file', 'execute_command'],
includeBash: false,
lines: undefined,
warns: false,
},
{ operations: ['read_file'], includeBash: true, lines: undefined, warns: false },
{ operations: ['read_file'], includeBash: true, lines: 50, warns: false },
{ operations: ['list_files', 'write_file'], includeBash: true, lines: undefined, warns: false },
] as const)(
'names bash_tool in the skill-file warning only when it is registered: %j',
({ operations, includeBash, lines, warns }) => {
const result = registerCodeExecutionTools({
toolRegistry: undefined,
toolDefinitions: [],
includeBash,
includeSkillFileInstructions: true,
workspaceTools: true,
workspaceOperations: new Set(operations),
workspaceReadFileDefaultLines: lines,
});
const names = result.toolDefinitions.map((def) => def.name);
const readFile = result.toolDefinitions.find((def) => def.name === 'read_file');
expect(names.includes('bash_tool')).toBe(warns);
expect(readFile?.description).toContain('skills/{skillName}/...');
expect(readFile?.description?.includes(ATTACHED_SKILL_FILE_SENTENCE)).toBe(warns);
},
);
it.each([
{ includeSkillFileInstructions: false, workspaceTools: true },
{ includeSkillFileInstructions: true, workspaceTools: false },
])(
'omits the skill-file warning outside attached skill runs: %j',
({ includeSkillFileInstructions, workspaceTools }) => {
const readFile = registerCodeExecutionTools({
toolRegistry: undefined,
toolDefinitions: [],
includeBash: true,
includeSkillFileInstructions,
workspaceTools,
workspaceOperations: new Set(['read_file', 'execute_command']),
}).toolDefinitions.find((def) => def.name === 'read_file');
expect(readFile?.description).not.toContain('Skill files are not on');
},
);
const makeRegistry = (): LCToolRegistry => new Map() as unknown as LCToolRegistry;
describe('fresh run (no pre-existing defs or registry entries)', () => {
it('registers read_file + bash_tool when includeBash=true', () => {
const toolRegistry = makeRegistry();
const result = registerCodeExecutionTools({
toolRegistry,
toolDefinitions: [],
includeBash: true,
});
const names = result.toolDefinitions.map((d) => d.name).sort();
expect(names).toEqual(['bash_tool', 'read_file']);
expect(result.registered.sort()).toEqual(['bash_tool', 'read_file']);
expect(toolRegistry.has('read_file')).toBe(true);
expect(toolRegistry.has('bash_tool')).toBe(true);
});
it('registers read_file only when includeBash=false', () => {
const toolRegistry = makeRegistry();
const result = registerCodeExecutionTools({
toolRegistry,
toolDefinitions: [],
includeBash: false,
});
expect(result.toolDefinitions.map((d) => d.name)).toEqual(['read_file']);
expect(result.registered).toEqual(['read_file']);
expect(toolRegistry.has('read_file')).toBe(true);
expect(toolRegistry.has('bash_tool')).toBe(false);
});
it('uses a code-only read_file description when skill instructions are disabled', () => {
const toolRegistry = makeRegistry();
const result = registerCodeExecutionTools({
toolRegistry,
toolDefinitions: [],
includeBash: true,
includeSkillFileInstructions: false,
});
const readFile = result.toolDefinitions.find((d) => d.name === 'read_file');
expect(readFile?.description).toContain('code-sandbox');
expect(readFile?.description).toContain('/mnt/data/');
expect(readFile?.description).toContain('Do not run ls/find');
expect(readFile?.description).toContain('only retained files under /mnt/data');
expect(readFile?.description).toContain('$HOME');
expect(readFile?.description).toContain('/tmp');
expect(readFile?.description).toContain('global installs');
expect(readFile?.description).toContain('background processes are call-local');
expect(readFile?.description).toContain('truncates around 256KB');
expect(readFile?.description).toContain('png, jpeg, gif, and webp images');
expect(readFile?.description).toContain('filesystem discovery');
expect(readFile?.description).not.toContain('{skillName}');
expect(readFile?.description).not.toContain('SKILL.md');
expect(JSON.stringify(readFile?.parameters)).not.toContain('{skillName}');
});
it.each([false, true])(
'extends the skill read schema locally, workspaceTools=%s',
(workspaceTools) => {
const result = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: false,
includeSkillFileInstructions: true,
workspaceTools,
workspaceOperations: new Set(CODE_WORKSPACE_OPERATIONS),
});
const def = result.toolDefinitions.find(({ name }) => name === 'read_file');
expect(def?.parameters).toMatchObject({
properties: {
start_line: {
type: 'integer',
minimum: 1,
description: expect.stringContaining('skill'),
},
max_lines: {
type: 'integer',
minimum: 1,
maximum: 500,
description: expect.stringContaining('skill'),
},
},
});
expect(def?.description).toContain('Omit both range parameters');
expect(def?.parameters?.properties?.path).toBeDefined();
expect(def?.parameters?.properties?.intent).toEqual({
type: 'string',
description: 'SDK read intent',
});
expect(def?.parameters?.required).toEqual(['path']);
expect(ReadFileToolDefinition.parameters).not.toHaveProperty('properties.start_line');
expect(ReadFileToolDefinition.parameters).not.toHaveProperty('properties.max_lines');
},
);
it('advertises explicit workspace paths and pagination for attached environments', () => {
const result = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
includeSkillFileInstructions: false,
workspaceTools: true,
workspaceOperations: new Set(CODE_WORKSPACE_OPERATIONS),
});
const readFile = result.toolDefinitions.find((definition) => definition.name === 'read_file');
const bashTool = result.toolDefinitions.find((definition) => definition.name === 'bash_tool');
const searchWorkspace = result.toolDefinitions.find(
(definition) => definition.name === 'search_workspace',
);
const listWorkspaceFiles = result.toolDefinitions.find(
(definition) => definition.name === 'list_workspace_files',
);
expect(readFile?.description).toContain('workspace/');
expect(readFile?.description).toContain('attached');
expect(readFile?.description).toContain(
'Only the registered workspace persists for attached commands',
);
expect(readFile?.description).toContain('operator-managed');
expect(readFile?.parameters).toMatchObject({
properties: {
start_line: { type: 'integer' },
max_lines: { type: 'integer', maximum: 500 },
},
});
expect(bashTool?.description).toContain('selected attached environment');
expect(bashTool?.description).toContain('empty directory');
expect(bashTool?.description).toContain('Network and file access follow the sandbox policy');
expect(bashTool?.description).not.toContain('/mnt/data');
expect(bashTool?.parameters).toMatchObject({
properties: {
command: { type: 'string' },
args: { type: 'array' },
cwd: { type: 'string', maxLength: 4096 },
timeoutMs: { type: 'integer', minimum: 1, maximum: 30000 },
},
required: ['command'],
});
expect(searchWorkspace).toMatchObject({
name: 'search_workspace',
parameters: {
properties: {
query: { type: 'string' },
path: { type: 'string' },
max_results: { type: 'integer', maximum: 200 },
},
required: ['query'],
},
});
expect(searchWorkspace?.description).toContain('literal text');
expect(listWorkspaceFiles).toMatchObject({
name: 'list_workspace_files',
parameters: {
properties: {
path: { type: 'string' },
max_results: { type: 'integer', maximum: 500 },
after_path: { type: 'string' },
},
},
});
expect(listWorkspaceFiles?.description).toContain('empty directory');
expect(listWorkspaceFiles?.description).toContain('after_path');
expect(filePathDescription(listWorkspaceFiles)).toContain('canonical relative');
});
it('advertises the configured attached-command timeout ceiling', () => {
const result = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
workspaceTools: true,
workspaceOperations: new Set(['execute_command'] as const),
workspaceCommandTimeoutMaxMs: 120_000,
});
expect(
result.toolDefinitions.find((definition) => definition.name === 'bash_tool'),
).toMatchObject({
parameters: {
properties: { timeoutMs: { minimum: 1, maximum: 120_000 } },
},
});
});
it('advertises configured defaults without changing shared definitions or skill upgrades', () => {
const toolRegistry = makeRegistry();
const options = {
toolRegistry,
includeBash: true,
includeSkillFileInstructions: false,
workspaceTools: true,
workspaceOperations: new Set(CODE_WORKSPACE_OPERATIONS),
workspaceCommandTimeoutMaxMs: 80_000,
workspaceCommandTimeoutDefaultMs: 60_000,
workspaceReadFileDefaultLines: 500,
};
const configured = registerCodeExecutionTools({ ...options, toolDefinitions: [] });
const upgraded = registerCodeExecutionTools({
...options,
toolDefinitions: configured.toolDefinitions,
includeBash: false,
includeSkillFileInstructions: true,
});
const readFile = upgraded.toolDefinitions.find(({ name }) => name === 'read_file');
expect(readFile?.description).toContain('skills/{skillName}/');
expect(readFile?.parameters).toMatchObject({
properties: {
max_lines: { maximum: 500, description: expect.stringContaining('Defaults to 500') },
},
});
expect(toolRegistry.get('read_file')).toBe(readFile);
expect(
upgraded.toolDefinitions.find(({ name }) => name === 'bash_tool')?.parameters,
).toMatchObject({
properties: {
timeoutMs: {
maximum: 80_000,
description: expect.stringContaining('Defaults to 60000 for foreground calls'),
},
},
});
const legacy = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
workspaceTools: true,
workspaceOperations: new Set(CODE_WORKSPACE_OPERATIONS),
});
expect(
legacy.toolDefinitions.find(({ name }) => name === 'read_file')?.parameters,
).toMatchObject({
properties: { max_lines: { description: expect.stringContaining('Defaults to 200') } },
});
expect(
legacy.toolDefinitions.find(({ name }) => name === 'bash_tool')?.parameters,
).toMatchObject({
properties: {
timeoutMs: {
description: expect.stringContaining('Defaults to 30000 for foreground calls'),
},
},
});
});
it('registers only operations advertised by the selected workspace', () => {
const result = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
includeSkillFileInstructions: false,
workspaceTools: true,
workspaceOperations: new Set(['read_file', 'list_files']),
});
expect(result.toolDefinitions.map(({ name }) => name).sort()).toEqual([
'list_workspace_files',
'read_file',
]);
});
it('fails closed when attached workspace operations were not validated', () => {
const result = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
includeSkillFileInstructions: false,
workspaceTools: true,
});
expect(result.toolDefinitions).toEqual([]);
});
it('upgrades a code-only read_file definition when skills are enabled later in the run', () => {
const toolRegistry = makeRegistry();
const codeOnly = registerCodeExecutionTools({
toolRegistry,
toolDefinitions: [],
includeBash: true,
includeSkillFileInstructions: false,
});
const upgraded = registerCodeExecutionTools({
toolRegistry,
toolDefinitions: codeOnly.toolDefinitions,
includeBash: false,
includeSkillFileInstructions: true,
});
const readFile = upgraded.toolDefinitions.find((d) => d.name === 'read_file');
expect(upgraded.registered).toEqual([]);
expect(readFile?.description).toContain('{skillName}/{filePath}');
expect(readFile?.description).toContain('skills/{skillName}/');
expect(readFile?.description).toContain('SKILL.md');
expect(toolRegistry.get('read_file')?.description).toBe(readFile?.description);
});
it('preserves attached workspace instructions when skills upgrade read_file', () => {
const toolRegistry = makeRegistry();
const codeOnly = registerCodeExecutionTools({
toolRegistry,
toolDefinitions: [],
includeBash: true,
includeSkillFileInstructions: false,
workspaceTools: true,
workspaceOperations: new Set(CODE_WORKSPACE_OPERATIONS),
});
const upgraded = registerCodeExecutionTools({
toolRegistry,
toolDefinitions: codeOnly.toolDefinitions,
includeBash: false,
includeSkillFileInstructions: true,
workspaceTools: true,
workspaceOperations: new Set(CODE_WORKSPACE_OPERATIONS),
});
const readFile = upgraded.toolDefinitions.find(
(definition) => definition.name === 'read_file',
);
expect(readFile?.description).toContain('skills/{skillName}/');
expect(readFile?.description).toContain('workspace/');
expect(readFile?.parameters).toMatchObject({
properties: { max_lines: { maximum: 500 } },
});
});
it('preserves pre-existing unrelated tool definitions', () => {
const toolRegistry = makeRegistry();
const existing: LCTool[] = [
{ name: 'calculator', description: 'calc', parameters: undefined } as LCTool,
];
const result = registerCodeExecutionTools({
toolRegistry,
toolDefinitions: existing,
includeBash: true,
});
const names = result.toolDefinitions.map((d) => d.name);
expect(names).toEqual(['calculator', 'read_file', 'bash_tool']);
});
it('keeps code-execution tool descriptions within provider advisory limits', () => {
const skillAwareWithRefs = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
includeSkillFileInstructions: true,
enableToolOutputReferences: true,
});
const codeOnlyWithoutRefs = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
includeSkillFileInstructions: false,
enableToolOutputReferences: false,
});
const attachedWithoutRefs = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
includeSkillFileInstructions: false,
enableToolOutputReferences: false,
workspaceTools: true,
workspaceOperations: new Set(CODE_WORKSPACE_OPERATIONS),
});
const attachedNativeSandboxWithoutRefs = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
includeSkillFileInstructions: false,
enableToolOutputReferences: false,
workspaceTools: true,
workspaceOperations: new Set(CODE_WORKSPACE_OPERATIONS),
workspaceNativeSandbox: true,
});
expect(
maxToolDescriptionLength([
...skillAwareWithRefs.toolDefinitions,
...codeOnlyWithoutRefs.toolDefinitions,
...attachedWithoutRefs.toolDefinitions,
...attachedNativeSandboxWithoutRefs.toolDefinitions,
]),
).toBeLessThanOrEqual(TOOL_DESCRIPTION_ADVISORY_MAX_LENGTH);
});
});
describe('idempotence (second call in same run)', () => {
it('is a no-op when both tools already live in the registry', () => {
const toolRegistry = makeRegistry();
const first = registerCodeExecutionTools({
toolRegistry,
toolDefinitions: [],
includeBash: true,
});
/* Second call simulates skills-path + execute_code-path overlap. */
const second = registerCodeExecutionTools({
toolRegistry,
toolDefinitions: first.toolDefinitions,
includeBash: true,
});
expect(second.registered).toEqual([]);
expect(second.toolDefinitions).toHaveLength(2);
const names = second.toolDefinitions.map((d) => d.name).sort();
expect(names).toEqual(['bash_tool', 'read_file']);
});
it('is a no-op when tools already live in toolDefinitions (no registry available)', () => {
const existing: LCTool[] = [
{ name: 'read_file', description: 'pre', parameters: undefined } as LCTool,
{ name: 'bash_tool', description: 'pre', parameters: undefined } as LCTool,
];
const result = registerCodeExecutionTools({
toolRegistry: undefined,
toolDefinitions: existing,
includeBash: true,
});
expect(result.registered).toEqual([]);
expect(result.toolDefinitions).toEqual(existing);
});
it('only adds the missing half when one is already registered', () => {
const toolRegistry = makeRegistry();
toolRegistry.set('read_file', {
name: 'read_file',
description: 'prev',
parameters: undefined,
} as LCTool);
const result = registerCodeExecutionTools({
toolRegistry,
toolDefinitions: [],
includeBash: true,
});
expect(result.registered).toEqual(['bash_tool']);
const names = result.toolDefinitions.map((d) => d.name);
expect(names).toEqual(['bash_tool']);
expect(toolRegistry.has('read_file')).toBe(true);
expect(toolRegistry.has('bash_tool')).toBe(true);
});
});
describe('no-registry variant', () => {
it('still returns merged toolDefinitions when toolRegistry is undefined', () => {
const result = registerCodeExecutionTools({
toolRegistry: undefined,
toolDefinitions: [],
includeBash: true,
});
const names = result.toolDefinitions.map((d) => d.name).sort();
expect(names).toEqual(['bash_tool', 'read_file']);
expect(result.registered.sort()).toEqual(['bash_tool', 'read_file']);
});
});
describe('enableToolOutputReferences', () => {
const findBashDef = (defs: LCTool[]): LCTool | undefined =>
defs.find((d) => d.name === 'bash_tool');
it('appends the {{tool<idx>turn<turn>}} guide when flag is true', () => {
const result = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
enableToolOutputReferences: true,
});
const bash = findBashDef(result.toolDefinitions);
expect(bash?.description).toContain('{{tool<idx>turn<turn>}}');
});
it('omits the {{tool<idx>turn<turn>}} guide when flag is false', () => {
const result = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
enableToolOutputReferences: false,
});
const bash = findBashDef(result.toolDefinitions);
expect(bash?.description).not.toContain('{{tool<idx>turn<turn>}}');
});
it('omits the guide by default when flag is unspecified', () => {
const result = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
});
const bash = findBashDef(result.toolDefinitions);
expect(bash?.description).not.toContain('{{tool<idx>turn<turn>}}');
});
it('returns the same frozen bash_tool reference across calls with the same flag', () => {
/**
* The two `bash_tool` variants are cached at module scope so
* repeated agent inits in the same process don't re-allocate
* + re-freeze + re-build the description on every call.
* Asserting reference equality across two fresh registries
* pins that contract — a regression that switches back to a
* per-call `Object.freeze` would fail this test.
*/
const a = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
enableToolOutputReferences: true,
});
const b = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
enableToolOutputReferences: true,
});
expect(findBashDef(a.toolDefinitions)).toBe(findBashDef(b.toolDefinitions));
});
it('returns distinct frozen references for the two flag variants', () => {
/**
* Sanity check on the two-singleton cache: the with-refs and
* without-refs definitions are distinct objects so toggling
* the flag in `registerCodeExecutionTools` actually picks up
* the alternate description, not the same cached reference.
*/
const withRefs = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
enableToolOutputReferences: true,
});
const withoutRefs = registerCodeExecutionTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeBash: true,
enableToolOutputReferences: false,
});
const a = findBashDef(withRefs.toolDefinitions);
const b = findBashDef(withoutRefs.toolDefinitions);
expect(a).not.toBe(b);
expect(a?.description).toContain('{{tool<idx>turn<turn>}}');
expect(b?.description).not.toContain('{{tool<idx>turn<turn>}}');
});
});
});
describe('registerFileAuthoringTools', () => {
const makeRegistry = (): LCToolRegistry => new Map() as unknown as LCToolRegistry;
it('recognizes host-side file authoring tools as code-session-aware without mutating the shared set', () => {
expect(isCodeSessionToolName('bash_tool')).toBe(true);
expect(isCodeSessionToolName('search_workspace')).toBe(true);
expect(isCodeSessionToolName('list_workspace_files')).toBe(true);
expect(isCodeSessionToolName('create_file')).toBe(false);
expect(isCodeSessionToolName('edit_file')).toBe(false);
expect(isCodeSessionToolName('create_file', FILE_AUTHORING_TOOL_NAMES)).toBe(true);
expect(isCodeSessionToolName('edit_file', FILE_AUTHORING_TOOL_NAMES)).toBe(true);
expect(CODE_EXECUTION_TOOLS.has('create_file')).toBe(false);
expect(CODE_EXECUTION_TOOLS.has('edit_file')).toBe(false);
});
it('registers create_file and edit_file with skill-aware descriptions', () => {
const toolRegistry = makeRegistry();
const result = registerFileAuthoringTools({
toolRegistry,
toolDefinitions: [],
includeSkillFileInstructions: true,
});
const names = result.toolDefinitions.map((d) => d.name).sort();
expect(names).toEqual(['create_file', 'edit_file']);
expect(result.registered.sort()).toEqual(['create_file', 'edit_file']);
expect(toolRegistry.has('create_file')).toBe(true);
expect(toolRegistry.has('edit_file')).toBe(true);
expect(result.toolDefinitions[0].responseFormat).toBe('content_and_artifact');
expect(result.toolDefinitions.map((d) => d.description).join('\n')).toContain('skills/');
expect(toolRegistry.get('create_file')?.description).toContain('frontmatter name must match');
expect(toolRegistry.get('create_file')?.description).toContain('trigger-friendly');
expect(toolRegistry.get('create_file')?.description).toContain('references/template.html');
expect(toolRegistry.get('create_file')?.description).toContain('templates/{file}');
expect(toolRegistry.get('edit_file')?.description).toContain('edit_file cannot rename skills');
expect(toolRegistry.get('edit_file')?.description).toContain('Keep SKILL.md concise');
expect(toolRegistry.get('edit_file')?.description).toContain('templates/');
expect(filePathDescription(toolRegistry.get('create_file'))).toContain(
'frontmatter name must match',
);
expect(filePathDescription(toolRegistry.get('edit_file'))).toContain(
'edit_file cannot rename skills',
);
});
it('registers code-only descriptions for code-exec-only agents', () => {
const toolRegistry = makeRegistry();
const result = registerFileAuthoringTools({
toolRegistry,
toolDefinitions: [],
includeSkillFileInstructions: false,
});
const createFile = result.toolDefinitions.find((d) => d.name === 'create_file');
const editFile = result.toolDefinitions.find((d) => d.name === 'edit_file');
expect(createFile?.description).toContain('code-execution sandbox');
expect(createFile?.description).toContain('/mnt/data/');
expect(createFile?.description).not.toContain('skills/');
expect(editFile?.description).toContain('code-execution sandbox');
expect(editFile?.description).toContain('/mnt/data/');
expect(editFile?.description).not.toContain('skills/');
expect(filePathDescription(createFile)).toContain('code-execution sandbox');
expect(filePathDescription(createFile)).not.toContain('skills/');
expect(filePathDescription(createFile)).not.toContain('SKILL.md');
expect(filePathDescription(editFile)).toContain('code-execution sandbox');
expect(filePathDescription(editFile)).not.toContain('skills/');
expect(filePathDescription(editFile)).not.toContain('rename skills');
});
it('registers attached-workspace paths and atomic edit semantics', () => {
const result = registerFileAuthoringTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeSkillFileInstructions: false,
workspaceTools: true,
workspaceOperations: new Set(CODE_WORKSPACE_OPERATIONS),
});
const createFile = result.toolDefinitions.find((d) => d.name === 'create_file');
const editFile = result.toolDefinitions.find((d) => d.name === 'edit_file');
expect(createFile?.description).toContain('workspace/{relativePath}');
expect(createFile?.description).not.toContain('/mnt/data/');
expect(editFile?.description).toContain('entire batch commits atomically');
expect(filePathDescription(createFile)).toContain('workspace/{relativePath}');
expect(filePathDescription(editFile)).toContain('workspace/{relativePath}');
expect(isFileAuthoringToolDefinition(createFile)).toBe(true);
expect(isFileAuthoringToolDefinition(editFile)).toBe(true);
});
it('registers only authoring operations advertised by the selected workspace', () => {
const result = registerFileAuthoringTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeSkillFileInstructions: false,
workspaceTools: true,
workspaceOperations: new Set(['edit_file']),
});
expect(result.toolDefinitions.map(({ name }) => name)).toEqual(['edit_file']);
});
it('fails closed when attached authoring operations were not validated', () => {
const result = registerFileAuthoringTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeSkillFileInstructions: false,
workspaceTools: true,
});
expect(result.toolDefinitions).toEqual([]);
});
it('is idempotent across repeated registration calls', () => {
const toolRegistry = makeRegistry();
const first = registerFileAuthoringTools({
toolRegistry,
toolDefinitions: [],
});
const second = registerFileAuthoringTools({
toolRegistry,
toolDefinitions: first.toolDefinitions,
});
expect(second.registered).toEqual([]);
expect(second.toolDefinitions).toHaveLength(2);
});
it('upgrades code-only definitions to skill-aware definitions', () => {
const toolRegistry = makeRegistry();
const codeOnly = registerFileAuthoringTools({
toolRegistry,
toolDefinitions: [],
includeSkillFileInstructions: false,
});
const upgraded = registerFileAuthoringTools({
toolRegistry,
toolDefinitions: codeOnly.toolDefinitions,
includeSkillFileInstructions: true,
});
expect(upgraded.registered).toEqual([]);
expect(upgraded.toolDefinitions.find((d) => d.name === 'create_file')?.description).toContain(
'skills/',
);
expect(toolRegistry.get('edit_file')?.description).toContain('skills/');
});
it('keeps file-authoring tool descriptions within provider advisory limits', () => {
const skillAware = registerFileAuthoringTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeSkillFileInstructions: true,
});
const codeOnlyRegistry = makeRegistry();
const codeOnly = registerFileAuthoringTools({
toolRegistry: codeOnlyRegistry,
toolDefinitions: [],
includeSkillFileInstructions: false,
});
const upgraded = registerFileAuthoringTools({
toolRegistry: codeOnlyRegistry,
toolDefinitions: codeOnly.toolDefinitions,
includeSkillFileInstructions: true,
});
const attached = registerFileAuthoringTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeSkillFileInstructions: true,
workspaceTools: true,
workspaceOperations: new Set(CODE_WORKSPACE_OPERATIONS),
});
expect(
maxToolDescriptionLength([
...skillAware.toolDefinitions,
...codeOnly.toolDefinitions,
...upgraded.toolDefinitions,
...attached.toolDefinitions,
]),
).toBeLessThanOrEqual(TOOL_DESCRIPTION_ADVISORY_MAX_LENGTH);
});
it('distinguishes host file authoring definitions from user tools with matching names', () => {
const result = registerFileAuthoringTools({
toolRegistry: makeRegistry(),
toolDefinitions: [],
includeSkillFileInstructions: true,
});
const createFile = result.toolDefinitions.find((d) => d.name === 'create_file');
expect(isFileAuthoringToolDefinition(createFile)).toBe(true);
expect(
isFileAuthoringToolDefinition({
name: 'create_file',
description: 'A user-defined create_file action',
parameters: { type: 'object', properties: {} } as LCTool['parameters'],
}),
).toBe(false);
});
});