Unify repository instruction loading across agent ingresses

Author: danny-avila

api/server/services/ToolService.js

@@ -49,7 +49,7 @@ const {
   isFatalAgentInitializationError,
   codeExecutionAuthHeaders,
   createAttachedWorkspaceBashTool,
-  createRepositoryInstructionLoader,
+  createRepositoryInstructionSource,
   resolveAttachedWorkspaceCommandTimeoutMax,
   createGitIdentityProgrammaticBashTool,
   resolveCodeExecutionContext,
@@ -106,7 +106,6 @@ const { processFileURL, uploadImageBuffer } = require('~/server/services/Files/p
 const { primeFiles: primeSearchFiles } = require('~/app/clients/tools/util/fileSearch');
 const { primeFiles: primeCodeFiles } = require('~/server/services/Files/Code/process');
 const { manifestToolMap, toolkits } = require('~/app/clients/tools/manifest');
-const loadRepositoryInstructions = createRepositoryInstructionLoader();
 const { createOnSearchResults } = require('~/server/services/Tools/search');
 const { reinitMCPServer } = require('~/server/services/Tools/mcp');
 const {
@@ -1563,6 +1562,12 @@ async function loadToolDefinitionsWrapper({
     primedCodeFiles,
     oauthActionToolNames,
     codeExecutionContext: resolvedCodeExecutionContext,
+    repositoryInstructionSource: createRepositoryInstructionSource({
+      enabled: codeExecutionEnabled,
+      context: resolvedCodeExecutionContext,
+      principalId: JSON.stringify([getTenantId(), req.user.id]),
+      getAuthHeaders: (workerId) => getCodeApiAuthHeaders(req, workerId),
+    }),
   };
 }
 
@@ -1759,23 +1764,11 @@ async function loadAgentTools({
     getAppConfig,
   });
 
-  const repositoryInstructionBlock = await loadRepositoryInstructions({
-    assertContent: (content) =>
-      assertModelBoundContent({
-        filters: appConfig.filters,
-        agents: [{ instructions: content }],
-        onTraversalFailure: reportLocatorTraversalFailure,
-      }),
+  const repositoryInstructionSource = createRepositoryInstructionSource({
     enabled: codeExecutionEnabled,
     context: codeExecutionContext,
-    mode: agent.repositoryInstructions,
     principalId: JSON.stringify([getTenantId(), req.user.id]),
-    signal,
-    authHeaders: () =>
-      codeExecutionAuthHeaders(
-        (bridgeWorkerId) => getCodeApiAuthHeaders(req, bridgeWorkerId),
-        codeExecutionContext,
-      ),
+    getAuthHeaders: (workerId) => getCodeApiAuthHeaders(req, workerId),
   });
   const { loadedTools, toolContextMap, dynamicToolContextMap, primedCodeFiles } = await loadTools({
     agent,
@@ -1879,7 +1872,7 @@ async function loadAgentTools({
 
   if (preparedActionSnapshot == null) {
     return {
-      repositoryInstructionBlock,
+      repositoryInstructionSource,
       toolRegistry,
       requestScopedConnections: getMCPRequestContext(req, res),
       userMCPAuthMap,
@@ -1901,7 +1894,7 @@ async function loadAgentTools({
       logger.warn(`No tools found for ${_agentTools.length} specified tool call(s)`);
     }
     return {
-      repositoryInstructionBlock,
+      repositoryInstructionSource,
       toolRegistry,
       requestScopedConnections: getMCPRequestContext(req, res),
       userMCPAuthMap,
@@ -2034,7 +2027,7 @@ async function loadAgentTools({
     toolRegistry,
     requestScopedConnections: getMCPRequestContext(req, res),
     toolContextMap,
-    repositoryInstructionBlock,
+    repositoryInstructionSource,
     dynamicToolContextMap,
     userMCPAuthMap,
     toolDefinitions,

client/src/components/SidePanel/Agents/__tests__/CodeSettings.spec.tsx

@@ -71,10 +71,29 @@ function IdentityForm({
       <output data-testid="identity">{JSON.stringify(methods.watch('git_identity'))}</output>
       <output data-testid="workspace-default">{methods.watch('code_workspace_id')}</output>
       <output data-testid="machine-default">{methods.watch('code_environment_id')}</output>
+      <output data-testid="repository-mode">{methods.watch('repositoryInstructions')}</output>
     </FormProvider>
   );
 }
 
+test('repository instruction mode defaults to prefer and retains an explicit off choice', async () => {
+  HTMLElement.prototype.scrollIntoView = jest.fn();
+  render(<IdentityForm />);
+  expect(
+    screen.getByRole('combobox', { name: 'com_ui_repository_instructions' }),
+  ).toHaveTextContent('com_ui_repository_instructions_prefer');
+  fireEvent.click(screen.getByRole('combobox', { name: 'com_ui_repository_instructions' }));
+  fireEvent.click(
+    await screen.findByRole('option', { name: 'com_ui_repository_instructions_off' }),
+  );
+  expect(screen.getByTestId('repository-mode')).toHaveTextContent('off');
+  fireEvent.click(screen.getByText('Toggle Dialog'));
+  fireEvent.click(screen.getByText('Toggle Dialog'));
+  expect(
+    screen.getByRole('combobox', { name: 'com_ui_repository_instructions' }),
+  ).toHaveTextContent('com_ui_repository_instructions_off');
+});
+
 test('saves a workspace default bound to the selected machine and permits clearing it', async () => {
   HTMLElement.prototype.scrollIntoView = jest.fn();
   render(<IdentityForm />);

packages/api/src/agents/__tests__/initialize.test.ts

@@ -33,6 +33,7 @@ jest.mock('@librechat/agents', () => ({
 }));
 
 import { Providers } from '@librechat/agents';
+import { createHash } from 'node:crypto';
 import {
   Tools,
   Constants,
@@ -287,29 +288,79 @@ describe('initializeAgent — execution context', () => {
     jest.clearAllMocks();
   });
 
-  it('places loaded repository instructions after agent instructions in the stable block', async () => {
-    const { agent, req, res, loadTools, db } = createMocks();
-    agent.instructions = 'Agent conventions';
-    loadTools.mockResolvedValue({
-      tools: [],
-      toolDefinitions: [],
-      repositoryInstructionBlock: 'Repository conventions',
-    });
-    const result = await initializeAgent(
-      {
-        req,
-        res,
-        agent,
-        loadTools,
-        endpointOption: { endpoint: EModelEndpoint.agents },
-        allowedProviders: new Set([agent.provider]),
-        isInitialAgent: true,
-      },
-      db,
-    );
-    expect(result.instructions).toBe('Agent conventions\n\nRepository conventions');
-    expect(result.additional_instructions ?? '').not.toContain('Repository conventions');
-  });
+  it.each(['prefer', 'defer', 'off'] as const)(
+    'uses saved repository instruction mode %s in definitions-only initialization',
+    async (mode) => {
+      const { agent, req, res, loadTools, db } = createMocks();
+      agent.instructions = 'Agent conventions';
+      agent.repositoryInstructions = mode;
+      const content = 'Repository conventions';
+      const authHeaders = jest.fn(async () => ({}));
+      const fetchSpy = jest.spyOn(global, 'fetch').mockResolvedValue(
+        new Response(
+          JSON.stringify({
+            protocolVersion: 1,
+            operation: 'read_file',
+            workspaceId: 'primary',
+            path: 'AGENTS.md',
+            content,
+            startLine: 1,
+            endLine: 1,
+            truncated: false,
+          }),
+        ),
+      );
+      loadTools.mockResolvedValue({
+        toolDefinitions: [],
+        repositoryInstructionSource: {
+          enabled: true,
+          principalId: `test-${mode}`,
+          context: {
+            environmentType: 'attached',
+            baseUrl: 'https://code.example/v1',
+            codeWorkspace: {
+              workspaceId: 'primary',
+              operations: ['read_file'],
+              instructions: [
+                {
+                  path: 'AGENTS.md',
+                  bytes: Buffer.byteLength(content),
+                  sha256: createHash('sha256').update(content).digest('hex'),
+                  truncated: false,
+                },
+              ],
+            },
+          },
+          authHeaders,
+        },
+      });
+      const result = await initializeAgent(
+        {
+          req,
+          res,
+          agent,
+          loadTools,
+          endpointOption: { endpoint: EModelEndpoint.agents },
+          allowedProviders: new Set([agent.provider]),
+          isInitialAgent: true,
+        },
+        db,
+      );
+      if (mode === 'off') {
+        expect(result.instructions).toBe('Agent conventions');
+        expect(authHeaders).not.toHaveBeenCalled();
+        expect(fetchSpy).not.toHaveBeenCalled();
+      } else {
+        expect(result.instructions).toContain('Repository conventions');
+        expect(result.instructions).toMatch(/^Agent conventions\n\nRepository-provided/);
+        expect(result.instructions).toContain(
+          mode === 'defer' ? 'unless they conflict' : 'prefer these instructions',
+        );
+      }
+      expect(result.additional_instructions ?? '').not.toContain('Repository conventions');
+      fetchSpy.mockRestore();
+    },
+  );
 
   it('carries request-resolved Azure identity to the run without changing persisted agent fields', async () => {
     const { agent, req, res, loadTools, db } = createMocks({

packages/api/src/agents/initialize.ts

@@ -57,6 +57,7 @@ import type {
 import type { LCAvailableTools, RequestScopedMCPConnectionStore } from '../mcp/types';
 import type { ContentTraversalLimitError } from '../protection/adapters/nested';
 import type { SkillContentInput } from '../protection/adapters/submissions';
+import type { RepositoryInstructionSource } from '../code/instructions';
 import type { TextContentFragment } from '../protection/types';
 import type { CheckAccessParams } from '../middleware/access';
 import type { MCPToolAlias } from '~/tools/classification';
@@ -112,6 +113,7 @@ import { assertModelBoundContent } from '../middleware/modelBoundContent';
 import { isImplicitStatefulCodeRouteAvailable } from '../code/config';
 import { registerMemoryTools, memoryToolUsageGuard } from './memory';
 import { applyIntentLabels, sanitizeIntentLabels } from './intent';
+import { loadRepositoryInstructions } from '../code/instructions';
 import { ContentFilterError } from '../middleware/contentFilter';
 import { resolveToolRoleGrants } from '~/tools/rolePermissions';
 import { createRequestAgentExecutionContext } from './runtime';
@@ -861,7 +863,7 @@ export interface InitializeAgentParams {
     primedCodeFiles?: import('@librechat/agents').CodeEnvFile[];
     /** Live workspace binding resolved by the execution-side loader. */
     codeExecutionContext?: CodeExecutionContext;
-    repositoryInstructionBlock?: string;
+    repositoryInstructionSource?: RepositoryInstructionSource;
   } | null>;
   /** Endpoint option (contains model_parameters and endpoint info) */
   endpointOption?: Partial<TEndpointOption>;
@@ -1965,7 +1967,7 @@ export async function initializeAgent(
     tools: structuredTools,
     primedCodeFiles,
     codeExecutionContext: loadedCodeExecutionContext,
-    repositoryInstructionBlock,
+    repositoryInstructionSource,
   } = loadToolsResult ?? {
     tools: [],
     toolContextMap: {},
@@ -1981,7 +1983,7 @@ export async function initializeAgent(
     oauthActionToolNames: undefined,
     primedCodeFiles: undefined,
     codeExecutionContext: undefined,
-    repositoryInstructionBlock: undefined,
+    repositoryInstructionSource: undefined,
   };
   const trustedCodeExecutionContext = loadedCodeExecutionContext ?? codeExecutionContext;
   const attachedWorkspaceOperations =
@@ -2264,6 +2266,18 @@ export async function initializeAgent(
     }
   }
 
+  const repositoryInstructionBlock = repositoryInstructionSource
+    ? await loadRepositoryInstructions({
+        ...repositoryInstructionSource,
+        mode: agent.repositoryInstructions,
+        signal: params.signal,
+        assertContent: (content) =>
+          assertModelBoundContent({
+            filters: appConfig?.filters,
+            agents: [{ instructions: content }],
+          }),
+      })
+    : undefined;
   if (repositoryInstructionBlock) {
     agent.instructions = [agent.instructions, repositoryInstructionBlock]
       .filter(Boolean)

packages/api/src/agents/management.spec.ts

@@ -39,6 +39,20 @@ const persistedAgent = {
 };
 
 describe('Agent Management contract', () => {
+  it('preserves repository instruction mode through API updates and response projection', () => {
+    for (const mode of ['prefer', 'defer', 'off'] as const) {
+      expect(agentManagementUpdateSchema.parse({ repositoryInstructions: mode })).toEqual({
+        repositoryInstructions: mode,
+      });
+      expect(
+        projectAgentManagementResponse({ ...persistedAgent, repositoryInstructions: mode })
+          .repositoryInstructions,
+      ).toBe(mode);
+    }
+    expect(
+      agentManagementUpdateSchema.safeParse({ repositoryInstructions: 'allow-all' }).success,
+    ).toBe(false);
+  });
   describe('inputs', () => {
     it('keeps create and update fields aligned with the browser Agent validators', () => {
       expect(

packages/api/src/agents/management.ts

@@ -280,6 +280,7 @@ export function projectAgentManagementResponse(
     stateful_code_environment: source.stateful_code_environment,
     code_environment_id: source.code_environment_id,
     code_workspace_id: source.code_workspace_id,
+    repositoryInstructions: source.repositoryInstructions,
     git_identity: source.git_identity,
     artifacts: source.artifacts,
     recursion_limit: source.recursion_limit,

packages/api/src/code/instructions.spec.ts

@@ -37,6 +37,38 @@ const response = () =>
   );
 
 describe('repository instruction loading', () => {
+  it('bounds optional authorization waits and preserves explicit cancellation', async () => {
+    jest.useFakeTimers();
+    try {
+      const load = createRepositoryInstructionLoader();
+      const args = {
+        enabled: true,
+        context,
+        principalId: 'test',
+        assertContent: jest.fn(),
+        authHeaders: () => new Promise<Record<string, string>>(() => {}),
+      };
+      const pending = load(args);
+      await jest.advanceTimersByTimeAsync(2000);
+      expect(await pending).toBeUndefined();
+      expect(
+        await load({
+          ...args,
+          authHeaders: async () => {
+            throw new Error('unavailable');
+          },
+        }),
+      ).toBeUndefined();
+      const controller = new AbortController();
+      const cancelled = load({ ...args, signal: controller.signal });
+      const assertion = expect(cancelled).rejects.toThrow('cancelled');
+      controller.abort(new Error('cancelled'));
+      await assertion;
+    } finally {
+      jest.useRealTimers();
+    }
+  });
+
   it('checks authorization and content policy on cache hits, without cross-principal reuse', async () => {
     const load = createRepositoryInstructionLoader();
     const fetchImpl = jest.fn(async () => response());